WebSphere DataPower XML Integration Appliance XI50

Version 3.8.0

Multi-Protocol Gateway Developers Guide



WebSphere DataPower XML Integration Appliance XI50

Version 3.8.0

Multi-Protocol Gateway Developers Guide



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

First Edition (November 2009)

This edition applies to version 3, release 8, modification 0 of IBM WebSphere DataPower XML Integration
Appliance XI50 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
Who should read this document . . . . . . . vii
How this document is organized . . . . . . . vii
Publications . . . . . . . . . . . . . . viii
Installation and upgrade documentation . . . viii
Administration documentation . . . . . . . ix
Development documentation. . . . . . . . ix
Reference documentation . . . . . . . . . ix
Integration documentation . . . . . . . . . x
Problem determination documentation . . . . x
Supplemental documentation . . . . . . . . x
External resources . . . . . . . . . . . . xi
File naming guidelines . . . . . . . . . . xii
Object naming guidelines. . . . . . . . . . xii
Typeface conventions . . . . . . . . . . . xii

Chapter 1. Introduction . . . . . . . . 1
Support for Web 2.0 configurations .
REST principals in Web 2.0 . .
Web 2.0 and JSON . . . . .

.
.
.

.
.
.

.
.
.

.
.
.

.
.
.

. 1
. 1
. 4

Chapter 2. WebGUI basics . . . . . . . 7

Objects on the appliance . . . . . . . . . . 7
Working with objects . . . . . . . . . . . 7
Accessing the WebGUI . . . . . . . . . . . 7
Welcome screen . . . . . . . . . . . . . 7
Common WebGUI conventions . . . . . . . . 8
Working with referenced objects . . . . . . . 8
Working with lists of referenced objects . . . . 9
Viewing and editing local files during configuration 9
Viewing local files . . . . . . . . . . . 10
Editing local files . . . . . . . . . . . 10
Common WebGUI tasks . . . . . . . . . . 10
Applying and saving changes . . . . . . . 10
Canceling changes . . . . . . . . . . . 10
Resetting objects . . . . . . . . . . . . 11
Deleting objects . . . . . . . . . . . . 11
Exporting objects . . . . . . . . . . . 11
Viewing configuration-specific messages . . . . 11
Viewing object status . . . . . . . . . . 12
Cloning services . . . . . . . . . . . . 12
Accessing probe captures . . . . . . . . . 13

Chapter 3. Securing communication . . 15

Supported cryptographic formats . . .
Working with keys and certificates . .
Creating key-certificate pairs . . .
Generating keys and certificates . .
Exporting keys and certificates . . .
Importing keys and certificates . . .
Working with Certificate objects . . .
Working with z/OS certificates . . .
Defining Certificate objects . . . .
Defining Firewall Credentials objects . .
Defining Identification Credentials objects
Copyright IBM Corp. 2002, 2009

.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.

15
15
15
16
17
18
19
19
19
21
21

Working with Key objects . . . . . .

Working with z/OS keys . . . . . .
Defining Key objects . . . . . . .
Defining Profile objects . . . . . . .
Defining shared secret keys . . . . . .
SSL Proxy Profile objects . . . . . . .
Creating a forward (or client) proxy . .
Creating a reverse (or server) proxy . .
Creating a two-way proxy . . . . .
Validation credentials . . . . . . . .
Creating for non-expiring, non-passwordprotected certificates . . . . . . .
Creating for select certificates . . . .

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

22
22
23
24
26
26
26
27
27
28

.
.

.
.

. 28
. 29

Chapter 4. Multi-Protocol Gateway

configuration . . . . . . . . . . . . 31
Creating a Multi-Protocol Gateway service . .
Available properties . . . . . . . . .
XML threat protection . . . . . . . . .
Protecting against single message XML
denial-of-service attacks . . . . . . .
Protecting against multiple message XML
denial-of-service attacks . . . . . . .
Protecting against message tampering . .
Protection against SQL injections . . . .
XML virus . . . . . . . . . . . .
Protecting against dictionary attacks . . .
URL builders . . . . . . . . . . . .
Building an IMS Connect URL . . . . .
Building an MQ URL . . . . . . . .
Building a TIBCO EMS URL. . . . . .
Building a WebSphere JMS URL . . . .
Scenario: Defining a load balancer group as the
destination . . . . . . . . . . . .

.
.
.

. 32
. 33
. 37

. 37

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

. 44

39
39
39
40
41
41
41
42
43
44

Chapter 5. Handler configuration . . . 47

Configuring an FTP poller handler . . . . . .
Configuring an FTP server handler . . . . . .
Defining as transparent . . . . . . . . .
Defining as virtual ephemeral . . . . . . .
Defining as virtual persistent . . . . . . .
Configuring an HTTP handler . . . . . . . .
Configuring an HTTPS handler . . . . . . . .
Configuring an IMS Connect handler . . . . . .
Configuring a WebSphere MQ handler . . . . .
High-level configuration . . . . . . . . .
Defining the basic configuration . . . . . .
Defining the publish and subscribe configuration
Defining the properties and headers
configuration . . . . . . . . . . . . .
Defining the advanced configuration . . . . .
Configuring an NFS poller handler . . . . . .
SFTP server handler configuration . . . . . . .
Configuration considerations . . . . . . .
Authentication and authorization . . . . . .

47
50
52
54
58
62
63
64
65
65
66
67
67
68
68
71
71
72

iii

SSH metadata variables . . . . . .

URL specifications with an SFTP handler
Configuring an SFTP Server handler . .
Configuring a stateful raw XML handler. .
Configuring a stateless raw XML handler .
TIBCO EMS handler configuration. . . .
Using topic spaces . . . . . . . .
Using map message . . . . . . .
Configuring a TIBCO EMS handler . .
WebSphere JMS handler configuration . .
Using topics spaces . . . . . . . .
Configuring a WebSphere JMS handler .

.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.

72
72
73
74
75
76
76
76
77
78
78
78

Chapter 6. Processing policies . . . . 81

Matching rules . . . . . . . . . . . .
Processing rules . . . . . . . . . . . .
Processing actions . . . . . . . . . . .
Contexts . . . . . . . . . . . . . .
Context in processing rules . . . . . . .
Context keywords . . . . . . . . . .
Processing rule builder . . . . . . . . .
Creating a processing policy . . . . . . . .
Defining processing actions . . . . . . . .
Adding an AAA action . . . . . . . .
Adding an antivirus action . . . . . . .
Adding a call processing rule (call) action . .
Adding a checkpoint event (checkpoint) action
Adding a conditional action . . . . . . .
Adding a convert query parameters to XML
(convert-http) action . . . . . . . . .
Cryptographic binary (cryptobin) action . . .
Adding a decrypt action. . . . . . . .
Adding an encrypt action . . . . . . .
Adding an event-sink action . . . . . .
Adding an extract using XPath (extract) action
Adding a fetch action. . . . . . . . .
Filter actions. . . . . . . . . . . .
For each (for-each) action . . . . . . .
Adding a log action . . . . . . . . .
MQ header action . . . . . . . . . .
Adding an on-error action . . . . . . .
Results actions . . . . . . . . . . .
Adding a rewrite header (rewrite) action . .
Adding a method rewrite action . . . . .
Route-type actions. . . . . . . . . .
Adding a set variable (setvar) action . . .
Adding a sign action . . . . . . . . .
Adding an SLM action . . . . . . . .
Adding an SQL action . . . . . . . .
Adding a Strip Attachments action . . . .
Transform-type actions . . . . . . . .
Adding a validate action . . . . . . .
Verify actions . . . . . . . . . . .
Defining reusable rules . . . . . . . . .
Locating remote resources in actions. . . . .
Supported protocols in attachments . . . .
Specifying the location of remote resources .
Attachment protocol . . . . . . . . .
Format of the <results> element . . . . . .
Using the variable builder . . . . . . . .
Debugging processing policies. . . . . . .

iv

.
.
.
.
.
.
.
.
.
.
.
.

81
82
82
86
86
86
87
87
88
88
88
90
91
. 91

. 92
. 93
. 101
. 103
. 116
117
. 117
. 118
. 121
. 124
. 124
. 128
. 129
. 132
. 132
. 133
. 134
. 135
. 137
. 137
. 138
. 138
. 144
. 146
. 147
. 147
. 147
. 148
. 149
. 150
. 150
. 151

Chapter 7. AAA Policy configuration

153

Creating AAA policies . . . . . . . . . .

Defining identity extraction methods . . . . .
Defining the authentication method . . . . . .
Mapping authentication credentials . . . . . .
Changing the authentication caching policy . .
Defining resource extraction methods . . . . .
Mapping requested resources . . . . . . . .
Defining the authorization method . . . . . .
Changing the authorization caching policy . .
Defining counters for authorized and rejected
messages . . . . . . . . . . . . . . .
Defining a counter for authorized messages . .
Defining a counter for rejected messages . . .
Defining logging for authorizations and rejections
Defining logging for authorizations . . . . .
Defining logging for rejections. . . . . . .
Post processing activities . . . . . . . . .
Running a custom style sheet . . . . . . .
Generating a SAML assertion . . . . . . .
Including an AP-REQ token to act as a Kerberos
client . . . . . . . . . . . . . . .
Processing a WS-Trust SecurityContextToken
request . . . . . . . . . . . . . .
Adding a WS-Security UsernameToken . . . .
Generating an LTPA token . . . . . . . .
Generating a Kerberos SPNEGO token . . . .
Requesting a TFIM token map. . . . . . .
Generating an ICRX token for z/OS identity
propagation . . . . . . . . . . . . .

154
155
161
168
170
170
172
174
181
182
182
182
182
183
183
183
183
183
184
184
185
185
185
185
186

Chapter 8. Managing files . . . . . . 187

Directories on the appliance . . . . .
Launching the File Management utility . .
Displaying directory contents . . . . .
Creating a subdirectory . . . . . . .
Deleting a directory . . . . . . . .
Refreshing directory contents . . . . .
Uploading files from the workstation . .
Working with Java Key Stores . . . . .
Required software . . . . . . . .
Granting permissions. . . . . . .
Types of key stores . . . . . . .
Uploading a file from a Java Key Store .
Fetching files . . . . . . . . . .
Copying files . . . . . . . . . .
Renaming files . . . . . . . . . .
Moving files . . . . . . . . . . .
Viewing files . . . . . . . . . .
Editing files . . . . . . . . . . .
Deleting files . . . . . . . . . .

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

187
189
189
189
190
190
190
191
191
191
191
191
192
192
193
193
194
194
194

Chapter 9. Managing the configuration

of the appliance . . . . . . . . . . 195
Creating Include Configuration File objects .
Creating Import Configuration File objects .
Backing up and exporting configuration data.
Backing up the entire appliance . . . .
Backing up domains . . . . . . . .
Exporting select objects . . . . . . .

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

.
.
.
.
.
.

.
.
.
.
.
.

195
196
197
198
198
199

Copying or moving select objects . . . .

Managing configuration checkpoints . . .
Defining number configuration checkpoints
allow . . . . . . . . . . . . .
Saving configuration checkpoints . . . .
Listing configuration checkpoints. . . .
Rolling back to a configuration checkpoint
Deleting configuration checkpoints . . .
Importing configuration data . . . . . .
Managing changes in configuration data . .
Comparing configurations . . . . . .
Reading the change report . . . . . .
Reverting changes . . . . . . . . .
Deployment policies . . . . . . . . .
Creating deployment policies . . . . .
Using the deployment policy builder . .
Specifying the matching statement . . .

Chapter 10. Managing monitors

Monitor types . . . . . . . .
Message monitors . . . . . . .
Traffic definitions . . . . . .
Message Type . . . . . . .
Message Filter Action. . . . .
Configuring count monitors . .
Configuring duration monitors .
Web services monitors . . . . .
Enabling statistics . . . . . .
Configuring Web services monitors
Specifying dual thresholds . . .

.
.
.
.
.
.
.
.
.
.
.

.
.
to
.
.
.
.
.
.
.
.
.
.
.
.
.
.

. 201
. 202
.
.
.
.
.
.
.
.
.
.
.
.
.
.

202
203
203
204
204
204
206
206
207
207
208
208
209
210

. . . 211
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.

211
212
213
215
215
216
218
220
220
220
222

Appendix A. Referenced objects . . . 225

Creating AAA Policy objects . . . . . .
Main tab . . . . . . . . . . . .
Identity tab . . . . . . . . . . .
Authenticate tab . . . . . . . . .
Map Credentials tab . . . . . . . .
Resource tab. . . . . . . . . . .
Map Resource tab . . . . . . . . .
Authorize tab . . . . . . . . . .
Post Processing tab . . . . . . . .
Namespace Mapping tab . . . . . .
SAML Attributes tab . . . . . . . .
LTPA Attributes tab . . . . . . . .
Transaction Priority tab . . . . . . .
Setting namespace data for XPath bindings
Defining SAML attributes . . . . . .
Adding LTPA user attributes . . . . .
Using an AAA Info file . . . . . . .
IBM Tivoli Access Manager Integration . .
IBM Tivoli Federated Identity Manager
Integration . . . . . . . . . . .
Kerberos objects . . . . . . . . .
XACML Policy Decision Point objects . .
Conformance Policy . . . . . . . . .
Document Crypto Map . . . . . . . .
Namespace Mappings tab . . . . . .
HTTP Input Conversion Map . . . . . .
Input Encoding tab . . . . . . . .
IMS Connect . . . . . . . . . . .

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

225
225
228
230
236
237
238
239
245
246
246
247
247
248
248
248
249
253

.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.

256
258
261
263
266
267
267
267
268

Defining LDAP Search Parameters objects . . . .

Load balancer groups . . . . . . . . . .
Intelligent load distribution. . . . . . . .
Algorithms for making load balancing decisions
Membership . . . . . . . . . . . . .
Health checks . . . . . . . . . . . .
Session affinity . . . . . . . . . . . .
Configuring a load balancer group . . . . .
Modifying to use workload management
information . . . . . . . . . . . . .
Assigning weight to members . . . . . . .
Disabling members . . . . . . . . . .
Enabling the retrieval of workload management
information . . . . . . . . . . . . .
Defining Matching Rule objects . . . . . . .
MTOM Policy . . . . . . . . . . . . .
Multi-Protocol Gateway object. . . . . . . .
Configuring basic operations . . . . . . .
Proxy Settings tab . . . . . . . . . . .
Monitors tab . . . . . . . . . . . .
Parser Limits tab . . . . . . . . . . .
HTTP Options tab . . . . . . . . . . .
HTTP Header Injection tab . . . . . . . .
HTTP Header Suppression tab . . . . . .
WS-Addressing tab . . . . . . . . . .
WS-ReliableMessaging tab . . . . . . . .
Stylesheet Parameter tab. . . . . . . . .
Policy Parameters . . . . . . . . . . . .
Main tab . . . . . . . . . . . . . .
Policy Parameters tab . . . . . . . . .
Defining Processing Action objects . . . . . .
Named Inputs tab . . . . . . . . . . .
Named Outputs tab . . . . . . . . . .
Stylesheet Parameters tab . . . . . . . .
Processing Metadata . . . . . . . . . . .
Main tab . . . . . . . . . . . . . .
Metadata Items tab . . . . . . . . . .
Defining Processing Policy objects . . . . . .
Policy Maps tab . . . . . . . . . . .
Defining Processing Rule objects . . . . . . .
RADIUS Settings . . . . . . . . . . . .
NAS-identifier . . . . . . . . . . . .
Configuring RADIUS Settings . . . . . . .
Schema Exception Map . . . . . . . . . .
Rules tab . . . . . . . . . . . . . .
Service level monitors . . . . . . . . . .
Creating an SLM policy . . . . . . . . .
Creating an SLM credentials class . . . . .
Creating an SLM resource class . . . . . .
Defining an SLM action . . . . . . . . .
Defining an SLM schedule . . . . . . . .
Defining peer groups . . . . . . . . . .
SOAP Header Disposition Table . . . . . . .
SOAP Header Refine Instruction tab. . . . .
SQL Data Source . . . . . . . . . . . .
High-level configuration. . . . . . . . .
Defining the base configuration . . . . . .
Adding configuration parameters. . . . . .
TIBCO EMS servers . . . . . . . . . . .
Using map message . . . . . . . . . .
Transactional messaging . . . . . . . . .

270
271
271
273
275
275
276
278

283
286
286
287
287
289
294
295
296
297
298
298
298
304
304
305
305
306
314
314
314
314
315
315
316
316
317
318
318
319
319
320
320
321
322
323
324
324
324
325
325
326
327
327
327
328
328
331

Contents

281
282
282

High-level configuration. . . . . . .
Configuring as a unique host . . . . .
Configuring for fault-tolerance . . . .
Configuring for load-balancing . . . .
Configuring for load-balancing and
fault-tolerance . . . . . . . . . .
Enabling heartbeat detection . . . . .
URL Rewrite Policy . . . . . . . . .
Creating a URL Rewrite Policy . . . .
User Agent . . . . . . . . . . . .
Creating a user agent. . . . . . . .
Modifying the basic configuration . . .
Adding an HTTP proxy policy . . . .
Adding an SSL proxy policy . . . . .
Adding a basic authentication policy . .
Adding a SOAP action policy . . . . .
Adding a public key authentication policy.
Adding a compression policy . . . . .
Adding a header retention policy. . . .
Adding an HTTP 1.0 restriction policy . .
Adding a header injection policy . . . .
Adding a chunked upload policy. . . .
Adding an FTP client policy . . . . .
WebSphere JMS servers . . . . . . . .
Transactional messaging . . . . . . .
Configuring a WebSphere JMS server . .
XML Manager . . . . . . . . . . .
Configure XML Manager objects . . . .
Flushing the document cache . . . . .
Flushing the stylesheet cache . . . . .
z/OS NSS Client . . . . . . . . . .
Creating the z/OS NSS Client . . . . .

.
.
.
.

.
.
.
.

334
334
335
337

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

339
342
342
343
345
346
347
347
348
348
349
349
350
350
351
351
351
352
353
353
356
360
361
362
362
362
363

Kerberos AP-REQ tokens . . . .

SAML assertions . . . . . . .
Signature confirmation . . . . . .
Generating a signature confirmation .
Verifying a signature confirmation .

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

Appendix C. Working with variables

.
.
.
.
.

367
367
367
368
368

369

Service variables . . . . . . . . . . . .
General service variables . . . . . . . .
Multi-Protocol Gateway and Web Service Proxy
service variables . . . . . . . . . . .
Configuration services service variables . . .
Load balancer service variables . . . . . .
Legacy MQ-specific service variables . . . .
Multistep variables . . . . . . . . . .
Transaction variables . . . . . . . . . . .
Asynchronous transaction variables . . . . .
Error handling transaction variables . . . . .
Headers transaction variables . . . . . . .
Persistent connection transaction variables. . .
Routing transaction variables . . . . . . .
URL-based transaction variables . . . . . .
Web Services Management transaction variables
Extension variables . . . . . . . . . . .
System variables . . . . . . . . . . . .
List of available variables . . . . . . . . .

370
370
370
371
372
372
373
374
374
375
376
376
377
377
378
378
380
381

Appendix D. Getting help and

technical assistance . . . . . . . . 383
Searching knowledge bases .
Getting a fix . . . . . .
Contacting IBM Support. .

.
.
.

.
.
.

.
.
.

.
.
.

.
.
.

.
.
.

.
.
.

. 383
. 383
. 384

Appendix B. Cryptographic support in

actions . . . . . . . . . . . . . . 365

Notices and trademarks . . . . . . . 385

ID references . . . .
EncryptedData tokens .
Security token references
X.509 certificates . .

Index . . . . . . . . . . . . . . . 387

vi

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

365
365
366
366

Trademarks .

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

. 385

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, Introduction, on page 1
Provides introductory information about the Multi-Protocol Gateway service on
a DataPower appliance.
v Accessing the WebGUI on page 7
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 3, Securing communication, on page 15
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 4, Multi-Protocol Gateway configuration, on page 31
Provide detailed information about developing Multi-Protocol Gateway services
on a DataPower appliance.
v Chapter 5, Handler configuration, on page 47
Copyright IBM Corp. 2002, 2009

vii

Provides information about configuring handler objects to manage incoming

traffic to the appliance.
v Chapter 6, Processing policies, on page 81
Provides information about creating document processing policies.
v Chapter 7, AAA Policy configuration, on page 153
Provides information about creating an AAA policy for a processing action.
v Chapter 8, Managing files, on page 187
Provides information about managing files on the appliance.
v Chapter 9, Managing the configuration of the appliance, on page 195
Provide information about managing the configuration of application domains
and importing and exporting configurations.
v Chapter 10, Managing monitors, on page 211
Providing information about managing monitors.
v Appendix A, Referenced objects, on page 225
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 365
Provides information about cryptographic support in processing actions.
v Appendix C, Working with variables, on page 369
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
You can access and download documents in the DataPower library from the IBM
WebSphere DataPower Product Documentation Portal. These details are discussed
in technical flash 1377654.
http://www.ibm.com/support/docview.wss?rs=2362&uid=swg21377654

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.

viii

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

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
Provides instructions for upgrading Generation 2 firmware and for rolling back
firmware upgrades.

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 XML Integration Appliance XI50: 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 XML Integration Appliance XI50: XSL Accelerator
Developers Guide
Provides instructions for using the WebGUI to configure XSL Proxy and XSL
Coprocessor services.
v IBM WebSphere DataPower XML Integration Appliance XI50: XML Firewall
Developers Guide
Provides instructions for using the WebGUI to configure XML Firewall services.
v IBM WebSphere DataPower XML Integration Appliance XI50: Web Application
Firewall Developers Guide
Provides instructions for using the WebGUI to configure Web Application
Firewall services.
v IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway
Developers Guide
Provides instructions for using the WebGUI to configure Multiple-Protocol
Gateway services.
v IBM WebSphere DataPower XML Integration Appliance XI50: Web Service Proxy
Developers Guide
Provides instructions for using the WebGUI to configure Web Service Proxy
services.

Reference documentation
v IBM WebSphere DataPower XML Integration Appliance XI50: Command Reference
Product-specific documentation for using commands from the command line.
The documentation provides an alphabetic list of all commands with syntax and
functional descriptions.
v IBM WebSphere DataPower SOA Appliances: Extension Elements and Functions
Catalog

Preface

ix

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 Tivoli Composite Application Management for SOA
Provides concepts for integrating the DataPower appliance with IBM Tivoli
Composite Application Management for SOA.
v IBM WebSphere DataPower SOA Appliances: Integrating with Tivoli Security Policy
Manager
Provides detailed information about integrating the DataPower appliance with
IBM Tivoli Security Policy Manager.
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.
v IBM WebSphere DataPower SOA Appliances: Integrating with WebSphere
Transformation Extender
Provides detailed information about integrating the DataPower appliance with
WebSphere Transformer Extender.

Problem determination documentation

v IBM WebSphere DataPower SOA Appliances: Message Reference
Provides the list of messages and event codes by message identifier.
v IBM WebSphere DataPower SOA Appliances: Problem Determination Guide
Provides troubleshooting and debugging tools.

Supplemental documentation
v Converting between JSON and JSONx
Provides information about and procedures for converting between JavaScript
Object Notation (JSON) and JSONx. JSONx is the JSON as XML.
v Configuring DoD PKI
Provides conceptual information about and procedures for configuring the
DataPower appliance with Department of Defense (DoD) Public Key
Infrastructure (PKI).
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 Understanding LTPA
Provides conceptual information about how the DataPower appliance can use
Lightweight Third Party Authentication (LTPA).
v Understanding SPNEGO
Provides conceptual information about how the DataPower appliance can use
Simple and Protected GSSAPI Negotiation Mechanism (SPNEGO). SPNEGO is
also referred to as Integrated Windows Authentication.
v Understanding Web Services Policy

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

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.

External resources
Beyond the online help, no other informational resource is available on the
appliance. You can access the following external resources if a problem occurs or if
you need help.
DataPower Product Documentation Portal
You can access and download documents in the DataPower library using
the details in technical flash 1377654.
http://www.ibm.com/support/docview.wss?rs=2362
&uid=swg21377654
DataPower product Web site
http://www.ibm.com/software/integration/datapower
This Web site provides information about the appliances in the DataPower
portfolio. From this page, you can access the product library, news, and
support areas. The Support link, in particular, has important flash notes
plus a wealth of pointers to Redbooks, frequently asked questions, and
troubleshooting information.
An important link of this page on the DataPower Support page is
Firmware and documentation download. From this page, you can access
and download updated documentation and firmware images for your
particular appliance. This page also provides directions for getting
assistance from IBM Support.
Redbooks Web site
http://www.redbooks.ibm.com
This Web site provides a search field where you can query for documents
that are related to DataPower products. A query against the term
DataPower yields a number of resources in the Redbooks series. These
documents relate to integrating DataPower products with other products in
the IBM ESB portfolio.
developerWorks
http://www.ibm.com/developerworks
This Web site yields an extensive list of articles about DataPower products.
DataPower discussion forum
http://www.ibm.com/developerworks/forums/forum.jspa?forumID=1198
This forum is the only discussion area that is officially sanctioned by IBM.
In this forum, you can find members from the IBM technical community
(technical sales, engineering, support, and field consultants) to answer
questions on a continual basis. This forum is not formal product support.
Answers to the questions that you post to this forum are on an ad-hoc
basis.

Preface

xi

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
v
v
v
v
v

a
A
0
_
.

through z
through Z
through 9
(underscore)
(dash)
(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
v
v
v
v

a
A
0
_
-

through z
through Z
through 9
(underscore)
(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.

xii

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

Chapter 1. Introduction
The Multi-Protocol Gateway is a powerful and versatile service. In additional to
threat protection and multistep processing capabilities, the Multi-Protocol Gateway
can process requests between various protocols. The supported protocols are HTTP,
HTTPS, WebSphere MQ, WebSphere JMS, IMS, FTP, NFS, SFTP, and TIBCO EMS.
The Multi-Protocol Gateway receives incoming requests, processes them with a
processing policy, and forwards the request to the remote server. The
Multi-Protocol Gateway processes the response similarly, applying the applicable
response rule, if configured.
The Multi-Protocol Gateway uses front-side handlers to manage client connections.
A single Multi-Protocol Gateway can have multiple front-side handlers that listen
or poll for requests. The ability of configuring multiple front-side handlers allows a
Multi-Protocol Gateway to receive requests from different protocols. For example, a
Multi-Protocol Gateway can have one front-side handler listening for HTTP
requests and another handler polling a WebSphere MQ queue for messages. Both
front-side handlers forward the incoming message to the Multi-Protocol Gateway
for processing and forwarding to the remote server.
All of the available protocols on which the Multi-Protocol Gateway can receive
incoming requests can also be used on the server-side to forward the request to its
destination. The client-side protocol does not need to match the server-side
protocol.
A Multi-Protocol Gateway service offers many of the same services and capabilities
as a Web Service Proxy service. Unlike a Web Service Proxy service, a
Multi-Protocol Gateway service cannot use a WSDL to determine a configuration.

Support for Web 2.0 configurations

DataPower appliances allow you to use a Representational State Transfer (REST)
architectural style for message processing and transformation including protocol
bridging. You can transform your messages payloads between formats, such as
SOAP, XML, and JSON. With these new processing capabilities, you can
v Match on and manipulate HTTP methods to interact with RESTful services
v Bridge between a Web 2.0 faade and existing applications
v Convert the representation of data from JSON to JSONx (XML)

REST principals in Web 2.0

REST is a Web programming architectural style that uses the HTTP specifications
(RFC 2616) to simplify the development and hosting of Web services and their
clients. RESTful programming manipulates media content of a resource through a
generic interface. With a generic interface, you can access or alter the content of a
resource or URI with the following HTTP methods (verbs):
GET

Retrieves a resource

POST Creates a resource

PUT

Copyright IBM Corp. 2002, 2009

Modifies or creates a resource

DELETE
Removes an existing resource
HEAD
Retrieves metadata
With these HTTP methods and your DataPower appliance, you can write
processing policies that are common to RESTful services by using the HTTP
methods shown in Table 1.
Table 1. Processing actions available with HTTP methods
Processing actions

Description

Fetch

Allows you to specify an HTTP method and

payload with a request

Results
Results asynchronous
Log
Method rewrite

Allows you to rewrite an HTTP method to

transform requests and responses.

If you send requests that do not contain a payload and you want to apply
processing rules, you must enable force the DataPower service to process messages
with the Processing Messages Whose Body Is Empty property. By default a
DataPower service passes requests without a payload directly to the client without
applying any processing rule.

REST proxy deployment scenario

You can use a DataPower appliance as a proxy to provide centralized monitoring
and traffic management. When used as a proxy, the DataPower appliance
intercepts all requests that a client sends to the application server. The DataPower
appliance forwards the request directly to the application server or sends the
request to another server for auditing or accounting purposes. Typically, there is
little message transformation.
Client

Application server

DataPower appliance

Response A (6)

Response A (5)

Response B (3)

Request A (4)

Request B (2)

Request A (1)

Accounting
services

Figure 1. DataPower appliance as a proxy

Message flow
Figure 1 shows a typical proxy implementation.
1. The client sends a Request A (1) to the DataPower appliance.

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

2. The DataPower appliance receives Request A (1) and sends a Request B (2) to a
RESTful accounting Web service.
3. The Accounting Services receive Request B (2) and sends a Response B (3) back
to the DataPower appliance.
4. The DataPower appliance forwards the Request A (4) to the application server.
5. The application server receives the Request A (4) and sends a Response A (5) to
DataPower appliance.
6. The DataPower appliance forwards Response A (6) to the client.

Implementation details
There are many ways to implement a proxy with a RESTful service for your
DataPower appliance. One way to implement a proxy, as shown in Figure 1 on
page 2, would be to:
1.
2.
3.
4.

Configure your service

Configure a processing policy with a results or fetch action.
Change the HTTP Method to support your Accounting Service
Add a remote Web service IP address and port.

REST bridge deployment scenario

You can use a DataPower appliance as a bridge to transform messages and
protocols from one format to another. Figure 2 illustrates a bridge scenario. For
example, a client sends requests in plain old XML (POX) but the application server
uses a SOAP protocol. You can specify a processing policy that transforms a
request into a protocol or message format that the application server understands.
REST client

Application server

DataPower appliance
1

Request A (POX)

Request A (SOAP)

Response A (POX)

Response A (SOAP)

SOAP
Web service

Figure 2. A DataPower appliance as a bridge

Message flow
Figure 2 shows a typical proxy implementation.
1. A RESTful client sends Request A (POX) to a SOAP Web service on an
application server.
2. The DataPower appliance receives Request A (POX) and transforms it to SOAP
using a transform action.
3. In addition, a URL rewrite policy and SOAPAction HTTP header can be used to
transform the message Request A 1 (SOAP).
4. The Web service on the application server receives Request A1 (SOAP) and
sends a Response A1 (SOAP) to the DataPower appliance.
5. The DataPower appliance transforms Response A1 (SOAP) to Response A (POX)
using a transform action.
6. The DataPower appliance forwards Response A (POX) to the client.

Chapter 1. Introduction

Implementation details
There are many ways to implement a bridge scenario. One way to implement the
bridge scenario, as shown in Figure 2 on page 3, would be to:
1. Configure your service with a HTTP front side handler.
2. Choose the appropriate HTTP methods for your front side handler.
3. Define your request type.
4. Configure your processing policy data conversion such as converting Plain Old
XML (POX) to SOAP.
5. Add a remote Web service IP address and port.

Web 2.0 and JSON

A DataPower appliance can transform JSON to JSONx or JSONx to JSON. JSONx is
an IBM standard format used to represent JSON as XML. A DataPower appliance
uses a parser to convert a JSON payload to XML (JSONx). You have the option of
using the jsonx2json.xsl built-in stylesheet to transform JSONx to JSON. In
addition, you can validate JSONx using the jsonx.xsd built-in schema.
To transform a JSON payload to JSONx, you must use the convert-http processing
action. When you add an input conversion map to the processing action, you must
select JSON as the default input encoding for the DataPower service.

JSON deployment scenario

A DataPower appliance can act as a bridge between an AJAX client and a SOAP
Web service. In Figure 3, a DataPower appliance transforms requests and responses
from JSON to SOAP and SOAP to JSON acting as a bridge between an AJAX client
and the SOAP application server.
AJAX client

Application server

DataPower Appliance
1

Request A (JSON)

Request A (SOAP)

Response A (JSON)

Response A1 (SOAP)

SOAP
Web service

Figure 3. A DataPower appliance using JSON and JSONx

Message flow
Figure 3 shows a typical data transformation implementation.
1. The AJAX client sends a Request A (JSON) to a SOAP Web service on an
application server.
2. The DataPower appliance receives the Request A (JSON) and transforms
Request A from JSON to JSONx to SOAP.
3. The DataPower appliance forwards the transformed Request A1 (SOAP) to the
SOAP Web service.
4. The Web service receives the Request A1 (SOAP) and sends a Response A1
(SOAP) to the DataPower appliance.
5. The DataPower appliance receives and transforms Response A1 (SOAP) to
JSONx to JSON and forwards the transformed Response A (JSON) to the AJAX
client.

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

Implementation details
There are many ways to implement JSON to JSONx data transformations. One way
to implement the JSON scenario, as shown in Figure 3 on page 4, would be to:
1. Configure your service with an HTTP front side handler
2. Configure the processing policy with a convert to XML action that specifies
JSON as the default encoding.
3. Configure a transform action to convert JSONx to SOAP
4. Add a remote Web service IP address and port.

Chapter 1. Introduction

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

Chapter 2. 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

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 4 illustrates this
type of input field.

Input

Figure 4. 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.

IBM WebSphere DataPower XML Integration Appliance XI50: 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 5 illustrates this type
of input list.

Input

Delete

Add

Figure 5. 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 2. WebGUI basics

Viewing local files

To
1.
2.
3.

view a local file, use the following procedure:

Select the file from the lists.
Click View to open the file editor in view mode.
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.
2.
3.
4.
5.

Select the file from the lists.

Click Edit to open the file editor in edit mode.
Edit the file as required.
Click Submit to save changes.
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
v
v
v
v
v

Deleting an object
Exporting the configuration of an object
Viewing configuration-specific messages of an object
Viewing status of an object
Cloning a service
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.

10

IBM WebSphere DataPower XML Integration Appliance XI50: 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 configuration-specific messages

While developing an object or service, the configuration might be invalid. To help
determine why an object is in the down operational state, you can view
configuration messages for a specific object.
This approach is easier than filtering a configured log target.

Viewing messages from the catalog

To view configuration-specific messages from the catalog:
1. Display the catalog for the object. The catalog lists the available instances of
this object.
2. Click the magnifying glass icon.

Viewing messages from the configuration pane

To view configuration-specific messages from the configuration pane:
Chapter 2. WebGUI basics

11

1. Display the catalog for the object. The catalog lists the available instances of
this object.
2. Click the name of the instance.
3. Click View Logs.

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 operational 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.
3.
4.
5.

Click the name of the service to clone to display the configuration screen.
Click Clone.
When the screen refreshes, specify the name of the clone.
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 changes to the running configuration.

12

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

9. Optional: Click Save Config to save the changes to the startup configuration.

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 2. WebGUI basics

13

14

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

Chapter 3. Securing communication

You can secure communication to and from the DataPower appliance through a
combination of utilities and objects provided by the appliance.

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).
4. VeriSign returns the signed certificate.
Copyright IBM Corp. 2002, 2009

15

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.

3.
4.

5.
6.
7.

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.
Select a key length from the RSA Key Length list. This defaults to 1024.
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.
Specify the number of days that the key is valid in the Validity Period field.
Specify a password to access the key file in the Password field. The password
must be at least 6 characters in length.
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.

16

on

Writes the key file to the temporary: directory.

off

(Default) Does not write the key file to the temporary: directory.

IBM WebSphere DataPower XML Integration Appliance XI50: 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:///samplesscert.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 3. Securing communication

17

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.

18

IBM WebSphere DataPower XML Integration Appliance XI50: 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.

Working with 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.

Working with z/OS certificates

DataPower appliances can use the secure certificate storage and services that
z/OS NSS provides. This capability allows you to create certificate objects using
certificates retrieved from z/OS. A certificate retrieved from z/OS is used the same
way a local certificate is used to perform encryption and signature verification.
To create certificate objects, the DataPower appliance communicates with z/OS
using a z/OS NSS client object. The z/OS NSS client object must be defined and in
the up operational state when you create certificate objects that use z/OS
certificates. The retrieved z/OS certificate remains local on the appliance until the
associated application domain or the appliance is restarted. For more information
about the z/OS NSS client object, see z/OS NSS Client on page 362.
To access and use z/OS certificates, the z/OS NSS client object on DataPower must
have permission to access the z/OS certificate. See your z/OS documentation for
more information on these settings.

Defining Certificate objects

To create and configure a Certificate, use the following procedure:
1. Select Objects Crypto Configuration Crypto Certificate.
2. Click Add to display the configuration pane.
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
Specify the local certificate file or the remote z/OS certificate file.
For a local certificate file, 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.
v Click Upload or Fetch to transfer the file.
Chapter 3. Securing communication

19

v Click Details to display information about the selected certificate file.

For a remote z/OS certificate file, specify the location and the file
name.
v Select saf-cert:// from the File Name list.
v Specify the file name using the following format:
nssclient/ZOSCERTLABEL

nssclient
Specifies an existing NSS client object.
ZOSCERTLABEL
Specifies the label name of an existing SAF certificate
residing on the z/OS system.
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.
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

20

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

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 changes to the running configuration.
5. Optional: Click Save Config to save the changes to the startup configuration.

Defining Firewall Credentials objects

A Firewall Credentials object consists of a list of Key and Certificate objects.
Certificates and keys that are not referenced in the Firewall Credentials object are
unavailable. If no Firewall Credentials object exists, all keys and certificates that are
stored locally are available.
To create a Firewall Credentials object, use the following procedure:
1. Click Objects Crypto Configuration Crypto Firewall Credentials.
2. Click Add to display the configuration pane.
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
Select Key objects to add. Refer to Defining Key objects on page 23
for more information.
Shared Secret Key
Select Shared Secret Key objects to add. Refer to Defining shared
secret keys on page 26 for more information.
Certificates
Select Certificate objects to add. Refer to Defining Certificate objects
on page 19 for more information.
4. Click Apply to save the changes to the running configuration.
5. Optional: Click Save Config to save the changes to the startup configuration.

Defining Identification Credentials objects

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

create an Identification Credentials object, use the following procedure:

Select Objects Crypto Configuration Crypto Identification Credentials.
Click Add to display the configuration pane.
Provide the following inputs:
Name Specify the name of the object.
Chapter 3. Securing communication

21

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 23
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 19 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 changes to the running configuration.
5. Optional: Click Save Config to save the changes to the startup configuration.

Working with 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 or Identification
Credentials object.

Working with z/OS keys

DataPower appliances can use the secure private key storage and services that
z/OS NSS provides. This capability allows you to access private keys on z/OS and
to perform the following operations:
v Retrieve private keys from z/OS
v
v
v
v

Create key objects using retrieved keys

Create key objects using remote keys that are stored on z/OS
Submit requests to z/OS to decrypt data using a certificates private key
Submit requests to z/OS to generate a digital signature using a certificates
private key

Use a key object created with a private key that is retrieved from z/OS the same
way you use a key object created with a local private key. Use a key object created
with a private key that is stored on z/OS to make requests for decryption or
signature generation on the z/OS system.
To create key objects, the DataPower appliance communicates with z/OS using a
z/OS NSS client object. The z/OS NSS client object must be defined and in the up
operational state when you create key objects.

22

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

To use a retrieved z/OS key, the key must be a SAF key that is not stored in ICSF.
The SAF key is cached locally on the appliance until the associated application
domain or the appliance is restarted.
To use a remote z/OS key, the key must be a SAF key that is stored in ICSF. The
SAF key is never taken off of your z/OS system. Therefore, the z/OS NSS client
object must be in the up operational state when using remote key objects. For more
information about the z/OS NSS client object, see z/OS NSS Client on page 362.
To access and use z/OS keys, the z/OS NSS client object on DataPower must have
permission to access the z/OS keys. See your z/OS documentation for more
information on these settings.

Defining Key objects

To create and configure a Key object, use the following procedure:
1. Select Objects Crypto Configuration Crypto Key.
2. Click Add to display the configuration pane.
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
Specify the local private key file or the remote z/OS private key file.
For a local key file, 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. 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
Uploading files from the workstation on page 190 for more
information.
For a remote z/OS key file, specify the location and the file name.
v Select saf-key:// or saf-remote-key:// from the File Name list.
v Specify the file name using the following format:
nssclient/ZOSKEYLABEL

nssclient
Specifies an existing NSS client object.
ZOSKEYLABEL
Specifies the label name of an existing SAF key residing on the
z/OS system. A saf-key:// must be a SAF key that is not stored
in ICSF. A saf-remote-key:// must be a SAF key that is stored in
ICSF.
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.
Chapter 3. Securing communication

23

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 changes to the running configuration.

5. Optional: Click Save Config to save the changes to the startup configuration.

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 21 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
Validation credentials on page 28 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

24

Includes all cipher suites, except the eNULL ciphers.

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

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.
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 changes to the running configuration.
5. Optional: Click Save Config to save the changes to the startup configuration.

Chapter 3. Securing communication

25

Defining shared secret keys

A shared secret key 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. A shared secret key uses a text file that contain the key
material to perform cryptographic operations.
To create a shared secret key:
1. Click Objects Crypto Configuration Crypto Shared Secret Key.
2. Click Add.
3. In the Name field, enter the name for the object.
4. Retain the default setting for Admin State. To place in an inactive
administrative state, click disabled.
5. From the File Name list, select the file that contains the key material.
6. Click Apply to save the changes to the running configuration.
7. Optional: Click Save Config to save the changes to the startup configuration.

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. In the Name field, enter the name for the object.
4. Retain the default setting for Admin State. To place 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 changes to the running configuration.
9. Optional: Click Save Config to save the changes to the startup configuration.

26

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

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. In the Name field, enter the name for the object.
4. Retain the default setting for Admin State. To place in an inactive
administrative state, click disabled.
5. Select Reverse from the SSL Direction list.
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 changes to the running configuration.

13. Optional: Click Save Config to save the changes 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. In the Name field, enter the name for the object.
4. Retain the default setting for Admin State. To place 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.

Chapter 3. Securing communication

27

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.

(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.
off

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 changes to the running configuration.

15. Optional: Click Save Config to save the changes to the startup configuration.

Validation credentials
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
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.

28

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

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.
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.
Chapter 3. Securing communication

29

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.
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.

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.
off

30

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

Chapter 4. Multi-Protocol Gateway configuration

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 back-end 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.

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.

MQ

The service can use GET and PUT queues to communicate with MQ
queues. This protocol requires the MQ license.

NFS

The service can poll an NFS-mounted directory for the presence of new
files and can place responses on an NFS mounted directory.

SFTP

The service can act as an SFTP server which allows SFTP clients to post to
and retrieve files from a back-end file system.

Stateful Raw XML

A stateful implementation that allows messages to flow from client to
back-end server and back again using persistent connections.
Stateless Raw XML
A stateless implementation that allows messages to flow from client to
back-end server and back again using persistent connections.
TIBCO EMS
Supports TIBCO Enterprise Messaging Service (EMS) messaging. This
protocol requires the TIBCO-EMS license.
WebSphere JMS
Supports the WebSphere JMS messaging. This protocol requires the
WebSphere-JMS license.
A Multi-Protocol Gateway service can support more than one client, or front side,
protocol. Similarly, the service can support more than one back-end, or server,
protocol.
Figure 6 on page 32 provides an illustration of the static back-end architecture that
the service supports.

Copyright IBM Corp. 2002, 2009

31

HTTP
HTTPS
MQ
Multi-Protocol Gateway

HTTP or
HTTPS or
MQ

Back End Server

Figure 6. Static back-end 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 back-end 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 back-end service that also
employs the same protocol. Figure 7 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 7. Dynamic back-end 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 service

To create a Multi-Protocol Gateway:
1. Click the Multi-Protocol Gateway icon from the Control Panel to display the
catalog.
2. Click Add to display the configuration pane.
3. On the General tab, configure the basic settings.
4. Optional: On the Advanced tab, modify networking and cryptographic
behavior.
5. Optional: On the Stylesheet Params tab, configure processing parameters.
6. Optional: On the Headers tab, configure header and parameter settings. These
settings include adding header injection parameters, adding header
suppression parameters, and defining stylesheet parameters.
7. Optional: On the Monitors tab, configure monitors.
8. Optional: On the WS-Addressing tab, configure the mediation for Web
Services Addressing. WS-Addressing mediation is between the requesting
clients and the responding server.

32

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

9. Optional: On the WS-ReliableMessaging tab, configure for Web Services

Reliable Messaging.
10. Optional: On the XML Threat Protection tab, configure XML threat protection.
11. Click Apply to save the changes to the running configuration.
12. Optional: Click Save Config to save the changes to the startup configuration.

Available properties
This section provides details about the fields available:
v General
v Advanced
v Style sheet parameters
v Headers
v Monitors
v Web Services Addressing
v Web Services Reliable Messaging
Table 2. Properties available on the General tab
Name

Purpose

Multi-Protocol Gateway
Name

Specify the gateway name.

Summary

Optional: Specify a brief description.

Type

Select the gateway type.

XML Manager

Assigns an instance of the XML Manager object. Refer to

XML Manager on page 360

Multi-Protocol Gateway
Policy

Assigns a processing policy. Refer to Chapter 6, Processing

policies, on page 81 for information about creating or
editing processing policies.

URL Rewrite Policy

Optional: Assigns a URL rewrite policy. Refer to URL

Rewrite Policy on page 342.

Backend URL

Specifies the URL of the static, remote server. To use a load

balancer, specify the name of an existing Load Balancer
Group object.

Front Side Protocol

Assigns one or more handlers. Refer to Chapter 5, Handler

configuration, on page 47.

SSL Client Crypto Profile

Optional: Assigns an instance of SSL Crypto Profile.

Response Type

Characterizes the server-generated response.

Flow Control

Specifies the flow control behavior.

Back Attachment processing

format

Specifies the attachment format.

Back Side Timeout

Specifies the number of seconds that a connection with a

server can remain idle.

Stream Output to Back

Specifies the streaming behavior.

HTTP Version to Server

Specifies the HTTP protocol version for server-side

connections.

Propagate URI

Indicates the URI propagation behavior.

Compression

Controls GZIP compression negotiation with the remote

server.

Chapter 4. Multi-Protocol Gateway configuration

33

Table 2. Properties available on the General tab (continued)

Name

Purpose

Request Type

Characterizes the client-generated request.

Front attachment processing

format

Specifies the attachment format.

Front Side Timeout

Specifies the number of seconds that a connection with a

client can remain idle.

Stream Output to Front

Specifies the streaming behavior.

Table 3. Properties available on the Advanced tab

Name

Purpose

Persistent Connections

Optional: Controls HTTP persistent connections.

Loop Detection

Optional: Controls loop-detection between hosts with the

Via: header field.

Follow Redirects

Optional: Controls server-side redirects (such as HTTP 302).

Allow Chunked Uploads

Optional: Controls the ability to send content-type,

chunked-encoded documents.

Process Backend Errors

Optional: Controls the processing of errors from the remote

server.

Front Persistent Connection

Timeout

Optional: Specifies the number of seconds that a persistent

connection can remain idle on the client side before the
service closes the connection.

Back Persistent Connection

Timeout

Optional: Specifies the number of seconds that a persistent

connection can remain idle on the server side before the
service closes the connection.

MIME Back Header

Processing

Optional: Controls support for MIME (Multi-Purpose

Internet Mail Extensions) header processing on the server
side.

MIME Front Header

Processing

Optional: Controls support for MIME header processing on

the client side.

Gateway Credentials

Optional: Assigns a Firewall Credentials object. Refer to

Defining Firewall Credentials objects on page 21.

Default parameter
namespace

Optional: Specifies the default XML namespace for

parameters.

Query parameter namespace

Optional: Specifies the default XML namespace for

parameters made available via a URL query string.

SOAP Schema URL

Optional: Specifies the full URL to the schema to validate

the SOAP schema for SOAP-formatted messages.

Message Processing Modes

Optional: Identifies one or more modes for message

processing.

Process Message Whose

Body is Empty

Optional: Whether to force the processing of XML messages

when their message body is empty or missing in RESTful
Web services.

Table 4. Properties available on the Stylesheet Params tab

34

Name

Purpose

Parameter Name

Specifies the name of a common parameter used by the

supplied style sheets for cryptographic processing.

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

Table 4. Properties available on the Stylesheet Params tab (continued)

Name

Purpose

Custom Name

Specifies the name of an unlisted parameter.

Parameter Value

Specifies the value for the parameter.

Table 5. Properties available on the Headers tab for header injection

Name

Purpose

Direction

Indicates the direction of the message.

Header Name

Specifies the name of the header to inject.

Header Name

Specifies the value for the header.

Table 6. Properties available on the Monitors tab

Name

Purpose

Message Count Monitor

Assigns count monitors. Refer to Configuring count

monitors on page 216.

Message Duration Monitor

Assigns duration monitors. Refer to Configuring duration

monitors on page 218.

Gateway Service Level

Monitor

Assigns Web service monitors. Refer to Configuring Web

services monitors on page 220.

Monitors Evaluation Method Indicates how monitors interact with each other when the
service uses more than one monitor.
Table 7. Properties available on the WS-Addressing tab
Name

Purpose

WS-Addressing Mode

Specifies the mode of WS-Addressing.

Strip WS-Addressing
Headers

Controls whether to remove all WS-Addressing headers

from server-generated responses before forwarding them to
the client.

WS-Addressing Message
Generation Pattern

Specifies the request/response transmission model between

the service and the remote server.

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.

WS-Addressing
Asynchronous Reply Point

Specifies the name of the handler object that receives

asynchronous server responses and forwards responses to
the original client.

WS-Addressing
Asynchronous Reply
Timeout

Specifies the maximum period of time to wait for an

asynchronous response before abandoning the transaction.

Rewrite WS-Addressing
Reply To Header

Specifies the name of the URL Rewrite Policy object to

rewrite the contents of the WS-Addressing ReplyTo header.

Rewrite WS-Addressing
Fault To Header

Specifies the name of the URL Rewrite Policy object to

rewrite the contents of the WS-Addressing FaultTo header.

Rewrite WS-Addressing To
Header

Specifies the name of the URL Rewrite Policy object to

rewrite the contents of the WS-Addressing To header.

Default WS-Addressing
Reply-To

Forces the inclusion of the optional ReplyTo header in

WS-Addressing messages.

Chapter 4. Multi-Protocol Gateway configuration

35

Table 7. Properties available on the WS-Addressing tab (continued)

Name

Purpose

Default WS-Addressing
Fault-To

Forces the inclusion of the optional FaultTo header in

WS-Addressing messages.

Force Incoming
WS-Addressing

Forces the inclusion of WS-Addressing headers into

server-originated traditionally addressed messages.

Table 8. Properties available on the WS-ReliableMessaging tab

Name

Purpose

Use WS-ReliableMessaging

Indicates whether to use Web Services Reliable Messaging

Target Sequence Expiration

Interval

Sets the target expiration lifetime in seconds for all Reliable

Messaging sequences.

AAA Policy

Specifies the name of an AAA Policy object 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.

SSL session binding

Indicates whether to use an SSL session binding to protect

sequence lifecycle messages.

Destination Accept Incoming Indicates whether to accept incoming CreateSequence

CreateSequence
SOAP requests and create a Reliable Messaging destination
when one is received.
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.

Destination InOrder
Delivery Assurance

Indicates whether to enable InOrder delivery assurance for

Reliable Messaging destinations in addition to the standard
ExactlyOnce delivery assurance.

Destination Accept Two-Way Indicates whether to accept offers for two-way Reliable
Offers
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.

36

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.

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.

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.

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

Table 8. Properties available on the WS-ReliableMessaging tab (continued)

Name

Purpose

Source Create Sequence on

Response

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.

Source Front Reply Point

Specifies the name of the handler object that receives the

asynchronous Reliable Messaging SequenceAcknowledgement
SOAP responses from the client. This handler must be
associated with the same DataPower service where the
corresponding Reliable Messaging sequence is occurring.

Source Back AcksTo Reply

Point

Specifies the name of the handler object that receives the

asynchronous Reliable Messaging SequenceAcknowledgement
SOAP responses from the server. This handler must be
associated with the same DataPower service where the
corresponding Reliable Messaging sequence is occurring.

Source Maximum
Simultaneous Sequences

Specifies 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.

XML threat protection

Using a coordinated set of configurations, you can maximize protection against
XML threats. Threats are malicious attempts to disrupt service. The DataPower
service provides the ability to protect against the following XML threats:
v Single message XML Denial-of-Service (XDoS)
v Multiple message XML Denial-of-Service (MMXDoS)
v
v
v
v
To
1.
2.
3.
4.

Message tampering
SQL injections
XML viruses (X-Virus)
Dictionary attacks
protect against XML threats, perform the following steps:
Click the XML Threat Protection tab.
Defines all of the properties for threat protection, as needed.
Click Apply to save the changes to the running configuration.
Optional: Click Save Config to save the changes to the startup configuration.

Protecting against single message XML denial-of-service

attacks
These settings provide protection against a denial-of-service (DoS) attack when a
single malicious XML message is sent to the service. Many of the parameters that
provide this protection are set in the XML Manager object associated with the
service. This pane offers the opportunity to override the settings in the XML
Manager object with service-level settings.

Chapter 4. Multi-Protocol Gateway configuration

37

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.
XML Maximum Distinct Prefixes
Defines the maximum number of distinct XML namespace prefixes in
a document. This limit counts multiple prefixes defined for the same
namespace, but does not count multiple namespaces defined in
different parts of the input document under a single prefix. A limit of
0 indicates that there is no limit on the number of distinct prefixes.
The default is 0.
XML Maximum Distinct Namespaces
Defines the maximum number of distinct XML namespace URIs in a
document. This limit counts all XML namespaces, regardless of how
many prefixes are used to declare them. A limit of 0 indicates that
there is no limit on the number of distinct namespaces. The default is
0.
XML Maximum Distinct Local Names
Defines the maximum number of distinct XML local names in a
document. This limit counts all local names, independent of the
namespaces they are associated with. A limit of 0 indicates that there
is no limit on the number of distinct local names. The default is 0.
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.

38

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

Protecting against multiple message XML denial-of-service

attacks
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.

Protecting against 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 back-end 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 Adding a validate action
on page 144 for more information.

Protection against SQL injections

To protect against SQL injections, create a filter action and add it to a 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
Chapter 4. Multi-Protocol Gateway configuration

39

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 actions on page 118 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.

40

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

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
Adding an antivirus action on page 88 for more information.

Protecting against dictionary attacks

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 and create an AAA
action. The count monitor must have its Measure property set to xpath.
The AAA action can be added to an existing or new processing policy. When
creating this action, define the following property:
Counter Monitor
Select a count monitor. Refer to Configuring count monitors on page 216
for more information.
Refer to Adding an AAA action on page 88 for more information.

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 42.
v For information about using the utility to build a TIBCO EMS URL, refer to
Building a TIBCO EMS URL on page 43.
v For information about using the utility to build a WebSphere JMS URL, refer to
Building a WebSphere JMS URL on page 44.

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.
Chapter 4. Multi-Protocol Gateway configuration

41

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 back-end URL, the URL of the
response from the back end 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 back end 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. Fom the Queue Manager list, select an existing instance of the MQ Queue
Manager object.
3. In the URI field, specify a string, such as /SomeBank/Services/checking to
include in the URL.
4. In the RequestQueue field, specify the name of a queue that the Queue
Manager manages. The service puts requests on this queue.
5. In the PublishTopicString field, specify a topic string associated with the
identified queue manager. The service publishes requests to this topic string. If
the RequestQueue field is specified, this field is ignored.
6. In the ReplyQueue field, specify the name of a queue that the Queue
Manager manages. The service polls this queue for responses.
7. In the SubscribeTopicString field, specify a topic string. If the ReplyQueue is
specified, this field is ignored.
8. In the SubscriptionName field, specify the name for the durable subscription.
9. 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.
10. Use the User Identifier toggle 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)

42

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

v If disabled (off), the builder does not insert a value. The service assumes
MQPMO_NO_SYNCPOINT only.
11. Use the ReplyToQ toggle 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 ReplyQueue option.
v If disabled (off), the processing policy does not change the value of
ReplyToQ in the MQMD header.
12. 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. From the Server list, select an existing instance of the TIBCO Server object.
3. In the Request Queue field, identify the queue or topic space for the request.

4.

5.
6.
7.

8.

v To specify a queue, use the queue format.

v To specify a topic space, use the topic:topic-space format.
In the Reply Queue field, identify the queue or topic space for the reply.
v To specify a queue, use the queue format.
v To specify a topic space, use the topic:topic-space format.
In the Selector field, specify an SQL 92 conditional expression to identify
messages of interest.
Use the Request Reply Queue toggle to indicate whether to use a temporary
queue for the reply from the server. The default is off.
Use the Transactionality toggle to indicate whether the service enforces
transactional session in the communication. When enabled (on), the builder
inserts Transactional=true in the URL and the service does not consider a
message to be successfully posted until it receives a response. The default is
off.
Click Build.

The utility creates a URL in the following format:

dptibems://server/?RequestQueue=queue&ReplyQueue=queue&
Selector=expression&RequestReply=queue&Transactional=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 or for adding other query parameters.

Chapter 4. Multi-Protocol Gateway configuration

43

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. From the Server list, select an existing instance of the WebSphere JMS object.
3. In the Request Queue field, identify the queue for the request.
4. In the Reply Queue field, identify the queue for the reply.
5. Optional: In the Request Topic Space field, identify a nondefault request topic
space.
6. Optional: In the Response Topic Space field, identify a nondefault reply topic
space.
7. In the Selector field, specify an SQL 92 conditional expression to identify
messages of interest.
8. Optional: In the Timeout field, specify the timeout for the connection.
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. Use the Transactionality toggle to indicate whether the service enforces
transactional session in the communication. When enabled (on), the builder
inserts Transactional=true in the URL and the service does not consider a
message to be successfully posted until it receives a response. The default is
off.
11. 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&Transactional=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 or for adding other query parameters.

Scenario: Defining a load balancer group as the destination

The following scenario explains how to use a Load Balancer Group as the back end
of a DataPower service. This scenario creates new objects and provides information
about only the configuration for load balancing. However, you can modify existing
objects.
1. Create the LBGroup Load Balancer Group object and define Server-1 and
Server-2 as members that reference the actual remote servers.
The configuration of a DataPower service defines the default port on the
remote servers. You can override the port for one or more members with the
Mapped Server Port property.
Refer to Configuring a load balancer group on page 278 for more
information.
2. Create the LBManager XML Manager object and add the LBGroup group to the
Load Balancer Groups list. Refer to Configure XML Manager objects on page
361 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.

44

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

b. Specify LBGroup (the Load Balancer Group) as the address of the back-end
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) (service view).
For complete information about managing Load Balancer Group objects, refer to
Load balancer groups on page 271.

Chapter 4. Multi-Protocol Gateway configuration

45

46

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

Chapter 5. Handler configuration

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.

Configuring an FTP poller 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

47

3. In the Name field, enter the name for the object.

4. Retain the default setting for Admin State. To place in an inactive
administrative state, click disabled.
5. Optional: In the Comment field, enter a descriptive summary.
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.

48

IBM WebSphere DataPower XML Integration Appliance XI50: 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.

(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.
off

on

Deletes the file.

(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.
off

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 5. Handler configuration

49

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. In the Maximum File Transfers Per Poll Cycle field, specify the number of
concurrent connections. Enter a value from 0 to 100. The default value is 0
which means unlimited number of connections based on available system
resources.
16. Click Apply to save the changes to the running configuration.
17. Optional: Click Save Config to save the changes to the startup configuration.

Configuring an FTP server 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.

50

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

Virtual persistent
The FTP server will have a persistent virtual file system with
subdirectories created by configuration. The contents of this file system are
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.
The following options provide control for communications with an FTP client
when there are intervening load balancers or firewalls:
Disable Passive Data Connection (PASV) IP Security Check
When a client requests passive mode through the PASV FTP command, the
FTP server sends a response back to the client with the IP address and port
to which the client must connect to in order to initiate the FTP data
connection. When the FTP server accepts an incoming connection on this
IP address and port, the FTP server performs a security check that verifies
that the incoming data connection comes from the already connected client.
This option disables this security check.
Use Alternate PASV IP Address
In passive mode, the FTP server can advertise an IP address other than the
default FTP server address for client connections. This might be useful
when there is a load balancer in front of the FTP server and the client
cannot directly reach the IP address of the server. Enabling this option
allows you to configure the numeric IP address that is advertised to the
FTP client.
Disable Active Data Connection (PORT) IP Security Check
The FTP server connects to an IP address and port specified by the client
in order to initiate the FTP data connection. When the server is about to
connect to the address, the server performs a security check to verify that
the IP address is the same as the IP address of client that initiated the
control connection. This option disables this security check.
The following option provides controls of FTP server listings when in transparent
mode:
Enable LIST command support
When in transparent mode, the FTP Server service supports two
commands for directory listings: LIST and NLST. The LIST command
provides a listing that includes file attributes. The NLST command only
provides a list of the names of the files in the directory. With this option,
the FTP Server service distinguishes between the two commands. For
backward compatibility, when the option is off, the FTP server makes no
distinction between the commands and always responds to the LIST
command as if it were the NLST command. When enabled, the FTP server
differentiates between the two commands and responds accordingly.
The following option provides the option of deleting files from the FTP server
when in transparent mode:

Chapter 5. Handler configuration

51

Enable delete support

When in transparent mode, you have the option of allowing the deletion of
files on the FTP server. When the option is on, you can delete files on the
FTP server. When the option is off, you cannot delete files on the FTP
server.

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. In the Name field, enter the name for the object.
4. Retain the default setting for Admin State. To place in an inactive
administrative state, click disabled.
5. Optional: In the Comment field, enter a descriptive summary.
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
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

52

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

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.
4) Use the Disable Passive Data Connection (PASV) IP Security Check
toggle to specify whether to disable the IP security check that verifies
that the incoming data connection comes from the already connected
client. The default is off to perform the check.
5) Use the Disable Active Data Connection (PORT) IP Security Check
toggle to specify whether to disable the IP security check that verifies
that outgoing data connections can only connect to the client. The
default is off to perform the check.
6) Define behavior for alternate IP address support.

Chapter 5. Handler configuration

53

a) Select the behavior for alternate IP address support from the Use
Alternate PASV IP Address toggle.
b) If allowing support, use the Alternate PASV IP Address field to
specify the numeric IP address.
c. Use the Enable LIST command support toggle to specify whether the FTP
server distinguishes between the LIST command and the NLST command.
The default is off to respond to either command with an NLST command.
This option only applies to transparent file systems.
d. Use the Enable delete support toggle to specify whether file delete
commands are allowed on the FTP server. The default is off. This option
only applies to transparent file systems.
e. 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.
f. 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.
g. 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. Click Apply to save the changes to the running configuration.
14. Optional: Click Save Config to save the changes 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. In the Name field, enter the name for the object.
4. Retain the default setting for Admin State. To place in an inactive
administrative state, click disabled.
5. Optional: In the Comment field, enter a descriptive summary.
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.

54

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

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.
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.
Chapter 5. Handler configuration

55

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.
4) Use the Disable Passive Data Connection (PASV) IP Security Check
toggle to specify whether to disable the IP security check that verifies
that the incoming data connection comes from the already connected
client. The default is off to perform the check.
5) Use the Disable Active Data Connection (PORT) IP Security Check
toggle to specify whether to disable the IP security check that verifies
that outgoing data connections can only connect to the client. The
default is off to perform the check.
6) Define behavior for alternate IP address support.
a) Select the behavior for alternate IP address support from the Use
Alternate PASV IP Address toggle.
b) If allowing support, use the Alternate PASV IP Address field to
specify the numeric IP address.
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.

56

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

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.
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.
Chapter 5. Handler configuration

57

4) Click Save.
c. Repeat the previous step to define another virtual directory.
15. Click Apply to save the changes to the running configuration.
16. Optional: Click Save Config to save the changes 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. In the Name field, enter the name for the object.
4. Retain the default setting for Admin State. To place in an inactive
administrative state, click disabled.
5. Optional: In the Comment field, enter a descriptive summary.
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 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.

58

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

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.
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.
4) Use the Disable Passive Data Connection (PASV) IP Security Check
toggle to specify whether to disable the IP security check that verifies
Chapter 5. Handler configuration

59

that the incoming data connection comes from the already connected
client. The default is off to perform the check.
5) Use the Disable Active Data Connection (PORT) IP Security Check
toggle to specify whether to disable the IP security check that verifies
that outgoing data connections can only connect to the client. The
default is off to perform the check.
6) Define behavior for alternate IP address support.
a) Select the behavior for alternate IP address support from the Use
Alternate PASV IP Address toggle.
b) If allowing support, use the Alternate PASV IP Address field to
specify the numeric IP address.
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
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.

60

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

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.
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 changes to the running configuration.
16. Optional: Click Save Config to save the changes to the startup configuration.
Chapter 5. Handler configuration

61

Configuring an HTTP 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. In the Name field, enter the name for the object.
4. Retain the default setting for Admin State. To place in an inactive
administrative state, click disabled.
5. Optional: In the Comment field, enter a descriptive summary.
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.
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.

62

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

12. Select the instance of the Access Control List object to apply from the Access
Control List list.
13. Click Apply to save the changes to the running configuration.
14. Optional: Click Save Config to save the changes to the startup configuration.

Configuring an HTTPS 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. In the Name field, enter the name for the object.
4. Retain the default setting for Admin State. To place in an inactive
administrative state, click disabled.
5. Optional: In the Comment field, enter a descriptive summary.
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.
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.

Chapter 5. Handler configuration

63

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.

12.
13.
14.
15.

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.
Select the instance of the SSL Proxy Profile object to assign from the SSL
Proxy list.
Select the instance of the Access Control List object to apply from the Access
Control List list.
Click Apply to save the changes to the running configuration.
Optional: Click Save Config to save the changes to the startup configuration.

Configuring an 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. In the Name field, enter the name for the object.
4. Retain the default setting for Admin State. To place in an inactive
administrative state, click disabled.
5. Optional: In the Comment field, enter a descriptive summary.
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 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.

64

on

Indicates the input headers are in EBCDIC encoding.

off

(Default) Indicates that input headers are in ASCII encoding.

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

11. Select an Access Control List from the Access Control List list.
12. In the Maximum Segment Size field, enter an integer in the range of 0 to 32
to specify the maximum segment size in KB. The default is 0 which disables
segmentation.
v A Maximum Segment Size of 0 disables IMS message segmenting. With
message segmenting disabled, you must use a policy to handle an IMS
message with a segmented payload and with LL and ZZ segment headers.
v A Maximum Segment Size in the range from 1 to 32 enables message
segmenting and specifies the maximum segment size. Request side
processing receives an incoming multi-segment IMS message and strips the
LL and ZZ segment headers to send a message with one continuous payload
to the request side policy. Response side processing splits the message into
multiple segments of the specified size and adds the appropriate LL and ZZ
segment headers after the response side policy processing finishes. The
headers are handled the same for a message with a payload smaller than
the Maximum Segment Size.
Note: The Maximum Segment Size specifies the maximum segment size in
KB into which a message is split when sending to an IMS client. This
does not limit the segment size of a request message. The DataPower
appliance can accept a request message up to a maximum segment
size of 64 KB from an IMS client.
13. Click Apply to save the changes to the running configuration.
14. Optional: Click Save Config to save the changes to the startup configuration.

Configuring a WebSphere MQ 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
For additional information on DataPower integration with WebSphere MQ, see
IBM WebSphere DataPower SOA Appliances: Integrating with WebSphere MQ.
This section provides information about configuring an MQ Front Side Handler.

High-level configuration
To configure an MQ Front Side Handler:
1. Select Objects Protocol Handlers MQ Front Side Handler to display the
MQ Front Side Handler catalog.
2. Click Add.
3. Define the basic configuration of the handler. Refer to Defining the basic
configuration on page 66 for details.
4. Define the publish and subscribe configuration. These fields are only supported
with WebSphere MQ V7 queue managers. Refer to Defining the publish and
subscribe configuration on page 67 for details.
5. Define the properties and headers configuration. Refer to Defining the
properties and headers configuration on page 67 for details.
Chapter 5. Handler configuration

65

6. Define the advanced configuration. Refer to Defining the advanced

configuration on page 68 for details.
7. Click Apply to save the changes to the running configuration.
8. Optional: Click Save Config to save the changes to the startup configuration.

Defining the basic configuration

To define the basic configuration for an MQ Front Side Handler:
1. In the Name field, enter the name for the object.
2. Retain the default setting for Admin State. To place in an inactive
administrative state, click disabled.
3. Optional: In the Comment field, enter a descriptive summary.
4. From the Queue Manager list, select a queue manager.
5. In the Get Queue field, specify the name of the GET queue.
6. In the Put Queue field, specify the name of the PUT queue.
7. In the The number of concurrent MQ connections field, specify the number
of concurrent MQ connections to allocate. The minimum is 1. The default is 1.
8. In the Get Message Options field, specify the cumulative value of the
MQGET options that are applicable to an MQ message in decimal or
hexadecimal format. 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).
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.
9. In the Polling Interval field, specify the number of seconds before an
MQGET operation returns if no messages are available. 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.
10. Use the Retrieve Backout Settings field to determine whether to retrieve the
backout threshold and backout queue name from the MQ server.
on

66

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
the MQ server. If MQ server does not contain backout settings, the
appliance uses existing backout properties, either empty or populated,

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

that are stored in the MQ Queue Manager object. If there are no

backout properties, backout is disabled.
(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.
11. Use the Use Queue Manager in URL field to determine whether the
var://service/URL-in variable returns the name of MQ Queue Manager or
the name of the MQ Queue Manager Group when this configuration defines a
queue manager group as the queue manager.
off

on

The variable returns the name of the queue manager

off
(Default) The variable returns the name of the queue manager group.
12. In the CCSI field, specify the Coded Character Set Identifier that the remote
MQ queue manager converts output data. 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.

Defining the publish and subscribe configuration

To define the publish and subscribe configuration for an MQ Front Side Handler:
1. In the Subscribe Topic String field, specify a topic string. If the Get Queue is
specified, this field is ignored.
2. In the Subscription Name field, specify the name for the durable subscription.
3. In the Publish Topic String field, specify a topic string associated with the
identified queue manager. The handler publishes messages to this topic string.
If the Put Queue field is specified, this field is ignored.
Note: These fields are only supported with WebSphere MQ V7 queue managers.

Defining the properties and headers configuration

To define the properties and headers configuration for an MQ Front Side Handler:
1. Use the Parse Properties field to specify whether to parse the properties of the
incoming message from a queue or from a subscription.
on

Specifies that parsing is enabled. The WebSphere MQ server returns the

messages with the properties.

off

(Default) Specifies that parsing is disabled. The DataPower appliance

does not request the properties with the message when issuing an
MQGET call, and the WebSphere MQ server returns the messages
without the properties.

For additional information, see the section on Message Properties in IBM

WebSphere DataPower SOA Appliances: Integrating with WebSphere MQ.
2. In the Selector field, specify the selector as a variable-length string containing a
SQL92 query. For additional information, see the section on Message Properties
in IBM WebSphere DataPower SOA Appliances: Integrating with WebSphere MQ.
Note: This field is only supported with WebSphere MQ V7 queue managers.

Chapter 5. Handler configuration

67

3. 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)
4. From the Header to Extract Content-Type list, select the MQ header structure
from which to extract the Content-Type header.
None

(Default) No header

MQRFH
MQRFH header
MQRFH2
MQRFH2 header
5. 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.

Defining the advanced configuration

To define the advanced configuration for an MQ Front Side Handler:
1. Use the Async Put field to specify whether to put a message to a queue
without waiting for a response from the queue manager.
on

Specifies that the put operation is asynchronous.

off

(Default) Specifies that the put operation is synchronous.

Note: This field is only supported with WebSphere MQ V7 queue managers.

2. In the Batch Size field, specify the number of messages to be processed as a
batch. The default is 0 which disables batch processing.

Configuring an NFS poller 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. In the Name field, enter the name for the object.

68

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

4. Retain the default setting for Admin State. To place in an inactive

administrative state, click disabled.
5. Optional: In the Comment field, enter a descriptive summary.
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-mountname/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:
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.
Chapter 5. Handler configuration

69

on

Deletes the input file.

(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.
off

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.
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

70

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

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. In the Maximum File Transfers Per Poll Cycle field, specify the number of
concurrent connections. Enter a value from 0 to 100. The default value is 0
which means unlimited number of connections based on available system
resources.
16. Click Apply to save the changes to the running configuration.
17. Optional: Click Save Config to save the changes to the startup configuration.

SFTP server handler configuration

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.
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.

Chapter 5. Handler configuration

71

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 Keys used as host private keys cannot be password protected.
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
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

72

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

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.
v When the client requests to delete a file and the Allow Delete is enabled, the
URL contains a query parameter to flag the request type. For example:
sftp://host.example.com:22/orders.xml?Delete=true. The Delete=true query
parameter is appended to the URL to designate that the file named orders.xml
will be deleted.

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. In the Name field, enter the name for the object.
4. Retain the default setting for Admin State. To place in an inactive
administrative state, click disabled.
5. Optional: In the Comment field, enter a descriptive summary.
6. Define the connection from the client to the appliance.
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. Keys used as host private keys
cannot be password protected.
Chapter 5. Handler configuration

73

If the appliance has HSM hardware, the Crypto Key objects can be HSM
generated keys specified as hsm:// in the key object.
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. Use the Allow Delete toggle to specify whether to delete files on the remote
FTP server.
on

Allows the deletion of files on the remote FTP server.

(Default) Does not allow the deletion of files on the remote FTP
server.
11. Select the AAA policy from the AAA Policy list.
off

Note: Although optional, without an AAA Policy, all users are authenticated.
12. 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 (/).
13. 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.
14. Click Apply to save the changes to the running configuration.
15. Optional: Click Save Config to save the changes to the startup configuration.

Configuring a 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.
3. In the Name field, enter the name for the object.
4. Retain the default setting for Admin State. To place in an inactive
administrative state, click disabled.
5. Optional: In the Comment field, enter a descriptive summary.
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.

74

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

7.
8.
9.
10.

11.

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.
Specify the port monitored by the handler in the Port Number field. The
default is 3000.
Specify the host name or IP address of the backend Stateful Raw XML server
in the Remote Host field.
Specify the remote TCP port of the Stateful Raw XML server in the Remote
Port field. The default is 12000.
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.
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 changes to the running configuration.
14. Optional: Click Save Config to save the changes to the startup configuration.

Configuring a 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. In the Name field, enter the name for the object.
4. Retain the default setting for Admin State. To place in an inactive
administrative state, click disabled.
5. Optional: In the Comment field, enter a descriptive summary.
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
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 changes to the running configuration.
12. Optional: Click Save Config to save the changes to the startup configuration.

Chapter 5. Handler configuration

75

TIBCO EMS handler configuration

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.

Using map message

The DataPower appliance performs the following roles to support TIBCO EMS
Map Message:
v Consumer of TIBCO EMS Map Message
v Producer of TIBCO EMS Map Message
You can configure the maximum bytes scanned, parsing depth, attribute count, and
node size to use to parse map messages in the XML parser of the domain XML
manager.

Consuming TIBCO EMS map message

The DataPower appliance acts as a consumer of TIBCO EMS map messages when
a service is configured with a TIBCO EMS Front Side Handler object. The handler
gets the incoming message that is converted into an XML stream of predefined
format. The converted TIBCO EMS message contains the request header
DP_JMSMessageType: map name-value pair to provide information about the
message format. Multistep processing and XSLT extension functions easily read
and transform the converted message as a regular XML request.

Producing TIBCO EMS map message

As a producer of map messages, the appliance converts an XML stream of
predefined format into TIBCO EMS Map Messages. The TIBCO EMS Front Side
Handler object provides one way to send the converted messages to the TIBCO
EMS Server. For additional information, see TIBCO EMS servers on page 328.

76

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

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. In the Name field, enter the name for the object.
4. Retain the default setting for Admin State. To place in an inactive
administrative state, click disabled.
5. Optional: In the Comment field, enter a descriptive summary.
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.
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)

Chapter 5. Handler configuration

77

ReplyTo
Contains the destination (queue) to which a reply to this message
should be sent
Type

9.
10.
11.
12.

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
Select the TIBCO EMS server to associate from the TIBCO EMS Server list.
Select an SSL Proxy Profile to assign from the SSL Proxy Profile list.
Select an Access Control List to apply from the Access Control List list.
Click Apply to save the changes to the running configuration.

13. Optional: Click Save Config to save the changes to the startup configuration.

WebSphere JMS handler configuration

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. In the Name field, enter the name for the object.
4. Retain the default setting for Admin State. To place in an inactive
administrative state, click disabled.
5. Optional: In the Comment field, enter a descriptive summary.
6. Specify the name of the GET queue in the Get Queue field. This queue
contains client-originated WebSphere JMS request messages.

78

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

7.

8.
9.

10.

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.
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.
Select the WebSphere JMS object to associate from the WebSphere JMS Server
list.
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.
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

Chapter 5. Handler configuration

79

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 changes to the running configuration.
13. Optional: Click Save Config to save the changes to the startup configuration.

80

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

Chapter 6. Processing policies

Processing policies define many, if not all, of the actions that are taken against
documents that pass through DataPower services.
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 in a processing policy. Matching rules support the implementation
of processing policies and XML manager-based schema validation rules. The
processing policy evaluates candidate documents against all expressions in the
matching rules. 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.
Matching rules come in the following flavors:
v An HTTP method matching rule matches on the http method type PUT, DELETE,
GET, POST and HEAD in the http request.
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. As error codes are written as hexadecimal
integers, the error code expression matches one or more hexadecimal integers.

Copyright IBM Corp. 2002, 2009

81

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.
v Route the transformed document to a dynamically determined server.
Processing rules are characterized by their direction.
v
v
v
v

A client-to-server rule is applied to client requests

A server-to-client rule is applied to server responses
A two way rule is applied to both client request and server responses
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 88.
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 Adding an
AAA action on page 88 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 Adding an antivirus action on page 88 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 Adding a call
processing rule (call) action on page 90 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 Adding a
checkpoint event (checkpoint) action on page 91 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

82

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

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
type for that service must be set to XML. Refer to Adding a convert query
parameters to XML (convert-http) action on page 92 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 93 for details.
Decrypt
A decrypt action performs full or field-level document decryption. Refer to
Adding a decrypt action on page 101 for details.
Encrypt
A encrypt action performs complete or field-level document encryption
using either WS-Security or XML encryption standards. Refer to Adding
an encrypt action on page 103 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.
Extract
An extract action applies an XPath expression to a specified context and
stores the result in another context. Refer to Adding an extract using
XPath (extract) action on page 117 for details.
Fetch

A fetch action uses a user agent to retrieve a document from a specified

location. Refer to Adding a fetch action on page 117 for details.

Filter

A filter action accepts or rejects check on incoming documents. Refer to

Filter actions on page 118 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
Chapter 6. Processing policies

83

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 121 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
type that are specified. The response, if any, is stored in the output context,
if one is defined. Refer to Adding a log action on page 124 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 Adding an on-error action on page 128 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 Adding a results
action on page 130 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
Adding a results asynchronous (results-async) action on page 131 for
details.
Rewrite header
A rewrite action rewrites HTTP headers or URLs using a URL rewrite
policy. Refer to Adding a rewrite header (rewrite) action on page 132 for
details.
Rewrite HTTP method
A rewrite-method action rewrites the HTTP method. Refer to Adding a
method rewrite action on page 132 for details.
Route with style sheet or XPath
A route-action action performs style sheet-based routing or XPath
expression-based routing. Refer to Adding a route with style sheet
(route-action) action on page 133 and Adding a route with XPath
expression (route-action) action on page 133, respectively, for details.

84

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

Route with variables

A route-set action performs dynamic, variable-based routing. Refer to
Route with variables (route-set) action on page 134 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 Adding a set variable (setvar)
action on page 134 for details.
Sign

A sign action attaches a digital signature to the document. Refer to

Adding a sign action on page 135 for details.

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
Adding an SLM action on page 137 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 Adding an SQL action on page 137 for details.
Strip attachments
A strip-attachments action removes all or specified MIME attachments from
a specified context. Refer to Adding a Strip Attachments action on page
138 for details.
Transform
An xform action transforms an XML document using a specified XSLT style
sheet. Refer to Transform-type actions on page 138 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 Adding a transform (xformbin) for non-XML
messages on page 139 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 Adding a processing instruction-based transform for XML
messages on page 140 for details.
Validate
A validate action performs schema-based validation against XML
documents using a user-specified method. Refer to Adding a validate
action on page 144 for details.
Chapter 6. Processing policies

85

Verify A verify action validates the digital signature on an incoming document.

Refer to Adding a verify action on page 146 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.
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 Adding a set variable (setvar) action
on page 134 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

86

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.

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

Processing rule builder

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.
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 8 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 8. Rule Action ordering

Creating a processing policy

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

2.
3.
4.

5.

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.
Click Add New Policy to display the processing policy configuration screen.
Specify the name of the processing policy in the Policy Name field.
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.
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.

Chapter 6. Processing policies

87

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.
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 Defining
Matching Rule objects on page 286 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
87 through step 9.
All candidate documents are processed by the rule that conforms to the defined
direction and matching rule.

Defining processing actions

The following sections provide the procedures for defining each of the available
processing actions.

Adding an AAA action

To
1.
2.
3.

add an AAA action:

Drag the AAA icon to the configuration path (the horizontal line).
Double-click the AAA icon.
In the Input field, enter or select the context for the data to be processed.

4. From the AAA Policy list, select an AAA policy. Refer to Creating AAA
policies on page 154 for complete information about creating an AAA policy.
5. Set Asynchronous to on to process the action asynchronously. For
asynchronous processing, this action does not need to complete before the
processing rule begins processing its next defined action.
6. Optional: In the Output field, enter or select the context for the data produced.
7. 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.

Adding an antivirus action

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

88

IBM WebSphere DataPower XML Integration Appliance XI50: 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. Set Asynchronous to on to process the action asynchronously. For
asynchronous processing, this action does not need to complete before the
processing rule begins processing its next defined action.
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
v To use a
v To use a
Micro.
v To use a

Clam ICAP host on a Virus Scanner server, click Clam.

Symantec ICAP host on a Virus Scanner server, click Symantec.
Trend Micro ICAP host on a Virus Scanner server, click Trend
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.
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.

Chapter 6. Processing policies

89

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.

Adding a 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 147.
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
150 for details.
7. Set Asynchronous to on to process the action asynchronously. For
asynchronous processing, this action does not need to complete before the
processing rule begins processing its next defined action.
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.

90

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

Adding a 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. Set Asynchronous to on to process the action asynchronously. For
asynchronous processing, this action does not need to complete before the
processing rule begins processing its next defined action.
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.

Adding a 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.
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.

Chapter 6. Processing policies

91

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. Set Asynchronous to on to process the action asynchronously. For
asynchronous processing, this action does not need to complete before the
processing rule begins processing its next defined action.
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.

Adding a 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.

92

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

7. Set Asynchronous to on to process the action asynchronously. For

asynchronous processing, this action does not need to complete before the
processing rule begins processing its next defined action.
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.

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.
Click the Crypto Binary radio button.
Click Next to display the Crypto Binary action window.
Specify or select the context for the data to be processed in the Input field.
Check the PKCS#7 Sign radio button to select document signature.
Set Asynchronous to on to process the action asynchronously. For
asynchronous processing, this action does not need to complete before the
processing rule begins processing its next defined action.
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.
3.
4.
5.
6.
7.

on

(Default) Specifies the commonly-used enveloped signature in which

the signed data is included in the PKCS #7 SignedData type.

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.
off

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.
Chapter 6. Processing policies

93

11. Select the output format to characterize the signed PKCS #7 object (SignedData
produced by the signature process) from the Output Encoding Format list.
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.

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.
off

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.
Defining 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.

94

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

8.
9.
10.
11.
12.

c. Click Submit to return to the Advanced window, which now lists the
newly defined parameter.
Repeat this step to define each additional parameter.
Confirm the Signers setting.
Confirm the Include Content Data setting.
Confirm the Input Encoding Format setting.
Confirm the Output Encoding Format setting.
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.

Chapter 6. Processing policies

95

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. Set Asynchronous to on to process the action asynchronously. For
asynchronous processing, this action does not need to complete before the
processing rule begins processing its next defined action.
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.
3.
4.
5.
6.

Confirm the Input setting.

Confirm that the Action Type is cryptobin.
Confirm that the PKCS#7 Verify radio button is selected.
Confirm the Asynchronous setting.
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.

96

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

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.
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

Chapter 6. Processing policies

97

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. Set Asynchronous to on to process the action asynchronously. For
asynchronous processing, this action does not need to complete before the
processing rule begins processing its next defined action.
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.

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.

98

IBM WebSphere DataPower XML Integration Appliance XI50: 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.
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.
3.
4.
5.
6.

Confirm the Input setting.

Confirm that the Action Type is cryptobin.
Confirm that the PKCS#7 Encrypt radio button is selected.
Confirm the Asynchronous setting.
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.
9.
10.
11.

Confirm the Encryption Algorithm setting.

Confirm the Input Encoding Format setting.
Confirm the Output Encoding Format setting.
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
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.

Chapter 6. Processing policies

99

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. Set Asynchronous to on to process the action asynchronously. For
asynchronous processing, this action does not need to complete before the
processing rule begins processing its next defined action.
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.
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.
4.
5.
6.

Confirm that the Action Type is cryptobin.

Confirm that the PKCS#7 Decrypt radio button is selected.
Confirm the Asynchronous setting.
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.

100

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

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.

Adding a decrypt action

This action might require that certain parameters be supplied during the
configuration of the service.
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 266 for
more information.
6. Set Asynchronous to on to process the action asynchronously. For
asynchronous processing, this action does not need to complete before the
processing rule begins processing its next defined action.

Chapter 6. Processing policies

101

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.
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.

(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).
off

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.

102

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

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.

Adding an 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.
5. Select SOAP Message from the Message Type list.
6. Set Asynchronous to on to process the action asynchronously. For
asynchronous processing, this action does not need to complete before the
processing rule begins processing its next defined action.
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.
Chapter 6. Processing policies

103

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.
Confirm the Action Type property.
Confirm the Envelope Method property.
Confirm the Message Type property.
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.

b.
c.
d.
e.

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.

104

IBM WebSphere DataPower XML Integration Appliance XI50: 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 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
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
Chapter 6. Processing policies

105

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-profile1.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
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.

106

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

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.
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-profile1.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-profile1.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.

Chapter 6. Processing policies

107

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
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.

108

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

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.
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.

Chapter 6. Processing policies

109

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.
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

110

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

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.
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.
Chapter 6. Processing policies

111

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.
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.

112

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

6. Set Asynchronous to on to process the action asynchronously. For

asynchronous processing, this action does not need to complete before the
processing rule begins processing its next defined action.
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-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.

Chapter 6. Processing policies

113

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.
4. Select Standard XML Encryption from the Envelope Method list.
5. Select Raw XML Document from the Message Type list.
6. Set Asynchronous to on to process the action asynchronously. For
asynchronous processing, this action does not need to complete before the
processing rule begins processing its next defined action.
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.
Confirm the Action Type property.
Confirm the Envelope Method property.
Confirm the Message Type property.
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
b.
c.
d.
e.

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.

114

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

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 266 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 6. Processing policies

115

9. Set Asynchronous to on to process the action asynchronously. For

asynchronous processing, this action does not need to complete before the
processing rule begins processing its next defined action.
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.

Adding an 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,
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.

116

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

Adding an 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 Adding a set variable (setvar) action
on page 134 for more information.
8. Set Asynchronous to on to process the action asynchronously. For
asynchronous processing, this action does not need to complete before the
processing rule begins processing its next defined action.
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.

Adding a 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. Optionally. specify or select the context for the request message body in the
Input field.
6. In the Source field, specify the location of the resource to retrieve. Refer to
Locating remote resources in actions on page 147 for details.
7. Set Asynchronous to on to process the action asynchronously. For
asynchronous processing, this action does not need to complete before the
processing rule begins processing its next defined action.
8. For HTTP protocols: From the Method list, select the HTTP method type.
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 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.

Chapter 6. Processing policies

117

Filter actions
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.

5.

6.

7.
8.

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.
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.
Set Asynchronous to on to process the action asynchronously. For
asynchronous processing, this action does not need to complete before the
processing rule begins processing its next defined action.
Specify or select the context for the data produced in the Output field.
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.

118

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

Adding 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. Set Asynchronous to on to process the action asynchronously. For
asynchronous processing, this action does not need to complete before the
processing rule begins processing its next defined action.
8. Select the type of filter from the Replay Filter Type list:
v WS-Security Password Digest Nonce
v WS-Addressing Message ID (Default)
9.
10.

11.
12.

v Custom XPath
Specify, in milliseconds, the duration to use the extracted value in the Replay
duration field. Use an integer greater than 0.
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.
Specify or select the context for the data produced in the Output field.
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:
Drag the Filter icon to the configuration path (the horizontal line).
Double-click the Filter icon to display the Filter action window.
Specify or select the context for the data to be processed in the Input field.
Click the Advanced tab.
Select the Required Elements Filter radio button from the Filter Method list.
Retain the value of store:///required-elements-filter.xsl in the Processing
Control File field.
7. Set Asynchronous to on to process the action asynchronously. For
asynchronous processing, this action does not need to complete before the
processing rule begins processing its next defined action.
8. Specify the XPath expression in the XPath Expression field.
1.
2.
3.
4.
5.
6.

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.

Chapter 6. Processing policies

119

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.

Adding 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.
6. Retain the value of store:///wssecurity-message-layout-filter.xsl in the
Processing Control File field.
7. Set Asynchronous to on to process the action asynchronously. For
asynchronous processing, this action does not need to complete before the
processing rule begins processing its next defined action.
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.

Adding a conformance filter

To add a conformance filter, use the following procedure:
1.
2.
3.
4.
5.

6.
7.
8.

120

Drag the Filter icon to the configuration path (the horizontal line).
Double-click the Filter icon to display the Filter action window.
Specify or select the context for the data to be processed in the Input field.
Specify or select the store:///conformance-filter.xsl style sheet with the
Processing Control File fields.
Set Asynchronous to on to process the action asynchronously. For
asynchronous processing, this action does not need to complete before the
processing rule begins processing its next defined action.
Select the conformance policy from the Conformance Policy list. Refer to
Conformance Policy on page 263 for details.
Specify or select the context for the data produced in the Output field.
Click Done to complete the action.

IBM WebSphere DataPower XML Integration Appliance XI50: 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.

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 148 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. Set Asynchronous to on to process the action asynchronously. For
asynchronous processing, this action does not need to complete before the
processing rule begins processing its next defined action.
Chapter 6. Processing policies

121

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.
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.

122

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

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 147 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.
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.

Chapter 6. Processing policies

123

var://service/multistep/loop-count
This variable returns the number of times the loop has iterated.

Adding a 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 147 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. Set Asynchronous to on to process the action asynchronously. For
asynchronous processing, this action does not need to complete before the
processing rule begins processing its next defined action.
10. For HTTP protocols: From the Method list, select the HTTP method type.
11. 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.
12. 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:
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.

124

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

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. Set Asynchronous to on to process the action asynchronously. For
asynchronous processing, this action does not need to complete before the
processing rule begins processing its next defined action.
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.

(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
off

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.

Chapter 6. Processing policies

125

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. Set Asynchronous to on to process the action asynchronously. For
asynchronous processing, this action does not need to complete before the
processing rule begins processing its next defined action.
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.
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. Set Asynchronous to on to process the action asynchronously. For
asynchronous processing, this action does not need to complete before the
processing rule begins processing its next defined action.
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

126

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.

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

(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
off

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.

Modifying the reply queue for responses

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. Set Asynchronous to on to process the action asynchronously. For
asynchronous processing, this action does not need to complete before the
processing rule begins processing its next defined action.
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.

Chapter 6. Processing policies

127

Modifying the queue manager for responses

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.
5. Optionally select the Input context. If the default, processing inserts the
correct context identifier.
6. Set Asynchronous to on to process the action asynchronously. For
asynchronous processing, this action does not need to complete before the
processing rule begins processing its next defined action.
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.

Adding an 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
Adding a set variable (setvar) action on page 134 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.

128

IBM WebSphere DataPower XML Integration Appliance XI50: 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 147.
To define a target rule, do one of the following:

7.

8.

9.

10.

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
150 for details.
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.
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.
Set Asynchronous to on to process the action asynchronously. For
asynchronous processing, this action does not need to complete before the
processing rule begins processing its next defined action.
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 Adding a results
action on page 130 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 Adding a results asynchronous
(results-async) action on page 131 for configuration details.
Both of the results-type actions offer the following options:
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
Chapter 6. Processing policies

129

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.

Adding a 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 147 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
Adding a fetch action on page 117 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.
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.

130

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

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. For HTTP protocols: From the Method list, select the HTTP method type.
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.

Adding a 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 147 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.
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.

Chapter 6. Processing policies

131

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. For HTTP protocols: From the Method list, select the HTTP method type.
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.

Adding a 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 342 for more information.
6. Set Asynchronous to on to process the action asynchronously. For
asynchronous processing, this action does not need to complete before the
processing rule begins processing its next defined action.
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.

Adding a method rewrite action

To add a method 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 Method Rewrite radio button.
4. Click Next to display the Method Rewrite action window.
5. For HTTP protocols: From the Method list, select the HTTP method type.
6. Click Done to complete the action. The configuration path shows the Method
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.

132

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

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
Adding a route with style sheet (route-action) action for details.
XPath expressions
Uses the route-set action to implement XPath expression-based routing.
Refer to Adding a 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 134 for details.

Adding a 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. Set Asynchronous to on to process the action asynchronously. For
asynchronous processing, this action does not need to complete before the
processing rule begins processing its next defined action.
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.

Adding a 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.

Chapter 6. Processing policies

133

3. Specify or select the context for the data to be processed in the Input field.
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. Set Asynchronous to on to process the action asynchronously. For
asynchronous processing, this action does not need to complete before the
processing rule begins processing its next defined action.
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 147 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. Set Asynchronous to on to process the action asynchronously. For
asynchronous processing, this action does not need to complete before the
processing rule begins processing its next defined action.
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.

Adding a 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 150 for details.
7. Specify the value for the variable in the Variable Assignment field.

134

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

8. Set Asynchronous to on to process the action asynchronously. For

asynchronous processing, this action does not need to complete before the
processing rule begins processing its next defined action.
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.

Adding a 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.
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. Set Asynchronous to on to process the action asynchronously. For
asynchronous processing, this action does not need to complete before the
processing rule begins processing its next defined action.
7. When the Envelope Message is enveloped or enveloping and the Message
Type is SOAP Message or Raw XML Document, select an instance of the Key
object from the Key list.
Chapter 6. Processing policies

135

8. When the Envelope Message is enveloped or enveloping and the Message

Type is SOAP Message or Raw XML Document, select an instance of the
Certificate object from the Certificate list.
9. When the Message Type is Selected Elements (Field-Level), 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 266 for
more information.
10. The following fields only apply when the Envelope Message is WSSec
Method.
a. In the WS-Security Version field, select the version of WS-Security.
b. In the Use Asymmetric Key field, specify whether to use an asymmetric
key for RSA/DSA signing or whether to use a symmetric key for HMAC
signing. This setting affects the signing algorithm and the KeyInfo output.
It is on by default to indicate that the RSA/DSA key is required as the
default behavior for WSSec signing. Otherwise, a symmetric key is
required for WSSec HMAC signing.
c. When the Use Asymmetric Key field is on, select the signing algorithm
from the Signing Algorithm list, the Key object from the Key list, and the
Certificate object from the Certificate list.
d. When the Use Asymmetric Key field is off, select the HMAC Signing
Algorithm from the list.
e. In the Symmetric Key Type field, select the type of the symmetric key for
the HMAC signing.
f. For the Use a Random Key and Encrypt It for the Recipient type of
symmetric key, in the Certificate of the Encrypted Keys Recipient field,
select the crypto certificate object with the public certificate of the intended
recipient who will verify the signed message.
g. For the Use an Existing DKT Token type of symmetric key, in the Name
of the Base DKT to Derive a Key field, enter the name of the Derived Key
Token (DKT).
h. For all symmetric key types except Use Static SharedSecret Object, use
the Use WS-SC Key Derivation toggle to determine whether the HMAC
signing key is a derived key.
i. For the Use Static SharedSecret Object type of symmetric key, in the
Shared Secret Key field, select the name of the shared secret key to use.
This value overrides any setting of the Alternate Shared Secret Key.
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).
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.

136

IBM WebSphere DataPower XML Integration Appliance XI50: 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.

Adding an 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
Service level monitors on page 320 for details.
7. Set Asynchronous to on to process the action asynchronously. For
asynchronous processing, this action does not need to complete before the
processing rule begins processing its next defined action.
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.

Adding an 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.
Click the SQL radio button.
Click Next to display the SQL Action window.
Specify or select the context for the data to be processed in the Input field.
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 326 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.
3.
4.
5.
6.

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

Chapter 6. Processing policies

137

sheet specified by the Transform field against the contents on the

context specified by the Input field.

10.

11.

12.

13.

14.
15.

Variable
Indicates that the SQL statement is contained in the variable specified
by the Variable Name field.
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.
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.
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.
Set Asynchronous to on to process the action asynchronously. For
asynchronous processing, this action does not need to complete before the
processing rule begins processing its next defined action.
Optionally specify or select the context for the data produced in the Output
field.
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.

Adding a 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).
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. Set Asynchronous to on to process the action asynchronously. For
asynchronous processing, this action does not need to complete before the
processing rule begins processing its next defined action.
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.

138

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

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.

Adding 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).
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.
6.

7.

8.
9.

You can click Upload or Fetch to obtain the file.

Optional: 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 342 for more information.
Set Asynchronous to on to process the action asynchronously. For
asynchronous processing, this action does not need to complete before the
processing rule begins processing its next defined action.
Specify or select the context for the data produced in the Output field.
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.

Adding a transform (xformbin) 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).
Chapter 6. Processing policies

139

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.
6.

7.

8.

9.

You can click Upload or Fetch to obtain the file.

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.
Optional: 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 342 for more information.
Set Asynchronous to on to process the action asynchronously. For
asynchronous processing, this action does not need to complete before the
processing rule begins processing its next defined action.
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.

Adding a processing instruction-based transform for XML

messages
To add an xformpi action, use the following procedure:
1.
2.
3.
4.

Drag the Transform icon to the configuration path (the horizontal line).
Double-click the Transform icon to display the Transform action window.
Specify or select the context for the data to be processed in the Input field.
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. Optional: 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 342 for more information.
6. Set Asynchronous to on to process the action asynchronously. For
asynchronous processing, this action does not need to complete before the
processing rule begins processing its next defined action.
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.

140

IBM WebSphere DataPower XML Integration Appliance XI50: 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.

Adding 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:///soaprefine.xsl style sheet.
6. Optional: 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 342 for more information.
7. Set Asynchronous to on to process the action asynchronously. For
asynchronous processing, this action does not need to complete before the
processing rule begins processing its next defined action.
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.
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.
Chapter 6. Processing policies

141

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.
This setting does not impact defined remove instruction in the SOAP
Header Disposition Table.

off

142

Delete SOAP headers without checking for ID references.

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

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 325 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:///bufferattachments.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 342 for more information.
7. Set Asynchronous to on to process the action asynchronously. For
asynchronous processing, this action does not need to complete before the
processing rule begins processing its next defined action.
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.

Adding 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.

Chapter 6. Processing policies

143

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 342 for more information.
7. Set Asynchronous to on to process the action asynchronously. For
asynchronous processing, this action does not need to complete before the
processing rule begins processing its next defined action.
8. Select the conformance policy from the Conformance Policy list. Refer to
Conformance Policy on page 263 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.

Adding a 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.
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.

144

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

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 342 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 319 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.

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. Set Asynchronous to on to process the action asynchronously. For
asynchronous processing, this action does not need to complete before the
processing rule begins processing its next defined action.
11. Specify or select the context for the data produced in the Output field.
12. Click Done to complete the action.
Chapter 6. Processing policies

145

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 actions
A verify action validates digital signatures in messages. The basic configuration
requires the selection of the type or types of signatures to verify. The verify action
can validate RSA/DSA (asymmetric) signatures, HMAC (symmetric) signatures, or
both types of signatures. If a message contains signatures that are signed by
RSA/DSA and HMAC algorithms, the verify action can validate one type of
signing algorithm and ignore the other. If set to a single signature type and the
signing method is different, verification fails.
During processing, the verify action can retrieve the key information from the
WS-Security token or from the signature information.
v RSA/DSA verification uses public keys (certificates).
v HMAC verification uses shared secret keys.
Kerberos signature verification: You must define the verifier principal and the
keytab that contains the shared secret key.
Optionally, you can define the signer principal to
validate that this principal signed this message.
These setting are available on the Advanced tab.
By default, the verify action checks the expiration of the WS-Security timestamp.
You can modify this behavior and other timestamp checks on the Advanced tab.

Adding a verify action

To add a verify action:
1. Drag the Verify icon to the configuration path (the horizontal line).
2. Double-click the Verify icon.
3. In the Input field, enter or select the context for the data to process.
4. Set Asynchronous to on to process the action asynchronously. For
asynchronous processing, this action does not need to complete before the
processing rule begins processing its next defined action.
5. From the Signature Verification Type list, select the types of signature to
verify.
6. Optional: For RSA/DSA signatures, define certificates.
a. In the Optional Signer Certificate field, enter the certificate to use when
processing cannot retrieve the key information.
b. From the Validation Credential list, select the credentials set to validate the
certificate.
7. Optional: In the Output field, enter or select the context for the data that was
processed.
8. Click the Advanced tab to override basic settings or define advanced settings.
v Optional: Override WS-Security timestamp checking for both HMAC and
RSA/DSA verification
v Kerberos principals and keytab for Kerberos signature (HMAC) verification
v Optional: Enable WS-Security 1.1 signature confirmation for both HMAC and
RSA/DSA verification

146

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

v Optional: SAML remote tokens (WS-Security 1.1) processing for both HMAC
and RSA/DSA verification
v Optional: Caching of extracted session key from the verified message.
Cached key is for future cryptographic operations that use
EncryptedKeySHA1.
v Optional: Processing of security header based on SOAP actor/role
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 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.
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 9 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 9. Actions and remote resources
Action type

WebGUI label

Optional or
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 back end)
v dptibems, if licensed (TIBCO EMS protocol to a static back end)
Chapter 6. Processing policies

147

v
v
v
v
v

dpwasjms (not secure) or dpwasjmss (secure)

ftp
http
https
ims (not secure) or imsssl (secure), if licensed

v
v
v
v
v
v

mq (MQ protocol to a dynamic back end)

smtp
sql, if licensed
tcp
tcps
tibems, if licensed (TIBCO EMS protocol to a dynamic back end)

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

actions support the attachment protocol. Refer to Attachment protocol on page
149 for details.

Specifying the location of remote resources

To specify the location, use one of the following methods:
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 150.
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>

148

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

<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 150.

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
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
v
v
v
v

Compress=gzip
Archive=tar or Archive=zip
Filename=file_name
Parsable=true
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
Chapter 6. Processing policies

149

# 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>

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 9 is visible.

Figure 9. 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

150

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

Figure 10 is visible.

Figure 10. 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.

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 6. Processing policies

151

152

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

Chapter 7. AAA Policy configuration

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 11 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
Message

Generate
Error

Figure 11. 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

153

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 AAA policies

The AAA Policy editor steps through creating or editing of an AAA policy from a
processing policy. The editor is launched from the AAA action.
To create an AAA policy:
1. Click the + button beside the AAA Policy list.
2. In the AAA Policy Name field, enter the name for the new AAA policy.
3. Click Create to start the interactive editor.
The editor guides you through the following activities:
v Defining methods to extract a users identity from an incoming request
v Defining the method to authenticate the user
v Define the method to map credentials

154

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

v
v
v
v
v

Defining methods to extract resources

Define the method to map resources
Define the method to authorize a request
Define counters for authorized and rejected messages
Define logging for authorizations and rejections.

v Defining post processing activities

4. After defining all aspects of the AAA policy, click Commit.
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.
It is possible use one AAA policy to support submissions from multiple
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 a
SAML assertion. All three identity extraction methods can be defined in one
AAA policy, and this AAA policy will support all three 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>

Chapter 7. AAA Policy configuration

155

<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:
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>

156

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

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>
...

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.

Chapter 7. AAA Policy configuration

157

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.
<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>

158

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

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.
<?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>[email protected]</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 Validation credentials on page 28 for more
information.
Retrieve Remote Token
Select whether to retrieve the remote token. Refer to Security
token references on page 366 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:

Chapter 7. AAA Policy configuration

159

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.
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
data for XPath bindings on page 248 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.

160

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

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 314 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
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 Validation credentials on page
28.
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:
Chapter 7. AAA Policy configuration

161

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:
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
Optional: 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 Configuring a
load balancer group on page 278 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

162

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

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.

(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.
v If on, the WebGUI displays the LDAP Search Parameters field.
Select the LDAP Search Parameters from the list. Refer to
Defining LDAP Search Parameters objects on page 270 for detail.
off

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 Validation
credentials on page 28 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
Chapter 7. AAA Policy configuration

163

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.
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

164

Generates a WS-Trust RequestSecurityTokenCollection.

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

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 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
Chapter 7. AAA Policy configuration

165

connecting to the NSS server for SAF authentication. Refer to z/OS

NSS Client on page 362 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 Tivoli Access Manager
objects on page 255 for more information.
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

166

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

certificate extracted from the WS-Security BinarySecurityToken

element. Refer to Validation credentials on page 28 for more
information.
Refer to the description in Defining identity extraction methods on page
155.
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:
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 Using an AAA Info file on page 249 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
XML Integration Appliance XI50: 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 Configuring a Kerberos
Keytab File object on page 260 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 Validation credentials on
page 28 for more information.

Chapter 7. AAA Policy configuration

167

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 data for XPath bindings on page 248 for more
information.
Retrieve Remote Token
Select whether to retrieve the remote token. Refer to Security token
references on page 366 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 Validation credentials on page 28 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.

168

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

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.
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 TFIM objects on
page 256 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 Using an AAA Info file on page 249 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 data for XPath bindings on page 248 for more
information.

Chapter 7. AAA Policy configuration

169

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)
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/"

170

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

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>

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 data for XPath bindings on page 248 for more
information.
For example, you could specify /*[local-name()="message"]/*[localname()="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:
Chapter 7. AAA Policy configuration

171

Processing Metadata Item

Select a Processing Metadata object to identify extracted items. Refer
to Processing Metadata on page 314 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.
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

172

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

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:
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 Using an AAA Info file on page 249 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 data for XPath bindings on page 248 for
more information.

Chapter 7. AAA Policy configuration

173

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.
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 Tivoli Access Manager
objects on page 255 for more information.
Default action
Select the default action. The default is T (Traverse).
[PDMQ]D (TAMBI
Dequeue)
[PDMQ]E (TAMBI
Enqueue)
[WebService]i (TFIM
Action)
A (Add)
a (Attach)
B (Bypass)
b (Browse)

c (Control)

r (Read)

d (Delete)

s (Server Admin)

g (Delegate)

T (Traverse)

l
m
N
R

t
v
W
x

(List Directory)
(Modify)
(Create)
(Bypass AuthAZ)

(Trace)
(View)
(Password)
(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 10.
Table 10. 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.

174

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

For information about creating or editing this type of action map, use
the WebGUI online help.
Refer to Creating Tivoli Access Manager objects on page 255 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.
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 to z/OS
NSS Client on page 362 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.

Chapter 7. AAA Policy configuration

175

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.
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 Configuring a load balancer group on page
278 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.

176

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

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.
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 Validation credentials on page 28.
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 23.
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 19.
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.

Chapter 7. AAA Policy configuration

177

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.
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 data for XPath bindings on page 248 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 248.
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 248.
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 248.
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 248.
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. Refer to Validation credentials on page 28 for
more information.

178

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

SAML message signing key

Select a Crypto Key to use for this transaction. Refer to Defining
Key objects on page 23 for more information.
SAML message signing certificate
Select a Crypto Certificate to use for this transaction. Refer to
Defining Certificate objects on page 19 for more information.
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.
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 data for XPath bindings on page 248 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 248.
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 248.
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 248.
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

Chapter 7. AAA Policy configuration

179

SAML Attributes panel. To define SAML attributes, refer to

Defining SAML attributes on page 248.
Use XACML Authorization Decision
The requester is authorized by an internal or external XACML Policy
Decision Point (PDP). Refer to Defining a XACML PDP on page 261 for
more information.
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).
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 Defining a XACML PDP on page
261 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.

180

on

Forces the use of the SAML2.0 profile.

off

(Default) Does not require the use of the SAML2.0

profile.

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

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.
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 Using an AAA Info file on page 249 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.

Chapter 7. AAA Policy configuration

181

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.
4. Click Next to return to the AAA Policy configuration where you can define
post processing activities.

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
Configuring count monitors on page 216 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.
v For rejected attempts, entries are at the warning level.

182

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

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.

Post processing activities

After authorizing the client, an AAA Policy can perform post processing activities.
You can define the following post processing activities:
v Run a custom post processing style sheet
v Generate a SAML assertion that contains an authentication statement for the
authenticated identify
v
v
v
v
v

Include an AP-REQ token to act as a Kerberos client

Process a WS-Trust SecurityContextToken (SCT) request
Add a WS-Security UsernameToken to the message
Generate an LTPA token
Generate a Kerberos SPNEGO token

v Request a Tivoli Federated Identity Manager (TFIM) token map

v Generate an ICRX token for z/OS identity propagation

Running a custom style sheet

After authorizing the client, the AAA policy can run a custom style sheet. The
AAA policy runs the actions that are defined in a custom style sheet. To perform
this activity, the AAA policy needs the location of the custom style sheet.

Generating a SAML assertion

After authorizing the client, 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.

Chapter 7. AAA Policy configuration

183

An 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.
To perform this activity, the AAA policy needs the following data:
v The SAML version
v The assertion originator (issuer identity)
v Optional: The NameQualifier as defined by the SAML protocol version
v Optional: The key-certificate pair to generate digital signatures
If a custom style sheet generates a SAML assertion, this activity will not generate
additional SAML assertions.

Including an AP-REQ token to act as a 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 perform this activity, the AAA policy needs the following data:
v The client identity (cname of the Kerberos ticket) for the Kerberos client principal
v The location of the Kerberos keytab file
v The server identity (sname of the Kerberos ticket) for the Kerberos server
principal
v The value type for the generated Kerberos BinarySecurityToken (BST)

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.
To perform this activity, the AAA policy needs the following data:
v Whether to place the generated token in the SOAP body or as a SOAP header
If the body, the generated token is in the wst:RequestSecurityTokenResponse
element
If a header, the generated token is the wst:RequestSecurityTokenResponse
element but is wrapped in a wst:IssuedToken element
v The validity duration for the SCT

184

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

 A negative integer makes the token never expire.

A value of 0 uses the value of the var://system/AAA/defaultexpiry variable if
defined; otherwise, 14400
A positive integer makes the token expire after the specified duration.
v Whether to generate a WS-Trust token timestamp
v The source for the symmetric shared key to initialize the security context
v Whether to allow WS-Trust token renew and, if allowed, how to process a
renewal request

Adding a WS-Security UsernameToken

An AAA policy can add a WS-Security UsernameToken to the message that is
forwarded to the server. The AAA policy uses the user name and password from
the credential mapping phase.
To perform this activity, the AAA policy needs the following data:
v Whether to replace the existing UsernameToken
v The identifier for the SOAP 1.1 actor or SOAP 1.2 role in processing a
WS-Security security header
v Whether to include the password in the token

Generating an LTPA token

An AAA policy can generate an LTPA token and add it to the HTTP headers that
are sent to the server.
To perform this activity, the AAA policy needs the following data:
v The format (or version) of the LTPA token
v The name of the key file that contains the cipher keys for encryption and
decryption
v The cleartext password for the key file
v The lifetime for the token (from the cookie creation to its expiration)
v Whether to wrap the token in the standard <Security/> WS-Security header
For information about LTPA, refer to Understanding LTPA.

Generating a Kerberos SPNEGO token

An AAA policy can generate a Kerberos SPNEGO token and add it to the HTTP
headers that are sent to the server.
To perform this activity, the AAA policy needs the following data:
v The client identity (cname of the Kerberos ticket) for the Kerberos client principal
v The location of the Kerberos keytab file
v The server identity (sname of the Kerberos ticket) for the Kerberos server
principal
For information about SPNEGO, refer to Understanding SPNEGO.

Requesting a TFIM token map

An AAA policy can request a Tivoli Federated Identity Manager (TFIM) token
map.

Chapter 7. AAA Policy configuration

185

To perform this activity, the AAA policy needs the name of an existing TFIM
configuration. For more information, refer to Creating TFIM objects on page 256.

Generating an ICRX token for z/OS identity propagation

An AAA policy can create an ICRX token from the authenticated credentials. When
generated, the WS-Security binary token with the ICRX token is inserted into the
WS-Security header. This token can be used for interoperability with the CICS
Transaction Server for z/OS identity propagation support.
To perform this activity, the AAA policy needs the name of the ICRX realm as
defined in the SAF configuration. Generally, this setting is the equivalent of the
prefix for a DN in a user registry.

186

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

Chapter 8. Managing files

The appliance provides a File Management utility to administer files stored in the
predefined directories and in any user defined subdirectories.

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

187

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

188

This encrypted subdirectory contains files that are used by the

appliance itself. This subdirectory is available from the command
line only.

IBM WebSphere DataPower XML Integration Appliance XI50: 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.
4.
5.
6.

Click Create Subdirectory. The File Management screen displays.

Enter the name of the new subdirectory in the directory Name field.
Click Confirm Create. The File Management screen refreshes.
Click Continue. The File Management screen displays the top-level directories
only.

Chapter 8. Managing files

189

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 189 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 189 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 189.

190

IBM WebSphere DataPower XML Integration Appliance XI50: 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 189 for details.
2.
3.
4.
5.

Navigate to the directory into which you want to upload the file.
Click Actions in that row to open the Directory Actions menu.
Click Upload Files to display the File Upload screen.
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 8. Managing files

191

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
189.
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 189 for details.
2. Navigate to the directory into which you want to upload the file.
Click Actions in that row to open the Directory Actions menu.
Click Fetch Files to display the Fetch File screen.
Specify the location of the file in the Source URL field.
Specify the file name in the Save as field.
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.

3.
4.
5.
6.
7.

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

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

192

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

1. Launch the File Management utility. Refer to Launching the File Management
utility on page 189 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 189.

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 189 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 189.

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 189 for details.
2.
3.
4.
5.
6.

Navigate to the directory that contains the files to be moved.

Select files by clicking the box adjacent to the file name.
Click Move to display the Move File screen.
From the New Directory list, select the target directory.
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 8. Managing files

193

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 189.

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 189 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 189 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 189 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 189.

194

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

Chapter 9. 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. In the Name field, enter the name for the object.
4. Retain the default setting for Admin State. To place in an inactive
administrative state, click disabled.
5. Optional: In the Comment field, enter a descriptive summary.
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.

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.
off

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

195

9. Click Apply to save the changes to the running configuration.

10. Optional: Click Save Config to save the changes 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. In the Name field, enter the name for the object.
4. Retain the default setting for Admin State. To place in an inactive
administrative state, click disabled.
5. Optional: In the Comment field, enter a descriptive summary.
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.

196

on

(Default) Overwrites objects of the same name.

off

Does not import the objects if an objects of the same name exists.

IBM WebSphere DataPower XML Integration Appliance XI50: 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
Deployment policies on page 208.
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.

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 changes to the running configuration.
14. Optional: Click Save Config to save the changes to the startup configuration.
off

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 9. Managing the configuration of the appliance

197

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. Optional: In the Comment field, enter a descriptive summary.
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. Optional: In the Comment field, enter a descriptive summary.
b. Optionally create or select the name of a Deployment Policy to accept, filter,
or modify a configuration during import.

198

IBM WebSphere DataPower XML Integration Appliance XI50: 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. Optional: In the Comment field, enter a descriptive summary.
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 9. Managing the configuration of the appliance

199

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.

200

IBM WebSphere DataPower XML Integration Appliance XI50: 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 9. Managing the configuration of the appliance

201

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.

202

IBM WebSphere DataPower XML Integration Appliance XI50: 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 changes to the running configuration.
6. Optional: Click Save Config to save the changes 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 204.

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 206.

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 9. Managing the configuration of the appliance

203

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 matching statement in a deployment policy
with the Use Deployment Policy list (optional).

204

IBM WebSphere DataPower XML Integration Appliance XI50: 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 Deployment policies on page 208.
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 206.
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 9. Managing the configuration of the appliance

205

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.

206

IBM WebSphere DataPower XML Integration Appliance XI50: 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 9. Managing the configuration of the appliance

207

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.

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 deployment policies

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 209.
v For details about manually specifying the statement, refer to Specifying the
matching statement on page 210.
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.

208

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

3. In the Name field, enter the name for the object.

4. Optional: In the Comment field, enter a descriptive summary.
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 changes to the running configuration.
9. Optional: Click Save Config to save the changes 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 9. Managing the configuration of the appliance

209

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. Optional: In the Name Match (PCRE) field, specify 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.
6. Optional: From the Configuration Property list, select the name of the
configuration property. This property limits the matching statement to resources
of the specified property.
7. Optional: In the Configuration Value Match (PCRE) field, specify the value for
the configuration property. 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

210

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

Chapter 10. 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 that 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 Configuring count monitors on page 216.
v Message duration monitors that 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 Configuring duration
monitors on page 218.
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
220.
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

211

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.

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 definitions on page 213.
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 215.
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 Message Filter Action on page 215.
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 Configuring count monitors on page 216.
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.

212

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

For procedural details, refer to Configuring duration monitors on page 218.

After completing the configuration of a message monitor, activate the monitor by
associating it with one or more DataPower services.

Traffic definitions
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. Click Object Monitoring Message Matching.
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.
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 10. Managing monitors

213

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.
b. Click Add.
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.

You can use any PCRE-compliant expression. For more information,

refer to http://www.pcre.org.

214

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

d. Click Save.
5. Use the following procedure to specify HTTP-based exclusion criteria:
a. Click the HTTP Headers tab.
b. Click Add.
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.
7. Click Apply to save the changes to the running configuration.
8. Optional: Click Save Config to save the changes 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. Click Object Monitoring Message Type.
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.
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 changes to the running configuration.
5. Optional: Click Save Config to save the changes to the startup configuration.

Message 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
Chapter 10. Managing monitors

215

target configured with an event subscription of class Monitor and a priority equal
to or lower than the priority set by the filter.
1. Click Object Monitoring Message Filter Action.
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.
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 changes to the running configuration.
5. Optional: Click Save Config to save the changes to the startup configuration.

Configuring count monitors

To configure a message count monitor, use the following procedure:
1. Click Object Monitoring Message Count Monitor.
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.

216

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

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.
5. Click Add.
6. Provide the following inputs:
Name Specify the name of this threshold.

Chapter 10. Managing monitors

217

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 Message Filter Action on page
215 for more information.
7. Click Save.
8. Click Apply to save the changes to the running configuration.
9. Optional: Click Save Config to save the changes to the startup configuration.
After creating a monitor, activate it by assigning it to one or more DataPower
services.

Configuring duration monitors

To configure a duration monitor, use the following procedure:
1. Click Object Monitoring Message Duration Monitor.
2. Click Add.

218

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

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 215 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.
5. Click Add.
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.
Chapter 10. Managing monitors

219

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 Message Filter Action on page 215
for more information.
7. Click Save.
8. Click Apply to save the changes to the running configuration.
9. Optional: Click Save Config to save the changes to the startup configuration.
After creating a monitor, activate it by assigning it to one or more DataPower
services.

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. The traffic
for every business partner 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.

Enabling statistics
To enable statistics, use the following procedure:
1. Click Administration Device Statistics Settings.
2. Set Admin State to enabled.
3. Click Apply to save the changes to the running configuration.
4. Optional: Click Save Config to save the changes to the startup configuration.

Configuring Web services monitors

To
1.
2.
3.

configure a Web services monitor, use the following procedure:

Click Object Monitoring Web Services Monitor.
Click Add.
Provide the following inputs:
Name Specify the name of the object.

220

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

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/*.
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.

5. Click Add.
Chapter 10. Managing monitors

221

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
7. Click Apply to save the changes to the running configuration.
8. Optional: Click Save Config to save the changes 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 only type error. In which case, messages of type low would
not be included in the log. The default log accepts messages of only type error.
To specify dual thresholds, use the following procedure:
1. Define the first (low) threshold:
a. Click Add.
b. Select First Limit in Threshold Level.
c. Provide the Threshold Value.
d. Select the Threshold Action.
e. Click Save.
2. Define the second (high) threshold

222

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

a.
b.
c.
d.
e.

Click Add.
Select Second Limit in Threshold Level.
Provide the Threshold Value.
Select the Threshold Action.
Click Save.

3. Click Apply to save the changes to the running configuration.

4. Optional: Click Save Config to save the changes to the startup configuration.

Chapter 10. Managing monitors

223

224

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

Appendix A. Referenced objects

Creating AAA Policy objects
1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.

Select Objects XML Processing AAA policy.

Click Add.
On the Main tab, define the general configuration.
On the Identify tab, define how to extract the identity.
On the Authenticate tab, define how to authenticate the identity.
On the Map Credentials tab, define how to how to map the credential.
On the Resource tab, define how to extract the resource.
On the Map Resource tab, define how to map the resource.
On the Authorize tab, define how to authorize the credential.
Optional: On the Post Processing tab, define post processing activities.
Optional: On the Namespace Mapping tab, define how to map namespaces.

12. Optional: On the SAML Attributes tab, define SAML attributes.

13. Optional: On the LTPA User Attributes tab, define LTPA user attributes.
14. Optional: On the Transaction Priority tab, define the priority of transactions.
15. Click Apply to save the changes to the running configuration.
16. Optional: Click Save Config to save the changes 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
Optional: 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 Configuring count monitors
on page 216 for more information.
Rejected counter
Optional: 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 Configuring count monitors on page 216 for
more information.
SAML Signature Validation Credentials
Optional and only if the AAA policy uses SAML-based identity extraction,
authentication, or authorization: Select the Crypto Validation Credentials to
validate digitally-signed SAML assertions from the Credentials list. Refer
to Validation credentials on page 28 for more information.
Copyright IBM Corp. 2002, 2009

225

SAML Message Signing Key

Optional and only if the AAA policy uses SAML-based identity extraction,
authentication: Select the Crypto Key to sign SAML assertions. Refer to
Defining Key objects on page 23 for more information.
SAML Message Signing Certificate
Optional and only if the AAA policy uses SAML-based identity extraction,
authentication: 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 19 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.
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.

226

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

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.
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
Appendix A. Referenced objects

227

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.
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

228

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

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 21 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 Setting
namespace data for XPath bindings on page 248 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
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.

Appendix A. Referenced objects

229

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.
Optional: Click Save Config to save the changes 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:

230

Host

Specify the IP address or domain name of the LDAP

authentication server.

Port

Specify the LDAP authentication server port number. If not

supplied, defaults to the canonical port number.

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

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
Configuring a load balancer group on page 278 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.

(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.
v If on, the WebGUI displays the following field.
off

Appendix A. Referenced objects

231

LDAP Search Parameters

Select the LDAP Search Parameters from the list. Refer to
Defining LDAP Search Parameters objects on page 270
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
client entropy before Base64 encoding. Use an integer in the range
of 8 through 128. The default is 32.

232

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

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:
Host

Specify the IP address or domain name of the Netegrity

authentication server.
Appendix A. Referenced objects

233

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
362 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 Creating Tivoli Access Manager objects on page 255
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.

234

IBM WebSphere DataPower XML Integration Appliance XI50: 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 Validation credentials on page
28 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 Validation credentials on page 28 for
more information.
The following inputs are displayed for all methods.

Appendix A. Referenced objects

235

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. Optional: Click Save Config to save the changes 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:

236

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

TFIM Configuration
Select an existing TFIM object. Refer to Creating TFIM objects
on page 256 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. Optional: Click Save Config to save the changes 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

237

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. Optional: Click Save Config to save the changes 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. Optional: Click Save Config to save the changes to the startup configuration.

238

IBM WebSphere DataPower XML Integration Appliance XI50: 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

239

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:

240

IBM WebSphere DataPower XML Integration Appliance XI50: 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
362 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)
c (Control)

r (Read)
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

241

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 Creating Tivoli
Access Manager objects on page 255 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.

242

IBM WebSphere DataPower XML Integration Appliance XI50: 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

243

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 Defining a XACML PDP on page
261 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.

244

IBM WebSphere DataPower XML Integration Appliance XI50: 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. Optional: Click Save Config to save the changes to the startup configuration.

Post Processing tab

After authorizing the client, an AAA policy can perform post processing activities.
You can define one or more of the following post processing activities:
v Run a custom post processing style sheet
v Generate a SAML assertion that contains an authentication statement for the
authenticated identify
v Include an AP-REQ token to act as a Kerberos client
v Process a WS-Trust SecurityContextToken (SCT) request
v Add a WS-Security UsernameToken to the message
v Generate an LTPA token
v Generate a Kerberos SPNEGO token
v Request a Tivoli Federated Identity Manager (TFIM) token map
v Generate an ICRX token for z/OS identity propagation

Appendix A. Referenced objects

245

For more information about these activities, refer to Post processing activities on
page 183.

Defining post processing activities

To define one or more post processing activities:
1. Click the Post Processing tab.
2. Define a post processing activity.
a. Select the check box associated with the activity to define.
b. Define the properties for this activity. Refer to the online help for additional
information.
3. Repeat the previous step to define another post processing activity.
4. Click Apply to save the changes to the running configuration.
5. Optional: Click Save Config to save the changes 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. Optional: Click Save Config to save the changes to the startup configuration.

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.

246

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

4. Click Save to return to the AAA Policy Configuration (SAML Attributes).

5. Click Apply to commit AAA Policy properties.
6. Optional: Click Save Config to save the changes 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.
Refer to Setting namespace data for XPath bindings on page 248 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.
Appendix A. Referenced objects

247

4. Click Save to return to the catalog.

Setting namespace data for 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.

Adding LTPA user attributes

To
1.
2.
3.

add name-value pairs to the LTPA token, use the following procedure:
Click LTPA User Attributes to display the catalog.
Click Add to display the LTPA User Attributes window.
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

248

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

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 data for XPath bindings on page 248 for more information.

Using an AAA Info file

An AAA Info file can be selected as the method for the following phases of an
AAA policy:
v Authenticate
v Map Credentials
v Map Resource
v Authorize

Structure of an AAA Info file

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">
</xsd:element>
<xsd:element name="Authorize" type="tns:AuthorizeType"
maxOccurs="unbounded">
</xsd:element>

Note: An 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 + (create) and ... (modify)
buttons. Clicking either button launches the AAA Info file editor. Refer to AAA
Info file editor on page 250 for more information.
Note: The AAA Info file can be edited outside of the AAA Info file editor and
uploaded to the appliance.

Appendix A. Referenced objects

249

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.
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 section in
an AAA Info file. 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.

250

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

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.
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
Appendix A. Referenced objects

251

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.
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.

252

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

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.
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 Integration

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.

Appendix A. Referenced objects

253

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 Tivoli Access Manager 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)
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 Tivoli Access Manager 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

254

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

the file entry in the [configuration-database] stanza defines the location of

the obfuscated version of the configuration file on the appliance.
Creating Tivoli Access Manager configuration files on the appliance: To create a
TAM configuration file:
1. Select Administration Miscellaneous IBM Tivoli Access Manager Tools.
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 Tivoli Access Manager 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.
2. Click Add to display the configuration pane.
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.
3) Click Save.
c. If necessary, repeat the previous step to create another replica.
5. Click Apply to save the changes to the running configuration.
6. Optional: Click Save Config to save the changes to the startup configuration.

Refreshing Tivoli Access Manager 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.
2.
3.
4.
5.

Click the Refresh Tivoli Access Manager Client Certificate tab.

Define the operational properties. Refer to the online help for details.
Click Refresh Tivoli Access Manager Client Certificate.
Follow the prompts.

Appendix A. Referenced objects

255

IBM Tivoli Federated Identity Manager Integration

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, 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 TFIM objects

To create and configure a TFIM object, use the following procedure:
1. Select Objects Access Settings IBM Tivoli Federated Identity Manager.
2. Click Add to display the configuration pane.
3. Use this pane to specify operational parameters.
a. Specify the name for the object in the Name field.
b. Retain the default setting for Admin State. To place in an inactive
administrative state, click disabled.
c. Optional: In the Comment field, enter a descriptive summary.
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.
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.

256

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

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.
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.
Appendix A. Referenced objects

257

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.

4. Click Apply to save the changes to the running configuration.

5. Optional: Click Save Config to save the changes to the startup configuration.

Kerberos objects
A basic description of the Kerberos authentication protocol is helpful for
understanding the support provided by the DataPower appliance.
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

258

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

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.
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.

Configuring a Kerberos KDC Server object

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.
Appendix A. Referenced objects

259

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 changes to the running configuration.
5. Optional: Click Save Config to save the changes to the startup configuration.

Configuring a Kerberos Keytab File object

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:
1. Select Objects Crypto Kerberos Keytab.
2. Click Add to display the configuration pane.
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 changes to the running configuration.
5. Optional: Click Save Config to save the changes to the startup configuration.

260

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

XACML Policy Decision Point objects

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.

Defining a XACML PDP

Use
1.
2.
3.

the following procedure to configure an XACML Policy Decision Point (PDP).

Select Objects Access Settings XACML Policy Decision Point.
Click Add to display the configuration pane.
In the Name field, enter the name for the object.

4. Retain the default setting for Admin State. To place in an inactive

administrative state, click disabled.
5. Optional: In the Comment field, enter a descriptive summary.
6. 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.
7. In the General Policy File field, specify the location of the top-level XACML
policy-set.
This property is meaningful only if Evaluate Individual Policies Equally is
set to off.
8. From the Dependent Policies Combining list, select the policy combining
algorithm.
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

Appendix A. Referenced objects

261

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.
This property is meaningful only if Evaluate Individual Policies Equally is
set to on.
9. Use the Dependent Policy Files field with the Add and Delete buttons to
construct a list of dependent policy files.
Policy sets can be local or remote to the appliance; use local or standard URLs
to locate files.
10. 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.
11. In the XACML Policies Cache Lifetime field, type an integer in the range
from 0 through 2678400 to specify the time, in seconds, to maintain compiled
XACML policies in the PDP cache. The default value of 0 specifies that
policies in the cache never expire.
12. Click Apply to save the changes to the running configuration.
13. Optional: Click Save Config to save the changes to the startup configuration.

Controlling the PDP cache

There are several ways to control the cache.
Explicitly clear the cache
Use the clear pdp cache command to clear the cache.
Specify the TTL for the PDP
During PDP configuration, 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 command. This command also clears the compiled XACML
policies that are referenced by AAA polices that are supported by the XML
manager.

262

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

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

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/BasicProfile1.1.html
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. In the Name field, enter the name for the object.
4. Retain the default setting for Admin State. To place in an inactive
administrative state, click disabled.
Appendix A. Referenced objects

263

5. Optional: In the Comment field, enter a descriptive summary.

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
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.

264

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

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.

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.
Appendix A. Referenced objects

265

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 changes to the running configuration.

20. Optional: Click Save Config to save the changes 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.
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.

266

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

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 changes to the running configuration.
6. Optional: Click Save Config to save the changes 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.
Admin State
Retain the default setting. To place the object in an inactive
administrative state, click disabled.
Comments
Specify a descriptive object-specific summary.

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
Appendix A. Referenced objects

267

XML (Default) Input is treated literally, no processing

4. Click Apply to save the changes to the running configuration.
5. Optional: Click Save Config to save the changes to the startup configuration.

IMS Connect
An IMS Connect object handles IMS protocol communications from a DataPower
service 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.
2. Click Add.
3. In the Name field, enter the name for the object.
4. Retain the default setting for Admin State. To place in an inactive
administrative state, click disabled.
5. Optional: In the Comment field, enter a descriptive summary.
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. In the Maximum Segment Size field, enter an integer in the range of 0 to 32
to specify the maximum segment size in kilobytes. The default is 0 which
disables segmentation.
v A Maximum Segment Size of 0 disables IMS message segmenting. With
message segmenting disabled, you must use a policy to handle an IMS
message with a segmented payload and with LL and ZZ segment headers.
v A Maximum Segment Size in the range from 1 to 32 enables message
segmenting and specifies the maximum segment size. The IMS message is
split into multiple segments of the specified size to send to IMS. A
multi-segment message from IMS is transformed into a message with one
continuous payload. Request side processing adds the LL and ZZ segment
headers. Response side processing removes the LL and ZZ segment headers.
The headers are handled the same for a message with a payload smaller
than the Maximum Segment Size.
11. Use the Expect LLLL Response Header toggle to indicate whether the
response message includes an extra 4-byte (LLLL) response message header
specifying the total response message size back from IMS Connect. The default
is off.

268

on

Indicates a response message with a 4 byte LLLL header field.

off

(Default) Indicates a response message without the initial LLLL

header.

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

12. 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 41 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 41 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.
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.

Appendix A. Referenced objects

269

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.
13. Click Apply to save the changes to the running configuration.
14. Optional: Click Save Config to save the changes to the startup configuration.

Defining LDAP Search Parameters objects

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.
2. Click Add to display the configuration pane.
3. In the Name field, enter the name for the object.
4. Retain the default setting for Admin State. To place in an inactive
administrative state, click disabled.
5. Optional: In the Comment field, enter a descriptive summary.
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.
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 [email protected], the LDAP search
filter would be [email protected].
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
[email protected], the LDAP search filter would be
(&([email protected])(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.

270

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

11. Click Apply to save the changes to the running configuration.

12. Optional: Click Save Config to save the changes to the startup configuration.

Load balancer groups

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 remote server for a
DataPower service or can be used to provide failover support for LDAP or IMS
Connect servers. A request to connect to a load balancer group results in the
selection of a healthy server to receive an incoming client request.
Figure 12 shows the load balancer group with four members

DataPower
appliance

Load Balancer
Group

Application
server A

Application
server B

Application
server C

Application
server D

Figure 12. Load balancer group with static members to support load balancing

Depending on the algorithm that makes load-balancing decisions, each load

balancer group can support 64 or 512 members. The following algorithms support
64 members:
v Least connections
v Weighted least connections
v Weighted round robin

Intelligent load distribution

Intelligent load distribution uses a load balancer group to distribute workload
more efficiently across application servers by providing the ability to dynamically
change configuration data about membership, weight of members, and session
affinity.
Note: The ability to use intelligent load distribution requires the Option for
Application Optimization feature.
To implement intelligent load distribution, you need to define a configuration on
the DataPower appliance and install an application on the deployment manager of
a WebSphere Application Server cell.
v On the DataPower appliance, you need to define a load balancer group that
references a WebSphere cell configuration.
Appendix A. Referenced objects

271

v On the deployment manager of a WebSphere Application Server cell, you need

to install the WebSphere On Demand Configuration (ODCInfo) application.
Figure 13 shows the required configuration.

DataPower
appliance

WebSphere
Cell

WebSphere Application Server

cell
Deployment
manager

ODCInfo

Load Balancer
Group

Figure 13. Configuration to support intelligent load distribution

The communication between the DataPower appliance and the cell in the
WebSphere environment is as follows:
1. The ODCInfo application retrieves data about the application servers in the cell.
2. The WebSphere cell configuration retrieves the information from the ODCInfo
application and updates the data in the load balancer group.
3. The load balancer group uses this data to adapt to changing traffic conditions
and application server capabilities to optimally distribute traffic among the
application servers in the cell.
If your application server must maintain session affinity, you can configure session
affinity to override load balancing decisions.

Required software
For dynamic membership and weights to work, you must install WebSphere
Application Server Network Deployment or WebSphere Virtual Enterprise.
v For WebSphere Application Server Network Deployment, an administrator uses
the WebSphere Administrative Console to manually update the membership and
weight information of application servers.
v For WebSphere Virtual Enterprise, membership and weight information is
updated dynamically based on runtime conditions. To enable dynamic updates,
an administrator uses the WebSphere Administrative Console to enable dynamic
workload management.

Advantages with WebSphere servers

After enabling intelligent load distribution for a load balancer group of WebSphere
servers, the load balancer group can take advantage of the following features:
v The ability to dynamically update membership. This feature addresses the
addition or removal of WebSphere servers in the WebSphere cell.

272

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

v The ability to dynamically update the weight of members to adapt to changes in

traffic conditions. This feature addresses the following conditions:
When an application server is overloaded, its weight is reduced to receive less
traffic
When an application server is under utilized, its weight is increased to receive
more traffic
v The ability to use the weighted algorithm to optimally distribute traffic to
application servers.
v Automatic session affinity configuration based on the WAS DM configuration as
well as the ability to override this configuration

Advantages with non-WebSphere servers

After enabling intelligent load distribution for a load balancer group of
non-WebSphere servers, the load balancer group can take advantage of the
following features:
v The ability to use the weighted least connection algorithm to optimally
distribute traffic to application servers.
v The ability to use session affinity through explicit configuration on the
DataPower appliance.
This type of load balancer group cannot take advantage of the ability to
dynamically update membership or weight of members.

Algorithms for making load balancing decisions

Load balancer groups use algorithms to make load balancing decisions. The
decision determines to which remote server to forward a new connection.
Load balancer groups support weighted and non-weighted algorithms:
v
v
v
v
v
v

First alive
Hash
Least connections
Round robin
Weighted least connections
Weighted round robin

A weighted algorithm uses weight (or preference) to help determine which server
receives the next request. A server with a higher weight receives more traffic than
one with a lower weight. The percentage of traffic that is sent to each server is
approximately equal to its weight divided by the cumulative weight of all servers
in the group.
A non-weighted algorithm assumes that the capacity of all servers in the group to
be equivalent. Although non-weighted algorithms are typically faster than
weighted algorithms, some non-weighted algorithms, such as the hash algorithm,
could send more traffic to some servers. If there are servers with different
capacities in the group, processing cannot optimize the capacities of all the servers.

First alive
The first alive algorithm uses the concept of a primary server and backup servers.
v The primary server is the first server in the members list.
Appendix A. Referenced objects

273

v A backup server is any subsequent server in the members list.

When the primary server is healthy, the DataPower service forwards all
connections to this server. When the primary server is quarantined or convalescent,
the DataPower service forwards connections to the next server in the list.

Hash
The hash algorithm 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 only Multi-Protocol
Gateway and Web Service Proxy services. Additionally, this property is available
on only the Main tab in the object view.
With the hash algorithm, the same client is served by the same server. Use this
algorithm for applications that require the storage of server-side state information,
such as cookies.

Least connections
The least connections algorithm maintains a record of active server connections and
forward a new connection to the server with the least number of active
connections.

Round robin
The round robin algorithm maintains a list of servers and forwards a new
connection to the next server in the members list.

Weighted least connections

The weighted least connections algorithm maintains a weighted list of application
servers with their number of active connections and forwards a new connection to
an application server based on a combination of its proportion to the weight (or
preference) and number of active connections.
This algorithm uses more computation times than the least connection algorithm.
However, the additional computation results in distributing the traffic more
efficiently to the server that is most capable of handling the request.
This algorithm applies to application servers, not authentication or authorization
servers, and requires the Option for Application Optimization feature.

Weighted round robin

The weighted round robin algorithm maintains a weighted list of servers and
forwards new connections in proportion to the weight (or preference) of each
server.
This algorithm uses more computation times than the round robin algorithm.
However, the additional computation results in distributing the traffic more
efficiently to the server that is most capable of handling the request.

274

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

Membership
A load balancer group generally contains two or more members. Members can be
defined through static or dynamic membership.

Static membership
A load balancer group that uses a static membership configuration contains the
configuration settings that an administrator on the DataPower appliance explicitly
defined and persisted. These configuration settings do not change except under the
following conditions:
v The processing of a style sheet changes configuration settings for group
members
v An administrator enables and configures the workload management feature

Dynamic configuration
A load balancer group that uses a dynamic membership configuration retrieves
membership data through the workload management feature. To create a dynamic
membership configuration, you need to enable and configure the workload
management feature.
Even after enabling and configuring the workload management feature, a firmware
load uses the persisted configuration. Only after retrieving the workload
management information and updating the membership of the load balancer group
can the load balancer group use dynamic weight and membership information in
any load balancing decision.
When enabled, the load balancer group retrieves runtime information from the
WebSphere On Demand Configuration (ODCInfo) application. This information
overrides the membership information in the running configuration of the load
balancer group. The retrieved workload management information alters the
membership and weight of application server members in the load balancer group
so that the load balancer group can route traffic to the application server that can
best handle the load.
As new servers are brought online or as existing servers are taken offline, the
membership information in the load balancer group adapts to these changes.

Health checks
A health check is essentially a scheduled rule that sends the same request to each
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.

Health states of members

The health of each member of a load balancer group is one of the following states:
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, its health state is up.
Appendix A. Referenced objects

275

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,
its 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
Convalescent: Optionally, you can associate a periodic health check with a load
balancer group. If the health check fails, the server is convalescent. The server is not
considered to be healthy until it passes a health check. When convalescent, its
health state is down.
While convalescent, the server is:
v Removed from the server pool
v Ineligible to receive forwarded client requests

Session affinity
Session affinity overrides the load-balancing algorithm by directing all requests in
a session to a specific application server. For some applications to work correctly,
the application requires session affinity between the client and the application
server.
Session affinity enhances application performance by using in-memory caching, not
a database. Session affinity uses cookies to track session information and,
potentially, to maintain login credentials.
With session affinity, the application server that handles the first client request
generates session information and places it in a Set-Cookie header in the response.
The client inserts this information in a Cookie header in all future requests in this
session with this application server.
Session affinity populates these cookies with a session ID that contains the
following information:
v An identifier for the recovery of session data
v Routing information to ensure that all requests in this session are always routed
to the same application server
By default, session affinity is enabled for load balancer groups.
v For WebSphere servers, the load balancer group uses the session affinity
information provided by the application server.
v For non-WebSphere servers, you must configure session affinity.

Types of session affinity

A load balancer group supports the following types (or modes) of session affinity:
v Passive
v Active
v Active-conditional

276

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

Although session affinity applies to both static and dynamic configurations, you
must use a static configuration for active or active-conditional session affinity for
non-WebSphere servers.

Passive session affinity

Passive session affinity can be used with only WebSphere servers.
You cannot define passive session affinity in the load balancer group configuration
on the DataPower appliance. To configure passive session affinity, an administrator
must use the WebSphere Administrative Console to define passive session affinity
at the WebSphere cluster level.
In passive mode, the application server inserts the Set-Cookie header in the HTTP
response. The DataPower appliance reads and acts on this cookie for all
subsequent requests in this session from this client. The appliance does not add or
update this cookie.

Active session affinity

Active session affinity is for non-WebSphere servers that do not use cookies.
In active mode, the DataPower appliance always creates session affinity to the first
request and continues to route subsequent requests to the same application server.

Active-conditional session affinity

Active-conditional session affinity is for non-WebSphere servers that use cookies.
In active-conditional mode, the DataPower appliance recognizes when an
application server establishes session affinity by comparing the Set-Cookie header
in the response to a list of cluster-specific cookie names.
v If the response header contains a Set-Cookie header from the list, the appliance
inserts in the response an additional Set-Cookie header with routing
information.
v If the response header does not contain a Set-Cookie header from the list, the
appliance does not insert a Set-Cookie header.

Session affinity modes and where to configure

Depending on the session affinity mode to enforce and the type of application
server, you need to define the configuration differently.

Passive session affinity

Passive session affinity cannot be configured from the DataPower appliance. Use
the WebSphere Administrative Console to configure passive session affinity at the
WebSphere cluster level.

Active session affinity

Active session affinity can be configured from the DataPower appliance or from
the WebSphere Administrative Console. For active session affinity the application
servers can be WebSphere or non-WebSphere servers

Appendix A. Referenced objects

277

To configure active session affinity from the DataPower appliance, override

WebSphere cell session affinity and define the insertion cookie information (such as
name, path, and domain).

Active-conditional session affinity

Active-conditional session affinity can be configured from the DataPower appliance
or from the WebSphere Administrative Console. For active-conditional session
affinity the application servers can be WebSphere or non-WebSphere servers
Depending on the type of application server, you must define the list of
cluster-specific cookies differently.
v For WebSphere servers, define the list at the cluster level from WebSphere
Administrative Console.
v For non-WebSphere servers, define the list as part of the load balancer group
configuration from the DataPower appliance.
To configure active-conditional session affinity from the DataPower appliance,
override WebSphere cell session affinity, define the list of cookies to monitor, and
define the insertion cookie information (such as name, path, and domain).

Configuring a load balancer group

The configuration of a load balancer group consists of the following activities:
1. Click Objects Network Load Balancer Group.
2. Click Add.
3. On the Main tab, define the base configuration.
4. On the Members tab, define server members.
v Required for groups of LDAP or IMS Connect servers.
v Required for groups of non-WebSphere servers.

5.
6.
7.
8.

v Optional for groups of WebSphere servers that will use intelligent load
distribution. Requires the Option for Application Optimization feature.
Optional: On the Session Affinity tab, override the session affinity from a
WebSphere cell. Requires the Option for Application Optimization feature.
Optional: On the Health tab, define health check criteria.
Click Apply to save the changes to the running configuration.
Optional: Click Save Config to save the changes to the startup configuration.

Defining the base configuration

A base configuration create a load balancer group without members.
To define the base configuration:
1. Click Objects Network Load Balancer Group.
2. Click Add.
3. In the Name field, enter the name for the object.
4. Retain the default setting for Admin State. To place in an inactive
administrative state, click disabled.
5. Optional: In the Comment field, enter a descriptive summary.
6. From the Algorithm list, select the algorithm to select the actual server.
7. Optional: In the Damp Time field, enter the number of seconds that a server
remains in an softdown state. This setting does not impact servers that are in
the down state.

278

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

8. Optional: Set Do not Bypass Down State to on to disable connection

forwarding to any member. This setting makes the next connection attempt
when at least one member is in the up state.
9. Optional: Set Try Every Server Before Failing to on to send the request to
each server until one responds or all fail. Each server that fails is set to the
softdown state.
10. Optional: Set Masquerade as Group Name to on to use the name of the load
balancer group, not the host name of the member, in the message header.
11. Click Apply to save the changes to the running configuration.
12. Optional: Click Save Config to save the changes to the startup configuration.
With the base configuration, you might need to define static members. You must
define static members for the following groups of servers:
v Groups of LDAP servers
v Groups of IMS Connect servers
v Groups of application servers that do not retrieve workload management
information through the ODCInfo application
For configuration details, refer to Adding static members.
For groups of WebSphere servers that retrieve workload management information
through the ODCInfo application, you can optionally define static members.
However, after retrieving the workload management information from the
WebSphere cell, static members are disabled.

Adding static members

To add static members to an existing load balancer group:
1. Click Objects Network Load Balancer Group.
2. Click the name of the load balancer group to modify.
3. Click the Members tab.
4. Add static members.
a. Click Add.
b. In the Actual Host field, enter the IP address or the domain-qualified host
name of the member.
c. For weighted algorithms: In the Weight field, enter the relative weight
(preference). The greater the value, the more likely this server is to receive a
connection request.
d. In the Mapped Server Port field, enter the member-specific target port or
retain the default value to use the DataPower service-defined port.
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.
e. In the Health Port field, enter the member-specific health port or retain the
default value to use the load balancer group-defined port.
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 tab.
f. Retain the default setting for Admin State. To place in an inactive
administrative state, click disabled.
Appendix A. Referenced objects

279

g. Click Save.
5. Repeat the previous step to add another server as a static member.
6. Click Apply to save the changes to the running configuration.
7. Optional: Click Save Config to save the changes to the startup configuration.

Overriding session affinity in a WebSphere cell

If you use non-WebSphere application servers and you need session affinity, you
can override session affinity from the WebSphere cell. When overriding session
affinity, you can use either active or active-conditional session affinity.

Before you begin

Determine the type of session affinity that your non-WebSphere application server
needs (active or active-conditional). Configure a load balancer group with members
that are non-WebSphere application servers.

About this task

Modify a load balancer group to support session affinity for non-WebSphere
application servers.
This functionality requires the Option for Application Optimization feature.

Procedure
1. Click Network Other Load Balancer Group
2. Click the name of load balancer group.
3. Click the Session Affinity tab.
4. Set the Override WebSphere Cell Configuration check box. The pane refreshes
to display additional parameters.
5. From the Mode list, select the type of session affinity.
6. For active-conditional: Define the cookies to monitor.
a. In the Monitored Cookies field, enter the name of the cookie to monitor.
b. Click Add
7. Optional: Repeat the previous step to add another cookie. The configuration
requires at least one cookie.
8. Click Apply to save the changes to the running configuration information.
9. Click Save Config to save the changes to the startup configuration.

Results
Session affinity is enabled for non-WebSphere application servers.

Defining health checks

To define the health check:
1. Click Objects Network Load Balancer Group.
2.
3.
4.
5.

280

Click the name of a load balancer group to modify.

Click the Health tab.
Set Enabled to on.
For standard health checks: In the URI field, enter 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.

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

6. In the Remote Port field, enter the port on the target server to receive the
query.
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.
7. From the Health Check Type list, select the type of health check to perform.
8. Optional for standard health checks: Set Send SOAP Request? to off to access
the target URI with an HTTP GET operation instead of the default HTTP
POST operation.
9. For SOAP requests with an HTTP POST operation: In the SOAP Request
Document field, enter the location (URL) of the SOAP message to send as the
request.
10. In the Timeout field, enter the number of seconds to wait for the completion
of the health check.
11. In the Frequency field, enter the number of seconds between health checks.
12. For standard health checks: Define the filter for a valid server response.
a. In the XPath Expression, enter the XPath expression that must be found in
a valid server response. Use the XPath tool to help define the expression.
b. In the XSL Health Check Filter field, enter the location (URL) of the style
sheet to filter the server response.
13. Optional for standard health checks: From the SSL proxy profile list, select
the SSL proxy profile to provide for a secured connection.
14. Click Apply to save the changes to the running configuration.
15. Optional: Click Save Config to save the changes to the startup configuration.

Modifying to use workload management information

Modify the configuration of a load balancer group to request workload
management information from the ODCInfo application on the WebSphere
deployment manager.

Before you begin

Configure a load balancer group.

About this task

Configure the load balancer group to request workload management information
from the ODCInfo application. The load balancer groups uses the WebSphere Cell
configuration to gather information about the application servers in the WebSphere
cell. The WebSphere Cell configuration that is referenced by the load balancer
group forwards this information to the load balancer group.
Note: Until the load balancer group successfully receives the workload
management information from the ODCInfo application, it uses the
members defined as part of its running configuration.

Procedure
1. Click Objects Network Settings Load Balancer Group.
2. Click the name of the load balancer group to modify.
Appendix A. Referenced objects

281

3. Modify a load balancer group to use the workload management information

from the WebSphere cell (WebSphere deployment manager).
a. Set Retrieve Workload Management Information to on. The WebGUI
refreshes to display additional properties.
b. From Workload Management Retrieval list, select WebSphere Cell.
c. From WebSphere Cell Subscription list, select a WebSphere Cell
configuration.
d. In Workload Management Group Name field, enter the name of the
WebSphere cluster.
4. Review the session affinity information on the Session Affinity tab to ensure
that session affinity is correctly configured.
5. Click Apply to save the changes to the running configuration information.
6. Click Save Config to save the changes to the startup configuration.

Results
The load balancer group begins to request information from the ODCInfo
application.

Assigning weight to members

A load balancer group uses the weight of its members when making load
balancing decisions based on a weighted algorithm. Weight is not relevant for a
load balancer group the uses a non-weighted algorithm.
To assign weight to members.
1. Click Objects Network Load Balancer Group.
2. Click the name of the load balancer group to modify.
3. Click the Members tab.
4. Change the weight for a specific member.
a. Click the pencil icon to edit the member.
b. In the Weight field, change the value.
c. Click Save.
5. Repeat the previous step to modify another member.
6. Click Apply to save the changes to the running configuration.
7. Optional: Click Save Config to save the changes to the startup configuration.

Disabling members
If you need to disable a member, you can disable the member from the load
balancer group without deleting the member from the group.
To disable specific members to not participate in load balancing decisions:
1.
2.
3.
4.

282

Click Objects Network Load Balancer Group.

Click the name of the load balancer group to modify.
Click the Members tab.
Disable members.
a. Click the pencil icon to edit the member.
b. Set Admin State to disable to place the member in an inactive
administrative state.
c. Click Save.

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

5. Click Apply to save the changes to the running configuration.

6. Optional: Click Save Config to save the changes to the startup configuration.

Enabling the retrieval of workload management information

For WebSphere application servers, complete the following procedure to install and
configure the WebSphere On Demand Configuration (ODCInfo) application. When
installed, the ODCInfo application help provide intelligent load distribution
through the retrieval of workload management information.

Before you begin

Identify the types of application servers in your WebSphere cell (WebSphere
Application Server) environment. Download the following ODCInfo files
v ODCInfo_ND60.war
v ODCInfo_ND61.war
v ODCInfoCheckInstall.jacl
v ODCInfoDeploy.jacl
v ODCInfoStart.jacl
v ODCInfoUninstall.jacl
from the directory /AO on your CD-ROM or Fix Central.

About this task

Install and configure the ODCInfo application on the deployment manager of the
WebSphere cell.

Procedure
1. Install the ODCInfo application on the deployment manager.
2. Start the ODCInfo application.
3. Create or modify a load balancer group to use the ODCInfo application to
retrieve workload management information from the WebSphere cell.

Installing the ODCInfo application

Use a script to install the ODCInfo application on the WebSphere deployment
manager. The ODCInfo application provides runtime information to the load
balancer group on the DataPower appliance to optimize dynamic load distribution.

Before you begin

Ensure the WebSphere Application Server product is installed and is running
before installing the ODCInfo application.
Note: Uninstall any previous version of the ODCInfo application before installing
another version.

About this task

Install the ODCInfo application on the application server that contains the
deployment manager for a cell. The ODCInfo application collects information
about application servers in the cluster, such as changes in weights or if an
application server was added or removed from the cluster.

Appendix A. Referenced objects

283

Procedure
1. Copy the ODCInfo.war file, ODCInfoCheckInstall.jacl, ODCInfoStart.jacl, and
ODCInfoDeploy.jacl to a local directory on the deployment manager.
2. Choose the Web archive file that matches the version of WebSphere Application
Server product.
v For version 6.0.x, use ODCInfo_ND60.war
v For version 6.1.x or version 7.0.x, use ODCInfo_ND61.war
3. Log in from the command line to the deployment manager.
4. Navigate to the /bin directory under the deployment manager profile. For
example:
cd /opt/IBM/WebSphere/AppServer/profiles/Dmgr01/bin
5. Install the ODCInfo application by entering:
./wsadmin.sh -f script_path/ODCInfoDeploy.jacl dmgr_server_name
dmgr_node_name path_to_war_file ODCInfo
For example:
./wsadmin.sh -f /tmp/ODCInfoDeploy.jacl dmgr wasnode2CellManager01
/tmp/ODCInfo_ND61.war ODCInfo
6. Verify the installation by entering:
./wsadmin.sh -f script_path/ODCInfoCheckInstall.jacl cellName
dmgr_server_name ODCInfo
A message is displayed indicating whether the application is installed.
7. Ensure that you define the host name and port for the ODCInfo application as
a host_alias for the default_host under WebSphere Application Server virtual
hosts.

What to do next
Start the ODCInfo application.

Starting the ODCInfo application

Start the ODCInfo application to begin collecting the remote host information, such
as weights or if a host was added or deleted.

Before you begin

The ODCInfo application must be installed and running on the deployment
manager of the WebSphere cell (WebSphere environment).

About this task

Start the ODCInfo application to begin collecting information about the application
servers in the WebSphere cell (WebSphere environment).

Procedure
1. Copy ODCInfoStart.jacl to a local directory on the deployment manager.
2. Log in from the command line to the deployment manager.
3. Navigate to the /bin directory under the deployment manager profile.

284

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

cd /opt/IBM/WebSphere/AppServer/profiles/Dmgr01/bin
4. Start the application by entering:
./wsadmin.sh -f script_path/ODCInfoStart.jacl cellName
dmgr_node_name ODCInfo
For example:
./wsadmin.sh -f /tmp/ODCInfoStart.jacl dpblade34Cell01
dpblade34CellManager01 ODCInfo
5. Verify that the ODCInfo application started.
a. Log in to the WebSphere Administrative Console.
b. Click Applications Enterprise Applications.

What to do next
Create or modify a DataPower load balancer group.

Uninstalling the ODCInfo application

To remove the ODCInfo application from the deployment manager, run the
ODCInfoUninstall script.

About this task

Before installing a new version of the ODCInfo application, you must uninstall the
old version.

Procedure
1. Copy the ODCInfoCheckUninstall.jacl file to a local directory on the
WebSphere deployment manager.
2. Log in from the command line to the deployment manager.
3. Navigate to the bin directory of the deployment manager profile. For example:
cd /opt/IBM/WebSphere/AppServer/profiles/Dmgr01/bin
4. Uninstall the application by entering:
./wsadmin.sh -f script_path/ODCInfoUninstall.jacl cellName
dmgr_server_name ODCInfo
For example:
./wsadmin.sh -f /tmp/ODCInfoUninstall.jacl wasnode2Cell01 dmgr
ODCInfo
5. Verify by entering:
./wsadmin.sh -f script_path/ODCInfoCheckInstall.jacl cellName
dmgr_server_name ODCInfo
The response indicates success or failure.

What to do next
Install the ODCInfo application.

Appendix A. Referenced objects

285

Defining Matching Rule objects

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. In the Name field, enter the name for the object.
4. Retain the default setting for Admin State. To place in an inactive
administrative state, click disabled.
5. Optional: In the Comment field, enter a descriptive summary.
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.

(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.
c. Define the matching criteria.
off

d. Click Save.
Repeat this step to define another matching rule.
9. Click Apply to save the changes to the running configuration.
10. Optional: Click Save Config to save the changes to the startup configuration.

MTOM Policy
The message transmission optimization mechanism (MTOM) policy provides a way
to optimize the transmission and wire format of an XML/SOAP message.
Optimization is performed by selecting elements with Base64 encoded character
data. The selected elements are decoded and attached as MIME attachment parts
before transmission. Decoding before transmission reduces the overhead that is
associated with Base64 encoded data.
To use an MTOM policy with a DataPower service:
1. Define a processing policy that includes a transform action for the MTOM
operation.
2. In the transform action:
a. Click the Use XSLT specified in this action radio button.
b. Specify the location of the MTOM processing control file; for example,
store:///mtom.xsl.
c. On the Advanced tab, select the MTOM policy that becomes the stylesheet
parameter for the transform action.
To create an MTOM policy:
1. Click Objects XML Processing MTOM policy.

286

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

2. Click Add.
3. In the Name field, enter the name for the object.
4. Retain the default setting for Admin State. To place in an inactive
administrative state, click disabled.
5. Optional: In the Comment field, enter a descriptive summary.
6. From the MTOM Mode, select the optimization mode.
7. Optional: Set Include Content Type to off to disable the inclusion of the
xmlmine:contentType declaration in output messages when the input message
does not contain this declaration. If the input message contains this
declaration, the MTOM policy passes through the attribute regardless of this
setting.
8. Click the MTOM Rules tab to add MTOM rules.
9. Add an MTOM rule.
a. Click Add.
b. In the XPath Expression field, enter the XPath expression that defines a
schema element or elements to be subject to this rule. Alternatively, click
XPath Tool to launch the builder.
c. Optional: In the Content Type field, enter the Content Type for the
extracted data elements. This setting overrides the value from the
xmlmime:contentType attribute. If the provided XPath expression matches
more than one element, each corresponding MIME attachment part will
contain a Content-Type header with this value. If different Content-Type
values are required, selective expressions are required.
d. Optional: In the Content ID field, enter the explicit value for the
Content-ID header. If not explicitly configured, Content-ID headers are
automatically generated. This setting allows for the explicit configuration
of Content-ID headers and their associated href values. Rules that match
multiple data elements result in one attachment part for all matched
elements. The resulting attachment part contains data from the last match
only.
e. Click Apply.
10. Repeat the previous step to add another MTOM rule.
11. Click Apply to save the changes to the running configuration.
12. Optional: Click Save Config to save the changes to the startup configuration.

Multi-Protocol Gateway object

Click Objects Service Configuration Multi-Protocol Gateway.
Click Add.

Configuring basic operations

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.

Appendix A. Referenced objects

287

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 5, Handler configuration, on
page 47 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 360 for more
information.
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.

288

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

This property is relevant only when the value defined by the algorithm for
the Load Balancer Group is hash.
Process Message Whose Body is Empty
Whether to force the processing of XML messages when their message
body is empty or missing in RESTful Web services.
Processing Policy
Select a Processing Policy. Refer to Chapter 6, Processing policies, on
page 81 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.
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 342 for more information.
SSL Proxy
Optionally assign an SSL Proxy Profile to this Gateway. Refer to SSL
Proxy Profile objects on page 26 for more information.
Crypto Credentials
Optionally assign a Firewall Credentials List. Refer to Defining Firewall
Credentials objects on page 21 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.
Appendix A. Referenced objects

289

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
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.

290

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

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.
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

Appendix A. Referenced objects

291

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.
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

292

Identifies the message as unencapsulated XML.

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

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.
XML

Identifies the message as unencapsulated XML.

Flow Control
Enable (on) or disable (off) flow control support. Use flow control to
manage the transmission of large files when the front side and back end
have different latencies and throughput while in streaming mode. This
option is available when the client traffic type and the server traffic type
are Non-XML or Pass-Thru. By default, flow control is disabled.
Note: The streaming behavior for output to back and output to front must
be set to Stream Messages. Also, if either the front side or the back
end will use the HTTP(S) protocol, Allow Chunked Uploads must
be set to on.
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.

Appendix A. Referenced objects

293

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
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
Optional: Use the list with the Add and Delete buttons to assign one or
more Web services monitors to this DataPower service. Refer to
Configuring Web services monitors on page 220 for more information.
Count Monitors
Optional: Use the list with the Add and Delete buttons to assign one or
more count monitors to this DataPower service. Refer to Configuring
count monitors on page 216 for more information.
Duration Monitors
Optional: Use the list with the Add and Delete buttons to assign one or

294

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

more duration monitors to this DataPower service. Refer to Configuring

duration monitors on page 218 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.
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.
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.

Appendix A. Referenced objects

295

XML Maximum Distinct Prefixes

Specifies the maximum number of distinct XML namespace prefixes in a
document. Only available when parser limits are enabled.
XML Maximum Distinct Namespaces
Specifies the maximum number of distinct XML namespace URIs in a
document. Only available when parser limits are enabled.
XML Maximum Distinct Local Names
Specifies the maximum number of distinct XML local names in a
document. 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.
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

296

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

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.

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.
Appendix A. Referenced objects

297

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 the online help.

WS-ReliableMessaging tab
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.
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

298

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

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
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.

Appendix A. Referenced objects

299

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 seconds 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.
Use any value of 2 - 600. The default is 10.
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.
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.

300

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

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. Use any value of 10 3600. The default is 360.
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
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.
Appendix A. Referenced objects

301

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
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.

302

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

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
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.
Appendix A. Referenced objects

303

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.
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.

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

304

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

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-secpolCertificate 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 changes to the running configuration.
5. Optional: Click Save Config to save the changes 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.
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.
Appendix A. Referenced objects

305

4. Click Apply to save the changes to the running configuration.

5. Optional: Click Save Config to save the changes to the startup configuration.

Defining Processing Action objects

Use the following procedure to define global, reusable Processing Action objects.
1. Select Objects XML Processing Processing Action.
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.
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.
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.

306

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

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.
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.

Appendix A. Referenced objects

307

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
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

308

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

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).
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.

Transform
Use when the Action Type is filter, route-action, xform, xformbin, or
xformpi.

Appendix A. Referenced objects

309

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 from which to generate the
dynamic style sheet; for example, a Document Crypto Map object.
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.
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.

310

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

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
in the XML payload, used during processing. This does not
change the destination of the output.
Refer to URL Rewrite Policy on page 342 for more information.
AAA Policy
Use when the Action Type is aaa to select the AAA Policy
implemented by this Processing Action. Refer to Creating AAA Policy
objects on page 225 for more information.
SLM Policy
Use when the Action Type is slm to select the SSL Policy implemented
by this Processing Action. Refer to Service level monitors on page 320
for more information.
Appendix A. Referenced objects

311

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 319 for more information.
Dynamic Stylesheet
Optional when the Action Type is filter, route-action, xform,
xformbin, or xformpi. Select the object from which to generate the
dynamic style sheet; for example, a Document Crypto Map object.
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 266 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.
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 267 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.

312

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

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 SSL Proxy Profile objects on page 26 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.
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.
Appendix A. Referenced objects

313

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.
4. Click Save to return to the Processing Action Configuration (Stylesheet
Parameter) screen.
5. Click Apply to save the changes to the running configuration.
6. Optional: Click Save Config to save the changes 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

314

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

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 changes to the running configuration.
6. Optional: Click Save Config to save the changes 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.

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.
Appendix A. Referenced objects

315

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.

Defining Processing Policy objects

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.
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.
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
the style sheet URL or retain the default value, store:///filter-rejectall.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.
4. On the Policy Map tab, define the policy maps.
5. Click Apply to save the changes to the running configuration.
6. Optional: Click Save Config to save the changes to the startup configuration.

Policy Maps tab

A policy map is a matching rule/processing rule pair in a processing policy. A
processing policy can contain multiple policy maps.
1. Click the Policy Maps tab.
2. Define policy maps.

316

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

a. Click Add.
b. From the Match list, select a matching rule. Refer to Defining Matching
Rule objects on page 286 for more information.
c. From the Rule list, select a processing rule. Refer to Defining Processing
Rule objects for more information.
d. Click Save.
3. If necessary, repeat the procedure to add additional maps to the processing
policy.

Defining Processing Rule objects

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.
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.
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.
Appendix A. Referenced objects

317

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 changes to the running configuration.
5. Optional: Click Save Config to save the changes to the startup configuration.

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.

318

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

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 Admin State. To place in an inactive
administrative state, click disabled.
b. Optional: In the Comment field, enter a descriptive summary.
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.
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 changes to the running configuration.
6. Optional: Click Save Config to save the changes 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.

Appendix A. Referenced objects

319

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
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 changes to the running configuration.
6. Optional: Click Save Config to save the changes to the startup configuration.

Service level monitors

A service level monitor (SLM) provides precise specification of user and resource
groups to be subject to administrative control and possible sanction. An SLM
consists of an SLM policy that includes one or more statements. The SLM policy
processes these statements in their configured order. If a statement generates a
rejection, the message is filtered (dropped). After a rejection, the policy does not
attempt to process subsequent statements.
Each SLM statement can consists of:
v An SLM credential class that defines the users (credentials) to be subject to
policy restrictions. Without a credential class, the appliance considers all
messages as belonging to a single global user. Therefore, the statement applies to
all messages that are identified as valid resources without respect to credential
class.

320

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

v An SLM resource class that defines a resources to be subject to policy

restrictions. Without a resource class, the statement applies to all messages that
pass the credential classification.
v An SLM schedule that specifies the time frame to enforce the policy. Without a
schedule, the policy is in enforcement mode at all times. The interval is fixed
and starts at 12:00 AM.
v An SLM action that specifies control procedure for transactions that exceed the
threshold
v A threshold that defines the limit (maximum transactions per second) before
triggering the action
Unlike message (count and duration) monitors and Web services monitors, SLMs
are not directly assigned to a DataPower service. SLMs are implemented as part of
a processing policy.

Creating an SLM policy

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. Each appliance in the
group includes traffic that has passed through the other peers to calculate whether
a threshold was reached. Refer to Defining peer groups on page 324 for more
information.
To create an SLM Policy:
1. Click OBJECT Monitoring SLM Policy.
2. Click Add.
3. In the Name field, enter the name for the object.
4. Retain the default setting for Admin State. To place in an inactive
administrative state, click disabled.
5. Optional: In the Comment field, enter a descriptive summary.
6. From the Evaluation Method list, select the operational behavior.
7. Optional: From the Peer Group list, select the multi-appliance group that
enforces traffic destined for the same resources. Refer to Defining peer
groups on page 324 for information.
8. Click the Statement tab, and add a policy statement.
a. Click Add.
b. In the Identifier field, enter a unique, positive integer that indicates the
order in which to process the statement.
c. Optional: In the User Annotation field, enter a value to appear in log
messages.
d. Optional: From the Credential Class list, select the credentials class that
defines the group of users to be subject to the policy. Refer to Creating an
SLM credentials class on page 322 for information.
e. Optional: From the Resource Class list, select the resource class that
defines the group of resources to be subject to the policy. Refer to
Creating an SLM resource class on page 323 for information.
f. Optional: From the Schedule list, select the schedule that defines the time
frame to enforce the policy. Refer to Defining an SLM schedule on page
324 for information.

Appendix A. Referenced objects

321

g. From the SLM Action list, select the action that defines the administrative
action for messages that exceed the threshold. Refer to Defining an SLM
action on page 324 for information.
h. Define thresholds.
1) In the Threshold Interval Length field, enter the length of each
measurement interval in seconds. The default is 0, which allows all
messages and never triggers the threshold to enforce the action.
2) From the Threshold Interval Type list, select how to measure intervals.
3) From the Threshold Algorithm list, select the methodology that
calculates the threshold.
4) From the Threshold Type list, select how to apply the threshold to the
monitored count or latency.
5) In the Threshold Level field, enter the threshold that triggers the
action.
6) In the High-Low Release Level field, if the algorithm is high-low, enter
the low threshold (stop point).
7) In the Burst Limit field, if the algorithm is token bucket, enter the size
of the committed burst.
i. Define reporting intervals.
1) In the Reporting Aggregation Interval field, enter the interval at which
to report statistics.
2) In the Maximum Records Across Intervals field, enter the maximum
aggregation of reporting records. A single aggregation interval can
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 intervals.
j. Auto Generated by GUI is read-only.
k. In the Maximum Credentials-Resource Combinations field, enter the
maximum number of records for credential and resource combinations to
set a maximum memory-consumption threshold.
l. Click Save.
9. Repeat the previous step to define another statement.
10. Click Apply to save the changes to the running configuration.
11. Optional: Click Save Config to save the changes to the startup configuration.

Creating an SLM credentials class

An SLM credentials class identifies a set of users (credentials) to be subject to an
SLM policy. An SLM credentials class consists of:
v A credential type that specifies the manner to obtain user credentials
v A match type that determines to which credentials to apply the SLM policy
v Depending on the credential and match type, properties that identify specific
instances of credentials
To create an SLM credentials class:
1. Click Objects Monitoring SLM Credential Class.
2. Click Add.
3. In the Name field, enter the name for the object.
4. Retain the default setting for Admin State. To place in an inactive
administrative state, click disabled.

322

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

5. Optional: In the Comment field, enter a descriptive summary.

6. From the Credential Type list, select the manner to obtain credentials.
7. From the Match Type list, select the matching algorithm that determines to
which credentials to apply an SLM policy.
8. In the Credential Value field, if the matching algorithm is for an regular
expression or exact match, enter a value and click Add to create the list of
values.
9. In the Custom Style Sheet field, if the credential type is for a custom style
sheet, enter the location of the style sheet.
10. In the Request Header field, if the credential type is for a header, enter the
name of the header.
11. Click Apply to save the changes to the running configuration.
12. Optional: Click Save Config to save the changes to the startup configuration.

Creating an SLM resource class

An SLM resource class identifies a set of resources to be subject to an SLM policy.
An SLM resource class consists of:
v A resource type that specifies the manner to identify resources
v A match type that determines to which resources to apply the SLM policy
v Depending on the resource and match type, properties that identify specific
instances of resources
To create an SLM resource class:
1. Click OBJECT Monitoring SLM Resource Class.
2. Click Add.
3. In the Name field, enter the name for the object.
4. Retain the default setting for Admin State. To place in an inactive
administrative state, click disabled.
5. Optional: In the Comment field, enter a descriptive summary.
6. From the Resource Type list, select the manner to identify resources.
7. From the Match Type list, select the matching algorithm that determines to
which resources to apply an SLM policy.
8. In the Resource Value field, if the matching algorithm is for an regular
expression or exact match, enter a value and click Add to create the list of
values.
9. In the Custom Style Sheet field, if the resource type is for a custom style
sheet, enter the location of the style sheet.
10. In the UDDI Subscription field, if the resource type is a UDDI subscription,
enter the subscription key.
11. From the WSRR Subscription list, if the resource type is a WSRR
subscription, select the subscription.
12. In the XPath Filter field, if the resource type is an XPath expression, enter the
expression. Alternatively, click XPath Tool to define the expression.
13. Click Apply to save the changes to the running configuration.
14. Optional: Click Save Config to save the changes to the startup configuration.

Appendix A. Referenced objects

323

Defining an SLM action

An SLM action defines the control procedure to trigger for transactions in excess of
the maximum transaction rate. As part of any control procedure, the monitor
writes an event to the log for each transaction that exceeds a threshold.
To create an SLM action:
1. Click OBJECT Monitoring SLM Action.
2. Click Add.
a. In the Name field, enter the name for the object.
b. Retain the default setting for Admin State. To place in an inactive
administrative state, click disabled.
c. Optional: In the Comment field, enter a descriptive summary.
d. From the Type list, select the control procedure (action) to trigger.
e. From the Log Priority list, select the priority (severity) to assign to the event
that is written to the log.
3. Click Apply to save the changes to the running configuration.
4. Optional: Click Save Config to save the changes to the startup configuration.

Defining an SLM schedule

An SLM schedule defines the time period (hours and days) during which to
enforce the statements in an SLM policy. Schedules allow the application of
different statements during different time periods.
To create an SLM schedule:
1. Click OBJECT Monitoring SLM Schedule.
2. Click Add.
3. In the Name field, enter the name for the object.
4. Retain the default setting for Admin State. To place in an inactive
administrative state, click disabled.
5. Optional: In the Comment field, enter a descriptive summary.
6. Define the time period to enforce the statement.
a. From the Week Day list, select the check boxes to define the days of the
week to enforce the statement. The time and duration apply to all selected
days. To define a weekend schedule, select Saturday and Sunday.
b. In the Start Time field, enter the start time to enforce the schedule in the
current timezone. Use the 24-hour format (hh:mm:ss). To enforce from 8:00
AM to 8:30 PM, enter 08:00:00.
c. In the Duration field, enter the number of minutes to enforce the schedule.
To enforce from 8:00 AM to 8:30 PM, enter 750.
7. Click Apply to save the changes to the running configuration.
8. Optional: Click Save Config to save the changes to the startup configuration.

Defining peer groups

A peer group is a collection of DataPower appliances that enables the exchange of
service level data among a group. This data exchange provides for the enforcement
of SLM policies across multiple appliances. To exchange data at periodic interval,
peer members must:
v Have identical SLM configurations, including the members list.

324

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

v Use the XML Management Interface to exchange data as SOAP over HTTPS.
Update messages (SOAP over HTTPS) with the new information is aggregated
in the information store of each peer member.
v Be clock-synchronized. You can use the NTP service. For information about the
NTP service, refer to the IBM WebSphere DataPower XML Integration Appliance
XI50: Administrators Guide.
To define a peer groups:
1. Click Objects Network Peer Groups.
2. Click Add.
3. In the Name field, enter the name for the object.
4. Retain the default setting for Admin State. To place in an inactive
administrative state, click disabled.
5. Optional: In the Comment field, enter a descriptive summary.
6. In the Type field. retain the default value (SLM).
7. In the URL field, enter the URL to communicate with the peer member and
click Add.
8. Click Apply to save the changes to the running configuration.
9. Optional: Click Save Config to save the changes to the startup configuration.

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.

Appendix A. Referenced objects

325

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.
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 changes to the running configuration.
6. Optional: Click Save Config to save the changes 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 policy.
Note: SQL-ODBC is a licensed feature that is not available on all DataPower
appliances.
A SQL data source provides the configuration to establish a direct connection to a
database instance on a remote data server. When configured, it is possible to
dynamically perform database operations, such as SELECT and INSERT, on the
remote database instance.
A SQL data source is used by a SQL action in a processing policy. The SQL action
retrieves the data for further processing by the processing policy. Conversely, the
processing policy can store the processed data in the configured database instance.
When configuring a SQL data source you can 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.

326

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

High-level configuration
To
1.
2.
3.

create a SQL data source:

Click Objects Network Setting SQL Data Source.
Click Add.
On the Main tab, define the basic configuration.

4. Optional: On the Data Source Configuration Parameters tab, define optional

but valid ODBC (or CLI) configuration parameters.
5. Click Apply to save the changes to the running configuration.
6. Optional: Click Save Config to save the changes to the startup configuration.

Defining the base configuration

To define the base configuration for a SQL data source:
1. Click Objects Network Setting SQL Data Source.
2. Click Add.
3. In the Name field, enter the name for the object.
4. Retain the default setting for Admin State. To place in an inactive
administrative state, click disabled.
5. Optional: In the Comment field, enter a descriptive summary.
6. From the Database Type list, select a database vendor.
7. Define the connection details:
a. In the Connection User Name field, enter the user name to establish the
connection. The data server maintains this information, not the appliance.
b. In the Connection Password field, enter the password for the user.
c. For an Oracle data source: From the Oracle Identifier Type list, select the
type of identifier.
d. In the Data Source ID field, depending on the type of database, enter the
database alias, the database name, or the identifier for the data source.
e. In the Data Source Host field, enter the IP address or host name of the
data server where the data source resides.
f. In the Data Source Port field, enter the listening port of the data source.
8. Optional: Set the data size limit that a SQL SELECT statement can return.
Without an explicit limit, the default is 128 kilobytes.
a. Set Limit Returned Data to on to enable limiting.
b. In the Returned Data Size Limit field, enter the data size limit in
kilobytes.
9. Optional: Set Allow Read-Only Access to on to allow read-only access to the
data source.
10. Optional: in the Maximum Connections field, enter the maximum number of
concurrent connections to allow.
11. Click Apply to save the changes to the running configuration.
12. Optional: Click Save Config to save the changes to the startup configuration.

Adding configuration parameters

Configuration parameters modify the behavior of the services that run with a data
server.
To add configuration parameters to an existing SQL data source:
1. Click Objects Network Setting SQL Data Source.
Appendix A. Referenced objects

327

2. Click the name of the SQL data source to modify.

3. Click the Data Source Configuration Parameters tab.
4. Define a configuration parameter:
a. Click Add.
b. In the Name field, enter the name of the parameter.
c. In the Value field, enter the value for the parameter.
d. Click Save.
5. Optional: Repeat step 4 to define another configuration parameter.
6. Click Apply to save the changes to the running configuration.
7. Optional: Click Save Config to save the changes to the startup configuration.

TIBCO EMS servers

Note: TIBCO EMS is a licensed feature that is not available on all DataPower
appliances.
The TIBCO EMS server provides messaging services for applications that
communicate by monitoring queues. The TIBCO EMS server ensures that sent
messages are directed to the correct receive queue or ensures that messages are
routed to another queue manager.

Using map message

The DataPower appliance performs the following roles to support TIBCO EMS
Map Message:
v Consumer of TIBCO EMS Map Message
v Producer of TIBCO EMS Map Message
You can configure the maximum bytes scanned, parsing depth, attribute count, and
node size to use to parse map messages in the XML parser of the domain XML
manager.
Consuming TIBCO EMS map messages is automatic when a service has a TIBCO
EMS Front Side Handler. For more information, see Consuming TIBCO EMS map
message on page 76.

Producing TIBCO EMS map messages

As a producer of map messages, the appliance converts an XML stream of a
predefined format into a TIBCO EMS Map Message and sends the message to the
TIBCO EMS server. No binary transformation is required. The Map Message is
generated using XML only.
The DataPower appliance produces TIBCO EMS Map Messages when the
DP_JMSMessageType header is specified in any of the following ways:
v Use a service object with a TIBCO EMS backend. The request header must
contain the name-value pair DP_JMSMessageType: map.
v Use any service object with a processing policy with a Results action or a Results
Asynchronous action configured as follows:
The destination is set to tibems:// or dptibems://
The context header var://context/CONTEXT_NAME/_extension/header/
DP_JMSMessageType is set to the value map

328

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

v Use any service object with a processing policy that contains a style sheet with a
soap-call extension function. The soap-call must use the HTTP-headers
parameter to set the DP_JMSMessageType header as in the following example:
<xsl:template match="/*">
<xsl:variable name="httpHeaders">
<header name="DP_JMSMessageType">map</header>
</xsl:variable>
<xsl:variable name="result"
select="dp:soap-call('http://x.xx.xx.xxx:nnnn/soapcalltest',
$call/*,'',0,'',$httpHeaders/*)"/>
<xsl:copy-of select="$result"/>
</xsl:template>

v Use any service object with a processing policy that contains a style sheet with a
url-open extension function. The url-open must use the HTTP-headers parameter
the same way as it is specified for the soap-call extension function.
v

Use a TIBCO EMS Front Side Handler object to send a response to a response
queue. The response header must contain the name-value pair
DP_JMSMessageType: map.

Note: In each case, if the DP_JMSMessageType header is not set, the message is
not converted to the map message format. Instead, XML is sent as the
TIBCO EMS Text or Byte Message.

Formatting TIBCO EMS map messages

The TIBCO EMS map message requests must conform to the following XML
schema:
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
<!-- Message element -->
<xs:element name="Message">
<xs:complexType>
<xs:sequence>
<xs:element ref="Field" minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>
<xs:unique name="unique-name">
<xs:selector xpath="Field"/>
<xs:field xpath="@name"/>
</xs:unique>
</xs:element>
<!-- Field element -->
<xs:element name="Field">
<xs:complexType mixed="true">
<xs:complexContent>
<xs:restriction base="xs:anyType">
<xs:choice minOccurs="0">
<xs:element ref="Message" maxOccurs="1"/>
<xs:element ref="Array"
maxOccurs="1"/>
</xs:choice>
<xs:attribute name="name" type="xs:string" use="required"/>
<xs:attribute name="type" use="required">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:enumeration value="bool"/>
<xs:enumeration value="byte"/>
<xs:enumeration value="char"/>
<xs:enumeration value="short"/>
<xs:enumeration value="int"/>
<xs:enumeration value="long"/>
<xs:enumeration value="float"/>
<xs:enumeration value="double"/>
Appendix A. Referenced objects

329

<xs:enumeration
<xs:enumeration
<xs:enumeration
<xs:enumeration
<xs:enumeration
<xs:enumeration
<xs:enumeration
<xs:enumeration
</xs:restriction>
</xs:simpleType>
</xs:attribute>
</xs:restriction>
</xs:complexContent>
</xs:complexType>
</xs:element>

value="bytes"/>
value="string"/>
value="short_array"/>
value="int_array"/>
value="long_array"/>
value="float_array"/>
value="double_array"/>
value="map_message"/>

<!-- Array element -->

<xs:element name="Array">
<xs:complexType>
<xs:sequence>
<xs:element ref="Element" maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<!-- Element of array-->
<xs:element name="Element">
<xs:complexType mixed="true">
<xs:sequence/>
</xs:complexType>
</xs:element>
</xs:schema>

The following example shows the XML representation of a TIBCO EMS Map
Message:
<Message>
<!-- nested map message #1 -->
<Field name="map1" type="map_message">
<Message>
<Field name="an_empty1_double_array" type="double_array"/>
<Field name="an_empty1_long_array" type="long_array"/>
<Field name="an_empty1_short_array" type="short_array"/>
<Field name="floaty" type="float">100000.00</Field>
<Field name="map11" type="map_message">
<Message>
<Field name="int_array" type="int_array">
<Array>
<Element>100000</Element>
<Element>2147483647</Element>
<Element>-2147483647</Element>
<Element>2147483648</Element>
<Element>-2147483649</Element>
<Element></Element>
<Element>BOGUS</Element>
</Array>
</Field>
<Field name="map111" type="map_message">
<Message/>
</Field>
<Field name="stringy" type="string">This is a quick brown fox.</Field>
</Message>
</Field>
<Field name="map12" type="map_message">
<Message/>

330

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

</Field>
</Message>
</Field>
<!-- nested map message #2 -->
<Field name="map2" type="map_message">
<Message>
<Field name="booly" type="bool">True</Field>
<Field name="map21" type="map_message">
<Message/>
</Field>
<Field name="the_bytes" type="bytes">RnJvbSBNb3Njb3cgV2l0aCBMb3ZlCg==</Field>
</Message>
</Field>
<!-- one short array -->
<Field name="short_array" type="short_array">
<Array>
<Element>5146</Element>
<Element>32767</Element>
<Element>-32767</Element>
<Element>32768</Element>
<Element>-32769</Element>
<Element></Element>
<Element>BOGUS</Element>
</Array>
</Field>
<!-- one short field -->
<Field name="shorty" type="short">5146</Field>
</Message>

Transactional messaging
Many times in asynchronous messaging, there is a one-way message flow
paradigm. A message is picked up off a queue or topic, multistep processing runs,
and the message is put on a backside queue or topic. With transactional messaging,
if the backside PUT or any PUT in multistep processing fails, the front-side GET is
rolled back.
Another common message pattern is message fanout. In this case, a message is
picked on the front side and sent to several output queues. With transactional
messaging, if any of these multiple PUT operations fails, the original message is
rolled back on the front side.
To support transactional messaging in these message patterns, use the same TIBCO
EMS session to perform all the operations within the DataPower transaction. To
share the same TIBCO EMS session, receive messages from and deliver messages
to the same TIBCO EMS server.
The following sections describe the requirements to configure transactional
messaging for different scenarios.

Single TIBCO EMS session to receive and send

The following conditions are required to use the same transacted TIBCO EMS
session to receive a TIBCO EMS request on front side of the service and to send it
on the back side:
v Configure the TIBCO EMS Server object with the Transactional property enabled.
v Configure the service with a TIBCO EMS Front Side handler and a TIBCO EMS
backend URL.
Appendix A. Referenced objects

331

v For the handler and the backend URL, use the same TIBCO EMS Server object
with the Transactional property enabled.
v Define the TIBCO EMS URL using the Transactional=true parameter. For
example:
dptibems://TIBCOEMSServer?RequestQueue=OUTQUEUE&Transactional=true

With this configuration, the TIBCO EMS Front Side handler and the TIBCO EMS
backend URL share the same TIBCO EMS transacted session. A single COMMIT or
ROLLBACK operation is issued depending on the processing result. This
guarantees once-and-only-once message delivery to TIBCO EMS messages.

Single TIBCO EMS session with commit

The following conditions are required to perform a COMMIT operation upon
successful send operation on the back side:
v Configure the TIBCO EMS Server object with the Transactional property enabled.
v Configure the service with a TIBCO EMS Front Side handler and a TIBCO EMS
backend URL.
v For the handler and the backend URL, use the same TIBCO EMS Server object
with the Transactional property enabled.
v Define the TIBCO EMS URL using the Sync=true parameter. For example:
dptibems://TIBCOEMSServer?RequestQueue=OUTQUEUE&ReplyQueue=BACK_INQUEUE&Sync=true

This configuration uses the same transacted TIBCO EMS session from TIBCO EMS
to the TIBCO EMS service object for these operations:
1. Receive messages on the front side
2. Send messages on the back
3. Perform a COMMIT or ROLLBACK operation immediately after sending the
request message on the back side.
If the TIBCO EMS Front Side handler is configured with a put queue property, the
reply message from the back response queue is received as a part of a new
transaction. In other words, there are two TIBCO EMS unidirectional transactions:
1. The first transaction carries the message from the front side request queue to
back side request queue.
2. The second transaction carries the reply message from back side response
queue for front side response queue.

Shared TIBCO EMS session in message fanout

The following conditions are required to receive a TIBCO EMS request on the front
side of the service and to send the request using a results action, dp:url-open or
dp:soap-call extension function using the same transacted TIBCO EMS session. The
results action, dp:url-open or dp:soap-call extension function could be a part of a
request, a response, or an error rule.
v Configure the TIBCO EMS Server object with the Transactional property enabled.
v Configure the service with a TIBCO EMS Front Side handler.
v Configure a processing policy with at least one action that uses a TIBCO EMS
URL open call such as a results action, a dp:url-open or a dp:soap-call extension
function.
Note: Asynchronous actions do not support the TIBCO EMS transacted session.
v Configure all URL open calls with the Transactional=true parameter.

332

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

v Configure the TIBCO EMS Front Side handler and all TIBCO EMS URL open
calls using the same TIBCO EMS server object with the Transactional property
enabled.
v Optional: Use a TIBCO EMS backend URL defined with the Transactional=true
parameter.
In this configuration, the same transacted TIBCO EMS session receives the message
on the front side and sends the message using either a results action or a
dp:url-open extension function and optionally sends on the backend URL. The
TIBCO EMS transacted session is shared not only between the TIBCO EMS Front
Side handler and the TIBCO EMS Backend URL, but also between any TIBCO EMS
URL open calls used in the processing policy.
A single COMMIT or ROLLBACK operation is issued depending on processing
result. This guarantees once-and-only-once message delivery to the TIBCO EMS
messages. All calls to the TIBCO EMS server use the same shared transacted
session.

Shared TIBCO EMS session in message fanout with commit

The following conditions are required to perform a COMMIT operation upon
successful send operation on any Results action, dp:url-open or dp:soap-call
extension functions. The results action, dp:url-open or dp:soap-call extension
function could be a part of either a request, a response, or an error rule.
v Configure the TIBCO EMS Server object with the Transactional property enabled.
v Configure the service with a TIBCO EMS Front Side handler.
v Configure a processing policy with at least one action that uses a TIBCO EMS
URL open call such as a results action, a dp:url-open or a dp:soap-call extension
function.
Note: Asynchronous actions do not support the TIBCO EMS transacted session.
v Specify the Sync=true parameter on TIBCO EMS URL open calls where
COMMIT or ROLLBACK should be performed immediately after the sending
message.
v Configure the TIBCO EMS Front Side handler and all TIBCO EMS URL open
calls using the same TIBCO EMS server object with the Transactional property
enabled.
v Optional: use TIBCO EMS Backend URL.
In this configuration, the same transacted JMS session receives the message on the
front side, sends the message using a processing action, and performs a COMMIT
or ROLLBACK operation immediately after sending message. The COMMIT or
ROLLBACK operation can be executed on any results action, dp:url-open or
dp:soap-call extension function which is part of the processing policy after the
request message was sent to the TIBCO EMS server. If the TIBCO EMS session is
shared between the front and back side, this COMMIT or ROLLBACK serves as an
the end of transactions for both receive and send operation.
If the TIBCO EMS URL is defined with a reply queue parameter or if the
processing policy contains any other actions that will be using the same shared
transacted TIBCO EMS session, a new transaction is created. This new transaction
will be committed or rolled back either when the processing policy finishes or
when some other action is configured with TIBCO EMS URL open call with the
Sync=true parameter.

Appendix A. Referenced objects

333

High-level configuration
When configuring the client connection to the TIBCO EMS server, you can define
the server in the following ways:
v As a unique host (without fault-tolerance or load-balancing)
v As a pair of fault-tolerant hosts
v As a group of load-balanced hosts
v As a group of load-balanced hosts with fault-tolerance
To configure a TIBCO EMS object, use the following high-level procedure:
1. Select Objects Network Settings TIBCO EMS to display the TIBCO EMS
catalog.
2. Click Add to display the TIBCO EMS configuration screen.
3. Define the basic properties on the Main tab.
4. Optionally define load-balancing and fault-tolerance behavior on the Load
Balancing/Fault-Tolerance tab.
5. Click Apply to save the changes to the running configuration.
6. Optional: Click Save Config to save the changes to the startup configuration.

Configuring as a unique host

To configure a TIBCO EMS object as a unique host, use the following high-level
procedure:
1. Select Objects Network Settings TIBCO EMS to display the TIBCO EMS
catalog.
2. Click Add to display the TIBCO EMS configuration screen.
3. In the Name field, enter the name for the object.
4. Retain the default setting for Admin State. To place in an inactive
administrative state, click disabled.
5. Optional: In the Comment field, enter a descriptive summary.
6. Define the access credentials:
a. Specify the user or account name to use to access the TIBCO EMS server
in the User Name field.
b. Specify the password for that user or account name that accesses the
TIBCO EMS server in the Password field.
c. Reenter the password in the Confirm Password field.
7. Define the message criteria:
a. Use the Transactional toggle to control transactional processing.
on

Enables transactional processing.

off
(Default) Disables transactional processing.
In a transacted session, a group of related messages are sent and received
in a single transaction.
b. Specify the memory allocation for pending messages in the Memory
Threshold field. The value is in bytes. Use an integer in the range of
1048576 through 1073741824. The default is 268435456.
c. Specify the MTU for the current TIBCO EMS server in the Maximum
Message Size field. The value is in bytes. The MTU defines the maximum
size of messages that this server can process . Messages that are larger
than the specified value are dropped. Use an integer in the range of
1048576 through 1073741824. The default is 1048576.

334

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

d. Select the default message type from the Default Message Type list. The
selected value is used when the message type cannot be determined from
message headers.
Byte

(Default) Indicates that the message payload is accessed as a Java

byte array.

Indicates that the message payload is accessed as a Java string

value.
8. Define the session and connection limits:
a. Specify the maximum number of concurrent, open connections to allow to
the server in the Total Connection Limit field. The minimum is 1. The
default is 5.
b. Specify the maximum number of concurrent multiplexed sessions that a
single connection can support in the Maximum Number of Sessions per
Connection field. The minimum is 5. The default is 20.
If the number of current connections is less than the connection limit, a new
session requests in excess of this value trigger the establishment of a new
connection to the server.
Text

For example, with default values (20 for sessions per connection, and 5 for
connection limit) and 3 active fully-subscribed connections, a new session
request generates the establishment of a fourth connection.
9. Optionally enable an automatic critical error-recovery procedure:
a. Use the Automatic Retry toggle to control whether to enable the automatic
recovery procedure. This procedure attempts to reestablish a connection
that was closed in response to an error condition.
on

(Default) Enables the automatic critical error-recovery procedure.

off
Disables the automatic critical error-recovery procedure.
b. When enabled, specify the interval between connection attempts in the
Retry Interval field. This interval is in seconds.
10. Optionally select an SSL Proxy Profile from the SSL Profile list. The SSL
Proxy Profile is used to establish a secure connection to the server. Refer to
IBM WebSphere DataPower SOA Appliances: Appliance Overview and IBM
WebSphere DataPower XML Integration Appliance XI50: XSL Accelerator
Developers Guide for details.
11. Use the Enable JMS-Specific Logging toggle to enable an enhanced
JMS-specific logging facility.
on

Enable the logging facility.

off
(Default) Disables the logging facility.
12. Specify the domain name or IP address with the listening port of the TIBCO
EMS server in the TIBCO EMS Server Host field. Specify this value in the
host:port format. Without a port specification, the default is port 7222.
13. Specify the string that identifies the connection client in the TIBCO EMS
Connection Client ID field.
14. Retain the default selection for the Load Balancing Algorithm list.
15. Click Apply to save the changes to the running configuration.
16. Optional: Click Save Config to save the changes to the startup configuration.

Configuring for fault-tolerance

To configure a TIBCO EMS object as a pair of fault-tolerant hosts, use the following
high-level procedure:
Appendix A. Referenced objects

335

1. Select Objects Network Settings TIBCO EMS to display the TIBCO EMS
catalog.
2. Click Add to display the TIBCO EMS configuration screen.
3. In the Name field, enter the name for the object.
4. Retain the default setting for Admin State. To place in an inactive
administrative state, click disabled.
5. Optional: In the Comment field, enter a descriptive summary.
6. Define the access credentials:
a. Specify the user or account name to use to access the TIBCO EMS server
in the User Name field.
b. Specify the password for that user or account name that accesses the
TIBCO EMS server in the Password field.
c. Reenter the password in the Confirm Password field.
7. Define the message criteria:
a. Use the Transactional toggle to control transactional processing.
on

Enables transactional processing.

off
(Default) Disables transactional processing.
In a transacted session, a group of related messages are sent and received
in a single transaction.
b. Specify the memory allocation for pending messages in the Memory
Threshold field. The value is in bytes. Use an integer in the range of
1048576 through 1073741824. The default is 268435456.
c. Specify the MTU for the current TIBCO EMS server in the Maximum
Message Size field. The value is in bytes. The MTU defines the maximum
size of messages that this server can process . Messages that are larger
than the specified value are dropped. Use an integer in the range of
1048576 through 1073741824. The default is 1048576.
d. Select the default message type from the Default Message Type list. The
selected value is used when the message type cannot be determined from
message headers.
Byte

(Default) Indicates that the message payload is accessed as a Java

byte array.

Text

Indicates that the message payload is accessed as a Java string

value.

8. Define the session and connection limits:

a. Specify the maximum number of concurrent, open connections to allow to
the server in the Total Connection Limit field. The minimum is 1. The
default is 5.
b. Specify the maximum number of concurrent multiplexed sessions that a
single connection can support in the Maximum Number of Sessions per
Connection field. The minimum is 5. The default is 20.
If the number of current connections is less than the connection limit, a new
session requests in excess of this value trigger the establishment of a new
connection to the server.
For example, with default values (20 for sessions per connection, and 5 for
connection limit) and 3 active fully-subscribed connections, a new session
request generates the establishment of a fourth connection.
9. Optionally enable an automatic critical error-recovery procedure:

336

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

a. Use the Automatic Retry toggle to control whether to enable the automatic
recovery procedure. This procedure attempts to reestablish a connection
that was closed in response to an error condition.
on

(Default) Enables the automatic critical error-recovery procedure.

off

Disables the automatic critical error-recovery procedure.

b. When enabled, specify the interval between connection attempts in the

Retry Interval field. This interval is in seconds.
10. Optionally select an SSL Proxy Profile from the SSL Profile list. The SSL
Proxy Profile is used to establish a secure connection to the server. Refer to
IBM WebSphere DataPower SOA Appliances: Appliance Overview and IBM
WebSphere DataPower XML Integration Appliance XI50: XSL Accelerator
Developers Guide for details.
11. Use the Enable JMS-Specific Logging toggle to enable an enhanced
JMS-specific logging facility.
on

Enable the logging facility.

off
(Default) Disables the logging facility.
12. Specify the domain name or IP address in the TIBCO EMS Server Host field.
Note: This property is a required property, but it is ignored in this
configuration.
13. Specify the string that identifies the connection client in the TIBCO EMS
Connection Client ID field.
14. Retain the default selection for the Load Balancing Algorithm list.
15. Define fault-tolerance capabilities:
a. Click the Load Balancing/Fault-Tolerance tab.
b. Click Add to display the Load Balancing/Fault-Tolerance property
window.
c. Define the fault-tolerance behavior:
1) Specify the domain name or IP address with the listening port of the
primary server in the TIBCO EMS Server Host field in the host:port
format. Without a port specification, the default is port 7222.
2) Specify the domain name or IP address with the listening port of the
backup server in the TIBCO EMS Backup Server Host field in the
host:port format. Without a port specification, the default is port 7222.
3) Click Save to return to the Load Balancing/Fault-Tolerance property
window.
d. Repeat step 15c for another fault-tolerance primary-backup server pair.
16. Click Apply to save the changes to the running configuration.
17. Optional: Click Save Config to save the changes to the startup configuration.

Configuring for load-balancing

To configure a TIBCO EMS object as a group of load-balanced hosts, use the
following high-level procedure:
1. Select Objects Network Settings TIBCO EMS to display the TIBCO EMS
catalog.
2. Click Add to display the TIBCO EMS configuration screen.
3. In the Name field, enter the name for the object.

Appendix A. Referenced objects

337

4. Retain the default setting for Admin State. To place in an inactive

administrative state, click disabled.
5. Optional: In the Comment field, enter a descriptive summary.
6. Define the access credentials:
a. Specify the user or account name to use to access the TIBCO EMS server
in the User Name field.
b. Specify the password for that user or account name that accesses the
TIBCO EMS server in the Password field.
c. Reenter the password in the Confirm Password field.
7. Define the message criteria:
a. Use the Transactional toggle to control transactional processing.
on

Enables transactional processing.

off
(Default) Disables transactional processing.
In a transacted session, a group of related messages are sent and received
in a single transaction.
b. Specify the memory allocation for pending messages in the Memory
Threshold field. The value is in bytes. Use an integer in the range of
1048576 through 1073741824. The default is 268435456.
c. Specify the MTU for the current TIBCO EMS server in the Maximum
Message Size field. The value is in bytes. The MTU defines the maximum
size of messages that this server can process . Messages that are larger
than the specified value are dropped. Use an integer in the range of
1048576 through 1073741824. The default is 1048576.
d. Select the default message type from the Default Message Type list. The
selected value is used when the message type cannot be determined from
message headers.
Byte

(Default) Indicates that the message payload is accessed as a Java

byte array.

Text

Indicates that the message payload is accessed as a Java string

value.

8. Define the session and connection limits:

a. Specify the maximum number of concurrent, open connections to allow to
the server in the Total Connection Limit field. The minimum is 1. The
default is 5.
b. Specify the maximum number of concurrent multiplexed sessions that a
single connection can support in the Maximum Number of Sessions per
Connection field. The minimum is 5. The default is 20.
If the number of current connections is less than the connection limit, a new
session requests in excess of this value trigger the establishment of a new
connection to the server.
For example, with default values (20 for sessions per connection, and 5 for
connection limit) and 3 active fully-subscribed connections, a new session
request generates the establishment of a fourth connection.
9. Optionally enable an automatic critical error-recovery procedure:
a. Use the Automatic Retry toggle to control whether to enable the automatic
recovery procedure. This procedure attempts to reestablish a connection
that was closed in response to an error condition.
on

338

(Default) Enables the automatic critical error-recovery procedure.

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

off
Disables the automatic critical error-recovery procedure.
b. When enabled, specify the interval between connection attempts in the
Retry Interval field. This interval is in seconds.
10. Optionally select an SSL Proxy Profile from the SSL Profile list. The SSL
Proxy Profile is used to establish a secure connection to the server. Refer to
IBM WebSphere DataPower SOA Appliances: Appliance Overview and IBM
WebSphere DataPower XML Integration Appliance XI50: XSL Accelerator
Developers Guide for details.
11. Use the Enable JMS-Specific Logging toggle to enable an enhanced
JMS-specific logging facility.
Enable the logging facility.

on

off
(Default) Disables the logging facility.
12. Specify the domain name or IP address in the TIBCO EMS Server Host field.
Note: This property is a required property, but it is ignored in this
configuration.
13. Specify the string that identifies the connection client in the TIBCO EMS
Connection Client ID field.
14. Select the algorithm from the Load Balancing Algorithm list:
None

(Default) Load-balancing is not enabled.

Least Connections
Creates a connection to the server that has the least number of active
connections.
Byte Rate
Creates a connection to the server that has the lowest total byte rate
(input and output).
15. Define load-balancing capabilities:
a. Click the Load Balancing/Fault-Tolerance tab.
b. Click Add to display the Load Balancing/Fault-Tolerance property
window.
c. Define the load balancing behavior:
1) Specify the domain name or IP address with the listening port of a
member server in the TIBCO EMS Server Host field in the host:port
format. Without a port specification, the default is port 7222.
2) Do not specify anything in the TIBCO EMS Backup Server Host field.
3) Click Save to return to the Load Balancing/Fault-Tolerance property
window.
d. Repeat step 15c for another server for load-balancing.
16. Click Apply to save the changes to the running configuration.
17. Optional: Click Save Config to save the changes to the startup configuration.

Configuring for load-balancing and fault-tolerance

Load-balancing takes precedence over fault-tolerance.
To configure a TIBCO EMS object as a group of load-balanced hosts with
fault-tolerance, use the following high-level procedure:
1. Select Objects Network Settings TIBCO EMS to display the TIBCO EMS
catalog.
Appendix A. Referenced objects

339

2. Click Add to display the TIBCO EMS configuration screen.

3. In the Name field, enter the name for the object.
4. Retain the default setting for Admin State. To place in an inactive
administrative state, click disabled.
5. Optional: In the Comment field, enter a descriptive summary.
6. Define the access credentials:
a. Specify the user or account name to use to access the TIBCO EMS server
in the User Name field.
b. Specify the password for that user or account name that accesses the
TIBCO EMS server in the Password field.
c. Reenter the password in the Confirm Password field.
7. Define the message criteria:
a. Use the Transactional toggle to control transactional processing.
on

Enables transactional processing.

off

(Default) Disables transactional processing.

In a transacted session, a group of related messages are sent and received

in a single transaction.
b. Specify the memory allocation for pending messages in the Memory
Threshold field. The value is in bytes. Use an integer in the range of
1048576 through 1073741824. The default is 268435456.
c. Specify the MTU for the current TIBCO EMS server in the Maximum
Message Size field. The value is in bytes. The MTU defines the maximum
size of messages that this server can process . Messages that are larger
than the specified value are dropped. Use an integer in the range of
1048576 through 1073741824. The default is 1048576.
d. Select the default message type from the Default Message Type list. The
selected value is used when the message type cannot be determined from
message headers.
Byte

(Default) Indicates that the message payload is accessed as a Java

byte array.

Indicates that the message payload is accessed as a Java string

value.
8. Define the session and connection limits:
Text

a. Specify the maximum number of concurrent, open connections to allow to

the server in the Total Connection Limit field. The minimum is 1. The
default is 5.
b. Specify the maximum number of concurrent multiplexed sessions that a
single connection can support in the Maximum Number of Sessions per
Connection field. The minimum is 5. The default is 20.
If the number of current connections is less than the connection limit, a new
session requests in excess of this value trigger the establishment of a new
connection to the server.
For example, with default values (20 for sessions per connection, and 5 for
connection limit) and 3 active fully-subscribed connections, a new session
request generates the establishment of a fourth connection.
9. Optionally enable an automatic critical error-recovery procedure:
a. Use the Automatic Retry toggle to control whether to enable the automatic
recovery procedure. This procedure attempts to reestablish a connection
that was closed in response to an error condition.

340

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

on

(Default) Enables the automatic critical error-recovery procedure.

off
Disables the automatic critical error-recovery procedure.
b. When enabled, specify the interval between connection attempts in the
Retry Interval field. This interval is in seconds.
10. Optionally select an SSL Proxy Profile from the SSL Profile list. The SSL
Proxy Profile is used to establish a secure connection to the server. Refer to
IBM WebSphere DataPower SOA Appliances: Appliance Overview and IBM
WebSphere DataPower XML Integration Appliance XI50: XSL Accelerator
Developers Guide for details.
11. Use the Enable JMS-Specific Logging toggle to enable an enhanced
JMS-specific logging facility.
on

Enable the logging facility.

off
(Default) Disables the logging facility.
12. Specify the domain name or IP address in the TIBCO EMS Server Host field.
Note: This property is a required property, but it is ignored in this
configuration.
13. Specify the string that identifies the connection client in the TIBCO EMS
Connection Client ID field.
14. Select the algorithm from the Load Balancing Algorithm list:
None

(Default) Load-balancing is not enabled.

Least Connections
Creates a connection to the server that has the least number of active
connections.
Byte Rate
Creates a connection to the server that has the lowest total byte rate
(input and output).
15. Define load-balancing and fault-tolerance capabilities:
a. Click the Load Balancing/Fault-Tolerance tab.
b. Click Add to display the Load Balancing/Fault-Tolerance property
window.
c. Define the load balancing and fault-tolerance behavior:
1) Specify the domain name or IP address with the listening port of the
primary member server in the TIBCO EMS Server Host field in the
host:port format. Without a port specification, the default is port 7222.
2) To add fault-tolerance to this member server, specify the domain name
or IP address with the listening port of the backup member server in
the TIBCO EMS Backup Server Host field in the host:port format.
Without a port specification, the default is port 7222.
3) Click Save to return to the Load Balancing/Fault-Tolerance property
window.
d. Repeat step 15c for another server for load-balancing or for another
fault-tolerance primary-backup server pair.
16. Click Apply to save the changes to the running configuration.
17. Optional: Click Save Config to save the changes to the startup configuration.

Appendix A. Referenced objects

341

Enabling heartbeat detection

To enable heartbeat detection of connections to TIBCO EMS servers (versions 4.4.0
& later), configure the following settings in the tibco.conf file on the TIBCO EMS
server. This file is read by the TIBCO EMS server.
v server_heartbeat_client = heartbeat-rate
v client_timeout_server_connection = timeout-rate
Where:
heartbeat-rate
Specifies the time interval in seconds for the server to send the DataPower
appliance a heartbeat.
timeout-rate
Specifies the amount of time in seconds for the DataPower appliance to
wait to receive a heartbeat before closing a connection to the TIBCO EMS
server. TIBCO recommends a value that is 3.5 times greater than the
heartbeat rate.
Refer to your TIBCO EMS documentation for more information on these settings.

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 Creating a URL Rewrite Policy on page 343.

342

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

Creating a URL Rewrite Policy

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.
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.

Appendix A. Referenced objects

343

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.
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

344

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

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.
5. Click Apply to save the changes to the running configuration.
6. Optional: Click Save Config to save the changes to the startup configuration.

User Agent
A user agent is a client that initiates a request for a local service to establish a
connection to a remote server. An XML manager uses a user agent, for example, to
retrieve resources from elsewhere on the network. The settings for a user agent can
affect messages that a DataPower service sends out.
The DataPower provides the default user agent in each application domain. The
configuration of the default user agent is as follows:
v Allows a maximum of eight HTTP redirect messages before declaring the target
as unreachable
v Set the idle timeout to 300 seconds before timing out and closing the connection.
The default user agent does not provide configuration for the following types of
policies:
HTTP proxy
The user agent forwards requests that match the URL expression to an
HTTP server instead of to the target server.
SSL proxy
The user agent establishes a secure connection to the remote server for
requests that match the URL expression.
Basic authentication
The user agent uses these credentials for authentication with the remote
server for requests that match the URL expression. This feature is useful
for HTTP connections.
SOAP Action
The user agent includes the specified contents in the SOAPAction header in
requests that match the URL expression.

Appendix A. Referenced objects

345

Public key authentication

The user agent uses these credentials for authentication with the remote
server for requests that match the URL expression. This feature is useful
for SCP and SFTP connections.
Allow compression
The user agent compresses the payload for requests that match the URL
expression.
Header retention
The user agent retains the specified message headers for requests that
match the URL expression.
Restrict to HTTP 1.0
The user agent restricts HTTP communication to HTTP 1.0 for requests that
match the URL expression.
Inject header
The user agent injects the specified headers into requests that match the
URL expression.
Chunked uploads
The user agent uses HTTP 1.1 Chunked content encoding for requests that
match the URL expression. This feature is useful for streaming large
documents.
FTP client
The user agent controls the client settings for outgoing FTP connections for
requests that match the URL expression. These client settings can be
overridden by query parameters in the URL that initiates the file transfer.
Each type of these policies uses URL matching patterns. When there are multiple
configurations for a policy type, the policy evaluates each candidate URL against
the matching pattern in sequential order. Therefore, order is important.
When you create a new user agent, the configuration defines these default settings.

Creating a user agent

To create a basic user agent:
1. Click Network Other User Agent.
2. Click Add.
3. In the Name field, enter the name for the object.
4. Retain the default setting for Admin State. To place in an inactive
administrative state, click disabled.
5. Optional: In the Comment field, enter a descriptive summary.
6. Optional: In the HTTP Request-Header field, enter the value the user agent
transmits as the HTTP request-header field.
7. Optional: In the Maximum Redirects field, change the maximum number of
HTTP redirect messages to allow before declaring the target as unreachable.
8. Optional: In the Timeout field, change the idle timeout to allow in seconds
before timing out and closing the connection.
9. On the Proxy Policy tab, define HTTP proxy policies.
10. On the SSL Proxy Profile Policy tab, define secure connection policies for
HTTP proxy servers.
11. On the Basic-Auth Policy tab, define basic authentication policies.

346

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

12. On the Soap-Action Policy tab, define SOAP action policies.

13. On the Pubkey-Auth Policy tab, define public key authentication policies.
14. On the Allow-Compression Policy tab, define policies that disable
compression.
15. On the Header-Retention Policy tab, define header retention policies.
16. On the Restrict to HTTP 1.0 Policy tab, define HTTP 1.0 restriction policies.
17. On the Inject Header Policy tab, define header injection policies.
18. On the Chunked Uploads Policy tab, define policies that disable HTTP 1.1
chunked content encoding.
19. On the FTP Client Policies tab, define FTP client policies.
20. Click Apply to save the changes to the running configuration.
21. Optional: Click Save Config to save the changes to the startup configuration.

Modifying the basic configuration

To modify the basic configuration of a user agent:
1. Click Network Other User Agent.
2. Click the name of an existing user agent.
3. Optional: In the HTTP Request-Header field, change the value the user agent
transmits as the HTTP request-header field.
4. Optional: In the Maximum Redirects field, change the maximum number of
HTTP redirect messages to allow before declaring the target as unreachable.
5. Optional: In the Timeout field, change the idle timeout to allow in seconds
before timing out and closing the connection.
6. Click Apply to save the changes to the running configuration.
7. Optional: Click Save Config to save the changes to the startup configuration.

Adding an HTTP proxy policy

A user agent can forward requests that meet the matching expression to an HTTP
proxy server instead of to the target server. By default, the user agent forwards
request to the target server.
To add an HTTP proxy policy to a user agent:
1. Click Network Other User Agent.
2. Click the name of an existing user agent.
3. Click the Proxy Policy tab.
4. Add a policy.
a. Click Add.
b. In the URL Matching Expression field, enter a shell-style expression to be
the pattern to match against the URL set.
c. Set Skip to on to forward request to the specified HTTP server.
d. Define the remote HTTP server to forward requests.
1) In the Remote Host field, enter the host name or IP address of the
HTTP server.
2) In the Remote Port field, enter the listening port on the HTTP server.
e. Click Save to add this policy to the list.
5. Repeat the previous step to add another policy.
6. Click Apply to save the changes to the running configuration.
Appendix A. Referenced objects

347

7. Optional: Click Save Config to save the changes to the startup configuration.
To secure the connection using SSL, add an SSL proxy policy.

Adding an SSL proxy policy

A user agent requests can require a secured (SSL-enabled) connection. The user
agent requires an SSL proxy profile to secure the connection. The SSL proxy profile
supports secure access to the HTTP proxy server. The SSL proxy profile must be
either a client or two-way profile. If the target URL matches the expression, the
connection will use the SSL proxy profile to secure the connection. Refer to SSL
Proxy Profile objects on page 26 for more information.
To
1.
2.
3.

add an SSL proxy policy to a user agent:

Click Network Other User Agent.
Click the name of an existing user agent.
Click the SSL Proxy Profile Policy tab.

4. Add a policy.
a. Click Add.
b. In the URL Matching Expression field, enter a shell-style expression to be
the pattern to match against the URL set.
c. From the SSL Proxy Profile list, select the SSL proxy profile to support
secure access to the HTTP proxy.
d. Click Save to add this policy to the list.
5. Repeat the previous step to add another policy.
6. Click Apply to save the changes to the running configuration.
7. Optional: Click Save Config to save the changes to the startup configuration.

Adding a basic authentication policy

A user agent requests require basic HTTP authentication (user name and
password). If the target URL matches this expression, an HTTP Authorization
header will be added. This header contains the supplied credentials. 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.
To add a basic authentication policy to a user agent:
1. Click Network Other User Agent.
2. Click the name of an existing user agent.
3. Click the Basic-Auth Policy tab.
4. Add a policy.
a. Click Add.
b. In the URL Matching Expression field, enter a shell-style expression to be
the pattern to match against the URL set.
c. Define credentials for authentication.
1) In the User name field, enter the name of the user.
2) In the Password and Confirm Password fields, enter the password for
the user.
d. Click Save to add this policy to the list.
5. Repeat the previous step to add another policy.
6. Click Apply to save the changes to the running configuration.

348

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

7. Optional: Click Save Config to save the changes to the startup configuration.

Adding a SOAP action policy

A user agent can require that the contents of the HTTP SOAPAction request header
field be supplied. The HTTP header contains the SOAP action (a URI that identifies
the intent of the SOAP HTTP request). If the header contains the SoapAction:
http://example.org/add header, the URI of http://example.org/add is the value.
To
1.
2.
3.
4.

add a SOAP action policy to a user agent:

Click Network Other User Agent.
Click the name of an existing user agent.
Click the Soap-Action Policy tab.
Add a policy.
a. Click Add.
b. In the URL Matching Expression field, enter a shell-style expression to be
the pattern to match against the URL set.
c. In the Soap Action field, enter the URI of the SOAP action.
d. Click Save to add this policy to the list.
5. Repeat the previous step to add another policy.
6. Click Apply to save the changes to the running configuration.
7. Optional: Click Save Config to save the changes to the startup configuration.

Adding a public key authentication policy

A user agent can use public key authentication to establish a connection to remote
resources. Public key authentication requires a private key on the appliance and a
certificate on the remote server. This feature is useful when the agent uses the SCP
or SFTP protocol.
If the private key (file and object) is not on the appliance, upload the key file to the
appliance to create a key object. The remote server must have the appropriate
certificate in $HOME/.ssh/authorized_keys directory.
Examples URL patterns include the following matching expression:
v https://server.domain.com/transactions/*
v sftp://[email protected]/images/*
v scp://user[a-c]@10.10.[0-4].23/inbound/*
To add a private key authentication policy to a user agent:
1. Click Network Other User Agent.
2. Click the name of an existing user agent.
3. Click the PubKey-Auth Policy tab.
4. Add a policy.
a. Click Add.
b. In the URL Matching Expression field, enter a shell-style expression to be
the pattern to match against the URL set.
c. From the Private Key list, select the desired private key.
d. Click Save to add this policy to the list.
5. Repeat the previous step to add another policy.
6. Click Apply to save the changes to the running configuration.
Appendix A. Referenced objects

349

7. Optional: Click Save Config to save the changes to the startup configuration.

Adding a compression policy

A user agent can compress the payload of its communications with remote
resources. Compression is useful when the payload is large. The default is to allow
compression.
To
1.
2.
3.
4.

disable an allow compression policy for a user agent:

Click Network Other User Agent.
Click the name of an existing user agent.
Click the Allow-Compression Policy tab.
Add a policy.
a. Click Add.
b. In the URL Matching Expression field, enter a shell-style expression to be
the pattern to match against the URL set.
c. Set Allow Compression to off.
d. Click Save to add this policy to the list.

5. Repeat the previous step to add another policy.

6. Click Apply to save the changes to the running configuration.
7. Optional: Click Save Config to save the changes to the startup configuration.

Adding a header retention policy

A user agent can retain certain message headers with a header retention policy.
Several DataPower services can inject or suppress HTTP headers. The user agent
operates on the message after the service. The policy can be defined to retain the
following headers:
Accept-Encoding
The HTTP Accept-Encoding request header. If selected, the traffic includes
the Accept-Encoding header independent of whether the DataPower service
specifies compression. Compressed responses are accepted.
Range

The HTTP Range request header.

TE

The HTTP TE request header.

MQMD

The WebSphere MQ MQMD header.

To
1.
2.
3.
4.

add a header retention policy to a user agent:

Click Network Other User Agent.
Click the name of an existing user agent.
Click the Header-Retention Policy tab.
Add a policy.
a. Click Add.
b. In the URL Matching Expression field, enter a shell-style expression to be
the pattern to match against the URL set.
c. From the Header Retention list, select the check boxes for the headers to
retain.
d. Click Save to add this policy to the list.

5. Repeat the previous step to add another policy.

6. Click Apply to save the changes to the running configuration.

350

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

7. Optional: Click Save Config to save the changes to the startup configuration.

Adding an HTTP 1.0 restriction policy

A user agent can restrict HTTP communications to the HTTP 1.0 specification, if
desired.
To add an HTTP 1.0 restriction policy to a user agent:
1. Click Network Other User Agent.
2. Click the name of an existing user agent.
3. Click the Restrict to HTTP 1.0 Policy tab.
4. Add a policy.
a. Click Add.
b. In the URL Matching Expression field, enter a shell-style expression to be
the pattern to match against the URL set.
c. Set Restrict to HTTP 1.0 to on.
d. Click Save to add this policy to the list.
5. Repeat the previous step to add another policy.
6. Click Apply to save the changes to the running configuration.
7. Optional: Click Save Config to save the changes to the startup configuration.

Adding a header injection policy

A user agent can inject an HTTP header (name-value pair) into a request to the
remote server. Several DataPower services can also inject HTTP headers. The user
agent operates on the request after the service.
To
1.
2.
3.

add a header injection policy to a user agent:

Click Network Other User Agent.
Click the name of an existing user agent.
Click the Inject Header Policy tab.

4. Add a policy.
a. Click Add.
b. In the URL Matching Expression field, enter a shell-style expression to be
the pattern to match against the URL set.
c. Define the header to inject.
1) In the Header Name field, enter the name of the header.
2) In the Header Value field, enter the value for the header.
d. Click Save to add this policy to the list.
5. Repeat the previous step to add another policy.
6. Click Apply to save the changes to the running configuration.
7. Optional: Click Save Config to save the changes to the startup configuration.

Adding a chunked upload policy

The user agent uses HTTP 1.1 chunked content encoding that is useful for
streaming large documents. When the appliance employs HTTP 1.1, the body of
the document can be delimited by either Content-Length or chunked encoding.
While all servers understand how to interpret Content-Length, many applications

Appendix A. Referenced objects

351

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 toward the remote server, keep this property enabled.
For chunked encoding, the remote server must be compliant with RFC 2616. This
HTTP 1.1 feature cannot be renegotiated at run time.
Several DataPower services can also control chunked uploads. The user agent
operates on the message after the service.
To
1.
2.
3.
4.

disable the chunked uploads policy for a user agent:

Click Network Other User Agent.
Click the name of an existing user agent.
Click the Chunked Uploads Policy tab.
Add a policy.
a. Click Add.
b. In the URL Matching Expression field, enter a shell-style expression to be
the pattern to match against the URL set.
c. Set Enable/Disable HTTP 1.1 Chunked Request Bodies to off.

d. Click Save to add this policy to the list.

5. Repeat the previous step to add another policy.
6. Click Apply to save the changes to the running configuration.
7. Optional: Click Save Config to save the changes to the startup configuration.

Adding an FTP client policy

A user agent can associate a set of FTP URLs with a specified policy. This policy
controls the default values of many FTP client options for outgoing FTP
connections. These settings can be further overridden by query parameters in the
URL that initiates the file transfer.
To add an FTP client policy to a user agent:
1. Click Network Other User Agent.
2. Click the name of an existing user agent.
3. Click the FTP Client Policies tab.
4. Add a policy.
a. Click Add.
b. In the URL Matching Expression field, enter a shell-style expression to be
the pattern to match against the URL set.
c. From the Passive Mode list, select how the use of FTP passive mode to
control the direction in which FTP data connections are made.
d. From the Encrypt Command Connection list, select how to control the use
of TLS to secure the FTP command connection.
e. From the Stop Command Encryption After Authentication list, 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.

352

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

f. From the Encrypt File Transfers list, select how to control the encryption of
file transfers. All setting are compatible with NAT.
g. From the Data Type list, select the default data type of file transfers. In
most cases, the default value of binary is appropriate.
h. From the Write Unique Filename if Trailing Slash list, select whether the
FTP server creates unique file names. Some FTP servers provide the STOU
command where the FTP server chooses the unique file name in the current
directory to which to write. When enabled and the URL end in a slash, the
STOU command, not the STOR command, chooses the unique file name.
Before enabling, ensure that the FTP server supports the STOU command.
i. From the Quoted Commands list, select the FTP quoted commands list to
send to the FTP server before each STOU, STOR, or RETR command.
j. From the Size Check list, select whether to perform a size check after a
transfer.
k. Click Save to add this policy to the list.
5. Repeat the previous step to add another policy.
6. Click Apply to save the changes to the running configuration.
7. Optional: Click Save Config to save the changes to the startup configuration.

WebSphere JMS servers

Note: WebSphere JMS is a licensed feature that is not available on all DataPower
appliances.
A WebSphere JMS (Java Message Service) object enables IBM JFAP (JetStream
Formats and Protocols) support for a Multi-Protocol Gateway. JFAP is used by the
default JMS provider in WebSphere Application Server (WAS). To use the
WebSphere JMS Server, you need to use WAS version 6.0.2 Fix Pack 11 (6.0.2.11) or
higher. With JFAP support, a Multi-Protocol Gateway can provide default JMS
capabilities both as a client-facing and server-facing messaging service.

Transactional messaging
Many times in asynchronous messaging, there is a one-way message flow
paradigm. A message is picked up off a queue or topic, multistep processing runs,
and the message is put on a backside queue or topic. With transactional messaging,
if the backside PUT or any PUT in multistep processing fails, the front-side GET is
rolled back.
Another common message pattern is message fanout. In this case, a message is
picked on the front side and sent to several output queues. With transactional
messaging, if any of these multiple PUT operations fails, the original message is
rolled back on the front side.
To support transactional messaging in these message patterns, use the same
WebSphere JMS session to perform all the operations within the DataPower
transaction. To share the same WebSphere JMS session, receive messages from and
deliver messages to the same WebSphere JMS server object.
The following sections describe the requirements to configure transactional
messaging for different scenarios.

Appendix A. Referenced objects

353

Single WebSphere JMS session to receive and send

The following conditions are required to use the same transacted WebSphere JMS
session to receive a WebSphere JMS request on front side of the service and to send
it on the back side:
v Configure the WebSphere JMS server object with the Transactional property
enabled.
v Configure the service with a WebSphere JMS Front Side handler and a
WebSphere JMS backend URL.
v For the handler and the backend URL, use the same WebSphere JMS server
object with the Transactional property enabled.
v Define the WebSphere JMS URL using the Transactional=true parameter. For
example:
dptibems://TIBCOEMSServer?RequestQueue=OUTQUEUE&Transactional=true

With this configuration, the WebSphere JMS Front Side handler and the WebSphere
JMS backend URL share the same WebSphere JMS transacted session. A single
COMMIT or ROLLBACK operation is issued depending on the processing result.
This guarantees once-and-only-once message delivery to WebSphere JMS
messages.

Single WebSphere JMS session with commit

The following conditions are required to perform a COMMIT operation upon
successful send operation on the back side:
v Configure the WebSphere JMS server object with the Transactional property
enabled.
v Configure the service with a WebSphere JMS Front Side handler and a
WebSphere JMS backend URL.
v For the handler and the backend URL, use the same WebSphere JMS server
object with the Transactional property enabled.
v Define the WebSphere JMS URL using the Sync=true parameter. For example:
dptibems://TIBCOEMSServer?RequestQueue=OUTQUEUE&ReplyQueue=BACK_INQUEUE&Sync=true

This configuration uses the same transacted WebSphere JMS session from
WebSphere JMS to the WebSphere JMS service object for these operations:
1. Receive messages on the front side
2. Send messages on the back
3. Perform a COMMIT or ROLLBACK operation immediately after sending the
request message on the back side.
If the WebSphere JMS Front Side handler is configured with a put queue property,
the reply message from the back response queue is received as a part of a new
transaction. In other words, there are two WebSphere JMS unidirectional
transactions:
1. The first transaction carries the message from the front side request queue to
back side request queue.
2. The second transaction carries the reply message from back side response
queue for front side response queue.

Shared WebSphere JMS session in message fanout

The following conditions are required to receive a WebSphere JMS request on the
front side of the service and to send the request using a results action, dp:url-open
or dp:soap-call extension function using the same transacted WebSphere JMS

354

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

session. The results action, dp:url-open or dp:soap-call extension function could be

a part of a request, a response, or an error rule.
v Configure the WebSphere JMS server object with the Transactional property
enabled.
v Configure the service with a WebSphere JMS Front Side handler.
v Configure a processing policy with at least one action that uses a WebSphere
JMS URL open call such as a results action, a dp:url-open or a dp:soap-call
extension function.
Note: Asynchronous actions do not support the WebSphere JMS transacted
session.
v Configure all URL open calls with the Transactional=true parameter.
v Configure the WebSphere JMS Front Side handler and all WebSphere JMS URL
open calls using the same WebSphere JMS server object with the Transactional
property enabled.
v Optional: Use a WebSphere JMS backend URL defined with the
Transactional=true parameter.
In this configuration, the same transacted WebSphere JMS session receives the
message on the front side and sends the message using either a results action or a
dp:url-open extension function and optionally sends on the backend URL. The
WebSphere JMS transacted session is shared not only between the WebSphere JMS
Front Side handler and the WebSphere JMS Backend URL, but also between any
WebSphere JMS URL open calls used in the processing policy.
A single COMMIT or ROLLBACK operation is issued depending on processing
result. This guarantees once-and-only-once message delivery to the WebSphere
JMS messages. All calls to the WebSphere JMS server use the same shared
transacted session.

Shared WebSphere JMS session in message fanout with commit

The following conditions are required to perform a COMMIT operation upon
successful send operation on any Results action, dp:url-open or dp:soap-call
extension functions. The results action, dp:url-open or dp:soap-call extension
function could be a part of either a request, a response, or an error rule.
v Configure the WebSphere JMS server object with the Transactional property
enabled.
v Configure the service with a WebSphere JMS Front Side handler.
v Configure a processing policy with at least one action that uses a WebSphere
JMS URL open call such as a results action, a dp:url-open or a dp:soap-call
extension function.
Note: Asynchronous actions do not support the WebSphere JMS transacted
session.
v Specify the Sync=true parameter on WebSphere JMS URL open calls where
COMMIT or ROLLBACK should be performed immediately after the sending
message.
v Configure the WebSphere JMS Front Side handler and all WebSphere JMS URL
open calls using the same WebSphere JMS server object with the Transactional
property enabled.
v Optional: use WebSphere JMS Backend URL.
In this configuration, the same transacted JMS session receives the message on the
front side, sends the message using a processing action, and performs a COMMIT
Appendix A. Referenced objects

355

or ROLLBACK operation immediately after sending message. The COMMIT or

ROLLBACK operation can be executed on any results action, dp:url-open or
dp:soap-call extension function which is part of the processing policy after the
request message was sent to the WebSphere JMS server. If the WebSphere JMS
session is shared between the front and back side, this COMMIT or ROLLBACK
serves as an the end of transactions for both receive and send operation.
If the WebSphere JMS URL is defined with a reply queue parameter or if the
processing policy contains any other actions that will be using the same shared
transacted WebSphere JMS session, a new transaction is created. This new
transaction will be committed or rolled back either when the processing policy
finishes or when some other action is configured with WebSphere JMS URL open
call with the Sync=true parameter.

Configuring a WebSphere JMS server

1. To begin configuration of a WebSphere JMS object, select Objects Network
WebSphere JMS to display the WebSphere JMS catalog.
2. Click Add to display the JMS Server configuration (Main) screen. Use this
panel to provide basic information required to access a remote WebSphere
JMS Server.
3. Provide the following inputs:
Name Specify the name of this WebSphere JMS Server 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.
User Name
Specify the user or account name to use to access the remote
WebSphere JMS Server.
Password
Specify the password for user or account name that accesses the
remote WebSphere JMS Server.
Confirm Password
Reenter the password.
Transactional
Use the toggle to enable or disable transactional processing.
In a transaction session, a group of related messages are sent and
received in a single transaction.
Memory Threshold
Specify an integer in the range 1048576 through 1073741824, with a
default of 268,435,456, that specifies the maximum local memory, in
bytes, that are allocated for pending messages.
Maximum Message Size
Specify an integer in the range 1048576 through 1073741824, with a
default of 1,0485,76. that specifies the MTU, in bytes, for the remote
WebSphere JMS Server. Messages larger than this specified value will
be dropped and not transmitted to the remote JMS server.

356

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

Default Message Type

Select the default JMS message type, which is provided by this
WebSphere JMS object only if the message type cannot be determined
from the JMS message headers.
Byte JMS message
(Default) Indicates that the message payload is accessed as a
Java byte array.
Text JMS message
Indicates that the message payload is accessed as a Java string
value.
Total Connection Limit
Optionally specify the maximum number of concurrent, open,
transport protocol connections between the DataPower appliance and
the remote WebSphere JMS Server.
The default value, 5 connections, specifies the maximum open
concurrent number of HTTP, HTTPS, SSL, and TCP connections. To
change the default value, specify an integer between 1 and 9.
The desirable number of sessions per connection
Optionally specify the maximum number of concurrent, open,
multiplexed sessions supported by a single transport-layer connection.
Session requests in excess of this value trigger the establishment of a
new transport-layer connection to the WebSphere JMS Server,
assuming that the number of open transport-layer connections is less
than the value specified by Total Connection Limit property.
Automatic Retry
Enable (on, the default) or disable (off) an automatic critical
error-recovery procedure that attempts to reestablish a connection that
has been broken in response to an error condition.
Retry Interval
Optionally specify the interval, in milliseconds, between connection
attempts.
Enable JMS-specific logging
Enable (on) or disable (off, the default) an enhanced
messaging-specific logging facility.
WebSphere JMS Target Transport Chain
Select the predefined transport chain provided by the WebSphere
Application Server, and used for message exchange between the
application server and the WebSphere JMS object.
Inbound Basic Messaging
(Default) Specifies the predefined InboundBasicMessaging
transport chain (JFAP-TCP/IP)
Inbound HTTP Messaging
Specifies the predefined InboundHTTPMessaging transport chain
(tunnels JFAP using HTTP wrappers)
Inbound HTTPS Messaging
Specifies the predefined InboundHTTPSMessaging transport
chain (tunnels JFAP using HTTPS wrappers)

Appendix A. Referenced objects

357

Inbound Secure Messaging

Specifies the predefined InboundSecureMessaging transport
chain (JFAP-SSL-TCP/IP)
If you have access to the WebSphere Administrative Console, you can
view transport chain information through the Application Servers
server-name Transport Chain menu.
The transport chain used for message exchange foes not need to
match the chain that is used for bootstrap access.
WebSphere JMS Messaging Bus
Specify the Service Integration Bus (SIB) used to access the remote
WebSphere Application Server.
An SIB supports applications using message-based and
service-oriented architectures. A bus is a group of interconnected
servers and clusters that have been added as members of the bus.
Applications connect to a bus at one of the messaging engines
associated with its bus members.
If you have access to the WebSphere Administrative Console, you can
view bus information, to include bus members and messaging
engines, queues and topics, and the bus-specific default topic space
through the Service integration Buses menu.
4. Click the WebSphere JMS Endpoint tab display the WebSphere JMS Endpoint
catalog (list of configured bootstrap servers).
5. Click Add to display the JMS Endpoint Property window, which you use to
specify the location of a bootstrap server.
A service integration bus (SIB) supports applications using message-based and
service-oriented architectures. A bus is a group of interconnected servers and
clusters that have been added as members of the bus. Applications connect to
a bus at one of the messaging engines associated with its bus members.
A messaging engine is a component, running inside a server, that manages
messaging resources for a bus member. Applications are connected to a
messaging engine when accessing a SIB.
Applications (such as the WebSphere JMS object) running outside the WAS
environment cannot locate directly a suitable messaging engine to connect to
the target bus. In such cases the remote clients or servers must access the bus
through a bootstrap server that is a member of the target bus.
A bootstrap server is an application server running the SIB process, but need
not be running any message engines. Rather the bootstrap server selects a
messaging engine that is running in an application server that supports the
bootstrap protocol requested by the remote appliance.
To connect to a messaging engine the remote application first connects to a
bootstrap server; the bootstrap server selects a messaging engine and then
tells the client application to connect to that message engine to gain bus
access.
A bootstrap server uses a host name or IP address, with a port number and a
bootstrap transport chain (identifying the protocol stack offered by the
bootstrap server) to define an endpoint address.
6. Provide the following inputs:
WebSphere JMS Host
Specify the host name or IP address of a WebSphere bootstrap server.

358

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

WebSphere JMS Port

Specify the port number monitored the bootstrap server for incoming
requests.
WebSphere JMS Transport Protocol
Select the predefined transport chain provided by the WAS bootstrap
server, and used for information exchange between the WebSphere
JMS object and the bootstrap server.
HTTP Specifies the predefined BootstrapTunneledMessaging
transport chain (tunnels JFAP using HTTP wrappers)
HTTPS
Specifies the predefined BootstrapTunneledSecureMessaging
transport chain (tunnels JFAP using HTTPS wrappers)

7.
8.
9.

10.

SSL

Specifies the predefined BootstrapSecureMessaging transport

chain (JFAP-SSL-TCP/IP)

TCP

(Default) Specifies the predefined BootstrapBasicMessaging

transport chain (JFAP-TCP/IP)

The protocol stack used to access the bootstrap server does not need
to be the same protocol stack that is used for actual message transfer
via the bus.
Click Save to bootstrap server identification and to return to the WebSphere
JMS Endpoint catalog.
If necessary, repeat steps 5 on page 358 to 7 to identify additional bootstrap
servers.
Is you want to establish a secure (SSL-enabled) connection between the
WebSphere JMS object and the remote WAS JMS default message provider,
click the SSL tab to display the WebSphere JMS SSL panel.
Provide the following inputs:
SSL Profile
Select an instance of the SSL Proxy Profile object to support secure
connections to the remote WebSphere server.
WebSphere JMS SSL Cipher Specification
Select the IBM cipher specification used by the assigned SSL Proxy
Profile object when establishing a secure connection to the WebSphere
server.
If you specify an SSL Proxy, the cipher suite associated with the proxy
is replaced by an IBM default cipher specification
(SSL_RSS_WITH_NULL_MD5), or with the suite specified.
Select one of the following values:
v SSL_RSA_WITH_NULL_MD5 (Default)
v SSL_RSA_EXPORT_WITH_RC2_CBC_40_MD5
v SSL_RSA_EXPORT_WITH_RC4_40_MD5
v SSL_RSA_WITH_RC4_128_MD5
v SSL_RSA_WITH_NULL_SHA
v SSL_RSA_EXPORT1024_WITH_RC4_56_SHA
v SSL_RSA_WITH_RC4_128_SHA
v SSL_RSA_WITH_DES_CBC_SHA
v SSL_RSA_EXPORT1024_WITH_DES_CBC_SHA
v SSL_RSA_FIPS_WITH_DES_CBC_SHA
v SSL_RSA_WITH_3DES_EDE_CBC_SHA
Appendix A. Referenced objects

359

v SSL_RSA_FIPS_WITH_3DES_EDE_CBC_SHA
v TLS_RSA_WITH_DES_CBC_SHA
v TLS_RSA_WITH_3DES_EDE_CBC_SHA
Summary of cipher specification descriptors:
40

key length

128

key length

CBC

Cipher Block Chaining (a mode in which every plain text

block encrypted with the block cipher is first exclusive-ORed
with the previous cipher text block

DES

Data Encryption Standard

EDE

Encrypt/Decrypt/Encrypt for the triple DES algorithm

EXPORT
Exportable
FIPS

Federal Information Processing Standard

MD5

Secure hashing that converts an arbitrarily long data string to

a fixed size (128 bytes) digest

NULL No encryption
RC2

a stream cipher designed for RSA

RC4

a stream cipher designed for RSA (variable key size from 40 to

128 bits)

RSA

Public key algorithm (requires RSA or DSS key exchange)

SHA

Secure Hash Algorithm (produces 160-bit hash)

SSL

Secure Sockets Layer

TLS

Transport Layer Security

FIPS Compliant Ciphers Suite

Use these toggle to force the use of IBM FIPS-compliant cipher
specifications.
11. Click Apply to save the changes to the running configuration.
12. Optional: Click Save Config to save the changes to the startup configuration.

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

360

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

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.
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.
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.
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.
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.
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 changes to the running configuration.
11. Optional: Click Save Config to save the changes to the startup configuration.

Appendix A. Referenced objects

361

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
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:

362

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

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. In the Name field, enter the name for the object.
4. Retain the default setting for Admin State. To place in an inactive
administrative state, click disabled.
5. Optional: In the Comment field, enter a descriptive summary.
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.

Appendix A. Referenced objects

363

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 changes to the running configuration.
15. Optional: Click Save Config to save the changes to the startup configuration.

364

IBM WebSphere DataPower XML Integration Appliance XI50: 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

365

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

366

IBM WebSphere DataPower XML Integration Appliance XI50: 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

367

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.

368

IBM WebSphere DataPower XML Integration Appliance XI50: 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 378.
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 378.
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

369

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 380.
Note: Refer to List of available variables on page 381 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 11 lists the
names and permission for these variables.
Table 11. 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 12 lists the names and permission for these variables.
Table 12. Names and permissions for general service variables that are available to only
Multi-Protocol Gateway and Web Service Proxy services

370

Variable name

Permission

var://service/mpgw/backend-timeout

Read-write

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

Table 12. 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 13 lists the names and permission
for these variables.
Table 13. 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

371

Load balancer service variables

This section contains information about load balancer variables in alphabetic order
by permission category. Table 14 lists the names and permission for these variables.
Table 14. 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 15 lists the names and permission for these
variables.
Table 15. 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.

372

IBM WebSphere DataPower XML Integration Appliance XI50: 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 16 lists the names and permission
for these variables.
Table 16. 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

373

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 17 lists the names and permission
for these variables.
Table 17. 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

374

IBM WebSphere DataPower XML Integration Appliance XI50: 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 18 lists the names and permission for these
variables.
Table 18. 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

375

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 19 lists the names and permission for these variables.
Table 19. 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 20 lists the names and permission
for these variables.
Table 20. Names and permissions for variables that are available for persistent connections

376

Variable name

Permission

var://service/connection/note

Read-write

IBM WebSphere DataPower XML Integration Appliance XI50: 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 21 lists the names and permission for these variables.
Table 21. 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 22 on page 378 lists the names and
permission for these variables.
Appendix C. Working with variables

377

Table 22. Names and permissions for variables that are available for URL-based
transactions
Variable name

Permission

var://service/protocol-method

Read-write

var://service/URI

Read-write

Read-write variables
var://service/protocol-method
Gets or sets the HTTP method of the transaction.
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 23 lists the names and
permission for these variables.
Table 23. 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 24 lists the
names and permission for these variables.
Table 24. Names and permissions for extension variables

378

Variable name

Permission

var://local/_extension/allow-compression

Write-only

var://local/_extension/donot-follow-redirect

Write-only

var://local/_extension/header/

Write-only

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

Table 24. Names and permissions for extension variables (continued)

Variable name

Permission

var://local/_extension/http-10-only

Write-only

var://local/_extension/prevent-persistent-connection

Write-only

var://local/_extension/sslprofile

Write only

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:

Appendix C. Working with variables

379

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.

System variables
This section contains information about system variables in alphabetic order by
permission category. Table 25 lists the names and permission for these variables.
Table 25. 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.

380

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

List of available variables

Table 26 lists the variables that you can define for document processing.
Table 26. 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

381

Table 26. All available variables (continued)

Short variable name

Full variable name

Category

persistence

var://service/persistence

Service, MQ

prevent-persistent-connection

var://local/_extension/prevent-persistentconnection

Extension

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

382

IBM WebSphere DataPower XML Integration Appliance XI50: 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 384

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

383

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.

384

IBM WebSphere DataPower XML Integration Appliance XI50: 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

385

Other company, product, and service names may be trademarks or service marks
of others.

386

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

Index
Special characters
... button
list of referenced object 9
referenced object 8
.java.policy file 191
[configuration-database] stanza, file
entry 254
[ldap] stanza, ssl-keyfile-pwd entry 254
[manager] stanza, replica entry 254
<results> element 150
<url> element 150
+ button
list of referenced object 9
referenced object 8

A
AAA
authentication
search parameters 270
search parameters 270
TFIM 256
aaa action
dictionary attack, protection 41
purpose 82
AAA action
defining 88
AAA Info file
Authenticate element 250
Authorize element 250
editor
authenticated identities 251
authorized access to
resources 253
confirmation 253
credentials 251
default credential 250
file information 253
map credentials 252
map resources 252
overview 250
unauthenticated identity 250
MapCredentials element 250
MapResource element 250
overview 249
AAA Info File
authentication 167
authorization, AAA 181
credentials mapping, AAA 169
resources mapping, AAA 173
AAA Policy
AAA Info file
Authenticate element 250
Authorize element 250
MapCredentials element 250
MapResource element 250
overview 249
authentication
AAA info file 167
BinarySecurityToken 166
Copyright IBM Corp. 2002, 2009

AAA Policy (continued)

authentication (continued)
ClearTrust 165
custom 166
Kerberos AP-REQ 167
LDAP 162
LTPA token 161
Netegrity 165
none 166
RADIUS 167
SAML assertion, artifact 166
SAML assertion, valid
signature 161
SAML assertions, remote 367
SAML server 163
signer certificate 167
SSL certificate, connection
peer 168
TAM 166
WS-SecureConversation
context 166
WS-Trust server 164
X.509 certificates, remote 366
z/OS NSS authentication 165
authorization
AAA Info File 181
always 174
any authenticated 174
ClearTrust 175
custom 175
LDAP 175
Netegrity 175
SAML attribute from
authentication 179
SAML attribute query 177
SAML authorization query 177
TAM 174
XACML PDP 180
z/OS NSS authorization 175
changing authentication caching
policy 170
changing authorization caching
policy 181
configuring 153
creating 154
credentials mapping
AAA Info file 169
custom 168
from identity extraction 169
none 169
TFIM 169
WS-SecureConversation 169
defining authentication method 161
defining authorization method 174
defining identity extraction
method 155
defining resource extraction
methods 170
file editor
authenticated identities 251

AAA Policy (continued)

file editor (continued)
authorized access to
resources 253
confirmation 253
credentials 251
default credential 250
file information 253
map credentials 252
map resources 252
overview 250
unauthenticated identity 250
identity extraction
BinarySecurityToken, WS-Security
Header 156
client IP address 159
custom 161
derived-key UsernameToken,
WS-Security Header 156
extracted token, cookie value 160
extracted token, message 160
HTTP Authentication Header 155
Kerberos AP-REQ, SPNEGO 157
Kerberos AP-REQ, WS-Security
Header 157
LTPA token 160
name, SAML
AttributeStatement 158
name, SAML authentication
assertion 158
password-carrying
UsernameToken, WS-Security
Header 155
Processing Metadata 160
SAML artifact 159
SAML assertions, remote 367
subject DN, certificate in message
signature 159
Token Subject DN (SSL),
connection peer 158
WS-SecureConversation
Identifier 156
WS-Trust Base 157
WS-Trust Supporting 157
X.509 certificates, remote 366
LTPA, adding user attributes 248
mapping authentication
credentials 168
mapping resources 172
namespace mappings
XPath bindings 248
object pages
Authenticate 230
Authorize 239
creating 225
Identity 228
LTPA Attributes 247
Main 225
Map Credentials 236
Map Resource 238
Namespace Mapping 246

387

AAA Policy (continued)

object pages (continued)
Post Processing 245
Resource 237
SAML Attributes 246
Transaction Priority 247
post processing
Authorized Counter 182
available activities 183
CICS Transaction Server 186
Count Monitors 182
custom style sheet 183
ICRX token 186
Kerberos AP-REQ 184
logging access attempts 182
LTPA 185
Rejected Counter 182
SAML assertion 183
SPNEGO 185
TFIM 185
WS-Security UsernameToken 185
WS-Trust 184
z/OS identity propagation 186
resource extraction
HTTP operations 171
local name of request element 171
Processing Metadata 171
URI of top-level element 170
URL from client 170
URL to backend 170
XPath from request 171
resources mapping
AAA Info File 173
custom 172
none 172
TAM 172
TFIM 172
XPath from resource
extraction 173
SAML attributes
defining 248
SFTP Server Front Side Handler 72
z/OS NSS Client 362
AAAInfo.xsd file 249
Accept-Encoding header, retaining 350
accepted configuration
deployment policy 208
actions
aaa
purpose 82
AAA
defining 88
antivirus
defining 88
purpose 82
call
defining 90
defining reusable rules 147
purpose 82, 150
checkpoint
defining 91
purpose 82
conditional
defining 91
purpose 82
contexts
input 86

388

actions (continued)
contexts (continued)
output 86
convert-http
defining 92
purpose 83
cryptobin
defining 93
purpose 83
decrypt
defining 101
Encrypted tokens 365
purpose 83
defining 88
encrypt
defining 103
Encrypted tokens 365
ID references 365
purpose 83
SOAP message with
WS-Security 103
SOAP message with XML
encryption 112
XML message with XML
encryption 114
event-sink 116
purpose 83
extract
defining 117
purpose 83
fetch
attachment protocol 149
defining 117
locating remote resources 147
purpose 83
query parameters 149
specifying remote locations 148
filter
conformance filter 120
defining 118
purpose 83
replay filter 119
required elements filter 119
standard filter 118
WS-Security message layout
filter 120
for-each 121
purpose 83
for-each action
specifying multiple URLs 148
log
defining 124
locating remote resources 147
purpose 84
specifying remote locations 148
method rewrite
defining 132
MQ Header
modifying reply queue 127
modifying reply queue
manager 128
modifying request message
headers 125
modifying response message
headers 126
overview 124

actions (continued)
MQ Header (continued)
retrieving responses with
correlation ID 126
retrieving responses with message
ID 126
on-error
defining 128
defining reusable rules 147
purpose 84
variable builder 150
purpose 82
results
attachment protocol 149
defining 130
locating remote resources 147
purpose 84
query parameters 149
specifying multiple URLs 148
specifying remote locations 148
results-async
attachment protocol 149
defining 131
locating remote resources 147
purpose 84
query parameters 149
specifying multiple URLs 148
specifying remote locations 148
rewrite header
purpose 84
rewrite header (rewrite)
defining 132
rewrite method
purpose 84
route-action
defining with style sheet 133
defining with XPath
expression 133
purpose 84
route-set
defining 134
locating remote resources 147
purpose 84
specifying remote location 148
setvar
defining 134
purpose 85
variable builder 150
sign
defining 135
generating signature
confirmation 368
ID references 365
purpose 85
verifying signature
confirmation 368
slm
defining 137
purpose 85
sql
defining 137
purpose 85
strip-attachments
defining 138
purpose 85
supported protocols 147
validate 144

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

actions (continued)
purpose 85
verify
adding 146
generating signature
confirmation 368
Kerberos AP-REQ tokens,
remote 367
purpose 85, 146
SAML assertions, remote 367
verifying signature
confirmation 368
X.509 certificates, remote 366
xform
defining 139
defining buffer attachment
transform 143
defining conformance
transform 143
defining SOAP refinement
transform 141
purpose 85
xformbin
defining 139
purpose 85
xformpi
defining 140
purpose 85
Add button
list of referenced object 9
admin account
exporting configuration data 197
Administration menu 7
administrative states, objects 12
allow compression policy, user
agent 350
antivirus (antivirus) action
defining 88
antivirus action
purpose 82
AP-REQ message, Kerberos 258
appliance configuration
backing up 197, 198
comparing 206
configuration checkpoints 202
copying
files 201
objects 201
exporting 197
select objects and files 199
importing configuration 204
managing configuration changes 206
moving
files 201
objects 201
reading change report 207
reverting changes 207
undoing changes 207
appliance-wide log
location 187
application domains
backing up configuration 198
Apply button 10
asymmetric signatures
verifying 146
asynchronous transaction variables
service/transaction-timeout 374

asynchronous transactions variables

listing 374
service/transaction-key 374
service/transaction-name 374
asynchronous variables
service/soap-oneway-mep 374
attachment protocol
actions 149
query parameters 149
attachments
buffering transform 143
Attachments Profile 1.0
Conformance Policy 263
audit log
location 187
viewing 187
audit: directory 187
Authenticate element, AAA Info file 250
authentication
configuring RADIUS settings 318
LDAP 270
search parameters 270
authentication caching policy,
changing 170
authentication policy
user agent
basic 348
public key 349
SCP protocol 349
SFTP protocol 349
authentication, AAA
AAA info file 167
available methods 161
BinarySecurityToken 166
ClearTrust 165
connection peer
SSL certificate 168
custom 166
Kerberos AP-REQ 167
LDAP 162
LTPA token 161
Netegrity 165
none 166
RADIUS 167
SAML assertion
artifact 166
valid signature 161
SAML assertions, remote 367
SAML server 163
signer certificate 167
TAM 166
WS-SecureConversation context 166
WS-Trust server 164
X.509 certificates, remote 366
z/OS NSS authentication 165
authorization caching policy,
changing 181
Authorization header, HTTP 348
authorization, AAA
AAA Info File 181
always 174
any authenticated 174
available methods 174
ClearTrust 175
custom 175
LDAP 175
Netegrity 175

authorization, AAA (continued)

SAML attribute from
authentication 179
SAML attribute query 177
SAML authorization query 177
TAM 174
XACML PDP 180
z/OS NSS authorization 175
Authorize element, AAA Info file 250
auto-config.cfg file 10

B
backend-timeout variable 371
basic configuration
MQ Front Side Handler 66
Basic Profile 1.0
Conformance Policy 263
Basic Profile 1.1
Conformance Policy 263
Basic Security Profile 1.0
Conformance Policy 263
BinarySecurityToken
authentication, AAA 166
identity extraction, AAA 156
bold typeface xii
buffer-attachments.xsl style sheet 143
builder
deployment policy 209
buttons
... 8
+ 8
Apply 10
Cancel 10
Delete 11
Edit 9
Logout 7
Save Config 7, 10
Undo 11
View 9

C
CA Unicenter Manager 360
caches
flushing
document cache 362
stylesheet cache 362
caching policy
AAA Policy
authentication 170
authorization 181
call action
defining 90
defining reusable rules 147
purpose 82
call processing rule (call) action
variable builder 150
call processing rule action
See call action
Cancel button 10
cert: directory 187
certificate files
location 187
Certificate objects
export packages 197
Index

389

certificates
DER 15
exporting 17
generating 16
importing 18
PEM 15
PKCS #12 15
PKCS #8 15
security
location, shared 188
location, Web browsers 188
supported formats 15
uploading 191
checkpoint action
purpose 82
checkpoint configuration files
location 187
checkpoint event (checkpoint) action
defining 91
chkpoints: directory 187
CICS Transaction Server 186
clear pdp cache CLI 262
clear xsl cache CLI 262
ClearTrust
authentication, AAA 165
authorization, AAA 175
client-to-server rule 82
Clone link 12
commands
clear pdp cache 262
clear xsl cache 262
web-mgmt 7
compression policy, user agent 350
conditional action
defining 91
purpose 82
config: directory 187
configuration
managing appliance
configuration 195
configuration checkpoints
defining number to allow 202
deleting 204
listing 203
loading 204
overwriting 203
rolling back 204
saving 203
configuration data
applying 10
backing up
WebGUI 197, 198
backing up application domains 198
comparing
WebGUI 206
configuration checkpoints 202
copying
files 201
objects 201
different release level 197
exchanging 197
exporting
location of files 187
select objects and files 199
WebGUI 197
files not included 197

390

configuration data (continued)

importing
WebGUI 197, 204
managing changes 206
moving
files 201
objects 201
objects not included 197
reading change report 207
reading changes 207
saving 10
undoing changes 207
configuration files
exported, location 187
location 187
TAM
ASCII 254
creating 255
modifying 254
obfuscated 254
configuration service variables
listing 371
service/config-param/ 371
service/max-call-depth 371
configuration states, objects 12
conformance filter 120
Conformance Policy
filter actions 263
object pages 263
WS-I Attachments Profile 263
WS-I Basic Profile 263
WS-I Basic Security Profile 263
conformance transform 143
conformance-filter.xsl style sheet 120
conformance-xform.xsl style sheet 143
Content-Length header 351
contexts
actions
input 86
output 86
keywords
INPUT 86
NULL 86
OUTPUT 86
PIPE 86
processing policies 86
processing rules 86
Control Panel
File Management 189
convert query parameters to XML
(convert-http) action
defining 92
convert query parameters to XML action
See convert-http action
convert-http action
defining 92
purpose 83
Count Monitor
Authorized Counter 182
dictionary attack, protection 41
post processing, AAA 182
Rejected Counter 182
count monitors
configuring 216
Count monitors 294

credentials
identification
configuring 21
creating 21
credentials mapping
LDAP 270
search parameters 270
credentials mapping, AAA
AAA Info file 169
available methods 168
custom 168
from identity extraction 169
none 169
TFIM 169
WS-SecureConversation 169
crypto binary (cryptobin) action
defining 93
crypto binary action
See cryptobin action
Crypto Certificate
configuring 19
creating 19
object pages 19
Crypto Firewall Credentials
object pages 21
Crypto Identification Credentials
object pages 21
Crypto Key
configuring 22
creating 22
object pages 22
Crypto Profile
configuring 24
creating 24
object pages 24
Crypto Tools
exporting certificates 17
exporting keys 17
generating certificates 16
generating keys 16
importing certificates 18
importing keys 18
Crypto Validation Credentials
object pages 28
cryptobin action
defining 93
purpose 83
cryptography
shared secrets 26
customer support
contacting 384
obtaining fixes 383
searching knowledge bases 383

D
dashboard 7
DataPower discussion forum xi
DataPower product Web site xi
debugging
processing policies 151
decrypt action
defining 101
Encrypted tokens 365
purpose 83
decrypt.xsl file 102

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

default log
location 187
Delete button 11
list of referenced object 9
denial-of-service, protection
multiple message (MMXDoS) 39
single message (XDoS) 37
deployment policy
accepted configuration 208
creating 208
filtered configuration 208
modified configuration 208
using the builder 209
Deployment Policy
object pages 208
deployment policy builder
creating matching statements 209
DER
certificate format 15
key format 15
developerWorks Web site xi
dictionary attack, protection 41
directories
audit: 187
available 187
cert: 187
chkpoints: 187
config: 187
displaying contents 189
dpcert: 187
export: 187
hiding contents 189
image: 187
local: 187
logstore: 187
logtemp: 187
managing 187
pubcert: 188
refreshing contents 190
sharedcert: 188
store: 188
tasktemplates: 189
temporary: 189
disabled administrative state 12
discussion forum, DataPower xi
Document Crypto Map
object pages
Main 266
Namespace Mappings 267
documentation conventions,
typefaces xii
Domain list 7
down operation state 12
dpcert: directory 187
dpmq protocol 147
dptibems protocol 147
dpwasjms protocol 147
dpwasjmss protocol 147
DSA signatures
verifying 146
duration monitors
configuring 218
Duration monitors 294

E
Edit button

elements
EncryptedData element 365
SecurityTokenReference 366
SignatureConfirmation 367
enabled administrative state 12
encoding, chunked content 351
encrypt action
defining 103
Encrypted tokens 365
ID references 365
purpose 83
SOAP message with WS-Security 103
SOAP message with XML
encryption 112
XML message with XML
encryption 114
encrypt-soap.xsl file 112
encrypt-wssec.xsl file 103
encrypt.xsl file 114
encrypted tokens
EncryptedData element 365
EncryptedData element 365
error code rule 81
error handling variables
listing 375
service/error-code 375
service/error-ignore 375
service/error-message 375
service/error-protocol-reasonphrase 375
service/error-protocol-response 375
service/error-subcode 375
service/strict-error-mode 376
error rule 82
event-sink action
defining event-sink 116
purpose 83
examples
specifying dual thresholds 222
Export link 11
export packages
admin account 197
files not included 197
objects not included 197
permission 197
export: directory 187
Extensible Access Control Markup
Language
See XACML PDP
extension functions
node-set() 360
set-target() 133
extension variables
listing 378
local/_extension/allowcompression 379
local/_extension/donot-followredirect 379
local/_extension/header/ 379
local/_extension/http-10-only 379
local/_extension/prevent-persistentconnection 379
local/_extension/sslprofile 379
local/_extension/timeout 380
external resources, accessing xi
extract action
defining 117

extract action (continued)

purpose 83
extract using XPath (extract) action
defining 117
extract using XPath action
See extract action

F
fault-tolerance
TIBCO EMS 335, 339
fetch action
attachment protocol 149
defining 117
locating remote resources 147
purpose 83
query parameters 149
specifying remote locations 148
supported protocols 147
file entry, [configuration-database]
stanza 254
File Management utility, launching 189
file system
See directories
files
.java.policy 191
AAAInfo.xsd 249
auto-config.cfg 10
certificates
location 187
checkpoint configurations
location 187
configurations
location 187
copying 192
remote URL 192
decrypt.xsl 102
deleting 194
editing
during configuration 10
File Management utility 194
encrypt-soap.xsl 112
encrypt-wssec.xsl 103
encrypt.xsl 114
exported, location 187
fetching 192
managing 187
moving 193
not in export packages
firmware files 197
log files 197
pkcs7-decrypt.xsl 100
pkcs7-encrypt.xsl 98
pkcs7-sign.xsl 94
pkcs7-verify.xsl 96
private keys
location 187
renaming 193
SQL-Injection-Filter.xsl 39
SQL-Injection-Patterns.xml 39
TAM
ASCII configuration 254
creating configuration 255
modifying configuration 254
obfuscated configuration 254
SSL key 254
SSL stash 254
Index

391

files (continued)
tibco.conf 342
uploading
JKS 191
remote 192
workstation 190
viewing
during configuration 10
File Management utility 194
filter action
conformance filter 120
Conformance Policy 263
defining 118
purpose 83
replay filter 119
required elements filter 119
SQL injections, protection 39
standard filter 118
WS-Security message layout
filter 120
filter-accept-all.xsl style sheet 118
filter-reject-all.xsl style sheet 118
filtered configuration
deployment policy 208
Firewall Credentials
configuring 21
creating 21
firmware files
between release levels 197
export packages 197
firmware images
location 187
fixes, obtaining 383
flash drive
See directories
for-each
purpose 83
for-each action
defining for-each 121
locating remote resources 147
specifying multiple URLs 148
use cases 121
Front Side Handler
object pages
FTP Poller 47
FTP Server 50
HTTP 62
HTTPS 63
IMS Connect 64
MQ 65
NFS Poller 68
SFTP Server 71
Stateful Raw XML 74
Stateless Raw XML 75
TIBCO EMS 77
WebSphere JMS 78
FTP client
command channel
encrypting 352
stopping encryption after
authentication 352
data (ASCII, binary) 352
encrypting file transfers 352
NAT compatibility 352
passive mode 352
sending command to server 352
unique file names (STOU, STOR) 352

392

FTP client (continued)

user agent 352
FTP Poller
Front Side Handler
ftp protocol 147
FTP Server
Front Side Handler

47

50

G
general variables
listing 370
service/soap-fault-response

370

H
header injection policy, user agent 351
header retention policy, user agent 350
heartbeat detection, TIBCO 342
HMAC signatures
verifying 146
HTTP 1.0 restriction policy, user
agent 351
HTTP 1.1
chunked contents 351
Content-Length header 351
HTTP Front Side Handler 62
HTTP header
identity extraction, AAA 155
HTTP Header Injection
Multi-Protocol Gateway 297
HTTP header matching rule 81
HTTP Header Suppression
Multi-Protocol Gateway 298
HTTP headers
Accept-Encoding, retaining 350
Authorization 348
Content-Length 351
MQMD, retaining 350
Range, retaining 350
request-header 346
SoapAction 349
TE, retaining 350
HTTP Input Conversion Map
object pages
Input Encoding 267
Main 267
HTTP method matching rule 81
HTTP operations
resource extraction, AAA 171
HTTP Options
Multi-Protocol Gateway 296
http protocol 147
HTTP proxy policy
securing with SSL proxy policy 348
user agent 347
HTTPS Front Side Handler 63
https protocol 147

I
IBM Tivoli Access Manager
See TAM
IBM Tivoli Federated Identity Manager
See TFIM
ICRX token 186

ID references
encrypt action 365
sign action 365
Identification Credentials
configuring 21
creating 21
identity extraction
AAA
BinarySecurityToken, WS-Security
Header 156
identity extraction, AAA
available methods 155
client IP address 159
connection peer
Token Subject DN, SSL 158
custom 161
extracted token
as cookie value 160
from message 160
HTTP Authentication Header 155
LTPA token 160
Processing Metadata 160
SAML artifact 159
SAML assertion
AttributeStatement 158
AuthenticationStatement 158
SPNEGO
Kerberos AP-REQ 157
subject DN
certificate in message
signature 159
SAML assertions, remote 367
SSL certificate 158
X.509 certificates, remote 366
WS-SecureConversation
Identifier 156
WS-Security Header
Kerberos AP-REQ 157
UsernameToken, derived-key 156
UsernameToken,
password-carrying 155
WS-Trust
Base 157
Supporting 157
image: directory 187
Import Package
creating 196
IMS Connect
object pages
Main 268
URL builder 41
IMS Connect Handler 64
ims protocol 147
imsssl protocol 147
Include Configuration File
creating 195
object pages 195
input context, actions 86
INPUT keyword 86
installation images
See firmware images
intellectual property 385
intermediary service provider,
SOAP 141
italics typeface xii

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

keys (continued)
PEM 15
PKCS #12 15
PKCS #7 15
supported formats
keywords
contexts
INPUT 86
NULL 86
OUTPUT 86
PIPE 86
knowledge bases
searching 383

J2RE (j2re1.4.2) 191

j2re1.4.2 (J2RE) 191
j2sdk1.4.2 (SDK) 191
Java Crypto Extension
See SunJCE
Java Crypto Extension Key Store
See JCEKS
Java Key Store
See JKS
Java Message Service
See JMS
java.security package 191
JCE
See SunJCE
JCEKS 191
JetStream Formats and Protocols
See JFAP
JKS
crypto extension 191
granting permissions 191
java.security package 191
keytool utility 191
managing 191
required software 191
uploading certificates 191
working with 191

K
KDC, Kerberos 258
Kerberos
AP-REQ message 258
configuring KDC server 259
KDC 258
keytab 258
principal 258
signature verification 146
Kerberos AP-REQ
authentication, AAA 167
identity extraction, AAA
SPNEGO 157
WS-Security Header 157
post processing, AAA 184
verify action 367
Kerberos AP-REQ tokens, remote
Kerberos KDC server
configuring 259
creating 259
object pages 259
Kerberos keytab
configuring 260
definition 258
Kerberos Keytab File
object pages 260
Key Distribution Center
See KDC
Key objects
export packages 197
key-certificate pairs
creating 15
keys
DER 15
exporting 17
generating 16
importing 18

15

367

LDAP
authentication
search parameters 270
authentication, AAA 162
authorization, AAA 175
credentials mapping
search parameters 270
search parameters 270
licensing
sending inquiries 385
links
Clone 12
Export 11
Show Probe 13
View Logs 11
View Status 12
load balancer group
adding members 279
basic configuration 278
creating 271, 278
health
convalescent (down) 276
healthy (up) 275
quarantined (softdown) 276
health checks
enabling 280
overriding port 278
health of members 275
members
assigning weight 282
disabling members 282
server state 271
Load Balancer Group
example
DataPower service 44
replacing back-end server 44
load balancer service variables
listing 372
service/lbhealth/ 372
load-balancing
TIBCO EMS 337, 339
local: directory 187
local/_extension/allow-compression
variable 379
local/_extension/donot-follow-redirect
variable 379
local/_extension/header/ variable 379
local/_extension/http-10-only
variable 379
local/_extension/prevent-persistentconnection variable 379

local/_extension/sslprofile variable 379

local/_extension/timeout variable 380
log action
defining 124
locating remote resources 147
purpose 84
specifying remote locations 148
supported protocols 147
log files
export packages 197
log/soapversion variable 373
logging
post processing, AAA
access attempts 182
Logout button 7
logs
appliance-wide
location 187
audit
location 187
viewing 187
default
location 187
viewing configuration-specific
logs 11
viewing from catalog 11
viewing from configuration pane 11
logstore: directory 187
logtemp: directory 187
LTPA
adding user attributes, AAA
Policy 248
authentication, AAA 161
identity extraction, AAA 160
post processing, AAA 185

M
map message
TIBCO EMS 76
MapCredentials element, AAA Info
file 250
MapResource element, AAA Info
file 250
Matching Rule
object pages 286
matching rules
error code 81
HTTP header 81
HTTP method 81
processing policies 81
URL 81
XPath 81
matching statements
deployment policy builder 209
deployment policy, manual 210
message catalogs 188
message layout filter, WS-Security 120
message monitors
configuring 212
count monitors 216
duration monitors 218
filter action 215
message type 215
traffic definition 213
message tampering, protection 39

Index

393

message transmission optimization

mechanism
See MTOM
messages
validating conformance 263
method rewrite action
defining 132
MMXDoS, protection 39
modified configuration
deployment policy 208
Modified configuration state 12
monitoring statistics, enabling 220
monitors
count monitors
configuring 216
duration monitors
configuring 218
message monitors
configuring 212
count monitors 216
duration monitors 218
filter action 215
message type 215
traffic definition 213
Multi-Protocol Gateway 294
types 211
Web services monitors
configuring 220
enabling 220
overview 220
specifying dual thresholds 222
monospaced typeface xii
MQ
URL builder 42
MQ Front Side Handler 65
advanced configuration 68
basic configuration 66
configuration 65
properties and headers
configuration 67
publish and subscribe
configuration 67
MQ Get Message Options (GMO)
MQGET options 66
MQGMO_* 66
MQ header action
modifying
reply queue 127
reply queue manager 128
request message headers 125
response message headers 126
overview 124
retrieving responses
with correlation ID 126
with message ID 126
MQ Host variables
listing 372
service/correlation-identifier 373
service/expiry 373
service/format 373
service/message-identifier 373
service/message-type 373
service/mq-ccsi 372
service/mqmd-reply-to-q 372
service/mqmd-reply-to-qm 372
service/persistence 373
service/priority 373

394

MQ Host variables (continued)

service/reply-to-q 373
service/reply-to-qm 373
service/report 373
mq protocol 147
MQ Proxy variables
listing 372
service/correlation-identifier 373
service/expiry 373
service/format 373
service/message-identifier 373
service/message-type 373
service/mq-ccsi 372
service/mqmd-reply-to-q 372
service/mqmd-reply-to-qm 372
service/persistence 373
service/priority 373
service/reply-to-q 373
service/reply-to-qm 373
service/report 373
MQ request messages
modifying message headers 125
specifying correlation ID 126
specifying message ID 126
MQ response messages
modifying headers 126
modifying reply queue 127
modifying reply queue manager 128
MQMD header, retaining 350
MTOM policy
defining 286
Multi-Protocol Gateway
configuring 31
configuring Multi-Protocol Gateway
objects 287
creating 32
creating Multi-Protocol Gateway
objects 287
object pages
HTTP Header Injection 297
HTTP Header Suppression 298
HTTP Options 296
Main 287
Monitors 294
Parser Limits 295
Proxy Settings 289
Stylesheet Parameter 304
WS-Addressing 298
WS-ReliableMpessaging 298
service description 287
service variables
backend-timeout 371
service/reply-to-q 371
service/reply-to-qm 371
skip-backside 371
threat protection 37
multistep variables
log/soapversion 373
multistep/loop-count service
variable 123
multistep/loop-iterator service
variable 123

N
namespace mappings, AAA Policy
NAS-identifier 318

248

NAT
FTP clients 352
navigation
Administration menu 7
Network menu 7
Objects menu 7
Services menu 7
Status menu 7
Netegrity
authentication, AAA 165
authorization, AAA 175
Network Address Translation
See NAT
Network menu 7
New configuration state 12
NFS Poller Front Side Handler 68
node-set() extension function 360
notices 385
NULL keyword 86

O
object pages
AAA Policy
Authenticate 230
Authorize 239
Identity 228
LTPA Attributes 247
Main 225
Map Credentials 236
Map Resource 238
Namespace Mapping 246
Post Processing 245
Resource 237
SAML Attributes 246
Transaction Priority 247
Conformance Policy 263
Crypto Certificate 19
Crypto Firewall Credentials 21
Crypto Identification Credentials 21
Crypto Key 22
Crypto Profile 24
Crypto Validation Credentials 28
Deployment Policy 208
Document Crypto Map
Main 266
Namespace Mappings 267
Front Side Handler
FTP Poller 47
FTP Server 50
HTTP 62
HTTPS 63
IMS Connect 64
MQ 65
NFS Poller 68
SFTP Server 71
Stateful Raw XML 74
Stateless Raw XML 75
TIBCO EMS 77
WebSphere JMS 78
HTTP Input Conversion Map
Input Encoding 267
Main 267
IMS Connect
Main 268
Include Configuration File 195
Kerberos KDC server 259

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

object pages (continued)

Kerberos Keytab File 260
Matching Rule 286
Multi-Protocol Gateway
HTTP Header Injection 297
HTTP Header Suppression 298
HTTP Options 296
Main 287
Monitors 294
Parser Limits 295
Proxy Settings 289
Stylesheet Parameter 304
WS-Addressing 298
WS-ReliableMessaging 298
Policy Parameters
Main 305
Policy Parameters 305
Processing Action
Main 306
Named Inputs 314
Named Outputs 314
Stylesheet Parameters 314
Processing Metadata
Main 314
Metadata Items 315
Processing Policy
Main 316
Policy Maps 316
Processing Rule 317
Schema Exception Map
Main 319
Rules 320
SLM Action 324
SLM Credentials Class 322
SLM Resource Class 323
SLM Schedule 324
SOAP Header Disposition Table
Main 325
SOAP Header Refine
Instruction 325
SSL Proxy Profile 26
TAM 255
TFIM 256
TIBCO EMS 328
URL Rewrite Policy
Main 342
URL Rewrite Rule 343
WebSphere JMS server 353
XACML PDP 261
XML Manager 360
objects
administrative state 12
configuration state 12
not in export packages
Certificate 197
Key 197
User 197
operational state 12
referenced
... button 8
+ button 8
creating 8
modifying 8
selecting 8
status 12
TFIM 256
Objects menu 7

on-error
variable builder 150
on-error action
defining 128
defining reusable rules 147
purpose 84
operational states, objects 12
output context, actions 86
OUTPUT keyword 86

P
Parser Limits
Multi-Protocol Gateway 295
patents 385
peer group
defining 324
PEM
certificate format 15
key format 15
persistent connections variables
listing 376
service/connection/note 377
PIPE keyword 86
PKCS #12
certificate format 15
key format 15
PKCS #7
certificate format 15
decrypting documents 100
encrypting documents 98
signing documents 93
verifying signed documents 96
PKCS #8
key format 15
pkcs7-decrypt.xsl file 100
pkcs7-encrypt.xsl file 98
pkcs7-sign.xsl file 94
pkcs7-verify.xsl file 96
Policy Decision Point
See XACML PDP
Policy Parameters
defining 304
object pages
Main 305
Policy Parameters 305
post processing, AAA
Authorized Counter 182
available activities 183
CICS Transaction Server 186
Count Monitors 182
custom style sheet 183
ICRX token 186
Kerberos AP-REQ 184
logging access attempts 182
LTPA 185
Rejected Counter 182
SAML assertion 183
SPNEGO 185
TFIM 185
WS-Security UsernameToken 185
WS-Trust 184
z/OS identity propagation 186
principal, Kerberos 258
private key files
location 187

private keys
uploading 191
Processing Action
object pages
Main 306
Named Inputs 314
Named Outputs 314
Stylesheet Parameters 314
Processing Metadata
identity extraction, AAA 160
object pages
Main 314
Metadata Items 315
resource extraction, AAA 171
ssh-password-metadata 72
ssh/password variable 72
ssh/publickey variable 72
ssh/username variable 72
processing policies
contexts 86
creating 87
debugging 151
defining 81
matching rules 81
processing rules 82
Processing Policy
object pages
Main 316
Policy Maps 316
Processing Rule
object pages 317
processing rules
client-to-server 82
contexts 86
direction 82
error 82
processing policies 82
server-to-client 82
two way 82
product documentation Web site xi
product Web site, DataPower xi
protocols
supported 147
Proxy Settings
Multi-Protocol Gateway 289
pubcert: directory 188
publish
MQ Front Side Handler 67

Q
query parameters
actions 149
attachment protocol 149
queues
TIBCO EMS 76
WebSphere JMS 78

R
RADIUS
authentication, AAA 167
NAS-identifier 318
purpose 318
Range header, retaining 350
Redbooks Web site xi
Index

395

referenced objects
... button 8
+ button 8
creating 8
modifying 8
selecting 8
referenced objects, lists
... button 9
+ button 9
Add button 9
adding 9
creating 9
Delete button 9
deleting 9
modifying 9
selecting 9
Rejected Counter Tool 182
replay filter 119
replay-filter.xsl style sheet 119
replica entry, [manager] stanza 254
request-header, HTTP 346
required-elements-filter.xsl style
sheet 119
resource extraction, AAA
available methods 170
HTTP operations 171
local name of request element 171
Processing Metadata 171
URI of top-level element 170
URL from client 170
URL to backend 170
XPath from request 171
resources mapping, AAA
AAA Info File 173
available methods 172
custom 172
none 172
TAM 172
TFIM 172
XPath from resource extraction 173
restriction policy for HTTP 1.0, user
agent 351
results action
<results> element 150
<url> element 150
attachment protocol 149
defining 130
locating remote resources 147
purpose 84
query parameters 149
specifying multiple URLs 148
supported protocols 147
results asynchronous action
See results-async action
results-async
defining 131
results-async action
<results> element 150
<url> element 150
attachment protocol 149
locating remote resources 147
purpose 84
query parameters 149
specifying multiple URLs 148
supported protocols 147
rewrite header (rewrite) action
defining 132

396

rewrite header action

See also rewrite header action
purpose 84
rewrite method action
See also rewrite method action
purpose 84
RFC 2616 351
route action
overview 133
with style sheet 133
with variables 134
with XPath expression 133
route with style sheet action
See route-action action
route with variables action
See route-set action
route with XPath expression action
See route-action action
route-action action
defining
with style sheet 133
with XPath expression 133
purpose 84
route-set action 148
defining 134
locating remote resources 147
purpose 84
supported protocols 147
RSA signatures
verifying 146

S
S11:actor SOAP attribute 141
S11:mustUnderstand SOAP attribute 141
S12:mustUnderstand SOAP attribute 141
S12:notUnderstood SOAP attribute 141
S12:relay SOAP attribute 141
S12:role SOAP attribute 141
SAML assertion
authentication, AAA
artifact 166
valid signature 161
identity extraction, AAA
AttributeStatement 158
AuthenticationStatement 158
post processing, AAA 183
SAML assertions 367
AAA Policy
authentication 367
identity extraction 367
verify action 367
SAML attributes
defining, AAA Policy 248
SAML server
authorization, AAA
attribute query 177
authorization query 177
Save Config button 7, 10
Saved configuration state 12
Schema Exception Map
object pages
Main 319
Rules 320
schemas
location 188

SCP protocol
authentication policy, user agent 349
public keys 349
SDK (j2sdk1.4.2) 191
search parameters, LDAP 270
security certificates
shared
location 188
Web browsers
location 188
Security Token Reference
See STR
SecurityContextToken, WS-Trust
post processing, AAA 184
SecurityTokenReference element 366
server pool
See load balancer group
server state
load balancer group 271
server-to-client rule 82
service level monitors
See SLM
service variables
listing 370
multistep/loop-count 123
multistep/loop-iterator 123
types 370
service/append-request-header/
variable 376
service/append-response-header/
variable 376
service/config-param/ variable 371
service/connection/note variable 377
service/correlation-identifier
variable 373
service/error-code variable 375
service/error-ignore variable 375
service/error-message variable 375
service/error-protocol-reason-phrase
variable 375
service/error-protocol-response
variable 375
service/error-subcode variable 375
service/expiry variable 373
service/format variable 373
service/lbhealth/ variable 372
service/max-call-depth variable 371
service/message-identifier variable 373
service/message-type variable 373
service/mq-ccsi variable 372
service/mqmd-reply-to-q variable 372
service/mqmd-reply-to-qm variable 372
service/persistence variable 373
service/priority variable 373
service/protocol-method variable 378
service/reply-to-q variable 371, 373
service/reply-to-qm variable 371, 373
service/report variable 373
service/routing-url variable 72, 377
service/routing-url-sslprofile
variable 377
service/set-request-header/ variable 376
service/set-response-header/
variable 376
service/soap-fault-response variable 370
service/soap-oneway-mep variable 374
service/strict-error-mode variable 376

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

service/transaction-key variable 374

service/transaction-name variable 374
service/transaction-timeout variable 374
service/URI variable 72, 378
service/wsa/genpattern variable 378
service/wsa/timeout variable 378
service/wsm/wsdl-error variable 378
service/wsm/wsdl-warning
variable 378
Services
Multi-Protocol Gateway Service 287
Services menu 7
set variable (setvar) action
defining 134
variable builder 150
set variable action
See setvar action
set-target() extension function 133
setvar action
<results> element 150
<url> element 150
defining 134
purpose 85
variable builder 150
SFTP protocol
authentication policy, user agent 349
public keys 349
SFTP Server
Front Side Handler 71
SFTP Server Front Side Handler
AAA Policy 72
authentication 72
authorization 72
configuration considerations 71
metadata variables 72
routing 72
URI propagation 72
URL specifications 72
Shared Secret Key
configuring 26
creating 26
shared secrets 26
sharedcert: directory 188
Show Probe link 13
sign action
defining 135
generating signature
confirmation 368
ID references 365
purpose 85
verifying signature confirmation 368
signature confirmation 367
SignatureConfirmation element 367
signatures
verifying 146
signed documents, PKCS #7
decrypting 100
encrypting 98
signing 93
verifying 96
skip-backside variable 371
SLM
overview 320
slm action
defining 137
purpose 85

SLM action
See slm action
SLM Action
creating 324
object pages 324
SLM Credentials Class
creating 322
object pages 322
SLM policy
adding statements 321
creating 321
creating SLM actions 324
SLM Policy
creating SLM Credentials Class
objects 322
creating SLM Resource Class
objects 323
creating SLM schedules 324
SLM Resource Class
creating 323
object pages 323
SLM Schedule
creating 324
object pages 324
SLM statements
adding to policy 321
overview 320
smtp protocol 147
SOAP attributes
S11:actor 141
S11:mustUnderstand 141
S12:mustUnderstand 141
S12:notUnderstood 141
S12:relay 141
S12:role 141
SOAP Header Disposition Table
object pages
Main 325
SOAP Header Refine
Instruction 325
SOAP refinement transform 141
SOAP service provider type 141
soap-refine.xsll style sheet 141
SoapAction header 349
specifying remote locations 148
specifying multiple URLs 148
SPNEGO
identity extraction, AAA 157
Kerberos AP-REQ 157
post processing, AAA 185
sql action
defining 137
purpose 85
SQL action
See sql action
SQL Data Source
adding configuration parameters 327
base configuration 327
defining 326
high-level configuration 327
SQL injections, protection 39
sql protocol 147
SQL-Injection-Filter.xsl style sheet 39
SQL-Injection-Patterns.xml file 39
SSH
AAA Policy 72
authentication 72

SSH (continued)
authorization 72
metadata variables 72
routing 72
streaming 71
timeout 71
URI propagation 72
URL specifications 72
ssh-password-metadata Processing
Metadata 72
ssh/password variable 72
ssh/publickey variable 72
ssh/username variable 72
SSL
client proxy, creating 26
forward proxy, creating 26
reverse, proxy, creating 27
server proxy, creating 27
two-way proxy, creating 27
SSL authentication 24
SSL proxy policy, user agent 348
SSL Proxy Profile
creating
client proxy 26
forward proxy 26
reverse proxy 27
server proxy 27
two-way proxy 27
object pages 26
ssl-keyfile-pwd entry, [ldap] stanza 254
Stateful Raw XML Handler 74
Stateless Raw XML Handler 75
statistics, enabling 220
Status menu 7
store: directory 188
STR dereference transform 366, 367
strip-attachments action
defining 138
purpose 85
style sheets
buffer-attachments.xsl 143
conformance-filter.xsl 120
conformance-xform.xsl 143
filter-accept-all.xsl 118
filter-reject-all.xsl 118
flushing the cache 362
location 188
replay-filter.xsl 119
required-elements-filter.xsl 119
soap-refine.xsl 141
wssecurity-message-layoutfilter.xsl 120
Stylesheet Parameter
Multi-Protocol Gateway 304
subdirectories
creating 189
deleting 190
subscribe
MQ Front Side Handler 67
SunJCE
JCEKS 191
support
See customer support
symmetric signatures
verifying 146
system variables
listing 380
Index

397

system variables (continued)

system/map/debug 380
system/tasktemplates/debug 380
system/map/debug variable 380
system/tasktemplates/debug
variable 380

T
TAM
ASCII configuration file 254
authentication, AAA 166
authorization server replicas 255
authorization, AAA 174
configuration, general 254
configuring TAM objects 255
creating configuration files 255
creating TAM objects 255
licensing 253
modifying configuration files 254
obfuscated configuration file 254
object pages 255
refreshing certificates 255
resources mapping, AAA 172
security 254
SSL key file 254
SSL stash file 254
tasktemplates: directory 189
tcp protocol 147
tcps protocol 147
TE header, retaining 350
temporary: directory 189
TFIM
AAA 256
credentials mapping, AAA 169
object 256
object pages 256
post processing, AAA 185
resources mapping, AAA 172
TFIM endpoint
WS-Trust messages 256
threat protection
denial-of-service
multiple message 39
single message 37
dictionary attack 41
message tampering 39
SQL injections 39
XML virus (X-Virus) 40
TIBCO EMS
fault-tolerant hosts 335, 339
heartbeat detection 342
load-balanced hosts 337, 339
map message 328
object pages 328
tibco.conf 342
transactional messaging 331
unique host 334
URL builder 43
TIBCO EMS Front Side Handler
map message 76
purpose 76
queues 76
support 76
topic spaces 76
TIBCO Rendezvous 76
TIBCO SmartSockets 76

398

tibco.conf file 342

Tivoli Access Manager
See TAM
topic spaces
TIBCO EMS 76
WebSphere JMS 78
trademarks 385
transaction headers variables
listing 376
service/append-request-header/ 376
service/append-response-header/
376
service/set-request-header/ 376
service/set-response-header/ 376
transaction routing variables
listing 377
service/routing-url 377
service/routing-url-sslprofile 377
transaction URL variables
listing 377
service/protocol-method 378
service/URI 378
transaction variables
listing 374
types 374
transform action
See also xform action
attachments
buffering 143
defining buffer attachment
transform 143
defining conformance transform 143
defining SOAP refinement
transform 141
defining standard transform
non-XML messages 139
XML messages 139
overview 138
processing instruction-based
transform 140
SOAP messages
refinement transform 141
XML messages
conformance 143
defining 139
processing instruction-based 140
transform actions
MTOM policy 286
Transform binary action
See xformbin action
Transform using processing instruction
action
See xformpi action
two way rule 82
typeface conventions xii

U
ultimate service provider, SOAP
Undo button 11
up operational state 12
URL builder
IMS Connect 41
MQ 42
TIBCO EMS 43
WebSphere JMS 44
URL matching rule 81

141

URL Rewrite Policy

object pages
Main 342
URL Rewrite Rule 343
use cases
for-each action 121
User Agent
creating 346
default configuration 345
modifying basic configuation 347
overview 345
policies
allow-compression policy 350
basic authentication 345, 348
chunked upload 351
chunked uploads, HTTP 1.1 345
compression 345
compression policy 350
FTP client 345, 352
header injection 345, 351
header retention 345, 350
HTTP 1.0 restriction policy 351
HTTP proxy 345
HTTP proxy policy 347
public key authentication 345, 349
restriction, HTTP 1.0 345
SOAP action 349
SOAPAction 345
SSL proxy 345
SSL proxy policy 348
user authentication
RADIUS 318
User objects
export packages 197
UsernameToken
identity extraction, AAA
derived-key 156
password-carrying 155
post processing, AAA 185
utilities
keytool 191

V
validate action 144
message tampering, protection 39
purpose 85
Validation Credentials
creating
non expiring, non-passwordprotected certificates 28
select certificates 29
types of lists 28
variable builder 150
variables
asynchronous
service/soap-oneway-mep 374
asynchronous transactions
listing 374
service/transaction-key 374
service/transaction-name 374
service/transaction-timeout 374
configuration service
listing 371
service/config-param/ 371
service/max-call-depth 371

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide

variables (continued)
error handling
listing 375
service/error-code 375
service/error-ignore 375
service/error-message 375
service/error-protocol-reasonphrase 375
service/error-protocolresponse 375
service/error-subcode 375
service/strict-error-mode 376
extension
listing 378
local/_extension/allowcompression 379
local/_extension/donot-followredirect 379
local/_extension/header/ 379
local/_extension/http-10-only 379
local/_extension/preventpersistent-connection 379
local/_extension/sslprofile 379
local/_extension/timeout 380
general
listing 370
service/soap-fault-response 370
list, all available 381
load balancer service
listing 372
service/lbhealth/ 372
MQ Host
listing 372
service/correlation-identifier 373
service/expiry 373
service/format 373
service/message-identifier 373
service/message-type 373
service/mq-ccsi 372
service/mqmd-reply-to-q 372
service/mqmd-reply-to-qm 372
service/persistence 373
service/priority 373
service/reply-to-q 373
service/reply-to-qm 373
service/report 373
MQ Proxy
listing 372
service/correlation-identifier 373
service/expiry 373
service/format 373
service/message-identifier 373
service/message-type 373
service/mq-ccsi 372
service/mqmd-reply-to-q 372
service/mqmd-reply-to-qm 372
service/persistence 373
service/priority 373
service/reply-to-q 373
service/reply-to-qm 373
service/report 373
Multi-Protocol Gateway
backend-timeout 371
service/reply-to-q 371
service/reply-to-qm 371
skip-backside 371

variables (continued)
multistep
log/soapversion 373
persistent connections
listing 376
service/connection/note 377
service
listing 370
type 370
service/routing-url 72
service/URI 72
ssh/password 72
ssh/publickey 72
ssh/username 72
system
listing 380
system/map/debug 380
system/tasktemplates/debug 380
transaction
listing 374
type 374
transaction headers
listing 376
service/append-request-header/
376
service/append-response-header/
376
service/set-request-header/ 376
service/set-response-header/ 376
transaction routing
listing 377
service/routing-url 377
service/routing-url-sslprofile 377
transaction URL
listing 377
service/protocol-method 378
service/URI 378
types 369
using 369
Web Service Proxy
backend-timeout 371
service/reply-to-q 371
service/reply-to-qm 371
skip-backside 371
WSM
listing 378
service/wsa/genpattern 378
service/wsa/timeout 378
service/wsm/wsdl-error 378
service/wsm/wsdl-warning 378
verify action
adding 146
generating signature
confirmation 368
Kerberos AP-REQ tokens, remote 367
purpose 85, 146
SAML assertions, remote 367
verifying signature confirmation 368
X.509 certificates, remote 366
View button 9
View Logs link 11
View Status link 12

W
Web Management Interface

Web Service Proxy

defining policy parameters 304
service variables
backend-timeout 371
service/reply-to-q 371
service/reply-to-qm 371
skip-backside 371
Web services monitors 294
configuring 220
enabling 220
overview 220
specifying dual thresholds 222
Web sites
DataPower product xi
developerWorks xi
discussion forum xi
product documentation xi
Redbooks xi
web-mgmt command 7
WebGUI
accessing 7
Administration menu 7
applying configuration changes 10
canceling changes 10
cloning services 12
common tasks 10
dashboard 7
deleting objects 11
Domain list 7
exporting objects 11
logging in 7
Logout button 7
Network menu 7
Objects menu 7
resetting configuration 11
reverting changes 11
Save Config button 7
saving configuration changes 10
Services menu 7
Status menu 7
viewing configuration-specific
logs 11
viewing object status 12
viewing probe data 13
Welcome screen 7
WebSphere JMS
transactional messaging 353
URL builder 44
WebSphere JMS Front Side Handler
purpose 78
queues 78
support 78
topic spaces 78
WebSphere JMS server
object pages 353
WebSphere Transformation Extender
See WTX
Welcome screen 7
workstation
uploading files 190
WS-Addressing
Multi-Protocol Gateway 298
WS-ReliableMessaging
Multi-Protocol Gateway 298
WS-SecureConversation
authentication, AAA 166
credentials mapping, AAA 169
Index

399

WS-SecureConversation (continued)
identity extraction, AAA 156
WS-Security
message layout filter 120
WS-Security Header
identity extraction, AAA
BinarySecurityToken 156
UsernameToken, derived-key 156
UsernameToken,
password-carrying 155
WS-Security Management
See WSSM
WS-Trust
authentication, AAA 164
identity extraction, AAA 157
post processing, AAA 184
WS-Trust messages
TFIM endpoint 256
WSM variables
listing 378
service/wsa/genpattern 378
service/wsa/timeout 378
service/wsm/wsdl-error 378
service/wsm/wsdl-warning 378
wssecurity-message-layout-filter.xsl style
sheet 120
WTX
DPA 310
Exported Files 310
input contexts 311
Mapping Logic Disabled 310
Named Inputs 314
Named Outputs 314
output contexts 311
xformbin action 139, 311

XML Manager
caches
flushing the document cache 362
flushing the stylesheet cache 362
configuring 360
document cache, flushing 362
Load Balancer Group
DataPower service 44
modifying 360
object pages 360
XML virus, protection 40
XPath bindings
AAA Policy 248
XPath matching rule 81

Z
z/OS identity propagation 186
z/OS NSS authentication
authentication, AAA 165
z/OS NSS authorization
authorization, AAA 175
z/OS NSS Client
creating 363
overview 362

X
X-Virus, protection 40
X.509 certificates 366
AAA Policy
authentication 366
identity extraction 366
verify action 366
XACML PDP
authorization, AAA 180
configuring 261
object pages 261
XDoS, protection 37
xform
defining standard transform 139
XML messages 139
xform action
defining 139
defining buffer attachment
transform 143
defining conformance transform 143
defining SOAP refinement
transform 141
purpose 85
xformbin action
defining 139
purpose 85
xformpi action
defining 140
purpose 85

400

IBM WebSphere DataPower XML Integration Appliance XI50: Multi-Protocol Gateway Developers Guide




Printed in USA