Web Service Proxy Developers Guide

WebSphere DataPower XML Integration Appliance XI50
Version 3.8.0
Web Service Proxy Developers Guide
WebSphere DataPower XML Integration Appliance XI50
Version 3.8.0
Web Service Proxy Developers Guide
Note
Before using this information and the product it supports, read the information in Notices and trademarks on page 419.
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 2004, 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 . . . . . . . . ix
Problem determination documentation . . . . x
Supplemental documentation . . . . . . . . x
External resources . . . . . . . . . . . . xi
File naming guidelines . . . . . . . . . . . xi
Object naming guidelines. . . . . . . . . . xii
Typeface conventions . . . . . . . . . . . xii
Chapter 1. WebGUI basics . . . . . . . 1

Objects on the appliance . . . . . . . . .
Working with objects . . . . . . . . . .
Accessing the WebGUI . . . . . . . . . .
Welcome screen . . . . . . . . . . . .
Common WebGUI conventions . . . . . . .
Working with referenced objects . . . . . .
Working with lists of referenced objects . . .
Viewing and editing local files during configuration
Viewing local files . . . . . . . . . .
Editing local files . . . . . . . . . . .
Common WebGUI tasks . . . . . . . . .
Applying and saving changes . . . . . .
Canceling changes . . . . . . . . . .
Resetting objects . . . . . . . . . . .
Deleting objects . . . . . . . . . . .
Exporting objects . . . . . . . . . . .
Viewing configuration-specific messages . . .
Viewing object status . . . . . . . . .
Cloning services . . . . . . . . . . .
Accessing probe captures . . . . . . . .
Chapter 2. Securing communication

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
Working with Key objects . . . . .
Working with z/OS keys . . . . .
Defining Key objects . . . . . .
Defining Profile objects . . . . . .
Defining shared secret keys . . . . .
Copyright IBM Corp. 2004, 2009
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
1
1
1
1
2
2
3
3
4
4
4
4
4
5
5
5
5
6
6
7
. . 9
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 9
. 9
. 9
. 10
. 11
. 12
. 13
. 13
. 13
. 15
. 15
. 16
. 16
. 17
. 18
. 20
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 . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
20
20
21
21
22
.
.
.
.
. 22
. 23
Chapter 3. Configuring Web Service

Proxy services . . . . . . . . . . . 25
Creating a Web Service Proxy . . . . . . .
Defining the basic configuration . . . . . .
Configuring Service Level Monitors . . . . .
Reading traffic graphs . . . . . . . . .
Creating an SLM peer group . . . . . .
Defining an SLM statement . . . . . . .
Configuring the policy. . . . . . . . . .
Determining the view for the policy . . . .
Processing rules . . . . . . . . . . .
Defining the Web Services policy . . . . .
Defining the Web Security conformance policy
Defining the service priority . . . . . . .
Defining the user policy . . . . . . . .
Configuring basic proxy settings . . . . . .
Configuring advanced proxy settings . . . . .
Configuring header and parameter settings . . .
Adding header injection parameters . . . .
Adding header suppression parameters . . .
Defining stylesheet parameters . . . . . .
Configuring Web Services Addressing . . . .
Configuring Traditional to WS-Addressing . .
Configuring WS-Addressing to Traditional . .
Configuring WS-Addressing to WS-Addressing
Configuring Reliable Messaging . . . . . .
Configuring XML threat protection . . . . .
Protecting against single message XML
denial-of-service attacks . . . . . . . .
Protecting against multiple message XML
denial-of-service attacks . . . . . . . .
Protection against SQL injections . . . . .
Protocol threat protection . . . . . . . .
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 . . . . . . . . . . . . .
WSDL Retrieval . . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
25
25
29
30
31
31
32
33
33
34
37
39
39
41
43
46
46
47
47
48
48
49
51
. 54
. 60
. 60
.
.
.
.
.
.
.
.
.
.
61
62
62
63
64
64
64
65
66
67
. 67
. 68
Chapter 4. Handler configuration . . . 69

Configuring an FTP poller handler
. 69
iii
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 . . . . . .
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
74
76
80
83
85
86
87
87
88
89
89
90
90
93
94
94
94
95
95
96
97
97
Chapter 5. Processing policies . . . . 99

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 . . . . . . . .
iv
. 99
100
100
104
104
104
105
105
106
106
106
108
109
. 109
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
110
111
119
121
134
135
135
136
139
142
142
146
147
150
150
151
152
153
155
155
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. . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
Chapter 6. AAA Policy configuration
.
.
.
.
.
.
.
.
.
.
.
.
156
156
162
164
165
165
165
166
167
168
168
169
171
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 . . . . . . . . . . . . .
172
173
179
186
188
188
190
192
199
200
200
200
200
201
201
201
201
201
202
202
203
203
203
203
204
Chapter 7. Managing files . . . . . . 205

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 . . . . . . . . . .
IBM WebSphere DataPower XML Integration Appliance XI50: Web Service Proxy Developers Guide
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
205
207
207
207
208
208
208
209
209
209
209
209
210
210
211
Moving files .
Viewing files
Editing files .
Deleting files
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
211
212
212
212
Chapter 8. Managing the configuration

of the appliance . . . . . . . . . . 213
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 . . . . . . .
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 . . .
.
.
.
.
.
.
.
.
to
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
213
214
215
216
216
217
219
220
.
.
.
.
.
.
.
.
.
.
.
.
.
.
220
221
221
222
222
222
224
224
225
225
226
226
227
228
Chapter 9. Managing monitors . . . . 229

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 . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
229
230
231
233
233
234
236
238
238
238
240
Appendix A. Referenced objects . . . 243

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 . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
243
243
246
248
254
255
256
257
263
264
264
265
265
266
266
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 . . . . . . . . . . .
Compile Options Policy objects . . . . . . .
Configuring Compile Option Policy objects . .
Document Crypto Map . . . . . . . . . .
Namespace Mappings tab . . . . . . . .
Defining LDAP Search Parameters objects . . . .
IMS Connect . . . . . . . . . . . . .
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 . . . . . . .
Processing Metadata . . . . . . . . . . .
Main tab . . . . . . . . . . . . . .
Metadata Items tab . . . . . . . . . .
Defining Processing Policy objects . . . . . .
Policy Maps tab . . . . . . . . . . .
Defining Processing Rule objects . . . . . . .
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 . . . . . . . . .
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 . . . . . . .
Universal Description, Discovery and Integration
Overview. . . . . . . . . . . . . .
266
267
271
328
330
331
331
Contents
274
276
279
281
284
284
285
285
286
287
289
289
291
293
293
294
296
299
300
301
301
304
305
305
305
306
307
307
308
309
309
310
311
312
312
313
313
314
314
315
315
315
316
316
317
320
322
323
324
326
UDDI Registry . . . . . . . . . . .
UDDI Subscription . . . . . . . . .
Publishing to a UDDI registry . . . . . .
Viewing the status of UDDI subscriptions . .
URL Map. . . . . . . . . . . . . .
URL Map Rule tab . . . . . . . . .
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 . . . . . .
Creating Web Service Proxy objects . . . . .
Creating a new Web Service Proxy . . . .
Specifying basic proxy operation . . . . .
Configuring Proxy settings . . . . . . .
Setting HTTP options. . . . . . . . .
Setting Parser Limits . . . . . . . . .
Assigning Monitors . . . . . . . . .
Enabling support for WS-Addressing . . .
Configuring Dynamic Endpoints . . . . .
Enabling Web Service Reliable Messaging . .
Adding a proprietary header . . . . . .
Deleting a header from the message stream .
Passing parameter-value pairs to style sheets
Refreshing WSDL Cache. . . . . . . .
Editing or adding WSDL files . . . . . .
Defining a user policy for WSDL operations .
Specifying UDDI Subscriptions . . . . .
WSRR Subscription tab . . . . . . . .
Operation Priority tab . . . . . . . .
Operation Conformance Policy tab . . . .
Operation Policy Subject Opt Out tab . . .
Policy Parameters tab . . . . . . . .
Reliable Messaging tab . . . . . . . .
WS-Proxy Endpoint Rewrite . . . . . . .
Main tab . . . . . . . . . . . . .
Local Rewrite Rule tab . . . . . . . .
Remote Rewrite Rule tab . . . . . . .
Publish Rewrite Rule tab . . . . . . .
Subscription Local Rewrite Rule tab . . . .
Subscription Remote Rewrite Rule tab . . .
Subscription Publish Rewrite Rule tab . . .
WebSphere JMS servers . . . . . . . . .
Transactional messaging . . . . . . . .
Configuring a WebSphere JMS server . . .
WebSphere Service Registry and Repository . .
vi
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
332
333
334
334
335
335
335
336
339
340
340
341
341
342
342
343
343
344
344
345
345
346
346
347
348
350
355
356
357
357
358
359
365
365
366
366
367
367
369
369
369
371
372
373
374
375
376
376
378
379
380
381
382
383
383
386
390
Overview of configuring WSRR . . . . .

WSRR Server . . . . . . . . . . .
WSRR Subscription . . . . . . . . .
Manually synchronizing WSRR subscriptions
XML Manager . . . . . . . . . . . .
Configure XML Manager objects . . . . .
Flushing the document cache . . . . . .
Flushing the stylesheet cache . . . . . .
z/OS NSS Client . . . . . . . . . . .
Creating the z/OS NSS Client . . . . . .
. 390
. 391
. 392
394
. 394
. 395
. 395
. 396
. 396
. 397
Appendix B. Cryptographic support in

actions . . . . . . . . . . . . . . 399
ID references . . . . . . . . .
EncryptedData tokens . . . . . .
Security token references . . . . .
X.509 certificates . . . . . . .
Kerberos AP-REQ tokens . . . .
SAML assertions . . . . . . .
Signature confirmation . . . . . .
Generating a signature confirmation .
Verifying a signature confirmation .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
Appendix C. Working with variables
.
.
.
.
.
.
.
.
.
399
399
400
400
401
401
401
402
402
403
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 . . . . . . . . .
404
404
404
405
406
406
407
408
408
409
410
410
411
411
412
412
414
415
Appendix D. Getting help and

technical assistance . . . . . . . . 417
Searching knowledge bases .
Getting a fix . . . . . .
Contacting IBM Support. .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 417
. 417
. 418
Notices and trademarks . . . . . . . 419

Trademarks .
. 419
Index . . . . . . . . . . . . . . . 421
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 Web
Service Proxy services, objects, and associated referenced objects on the DataPower
appliance. Developers should have the following knowledge:
v Network architecture and concepts
v Internet protocols, including HTTP, TCP/IP, MQ
v
v
v
v
v
Lightweight Directory Access Protocol (LDAP) and directory services

Authentication and authorization
XML and XSLT
Web Services
Web Services Security
Developers should also be familiar with SSL protocol, key exchange (public and
private), digital signatures, cryptographic algorithms, and certificate authorities.
This document assumes that an Administrator has installed and initially
configured the appliance as described in the IBM WebSphere DataPower SOA
Appliances: 9003: Installation Guide or in the IBM WebSphere DataPower SOA
Appliances: Type 9235: Installation Guide, depending on the model type.
How this document is organized

This document is organized across the following broad concepts:
v Chapter 1, WebGUI basics, on page 1
Provides basic informations about using the DataPower graphical interface,
which is referred to as the WebGUI, as well as information about performing
common tasks in the WebGUI.
v Chapter 2, Securing communication, on page 9
Provide information about securing communication to and from the DataPower
appliance. The appliance provide these capabilities with a combination of
utilities and objects.
v Chapter 3, Configuring Web Service Proxy services, on page 25
Provide detailed information about developing Multi-Protocol Gateway services
on a DataPower appliance.
v Chapter 4, Handler configuration, on page 69
Provides information about configuring handler objects to manage incoming
traffic to the appliance.
v Chapter 5, Processing policies, on page 99
vii
Provides information about creating document processing policies.

v Chapter 6, AAA Policy configuration, on page 171
Provides information about creating an AAA policy for a processing action.
v Chapter 7, Managing files, on page 205
Provides information about managing files on the appliance.
v Chapter 8, Managing the configuration of the appliance, on page 213
Provides information about managing the configuration of application domains
and importing and exporting configurations.
v Appendix A, Referenced objects, on page 243
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 399
Provides information about cryptographic support in processing actions.
v Appendix C, Working with variables, on page 403
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
v
v
v
v
Administration documentation on page ix

Development documentation on page ix
Reference documentation on page ix
Integration documentation on page ix
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.
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
viii
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
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:
Preface
ix
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
Simple and Protected GSSAPI Negotiation Mechanism (SPNEGO). SPNEGO is
also referred to as Integrated Windows Authentication.
v Understanding Web Services Policy
Web Services Policy (WS-Policy).
v Understanding WS-Addressing
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.
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:.
Preface
xi
If the directory (or domain) supports subdirectories, the path to the file can have a
length of 4000 characters. When you create a domain, its name is the base file
name in several DataPower directories when viewed from the default domain.
The following characters are valid in directory and file names:
v a through z
v A through Z
v 0 through 9
v _ (underscore)
v - (dash)
v . (period)
Note: Names cannot contain two consecutive periods (..).
Object naming guidelines

The object name must be unique in the object namespace. The following characters
are valid in when specifying the name for an object:
v a through z
v A through Z
v 0 through 9
v _ (underscore)
v - (dash)
v . (period)
Note: Names cannot contain two consecutive periods (..).
Typeface conventions
The following typeface conventions are used in the documentation:
bold
Identifies commands, programming keywords, and GUI controls.
italics
Identifies words and phrases used for emphasis and user-supplied

variables.
monospaced
Identifies user-supplied input or computer output.
xii
Chapter 1. WebGUI basics

The WebGUI is the primary interface for managing the appliance itself and for
configuring objects.
Objects on the appliance

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

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

To use the WebGUI, the Web Management Interface must be configured. This
interface was defined during the initial firmware setup (during appliance
installation) or afterward with the web-mgmt command.
To access the WebGUI, use the following procedure:
1. Direct your browser to the WebGUI login screen. Use the IP address and port
number assigned during the configuration of the Web Management interface.
The address uses the HTTPS protocol and has the https://address:port
format.
2. In the login fields, specify an account name and password.
3. From the Domain list, select the domain to which to log in.
4. Click Login.
After verifying credentials, the WebGUI displays the Control Panel.
Welcome screen
After successfully logging in, the WebGUI displays its Welcome screen. Visibility of
objects in the WebGUI is controlled by a combination of the Role-based
management (RBM) object and whether the administrator is in the default domain
or an application domain.
This screen is separated into the following areas:

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

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

When using the WebGUI to create and modify objects, the configuration screen
might display an input field to select a referenced object. Figure 1 illustrates this
type of input field.
Input
Figure 1. Input field for referenced objects
When the WebGUI displays this type of input field, you can specify the referenced
object in the following ways:
v Select the name of an existing referenced object from the list.
v Use the + button to create a new referenced object. When created, the input field
contains the name of the newly created referenced object.
v Use the ... button to modify the referenced object whose name is in the input
field. When modified, the input field retains the name of the referenced object.
When you click the + button or ... button, the WebGUI launches a new window
that displays the configuration screen for that type of object.
Working with lists of referenced objects

When using the WebGUI to create or modify objects, the configuration screen
might display an input list to define a group of referenced objects. The input for
this configuration item is the list of referenced objects. Figure 2 illustrates this type
of input list.
Input
Delete
Add
Figure 2. Input list for referenced objects
When the WebGUI displays this type of list, you can manage referenced objects in
the following ways:
v Select the name of an existing referenced object from the list. Click Add to add it
to the list of referenced objects.
v Use the + button to create a new referenced object. When created, the input field
contains the name of the new referenced object. Click Add to add it to the list of
referenced objects.
v Use the ... button to modify the referenced object whose name is in the input
field. When modified, the input field retains the name of the referenced object.
Click Add to add it to the list of referenced objects.
v Select the name of a referenced object from the list (either the input field or the
list of referenced objects). Click Delete to remove it from the list of referenced
objects.
When you click the + button or ... button, the WebGUI launches a new window
that displays the configuration screen for that type of object.
Viewing and editing local files during configuration

As you use the WebGUI to select a local file during configuration, the
configuration screen might display the View and Edit buttons beside the selection
lists.
Working with files in this way has the following advantages:
v Ensure that the file is the one that you want
v Ability to edit the file to address errors found while defining a configuration
v Use a single session instead of opening another session to manage files through
the File Management utility
You cannot view or edit remote files.
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.
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:
this object.
2. Click the name of the object to delete to display the configuration screen.
3. Click Delete.
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:
this object.
2. Click the name of the object to export to display the configuration screen.
3. Click Export.
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:
this object.
2. Click the magnifying glass icon.
Viewing messages from the configuration pane

To view configuration-specific messages from the configuration pane:
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:
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.
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.

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.
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.
10
on
Writes the key file to the temporary: directory.
off
(Default) Does not write the key file to the temporary: directory.
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.
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.
11
1. Select Administration Miscellaneous Crypto Tools to display the Crypto

Tools screen.
2. Click the Export Crypto Object tab.
3. Provide the following information:
Object Type
Select the type of object to export. Any appliance can export certificates.
Devices with HSM hardware can export private keys.
Object Name
Type the exact name of the object. To view a list of all such objects,
select Objects Crypto Objects Cryptographic Certificate (or Key).
Output File Name
Specify the name of a export package to contain the exported objects.
Do not specify a local directory or file extension. The appliance writes
the file to the temporary: directory.
Encryption Mechanism
Select Key-Wrapping-Key.
Note: Available when the appliance has HSM hardware to specify the
encryption mechanism to export private keys.
4. Click Export Crypto Object to create the export package with the selected
object.
Use the File Management utility to access the file.
Importing keys and certificates

Use the Import Crypto Objects tab of the Crypto Tools screen to import key and
certificate objects.
Objects that are exported from one DataPower appliance can be imported to
another appliance. Importing objects, rather than uploading files, eliminates the
need to create objects from files.
Note: If the appliance has HSM hardware, you can import Key objects. For details,
refer to IBM WebSphere DataPower SOA Appliances: Hardware Security Module
Guide.
1. Select Administration Miscellaneous Crypto Tools to display the Crypto
Tools screen.
2. Click the Import Crypto Object tab.
3. Provide the following information:
Object Type
Select the type of object to import. Any appliance can import
certificates. Devices with HSM hardware can import private keys.
Object Name
Specify the name of the object to create on import. This name must be a
unique in the object namespace.
Input File Name
Use the controls to select the export package. If the file does not reside
on the DataPower appliance, click Upload or Fetch to transfer the file.
12
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 396.
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.
13
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
14
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.
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.
Admin State
Private Key
Select Key objects to add. Refer to Defining Key objects on page 17
for more information.
Shared Secret Key
Select Shared Secret Key objects to add. Refer to Defining shared
secret keys on page 20 for more information.
Certificates
Select Certificate objects to add. Refer to Defining Certificate objects
on page 13 for more information.
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:
15
Admin State
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 17
Certificate
Access a list of all Certificate objects, and select the Certificate object for
this Identification Credentials. Refer to Defining Certificate objects on
page 13 for more information.
Intermediate CA Certificate
Intermediate CA certificates might be required when the CA that is
signing this certificate is not widely-recognized. If the intermediate CA
certificate is also signed by a less recognized CA, an additional
intermediate CA certificate might be required for that CA. You can
specify as many intermediate certificates as are required.
If necessary, use the list of available Certificate objects to establish a
verifiable trust-chain. A trust-chain consists of one or more Certification
Authority (CA) certificates and provides a linked path from the
certificate that is in the Identification Credentials to a CA that is trusted
by a remote appliance. The trust chain enables the appliance to
authenticate the certificate.
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.
16
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 396.
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.
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 208 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.
17
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.

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.
Name
Admin State
Identification Credentials
Select the Identification Credentials to assign to this Profile object, or
retain the default value, none, when no Identification Credentials is
needed.
The Identification Credentials provides the PKI certificate-key pair that
will be used to authenticate the appliance during the SSL handshake.
Refer to Defining Identification Credentials objects on page 15 for more
information.
Validation Credentials
Select the Validation Credentials for this Profile object, or retain the
default value, none, when no Validation Credentials is needed. Refer to
Validation credentials on page 22 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
18
Includes all cipher suites, except the eNULL ciphers.
DEFAULT
Includes all cipher suites, except for the following ciphers and
cipher suites:
v eNULL ciphers
v Cipher suites that use DH authentication
v Cipher suites that contain the RC4, RSA, and SSL version 2
ciphers
HIGH Includes all high encryption cipher suites. These ciphers
support a key length in excess of 128 bits.
MEDIUM
Includes all medium encryption cipher suites. These ciphers
support a key length of 128 bits.
LOW
Includes all low encryption cipher suites. These ciphers support

a key length of 56 or 64 bits, but exclude EXPORT cipher suites.
EXPORT
Includes all cipher suites that support a key length of 40 or 56 bits
and are eligible for export outside of the United States.
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.
19
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
5. From the File Name list, select the file that contains the key material.
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.
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.
20
Creating a reverse (or server) proxy

To create a reverse SSL Proxy Profile, use the following procedure:
catalog.
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


Creating a two-way proxy

To create an SSL Proxy Profile, use the following procedure:
catalog.
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.
21
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

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


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.
22
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.
Name
Admin State
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.
23
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
24
Chapter 3. Configuring Web Service Proxy services

A single Web Service Proxy object can handle traffic that is bound for all endpoints
that are described in multiple WSDL files. For example, a Web Service Proxy could
include the following WSDL files:
v A WSDL file for service endpoints that query accounts
v A WSDL file for service endpoints that modify accounts
v A WSDL file for service endpoints that manage certificates of deposit
A remote client can use the address and port that are assigned to a single Web
Service Proxy to obtain services from all endpoints that these WSDL files describe.
Note: The combined WSDL file is used for publishing to remote registries. Refer to
Defining the user policy on page 39 for information about how to control
endpoints.
Creating a Web Service Proxy

To create a Web Service Proxy, you only need to define the basic configuration. The
basic configuration consists of specifying the source of the configuration. The
configuration source can be any combination of the following types:
v One or more WSDL files
v One or more UDDI subscriptions
v One or more WSRR subscriptions
After providing the basic configuration, you can perform the following activities:
1. Configure Service Level Monitor (SLM) objects and SLM peer groups
2. Configure the policy, which includes defining processing rules, the Web
Services policy (WS-Policy), the Web Security conformance policy (WS-I
Conformance Policy), and the user policy
3. Modify default basic proxy settings and configure advanced proxy settings
4. Configure header and parameter settings, which includes adding header
injection parameters, adding header suppression parameters, and defining
stylesheet parameters
5. Configure the mediation for Web Services Addressing between the requesting
clients and the responding server
6. Configure for Reliable Messaging
7. Implement proxy-specific threat protection measures
Defining the basic configuration

To define the basic configuration, perform the following steps:
1. From the Control Panel, click the Web Service Proxy icon to display the Web
Service Proxy catalog.
2. Click Add.
3. Specify the name of the Web Service Proxy in the Web Service Proxy Name
field, and click Create Web Service Proxy to display the Web Service Proxy
(WSDLs) configuration screen.
25
4. Select the configuration source.

v To use WSDL files:
a. Retain or click Add WSDL as the source.
b. Specify or select the location of the WSDL file in the WSDL File URL
fields.
If the file is on the appliance, select the local file from the directory
and file lists.
If the file is on the local workstation, click Upload and copy the file
to the local: directory. Refer to Uploading files from the workstation
If the file is on a remote server, click Fetch and copy the file to the
local: directory. Refer to Fetching files on page 210 for more
information.
v To use a UDDI subscription:
a. Click Add UDDI Subscription as the source.
b. Under UDDI Subscription Name, determine whether to use a new or
existing UDDI Subscription object.
If new:
1) Specify a unique alphanumeric name for a new subscription in
the input field.
2) Specify a subscription key value from the UDDI Registry in the
Subscription Key field and click Add. This key value should be
copied from the Registry display into this field. Here is an
example key value:
uddi:3e5bf2f0-21a7-11db-953d-6acc5ca1953d
Repeat as needed to include all keys to configure the Proxy.

Typically, at least two keys are needed, one for the
bindingTemplate and one for the tModel that includes the bulk of
the WSDL information. For more information, refer to UDDI
Subscription on page 333.
3) Select an UDDI Registry object from the UDDI Registry list. This
object defines the address of the remote registry, among other
properties. The Registry selected must host the subscriptions used
in the Subscription Key list.
4) Specify the user name needed to authenticate with the selected
Registry to obtain the subscription information desired in the
Username field. This value will be used for all of the keys
included; the remote Registry must be configured to use this same
value for all the desired subscription keys.
5) Specify the Password needed to authenticate with the selected
Registry in the Password field. This password must correspond
with the supplied user name.
6) Confirm the password in the Confirm Password field.
If existing, click Existing and select the subscription object. The
screen refreshes with the properties of the selected subscription.
v To use a WSRR subscription:
a. Click Add WSRR Subscription as the source.
b. Under WSRR Subscription Name, determine whether to use a new or
existing WSRR Subscription object.
If new:
26
1) Click New and specify a unique alphanumeric name for a new

subscription in the input field.
2) Select the resource type from the Subscription Object list.
3) Select the WSRR server from the WSRR Server list. Refer to
WSRR Server on page 391 for additional information.
4) Unambiguously identify the subscribed-to resource. The resource
name and namespace are assigned when a resource, such as a
WSDL file, is loaded to a WSRR or when a collection of resources
is aggregated as a concept.
a) Specify the name of the object in the Object Name field.
b) Specify the namespace in the Namespace field.
5) Select the synchronization method from the Synchronization
Method list.
6) When the synchronization method is Poll, specify the interval in
seconds between polls in the Refresh Interval field.
7) Use the Use WSDL Version toggle to enable (on) or disable (off)
having the WSRR subscription service retrieve a WSDL file with a
user-specified version number from the registry. The default is off.
If you specify on, enter the Version number in the WSDL Version
input field. Refer to WSRR Subscription on page 392 for
additional information.
8) Use the Fetch Policy Attachments (Only for WSRR 6.1 Server)
toggle to enable (on) or disable (off) having the WSRR
subscription service retrieve Web Service Policy attachments that
apply to a WSDL file. The default is on. Retrieved policies apply
to any WS-Proxy meeting the following conditions:
- Uses the same WSRR subscription service
- The subscription service allows external policy attachments
- Uses WSRR server version 6.1 or higher
If existing, click Existing and select the subscription object. The
screen refreshes with the properties of the selected subscription.
5. Use the Use WS-Policy References toggle to indicate whether to use policies
that are defined in the WSDL files and policies that are referenced in the
WSDL files with wsp:PolicyURIs attributes or with <wsp:PolicyReference>
elements.
v A wsp:PolicyURIs attribute allows policy expressions to be attached to
arbitrary XML elements. These attachments can be referred to as XML
element attributes.
v A <wsp:PolicyReference> element references a policy expression to be
attached to the policy subjects are in the policy scope. These attachments
can be referred to as external policy attachments.
on
(Default) Enables policies that are defined in or referenced by the

WSDL file.
Disables policies that are defined in or referenced by the WSDL file.

Uses only policies that are defined through augmentation.
When enabled, provide the following inputs:
a. Select the Policy Parameters object from the WS-Policy Parameter Set list.
off
b. Select the enforcement mode for the WSDL file from the WS-Policy
Enforcement Mode list.
27
enforce
Creates a configuration that might transform client requests or
client responses to satisfy policy.
filter
Creates a configuration that rejects client requests and server

responses that do not satisfy policy. A rejection triggers error
handling.
For example, if a policy requires a response to be encrypted, filter will

reject the response and trigger error handling if the response is not
encrypted, but enforce will encrypt the response.
If the mode is enforce and the configuration does not provide the required
policy parameters to encrypt the response, the mode switches to filter
behavior and triggers error handling and the log contains a message that is
similar to the following warning:
Wed Nov 07 2007 08:24:00 [ws-security-policy][ws-proxy][warn]
wsgw(wssp-policy-015h): tid(1425)[request]: WS-SecurityPolicy
Mapping: A message cannot be encrypted during enforcement
6. Click Next to show the endpoint configuration grid and defined operations
(shown in the blue bar). The grid provides the Local, Remote, and Published
configurations based on the configuration source.
7. Define the endpoint configurations.
v For WSDL-based configurations:
a. For each operation, define the Local configuration.
1) Select a Front Side Handler from the Local Endpoint Handler list.
The handler determines the location that accepts client requests. You
can assign the same handler to each operation or assign a different
handler to each operation. Refer to Chapter 4, Handler
configuration, on page 69 for details.
2) Modify the URI portion of the rewritten Web service binding in the
URI field, as needed.
3) Use the check boxes in the Binding area to specify additional
binding protocol to use in the rewritten Web service. Binding
protocols that the WSDL defines cannot be deselected. For each
additional binding, the configuration creates a new port and
port-operation.
For example if the WSDL defines the SOAP 1.1 binding, you can
select SOAP 1.2 or HTTP GET. However, you cannot deselect SOAP
1.1.
4) Click Add.
If you selected additional binding, the default binding has no suffix and
each of the selected binding has a suffix. For example if you selected
SOAP 1.2 and clicked Add, the Binding (Suffix) column shows soap11()
and soap12(0). These suffixes are represented on the Policy tab for the
synthesized ports and operations to support the additional binding.
b. For each operation, adjust the Remote configuration, as needed.
Generally, an adjustment is not needed. However, it might be useful to
redirect traffic to an alternate endpoint while maintenance or upgrades
are performed on the application server.
c. For each operation, adjust the Published configuration, as needed.
Generally, an adjustment is not needed. By default, the Published
configuration is the same as the Local configuration.
v For subscription-based configurations:
28
a. Select a Front Side Handler from the Local Endpoint Handler list. The
handler determines the location that accepts client requests. You can
assign the same handler to each operation or assign a different handler
to each operation. Refer to Chapter 4, Handler configuration, on page
69 for details.
b. For the Local URI:
Select From WSDL to determine the URI that the Web Service Proxy
uses to accept client requests. When the URL is determined in this
way, the Web Service Proxy obtains the subscription information from
the registry, parses the WSDL information in that subscription, and
instantiates the necessary URLs based on the contents of the WSDL.
Select the other radio button and specify a fixed URI in the associated
field. A URI does not include the protocol, address, or port. For
example, the value /agent/scheduler could represent the URI.
c. Adjust the Remote Endpoint configuration, as needed. An adjustment
might be useful to redirect traffic to an alternate endpoint while
maintenance or an upgrade is performed on the application server.
d. Adjust the Published Endpoint configuration, as needed. An adjustment
usually is not needed. By default, the Published endpoint is the same as
the Local Endpoint configuration.
8. Click Next to display the summary.
If the summary lists an error under WSDL Status or WS-I BP Status, click the
red text (for example, Warning) to view the details.
9. Repeat step 4 on page 26 through step 8 to define all of the configuration
sources for the Web Service Proxy.
10. Click Apply.
To test the service, submit requests to the addresses that are defined by the Front
Side Handlers.
To check the status for subscription-based configurations, select Status Web
Services and view the appropriate UDDI or WSRR subscription-related providers.
Configuring Service Level Monitors

You can define the following types of Service Level Monitor (SLM) objects and
assign an SLM to the current Web Service Proxy from the Web Service Proxy
Configuration (SLM) screen:
v A global SLM that monitors all Web Service Proxy transactions
v A WSDL-specific SLM that monitors all services that are described in a specific
WSDL file
v A service-specific SLM that monitors a single Web service
v A port-specific SLM that monitors a single Web service port
v An operation-specific SLM that monitors a single Web service operation
v A custom SLM Statement that provides more precise control of monitored
transactions
You can click the expansion icons to expand the view of the current Web Service
Proxy. The display provides the following blank templates:
Web Service Proxy template
Use this template to create a global SLM to monitor all transactions and
errors in the scope of the Web Service Proxy.
29
WSDL template
Use this template to create a WSDL-specific SLM to monitor all
transactions and errors in the scope of a WSDL file; note that if the Web
Service Proxy is based upon a single WSDL file this template and the
Services Proxy template are equivalent.
WSDL Service template
Use this template to create a WSDL-service-specific SLM to monitor all
transactions and errors in the scope of a WSDL service.
WSDL Port template
Use this template to create a WSDL-port-specific SLM to monitor all
transactions and errors in the scope of a WSDL port.
WSDL Operation template
Use this template to create a WSDL-operation-specific SLM to monitor all
transactions and errors in the scope of a WSDL operation.
Each template supports the specification of a transaction-based rule and an
error-based role. The transaction-based rule is based on a raw count of
transactions. The error-based rule is based on transaction errors. Dual rules mean
that you can implement level-specific restrictions based on transaction volume and
error frequency.
1. In the Request area, define a basic transaction-based rule to count all user
transactions during the specified interval. This rule is always scheduled.
a. In the Interval field, enter the number of seconds to count user transaction.
b. In the Limit field, enter the maximum rate of allowed transactions per
second.
c. From the Action list, select the SLM action to enforce for transactions in
excess of the maximum rate.
2. In the Failure area, define a basic error-based rule to count all error
transactions during the specified interval. This rule is always active.
a. In the Interval field, enter the number of seconds to count user transaction.
b. In the Limit field, enter the maximum rate of allowed transactions per
second.
c. From the Action list, select the SLM action to enforce for transactions in
excess of the maximum rate.
3. Click Apply to complete basic specification.
Submit requests to the Web Service Proxy to create a flow of traffic. At any time,
click the Graph alongside any level at which you specified some threshold. A new
window displays a graph of the traffic during the selected interval. Refer to
Reading traffic graphs for details.
Reading traffic graphs

When you click Graph, the new window displays the graph of the traffic during
the selected interval. A graph can show the following traffic definitions:
v Rate
v Latency
v Count
The x-axis shows the time interval, and the y-axis shows the total traffic in 10%
increments. Refer to Traffic definitions on page 231 for details about the types of
traffic definitions that are displayed.
30
Creating an SLM peer group

Peer Groups enable the exchange of SLM data among a group of DataPower
appliances. This exchange provides for the enforcement of SLM policies across
multiple appliances. Group members use SOAP over HTTPS to exchange SLM data
at periodic intervals, must be running identical SLM configurations, and must be
clock-synchronized. The update messages with the newly received update
information is aggregated in the information store of each group member.
Note: You can use the NTP service to synchronize the clocks among a group of
DataPower appliances. For information about enabling the NTP service,
refer to IBM WebSphere DataPower XML Integration Appliance XI50:
Administrators Guide.
To add an appliance as an SLM peer:
1. Specify the URL of the peer DataPower appliance in https://IP_address:port
format. The default SOAP over HTTPS port for the XML Management Interface
is 5550. If this port was changed on any of the peers, this entry must reflect the
correct port.
2. Click Add.
Note: The membership list must be identical across all group members. When
creating the membership list, include the current appliance.
Refer to Defining peer groups on page 313 for additional details.
Defining an SLM statement

You can define an SLM statement to provide more precise control of monitored
transactions. Refer to Service level monitors on page 309 for more information.
To define a custom SLM Statement:
1. Click Create New Statement.
2. Optional: In the User Annotation field, enter any desired comment.
3. From the Credential Class list, select a credentials class for use by this policy.
Refer to Creating an SLM credentials class on page 311 for more
information.
4. From the Resource Class list, select a resource class for use by this policy.
Refer to Creating an SLM resource class on page 312 for more information.
5. From the Schedule list, select an SLM schedule for use by this policy. Refer to
Defining an SLM schedule on page 313 for more information.
6. From the SLM Action list, select the control procedure to enforce for
transactions that exceed the threshold. Refer to Defining an SLM action on
7. In the Threshold Interval Length field, enter the measurement interval in
seconds.
8. From the Threshold Interval Type list, select how to measure intervals.
9. From the Threshold Algorithm list, select the algorithm.
v If High-Low, specify the low threshold in the High Low Release Level
field. The threshold is triggered (and an action enforced) when the
threshold level is reached. Enforcement continues until the value specified
by this low threshold is reached.
v If Token Bucket, specify the maximum allowable burst in the Burst Limit
field. Use a value that is approximately twice the value of threshold level.
31
10. From the Threshold Type list, select the threshold type.
11. In the Threshold Level field, enter the count or value threshold to trigger the
action. The units of measure depends on the threshold type.
v If the threshold type is a count, the value indicates an aggregate number.
v If the threshold type is for latency, the value indicates a number of seconds.
12. In the Reporting Aggregation Interval field, enter the reporting interval in
minutes. This property determines the interval to report statistics. This
property has no effect on threshold intervals.
13. In the Maximum Records Across Intervals field, enter the maximum
aggregate of reporting records.
14. In the Maximum Records Across Intervals field, enter the maximum
aggregation of reporting records. A single aggregation interval could contain
multiple records; for example, one record per resource or credential. Use this
property to configure the maximum number of total records to save across the
maximum number of saved intervals.
15. In the Maximum Credentials-Resource Combinations field, enter the number
of records for the combination of credentials and resources. This property
limits the maximum number of combinations and allows a maximum
memory-consumption threshold to be set.
16. Click Add SLM Statement.
Configuring the policy

You can assign level-specific processing policies from the Web Service Proxy
Configuration (Policy) screen.
1. Click the Policy tab to display the Web Service Proxy Configuration (Policy)
screen.
Web Service Proxy Policy

Open tree to: Proxy | WSDLs | Services | Ports | Operations
proxy: proxy-name
WS-Policy: value
WS-I Conformance:
value
Priority:
value
rule-name (rule-type)
rule-name (rule-type)
+ Add Rule
wsdl: WSDL-name
Figure 3. Sample policy screen
2. Determine the view from which to manage the policy. Refer to Determining
the view for the policy on page 33 for details.
3. Define processing rules at any level by clicking the level-specific Add Rule
button. Refer to Processing rules on page 33 for details.
4. Define the Web Security Policy to apply to this level of the WSDL file. Refer to
Defining the Web Services policy on page 34 for details.
32
5. Define the Web Security conformance policy to apply to this level of the WSDL
file. Refer to Defining the Web Security conformance policy on page 37 for
details.
6. Define the priority to apply to this level of the WSDL file. Refer to Defining
the service priority on page 39 for details.
7. Define the user policy to apply to this level of the WSDL file. Refer to
Defining the user policy on page 39 for details.
On requests, the Web Service Proxy uses the policy as defined by the following
flow:
1. The defined Web Security policy
2. The defined Web Security Conformance Policy
3. The defined user policy
4. The defined processing rule
On responses, the Web Service Proxy uses the policy as defined by the following
flow:
1. The defined user policy
2. The defined processing rule
3. The defined Web Security Conformance Policy
4. The defined Web Security policy
Determining the view for the policy

You can use the WebGUI to augment policy for the endpoint policy subject and for
the operation policy subject. The WebGUI provides two tree views for the policy: a
standard view and a fully expanded tree view. The difference between these views
is that the fully expanded view allows the augmentation of policy to portType
elements and to binding elements of the WSDL document. Only in the fully
expanded view is it possible to augment policy for these elements for the endpoint
policy subject and for the operation policy subject.
To augment policy for portType elements or for binding elements of the WSDL
document, click yes at the Show portType and binding nodes field. This field is
located at the upper right-hand portion of the WebGUI.
Depending on the current view, the WebGUI might not display these nodes. In this
case, click the expansion icons to expand the current view of the policy.
Processing rules
A Web Service Proxy automatically runs a number of actions before running the
first visible action in its processing rules. Specifically, a Web Service Proxy runs an
slm action and a validate action.
Note: The validate action might reject the message before running any visible
action. Use the User Policy check boxes to control the behavior of the
implied validate action. Refer to Defining the user policy on page 39 for
details.
33
Processing rules in the policy hierarchy execute from most specific to least specific.
A processing rule at the Operation level executes before a processing rule at the
Service, WSDL, or Proxy level. Only one processing rule executes on any single
message.
To create a processing rule at any level, use the following procedure:
1. Click Add Rule at the appropriate level. The screen refreshes to show the
processing rule area.
2. Define the processing rule. Refer to Chapter 5, Processing policies, on page 99
for details.
Note: Processing Policy objects and Processing Rule objects for Web Service Proxy
Services cannot be used by other DataPower services. Conversely, Processing
Policy objects and Processing Rule objects for other DataPower services
cannot be used by Web Service Proxy services.
Web Service Proxy services can accept encrypted messages when the entire
payload is encrypted. Either the root node of the message must be encrypted, or
the first child of the SOAP:Body element must be encrypted.
The Web Service Proxy automatically decrypts the encrypted payload. The
decryption uses the private key that corresponds to the certificate that encrypted
the data. The certificate is identified by an Identification Credential object or is
identified by the Decrypt Key property on the Proxy Settings tab.
Note: Web Service Proxy services do not automatically perform field-level
decryption.
Use the following procedure to enable field-level decryption:
1. Use the User Policy check boxes to disable automatic validation. Refer to
Defining the user policy on page 39 for details.
2. Create a new rule with the decrypt and validate actions.
v Configure the decrypt action to perform the field-level decryption.
v Configure the validate action to perform any required validation.
Refer to Chapter 5, Processing policies, on page 99 for details.
Defining the Web Services policy

The policy for the Web Service Proxy has the following hierarchy based on the
configuration source:
v proxy
v wsdl
v service
v port
v port-operation
To define the Web Services policy (WS-Policy), use the following procedure:
1. Click WS-Policy to open the configuration area. This button is shown in
Figure 3 on page 32.
Based on the level of the hierarchy, the WS-Policy configuration options change
in the following manner:
v At the proxy level, the Sources tab is disabled. At this level, you cannot
augment policy.
34
v At the wsdl level, the Processing tab provides a property to indicate the
enforcement mode (enforce or filter). This is the only level where this
property is available. Although the Sources tab is enabled, you can only
indicate whether or not you want to use policy that is defined in or
referenced by the source WSDL file. At this level, you cannot augment policy.
v At the service level, all tabs are enabled. You can augment policy through
the WebGUI. The augmented policy applies to the service policy subject (for
example, wsdl11:service).
v At the port, binding, and portType levels, all tabs are enabled. You can
augment policy through the WebGUI. The augmented policy applies to the
endpoint policy subject (for example, wsdl11:port, wsdl11:binding, or
wsdl11:portType).
Note: If you added support for additional bindings, the Sources tab is
disabled on the synthesized port. The augmented policy for
synthesized ports must be inherited from the service level.
v At the binding-operation and portType-operation levels, all tabs are
enabled. You can augment policy through the WebGUI. The augmented
policy applies to the operation policy subject (for example,
wsdl11:operation).
v At the port-operation level, the Sources tab is disabled. At this level, you
cannot use the WebGUI to augment policy. To augment policy for the
operation policy subject, you must manually edit the WSDL file to provide
the policies as embedded policy.
2. Select the enforcement mode for the WSDL file from the WS-Policy
Enforcement Mode list.
enforce
Creates a configuration that might transform client requests or client
responses to satisfy policy.
Creates a configuration that rejects client requests and server responses
that do not satisfy policy. A rejection triggers error handling.
For example, if a policy requires a response to be encrypted, filter will reject
the response and trigger error handling if the response is not encrypted, but
enforce will encrypt the response.
filter
If the mode is enforce and the configuration does not provide the required
policy parameters to encrypt the response, the mode switches to filter behavior
and triggers error handling and the log contains a message that is similar to the
following warning:
Wed Nov 07 2007 08:24:00 [ws-security-policy][ws-proxy][warn]
wsgw(wssp-policy-015h): tid(1425)[request]: WS-SecurityPolicy
Mapping: A message cannot be encrypted during enforcement
3. Select the Policy Parameter object from the Policy Parameter Set list, click the +
button to create a new object, or click the ... button to edit an existing object. A
Policy Parameters object defines policy parameters as key-value pairs for use in
a policy mapping style sheet. The Policy Parameter object persists the values of
the policy parameters.
A policy parameter is the way that you must map the needed parameters that
are defined in or referenced by the WSDL file or that are defined in an attached
source to the specific DataPower object. If you do not define all of the needed
parameters, processing a message with the defined WS-Policy generates errors.
35
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}wssecpol-Certificate parameter to alice.
Note: If you defined a policy parameters at the port or port-operation level,
these parameters are not applied to its parallel synthesized port or
operation. The policy parameters for synthesized ports and operations
must be inherited from the service level or redefined at the synthesized
level.
If creating a new object or modifying an existing object, use the following
procedure:
a. Specify the name of the Policy Parameter in the Name field.
b. Select the policy domain from the Policy Domain list. Using the previous
example, select http://docs.oasis-open.org/ws-sx/ws-securitypolicy/
200702.
c. Select the assertion filter from the Assertion Filter list. Using the previous
example, select X509Token.
d. Select the parameter name from the Parameter Name list. Using the
previous example, select ws-secpol-Certificate.
e. Specify the value for the parameter in the Parameter Value field. Using the
previous example, specify alice.
f. Click Add.
Repeat this procedure for each required policy parameter.
g. After defining all policy parameters, click Submit.
4. Click the Sources tab to define the behavior of policy attachments.
a. In the WSDL-Embedded Policy References area, click the Use WSDL
Policy References check box to enable policies that are attached to WSDL
with wsp:PolicyURIs attributes or with <wsp:PolicyReference> elements.
v An wsp:PolicyURIs attribute allows policy expressions to be attached to
arbitrary XML elements. These attachments can be referred to as XML
element attachments.
v An <wsp:PolicyReference> element references a policy expression to be
attached to the policy subjects that are in the policy scope. These
attachments can be referred to as external policy attachments.
b. Use the Use Additional Policy Sources area to collect individual policy
assertions into a policy expression. To help you configure policy that defines
policy expression, select the template file that contains the policy expression
store:///policies/templates
The templates in this directory correlate to a well-known set of
security patterns for deployed Web services.
store:///policies/templates/bea
The templates in this directory interoperate with BEA-specific
security patterns.
store:///policies/templates/dotnet
The templates in this directory interoperate with .NET-specific
security patterns.
Refer to online help for details about individual template files.
1) Select or specify the URL of the XML template file that contains the
policy expression.
36
2) If the template contains multiple Policy elements and you do not want
to use all of these elements, select the identifier of the element to add
from the wsu:ID list.
3) Click Attach Source.
4) After adding all external attachments, click Done.
Beside the WS-Policy button, the WebGUI shows the number of external
attachments. If there are two external attachments, the WebGUI shows 2
external attachments. If there are no external attachments, the WebGUI
shows (default).
5. Click the Enabled Subjects tab to indicate whether policy defined for that
policy subject should be enforced during processing, not during configuration.
Note: If you modified enablement at the port or port-operation level, these
settings are not applied to its parallel synthesized port or operation.
These settings for synthesized ports and operations must be inherited
from the service level or redefined at the synthesized level.
Use the following check boxes to enable the associated policy subjects. When
not selected, the policies that are defined for the associated policy subjects are
disabled. These policies are disabled regardless of how the policy was defined.
Remember that policy can be defined in the following manners:
v Directly in the configuration source (WSDL file or subscription)
v As XML element attachments (wsp:PolicyURIs attributes) in the configuration
source (WSDL file or subscription)
v As external policy attachments (<wsp:PolicyReference> elements) in the
configuration source (WSDL file or subscription)
v Through policy subject inheritance
v Through refinement by augmenting policy (additional policy sources on the
Sources tab)
Service Subject
If selected, enforce the policy that is defined for the service policy
subject.
Endpoint Subject
If selected, enforce the policy that is defined for the endpoint policy
subject.
Operation Subject
If selected, enforce the policy that is defined for the operation policy
subject.
Message Input Subject
If selected, enforce the policy that is defined for the message policy
subject when the message is an input message.
Message Output Subject
If selected, enforce the policy define for the message policy subject
when the message is an output message.
6. Click Done.
Click Close to close this configuration area.
Defining the Web Security conformance policy

To define the Web Security conformance (WS-I Conformance) policy, use the
following procedure:
37
1. Click WS-I Conformance to open the configuration area. This button is shown
in Figure 3 on page 32.
2. Click Create New to display the configuration details.
3. Specify the name of the policy in the Conformance Policy Name field.
4. 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
in WS-I Attachments Profile, version 1.0.
WS-I BSP 1.0
in WS-I Basic Security Profile, version 1.0.
5. 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.
6. Click the Advanced tab.
7. 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.
8. For all nonconformance reporting levels except Never, specify the target URL
to which to send conformance reports in the Destination field.
9. 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
38
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.
10. 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.
11. 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.
12. 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.
13. Click Done to assign the conformance policy.

Defining the service priority

To assign a priority for scheduling or for resource allocation, use the following
procedure:
1. Click Priority to open the configuration area. This button is shown in Figure 3
on page 32.
2. Select the service priority:
High
Receives above normal priority.
Normal
(Default) Receives normal priority.
Low
Receives below normal priority.
Defining the user policy

You can control the availability and behavior of each component level of the
included WSDL files that are made available by the Web Service Proxy.
A WSDL file can provide the following component levels:
v WSDL
v Service
v Port
v Operation
39
Note: You can control the degree of validation performed on WSDL components
with a Compile Options Policy object. The Compile Options Policy is part of
the configuration of an XML Manager. The assignment of an XML Manager
is part of the configuration of the Web Service Proxy. Refer to Compile
Options Policy objects on page 284 for more information.
To control the availability and behavior of WSDL components, click any of the
small icons at the desired level to display the form that controls behavior. Figure 4
show the series of icons.
Figure 4. User policy controls
Use the check boxes to establish the desired policy. After establishing the policy,
the icons represent the applied selections.
v When a check box is selected, it indicates that the selection is applied. The icon
for this selection contains a green check mark.
v When a check box is not selected, it indicates that a selection is not applied. The
icon for this selection contains a red x.
The established policy cascades. When the policy cascades, the policy applies to all
components that are contained by the current level.
Use the following controls to establish the availability and behavior of policy to
apply to WSDL components:
Enable this component
When selected, allows requests for the operations and services included by
this component level. A WSDL component, for example, includes all ports,
services and operations defined in the WSDL.
Publish in WSDL
When selected, include the component in any WSDL published to external
directories or returned in the WSDL produced by the proxy in response to
requests by external clients. It is possible to enable an operation but not
publish it until some other time, or to stop publishing it after a sunset
period, for example.
Schema validate fault messages
When selected, validates fault messages against the schema contained in
the corresponding WSDL. Not all WSDL files contain schema information
for faults; for this reason, the Proxy will allow fault messages to pass when
no fault schema information is available. When this is checked, and the
WSDL contains fault schema information, fault messages are checked
against that schema and rejected if they do not validate.
Schema validate request messages
When selected, validates request messages against the schema contained in
the corresponding WSDL. Otherwise, disables standard schema validation
for requests.
Schema validate response messages
When selected, validates response messages against the schema contained
in the corresponding WSDL. Otherwise, disables standard schema
validation for responses.
40
Do not schema validate SOAP headers

When selected, does not validates SOAP headers. A WSDL can contain
schema information about SOAP headers. As this is not a standard
practice, this validation is not performed by default. Otherwise, allows
RPC operation wrapper for fault messages. This setting applies to the full
WSDL file.
Use WS-Addressing
When selected, use Web Services Addressing (WS-Addressing). Otherwise,
ignores WS-Addressing configuration settings. The default is to use
WS-Addressing.
Use WS-ReliableMessaging
When selected, use Web Service Reliable Messaging. Otherwise, ignores all
Reliable Messaging configuration settings. The default is to use Reliable
Messaging.
Configuring basic proxy settings

Click the Proxy Settings tab to display basic Web Service Proxy default settings.
1. Optional: In the Comment field, enter a descriptive summary.
2. Use the Type radio buttons to select the Web Service Proxy type.
Dynamic Backend
Indicates support for multiple backend servers. Backend servers are
configured with a route-action or route-set action in the processing
policy.
Static Backend
Indicates support for a single backend server.
3.
4.
5.
6.
Static from WSDL

(Default) Indicates that basic Web Service Proxy configuration is from
associated WSDL files. Creates a Static Backend URL by rewriting the
wsdl:service address with the Remote Endpoint Rewrite Policy during
configuration and at refresh time.
Optionally select a Cryptographic Key object from the Decrypt Key list. This
key decrypts encrypted payloads.
Specify the full name of the client principal when the Web Service Proxy
needs to decrypt automatically encrypted requests in the Client Principal
field. Use this property when the encryption uses a Kerberos session key or
uses a key that was derived from the session key.
Specify the full name of the server principal when the Web Service Proxy
needs to decrypt automatically encrypted responses in the Server Principal
field. Use this property when the encryption uses a Kerberos session key or
uses a key that was derived from the session key.
Select the Kerberos Keytab that contains the principals for the Kerberos
Keytab list. The Web Service Proxy uses these principals to decrypt
automatically encrypted requests and responses
7. Use the SOAP Action Policy radio buttons to determine the handling of the
HTTP SOAPAction header.
Lax (Default) An empty header or a header that contains the empty string
from the client is considered a match. The client can quote the SOAP
action header. For example, SOAPAction:"" is treated as a match.
Off The header is ignored when issued by clients and is never compared
against the content in the WSDL.
41
Strict
The client must provide the header as it is specified in the WSDL file.
The client can quote the SOAP action header.
8. Select an XML Manager from the XML Manager list. Refer to XML Manager
9. Select an AAA Policy from the AAA Policy list. Refer to Chapter 6, AAA
Policy configuration, on page 171 for more information.
10. If the Type is Static Backend, specify the URL of the backend server in the
Backend URL field. The URL provides the protocol to use. For assistance in
generating a valid URL, click the appropriate Helper button.
If the URL starts with https://, the proxy uses the HTTPS protocol. This
protocol requires an SSL Proxy Profile.
11. Optionally select the SSL Proxy Profile from the SSL Proxy Profile list. The
SSL Proxy Profile acts as an SSL client (that is, when using a secure connection
to the backend servers) and provides the credentials to use when acting as an
SSL client. Refer to SSL Proxy Profile objects on page 20 for more
information.
Note: If a User Agent is in use by the assigned XML Manager, that User
Agent might contain settings that override these SSL settings. Click the
... button beside the XML Manager to access the User Agent. Refer to
User Agent on page 339 for more information.
12. Specify the number of seconds in the Back Side Timeout field that a server
connection can remain idle before it times out and is closed. Use an integer in
the range of 10 through 86400. The default is 120.
13. Select the streaming behavior from the Stream Output to Back list.
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.
14. Select the HTTP protocol version for server-side connections from the HTTP
Version to Server list.
v HTTP 1.0
v HTTP 1.1 (Default)
15. Use the Propagate URI toggle to turn the URI propagation behavior 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.
42
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.
16. Use the Compression toggle to enable (on) or disable (off) GZIP compression
negotiation with the backend server. By default, compression negotiation is
disabled.
17. Specify the number of seconds in the Front Side Timeout field that a client
connection can remain idle before it times out and is closed. Use an integer in
the range of 10 through 86400. The default is 120.
Note: For a Stateful Raw XML connection, set this value higher to ensure that
the connection is not closed due to a timeout.
18. Select the streaming behavior from the Stream Output to Front list.
Buffer Messages
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.
19. Click Apply to save changes to the running configuration.
Configuring advanced proxy settings

Click the Advanced Proxy Settings tab to display basic Web Service Proxy
advanced settings.
Persistent Connections
Use this toggle to enable (on) or disable (off) HTTP persistent connections.
By default, persistent connections are enabled.
Loop Detection
Use this toggle to enable (on) or disable (off) loop-detection. Some protocols
allow loop-detection between hosts. Enable loop detection to include the
HTTP Via: header field. The value of this header field is the name of the
Web Service Proxy. By default, loop-detection is disabled.
Follow Redirects
Use this toggle to enable (on) or disable (off) the following of server-side
redirects (such as HTTP 302) by the appliance. By default, the appliance does
not follow redirects. The number of redirects can be limited by a User Agent
that matches the backend URL that is in use.
43
Rewrite Host Names When Gatewaying

Use this toggle to enabled (on) or disable (off) host rewriting. By default
host-rewriting is enabled.
v When enabled, the backend server receives a request that reflects the final
route. The final route is determined by the DataPower service. The final
route is not the one in the original, client submission.
v When disabled, the backend server receives a request that reflects the
information as it arrived at the DataPower appliance.
Some protocols have distinct name-based elements that are separate from the
URL to demultiplex. HTTP uses the Host header for this purposes.
Web servers that issue redirects might want to disable this feature. These Web
servers often depend on the Host header for the value of their redirect.
Allow Chunked Uploads
Use this toggle to enable (on) or disable (off) the ability to send Content-Type
Chunked Encoded documents to the backend server.
When the appliance employs the HTTP 1.1 protocol, the body of the
document can be delimited by either Content-Length or chunked encodings.
While all servers will understand how to interpret Content-Length, many
applications will fail to understand Chunked encoding. For this reason,
Content-Length is the standard method used. However doing so interferes
with the ability of the 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.
Front Persistent Timeout

Sets the amount of time, in seconds, that a persistent connection can remain
idle on the front side before the appliance closes the connection. Use an
integer in the range of 0 through 18400. The default is 180.
Back Persistent Timeout
Sets the amount of time, in seconds, that a persistent connection can remain
idle on the back side before the appliance closes the connection. Use an
Back Side MIME Header Processing
Use this toggle to enable (on) or disable (off) MIME (Multi-Purpose Internet
Mail Extensions) header processing support.
The body of a message (that is, the payload, independent of any protocol
headers) can sometimes contain MIME headers before any preamble and
44
before the first MIME boundary in the body of the message. These MIME
headers can contain important information that is not available in the
protocol headers, such as the string identifying the MIME boundary.
v When enabled, the Web Service Proxy processes these MIME headers.
v When enabled and there are no MIME headers, the Web Service Proxy
continues to try and parse the message with the available protocol header
information.
v When disabled and MIME headers are present in the body of the message,
these MIME headers are considered part of the preamble and not used to
parse out the message. If the protocol headers (such as HTTP) indicate the
MIME boundaries, the appliance can parse and process individual
attachments. If such information is not available, no attachments can be
parsed from the body of the message.
By default, MIME support is enabled.
Front Side MIME Header Processing
Use this toggle to enable (on) or disable (off) MIME (Multi-Purpose Internet
Mail Extensions) header processing support.
The body of a message (that is, the payload, independent of any protocol
headers) can sometimes contain MIME headers before any preamble and
before the first MIME boundary contained in the body of the message. These
MIME headers can contain important information not available in the
protocol headers, such as the string identifying the MIME boundary.
v When enabled, the Web Service Proxy processes these MIME headers.
v When enabled and there are no MIME headers in the message, the Web
Service Proxy continues to try and parse the message with the available
protocol header information.
v When disabled and MIME headers are present in the body of the message,
these MIME headers are considered part of the preamble and not used to
parse out the message. If the protocol headers (such as HTTP) indicate the
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.
By default, MIME support is enabled.
Service Priority
Optionally select the service priority.
High
Low
Normal
Default parameter namespace
Optionally specify the default XML namespace for parameters that are made
available from the CLI or WebGUI. The default namespace for such
parameters is http://www.datapower.com/param/config.
Query parameter namespace
Optionally specify the default XML namespace for parameters that are made
available from a URL query string. The default namespace for such
parameters is http://www.datapower.com/param/query.
SOAP Schema URL
When the traffic type is SOAP, the SOAP Schema URL field appears. Use
45
this field to specify the full URL to the schema to validate the SOAP schema
for SOAP-formatted messages. When a service is in SOAP mode, either on
the request or response side, it validates incoming messages against a W3C
Schema for SOAP messages. You can customize the schema to use by
changing this property. Change the schema to accommodate nonstandard
configurations or special cases.
Message Processing Modes
Optionally select the check box for one or more message processing modes.
Request rule in order
Enforces first-in first-out serial processing of messages for actions in
the request rule. The appliance initiates and completes request rule
processing for messages in the order that they were pulled from the
frontend request queue. The appliance starts the request rule for the
second message in the request queue only after it completes the
processing of the first message. The backend request queue accepts
whatever message arrives first, except when you enforce Backend in
order serial processing. In that case, the appliance buffers messages
so that it sends messages to the backend request queue in the same
order that they were pulled from the frontend request queue.
Backend in order
Enforces the serial processing of messages delivered to the backend
request queue. If needed, the appliance will buffer messages that
complete request rule processing out of order and only deliver
messages to the backend request queue in the same order that they
were pulled from the frontend request queue.
Response rule in order
Enforces serial processing of messages for actions in the response
rule. The appliance initiates and completes response rule processing
for messages in the order that they were pulled from the backend
reply queue. The appliance starts the 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.
Credentials
Optionally select a Firewall Credentials Set. Refer to Defining Firewall
Credentials objects on page 15 for more information.
Click Apply to save changes to the running configuration.
Optional: Click Save Config to save the changes to the startup configuration.
Configuring header and parameter settings

Click the Headers/Params tab to control the HTTP headers and stylesheet
parameter settings.
Adding header injection parameters

To add a proprietary header field into the Proxy-to-client or Proxy-to-server HTTP
stream, use the following procedure:
1. Click Add under HTTP Header Injection to display the HTTP Header Injection
panel.
46

Direction
Select the direction of the message.
Back
(Default) Indicates a request that travels from the DataPower
appliance to the server.
Front
Indicates a response that travels from the DataPower appliance to
the client
Header Name
Specify the name of the proprietary header.
Header Value
Specify the contents of the proprietary header field.
3. Click Submit.
Adding header suppression parameters

To delete a header field from the Proxy-to-client or Proxy-to-server HTTP stream,
use the following procedure:
1. Click Add under HTTP Header Suppression to display the Proxy Header
Suppression Panel.
Direction
Back
Front
Indicates a response that travels from the DataPower appliance to
the client
Header Tag
Specify the name of the target header (the header field to be deleted).
3. Click Submit.
Defining stylesheet parameters

To pass parameter-value pairs to the style sheets, use the following procedure:
1. Click Add under Stylesheet Parameter to display the Stylesheet Parameter
Property Panel.
Parameter Name
Specify the name of the parameter.
Parameter Value
Specify the value of the parameter.
3. Click Submit.
47
Configuring Web Services Addressing

To enable support for Web Services Addressing (WS-Addressing), click the
WS-Addressing tab to display the WS-Addressing screen. On this screen, specify
the WS-Addressing mode to provide. The level of support is determined by the
WS-Addressing capabilities of the associated clients and servers. The DataPower
service provides the mediation, if any, between clients and servers.
Support for a specific level of WS-Addressing does not preclude simultaneous
support for traditional addressing formats.
Select the mode from the WS-Addressing Mode list.
No WS-Addressing
(Default) Disables WS-Addressing support. Both clients and servers use
traditional addressing. Requires no additional configuration.
Synchronous Gatewayed to WS-Addressing
Specifies that the DataPower service mediates addressing between clients
that use traditional addressing and servers that use WS-Addressing. Refer
to Configuring Traditional to WS-Addressing for configuration details.
WS-Addressing Gatewayed to Synchronous
that use WS-Addressing and servers that use traditional addressing. Refer
to Configuring WS-Addressing to Traditional on page 49 for
configuration details.
Pure WS-Addressing
and servers that use WS-Addressing. Refer to Configuring WS-Addressing
to WS-Addressing on page 51 for configuration details.
Configuring Traditional to WS-Addressing

When Synchronous Gatewayed to WS-Addressing, provide the following inputs:
Strip WS-Addressing Headers
Determines whether to remove all WS-Addressing headers from
server-generated responses before forwarding them to the client.
Note: WS-Reliable Messaging requires the termination of WS-Addressing
sequences. Changing the default value can break interoperability.
on
(Default) Strips WS-Addressing headers.
off
Forwards WS-Addressing headers as is.
WS-Addressing Message Generation Pattern

Specifies the request/response transmission model between the DataPower
service and the target server.
Synchronously
(Default) Identifies a synchronous exchange pattern in which the
server response is received over the same channel used by the
DataPower service to convey the client request.
Out-of-Band
Identifies an out-of-band exchange pattern in which the routing of
the response to the original client is handled by the target server
and does not pass through the DataPower service.
48
If selected, ensure that explicit (non-anonymous) client-originated

ReplyTo and FaultTo element values are preserved by the
DataPower service and passed intact to the server.
Asynchronously
Identifies an asynchronous exchange pattern in which the server
response is received over a different channel than the one used by
the DataPower service to convey the client request.
v Use the WS-Addressing Reply Point property to identify the
Front Side Handler to convey asynchronous server responses to
the original requesting clients.
v Use the WS-Addressing Asynchronous Reply Timeout property
to specify the maximum time for a server response.
Asynchronous HTTP Response Code
Specifies the HTTP Response Code sent to a client prior to transmitting the
actual asynchronous server response to close the original client channel.
If the server response to an HTTP client request is asynchronous, the
DataPower service must close the original HTTP channel with a valid
response code. After the channel is closed, the DataPower service forwards
the server-generated response or fault message to the client over a new
channel.
Use an integer in the range of 200 through 599. The default is 204.
WS-Addressing Asynchronous Reply Point
Select the Front Side Handler to receive asynchronous server responses,
and forward responses to the original client.
Use this property to specify the Front Side Handler that will receive the
asynchronous server response, and then forward the response to the
original client.
The Front Side Handler specified by this property can be programmatically
overridden by the var://context/__WSA_REQUEST/replyto variable.
WS-Addressing Asynchronous Reply Timeout
Specifies the maximum period of time to wait for an asynchronous
response before abandoning the transaction. Use an integer in the range of
1 through 4000000. The default is 120.
The timer value specified by this property can be programmatically
overridden by the var://service/wsa/timeout variable.
Click Apply to save the changes to the running configuration.
Configuring WS-Addressing to Traditional

When WS-Addressing Gatewayed to Synchronous, provide the following inputs:
Rewrite WS-Addressing Reply To Header
Identifies the URL Rewrite Policy used to rewrite the contents of the
WS-Addressing ReplyTo header. Use this property to modify the contents
of an incoming ReplyTo header that identifies the recipient endpoint of
response messages.
Select the URL Rewrite Policy used to manipulate the contents of the
original ReplyTo header.
49
Rewrite WS-Addressing Fault To Header

WS-Addressing FaultTo header. Use this property to modify the contents
of an incoming FaultTo header that identifies the recipient endpoint of
fault messages.
original FaultTo header.
Rewrite WS-Addressing To Header
WS-Addressing To header. Use this property to modify the contents of an
incoming To header that identifies the message destination.
original To header.
Strip WS-Addressing Headers
Determines whether to remove all WS-Addressing headers from
server-generated responses before forwarding them to the client.
Note: WS-Reliable Messaging requires the termination of WS-Addressing
sequences. Changing the default value can break interoperability.
on
(Default) Strips WS-Addressing headers.
off
Forwards WS-Addressing headers as is.
Default WS-Addressing Reply-To

Forces the inclusion of the optional ReplyTo header in WS-Addressing
messages. Use this property to ensure that all messages contain the
optional WS-Addressing ReplyTo header that identifies the recipient
endpoint of a response message.
Because the WS-Addressing specifications do not require the inclusion of
the ReplyTo header, the DataPower service might receive messages that do
not contain a ReplyTo header or that contain the header with no value.
When this happens, the DataPower service modifies the WS-Addressing
message to include a ReplyTo header that contains the URL value specified
by this property.
If a default recipient endpoint of response messages is not explicitly
identified by this command, the DataPower service provides
http://schemas.xmlsoap.org/ws/2004/08/addressing/role/anonymous (the
default value).
Default WS-Addressing Fault-To
Forces the inclusion of the optional FaultTo header in WS-Addressing
optional WS-Addressing FaultTo header that identifies the recipient
the FaultTo header, the service could receive messages that do not contain
a FaultTo header, or that contain the header with no value.
message to include a FaultTo header that contains the URL value specified
by this property.
50

default value).
Force Incoming WS-Addressing
Forces the inclusion of WS-Addressing headers into server-originated
traditionally addressed messages.
In WS-Addressing to Synchronous Mode, the DataPower service generally
handles a mix of Web Service addressed and traditionally addressed
messages. Use this property to ensure that all messages use
WS-Addressing.
on
Converts traditionally addressed messages to WS-Addressing format

through the addition of reply-to and fault-to WS-Addressing
headers.
v The ReplyTo header will contain http://schemas.xmlsoap.org/ws/
2004/08/addressing/role/anonymous (the default value).
v The FaultTo header will contain http://schemas.xmlsoap.org/ws/
off
(Default) Disables the inclusion of WS-Addressing headers into

incoming client requests

channel.
Configuring WS-Addressing to WS-Addressing

When Pure WS-Addressing, provide the following inputs:
Rewrite WS-Addressing Reply To Header
WS-Addressing ReplyTo header. Use this property to modify the contents
of an incoming ReplyTo header that identifies the recipient endpoint of
response messages.
original ReplyTo header.
Rewrite WS-Addressing Fault To Header
WS-Addressing FaultTo header. Use this property to modify the contents
of an incoming FaultTo header that identifies the recipient endpoint of
fault messages.
51
original FaultTo header.
Rewrite WS-Addressing To Header
WS-Addressing To header. Use this property to modify the contents of an
incoming To header that identifies the message destination.
original To header.
Default WS-Addressing Reply-To
Forces the inclusion of the optional ReplyTo header in WS-Addressing
optional WS-Addressing ReplyTo header that identifies the recipient
the ReplyTo header, the service could receive messages that do not contain
a ReplyTo header, or that contain the header with no value.
message to include a ReplyTo header that contains the URL value specified
by this property.
default value).
Default WS-Addressing Fault-To
Forces the inclusion of the optional FaultTo header in WS-Addressing
optional WS-Addressing FaultTo header that identifies the recipient
the FaultTo header, the service could receive messages that do not contain
a FaultTo header or that contain the header with no value.
message to include a FaultTo header that contains the URL value specified
by this property.
default value).
Force Incoming WS-Addressing
Forces the inclusion of WS-Addressing headers into server-originated
traditionally addressed messages.
In WS-Addressing to Synchronous Mode, the DataPower service generally
handles a mix of Web Service addressed and traditionally addressed
messages.
Use this property to ensure that all messages use WS-Addressing.
on
52
The DataPower service converts traditionally addressed messages to

WS-Addressing format through the addition of reply-to and
fault-to WS-Addressing headers.
v The ReplyTo header will contain http://schemas.xmlsoap.org/ws/

v The FaultTo header will contain http://schemas.xmlsoap.org/ws/
off
(Default) Disables the inclusion of WS-Addressing headers into

incoming client requests
WS-Addressing Message Generation Pattern

Specifies the request/response transmission model between the DataPower
service and the target server.
Synchronously
(Default) Identifies a synchronous exchange pattern in which the
server response is received over the same channel used by the
DataPower service to convey the client request.
Out-of-Band
Identifies an out-of-band exchange pattern in which the routing of
the response to the original client is handled by the target server and
does not pass through the DataPower service.
If selected, ensure that explicit (non-anonymous) client-originated
ReplyTo and FaultTo element values are preserved by the DataPower
service and passed intact to the server.
Asynchronously
Identifies an asynchronous exchange pattern in which the server
response is received over a different channel than the one used by
the DataPower service to convey the client request.
v Use the WS-Addressing Reply Point property to identify the Front
Side Handler to convey asynchronous server responses to the
original requesting clients.
v Use the WS-Addressing Asynchronous Reply Timeout property to
specify the maximum time for a server response.
channel.
WS-Addressing Asynchronous Reply Point
Select the Front Side Handler that receives asynchronous server responses,
and forwards such responses to the original client. Use this property to
specify the Front Side Handler that will receive the asynchronous server
response, and then forward the response to the original client.
The Front Side Handler specified by this property can be programmatically
overridden by the var://context/__WSA_REQUEST/replyto variable.
WS-Addressing Asynchronous Reply Timeout
Specifies the maximum period of time to wait for an asynchronous
response before abandoning the transaction. Use an integer in the range of
53
The timer value specified by this property can be programmatically

overridden by the var://service/wsa/timeout variable.
Configuring Reliable Messaging

To enable support for Web Service Reliable Messaging (WS-ReliableMessaging) for
this DataPower service, click the WS-ReliableMessaging tab to display the
WS-ReliableMessaging screen.
Use this screen to specify the WS-ReliableMessaging configuration that this
DataPower service is to provide.
Use WS-ReliableMessaging
Enable or disables Web Services Reliable Messaging.
on
Enables Reliable Messaging.
off
(Default) Disables Reliable Messaging
When enabled, the WebGUI displays the following inputs:

Target Sequence Expiration Interval
Sets the target expiration lifetime in seconds for all Reliable Messaging
sequences.
If an incoming CreateSequence SOAP message has an Expires lifetime that
is longer than this value, the value in the SequenceResponse SOAP message
is reduced to this value. The same process applies to the Expires lifetime
in any accepted Offer in an incoming CreateSequence and for the
requested Expires value in any CreateSequence SOAP call that is made to
the client or server from a Reliable Messaging source. This implementation
never requests or accepts a non-expiring sequence (a value of PT0S that
represents zero seconds).
The default is 3600.
AAA Policy
Selects the AAA Policy to perform authentication of incoming Reliable
Messaging messages. This AAA Policy can be the same one that is used in
later processing by the request or response rule. The results are cached, so
it is not evaluated again.
While this is focused on protecting the Reliable Messaging control
messages, such as CreateSequence and TerminateSequence, it is also run on
incoming Reliable Messaging data messages, with a Sequence header. This
prevents unauthorized clients from using appliance resources by issuing
CreateSequence requests, or from disrupting existing Reliable Messaging
sequences with CloseSequence or TerminateSequence messages, or from
falsely acknowledging messages with SequenceAcknowledgement messages.
SSL session binding
Indicates whether to use an SSL session binding to protect sequence
lifecycle messages.
All Reliable Messaging control messages and sequence messages are bound
to the original SSL/TLS session that is created by the Reliable Messaging
source to transmit the CreateSequence control message. Sequence messages
54
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.
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.
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.

55
off
(Default) Does not accept two-way requests.

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
Messaging queue while waiting for Ack messages. This property
controls memory utilization.
The default is 30.
Source Request Ack Count
Specifies the number of messages that the a Reliable Messaging
source sends before including the AckRequested SOAP header to
request an acknowledgement.
The default is 1.
Source Inactivity Close Interval
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.
56
on
Requires Reliable Messaging for all requests.
off
(Default) Does not require Reliable Messaging for all requests.
Required on Response
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.

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.

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

Retransmission Interval property sets with the initial
timeout.
off

57

The default is 4.
The default is 10.
The default is 1.
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
off

SOAP message.
58
on

timeout.
off


The default is 4.
The default is 10.
The default is 1.
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.
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
server. The Front Side Protocol Handler must be associated with the same
is occurring.
59
This property controls whether the backside Reliable Messaging source

uses a unique URL to receive asynchronous Acks from the server Reliable
Messaging destination, or whether Acks are sent synchronously in future
responses to the backside server.
v With a specified Front Side Protocol Handler and the response process
causes a CreateSequence SOAP message to be sent, the AcksTo element
of the CreateSequence SOAP message will be set to the URL that is
specified in back AcksTo.
v Without a Front Side Protocol Handler, the AcksTo element has the value
http://www.w3.org/2005/08/addressing/anonymous, which indicates
synchronous Acks.
Source Maximum Simultaneous Sequences
Sets a limit on the maximum number of simultaneously active sequences
from Reliable Messaging sources of this DataPower server. Each remote
Reliable Messaging destination endpoint reference (URL) requires one
sequence. Transactions that request the creation of sequences in excess of
this limit result in a SOAP Fault. This property controls memory resource
utilization.
The default is 400.
Configuring XML threat protection

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

Multiple message XML Denial-of-Service (MMXDoS)
SQL injections
Protocol threats
XML viruses (X-Virus)
Dictionary attacks
configure against XML threats, perform the following steps:
Click XML Threat Protection.
Defines all of the properties for threat protection, as needed.
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.
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.
60
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.
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:
61
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.
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
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 136 for more information.
Protocol threat protection

To configure a Web Service Proxy service for protocol threat protection, provide the
following inputs:
Characterize client traffic type
Select the type of request to allow for client requests. The default is SOAP.
62
Characterize server traffic type

Select the type of response to allow for server responses. The default is
SOAP.
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.
Strip

Streaming
63
Unprocessed
attachments.
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 106 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 234
Refer to Adding an AAA action on page 106 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 65.
v For information about using the utility to build a TIBCO EMS URL, refer to
Building a TIBCO EMS URL on page 66.
v For information about using the utility to build a WebSphere JMS URL, refer to
Building a WebSphere JMS URL on page 67.
Building an IMS Connect URL

To use the IMS Connect URL builder for assistance in the construction of a URL,
1. Click IMS Connect Helper.
2. Select an existing instance of the IMS Connect object from the IMS Connect
Config list.
64
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
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)
65
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
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
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.

dptibems://server/?RequestQueue=queue&ReplyQueue=queue&
Selector=expression&RequestReply=queue&Transactional=true
66
Building a WebSphere JMS URL

To use the WebSphere JMS URL builder for assistance in the construction of a URL,
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.
dpwasjms://server/?RequestQueue=queue&ReplyQueue=queue&
Selector=expression&RequestTopicSpace=topic-space&
ResponseTopicSpace=topic-space&TimeOut=timeout&RequestReply=queue&Transactional=true
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 296 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
395 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.
67
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 289.
WSDL Retrieval
WSDL queries are restricted to GET and HEAD requests:
v A GET request retrieves the entire WSDL.
v A HEAD request informs that the WSDL service is live.
Before issuing these types of WSDL queries, enable the HTTP GET and HEAD
methods on the Front Side Handler.
To expose a WSDL from within a Web Service Proxy with the ?wsdl URI, use the
following format for the URL:
http://host:port]/URI?wsdl
68
Chapter 4. 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.
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. This handler requires the
TIBCO-EMS license.
WebSphere JMS Front Side Handler
Creates a 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.
69

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
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.
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:
70
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.
../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
71
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.
Configuring an FTP server handler

An FTP Server Front Side Handler object handles FTP protocol communications
with DataPower services.
An instance of this object can have one of the following configurations:
Transparent
The FTP server has a transparent file system. The files and directories
shown are those on the FTP server.
Virtual ephemeral
The FTP server will have an ephemeral virtual file system with
subdirectories created by configuration. The contents of this file system are
private to an individual FTP control connection to the FTP server.
The contents of this file system will not persist after this FTP control
connection ends.
Virtual persistent
The FTP server will have a persistent virtual file system with
subdirectories created by configuration. The contents of this file system are
shared by all FTP control connections to this FTP server with the same
72
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:
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.
73
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
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
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
74
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
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
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. Use the Enable LIST command support toggle to specify whether the FTP
server distinguishes between the LIST command and the NLST command.
75
d.
e.
f.
g.
The default is off to respond to either command with an NLST command.

This option only applies to transparent file systems.
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.
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.
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.
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.
Defining as virtual ephemeral

virtual ephemeral file system, use the following procedure:
systems.
76
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
default is 256.
Control List list.
Proxy list.
77
Idle Timeout field.
c. Select the use of encryption for data connections (file transfers) from the
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
default is off.
an empty string.
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:
78
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.
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.
79
Defining as virtual persistent

virtual persistent file system, use the following procedure:
systems.
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
default is 256.
Control List list.
Proxy list.
80
Idle Timeout field.
81

c. Select the use of encryption for data connections (file transfers) from the
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
default is off.
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.
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
82
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
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
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.
the FTP client can find this directory in the Virtual Directory field.
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.
Configuring an HTTP handler

An HTTP Front Side Handler object handles HTTP protocol communications with
DataPower services.
83
To configure an instance of the HTTP Front Side Handler object, use the following
procedure:
1. Select Objects Protocol Handlers HTTP Front Side Handler.
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.
systems.
7.
8.
9.
10.
b. Specify the listening port in the Port Number field. The default is 443.
Select the HTTP version to use on the client connection from the HTTP
Version to Client list. The default is HTTP 1.1
Use the Allowed Methods and Versions check boxes to select the allowed
methods and versions for incoming HTTP requests.
Use the Persistent Connections toggle to enable or disable the negotiation of
persistent connections.
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
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
f. Specify the maximum length of the query string in Maximum Allowed
Length of HTTP Query String field. The default is 0, which means
unlimited.
12. Select the instance of the Access Control List object to apply from the Access
Control List list.
84
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.
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.
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
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
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
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.
85
12. Select the instance of the SSL Proxy Profile object to assign from the SSL
Proxy list.
13. Select the instance of the Access Control List object to apply from the Access
Control List list.
Configuring an IMS Connect handler

An IMS Connect Handler object handles IMS protocol communications with
DataPower services.
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.
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.
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.
on
Indicates the input headers are in EBCDIC encoding.
off
(Default) Indicates that input headers are in ASCII encoding.
11. Select an Access Control List from the Access Control List list.
12. 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.
86
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.
Configuring a WebSphere MQ handler

An MQ Front Side Handler object handles MQ protocol communications with
DataPower services.
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 88 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 89 for details.
5. Define the properties and headers configuration. Refer to Defining the
properties and headers configuration on page 89 for details.
6. Define the advanced configuration. Refer to Defining the advanced
configuration on page 90 for details.
87
Defining the basic configuration

To define the basic configuration for an MQ Front Side Handler:
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.
88
on
Retrieves backout settings from the MQ server and compares to the

backout values set in the MQ Queue Manager object. On retry, the
DataPower appliance uses the higher priority backout settings from
the MQ server. If MQ server does not contain backout settings, the
appliance uses existing backout properties, either empty or populated,
that are stored in the MQ Queue Manager object. If there are no
backout properties, backout is disabled.
off
(Default) Do not retrieve backout settings from the MQ server. If these

properties already exist in the MQ Queue Manager object, the
appliance use those values.
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.
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.
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)
89
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.
To configure an NFS Poller Front Side Handler, use the following procedure:
1. Select Objects Protocol Handlers NFS Poller Front Side Handler to
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.
90
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
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.
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.
off
91
../processed/$1.
11. Define the process for deleting files on processing error.
a. Use the Delete File on Processing Error toggle to select whether to delete
the input or processing rename file when it could not be processed.
on
Deletes the file.
(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.
off
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.
../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
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.
92
14.
15.
16.
17.
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.
Select the XML Manager that contains the User Agent configuration to use
from the XML Manager list.
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.
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.
on all addresses.
systems.
7. Specify the port monitored by the handler in the Port Number field. The
default is 3000.
8. Specify the host name or IP address of the backend Stateful Raw XML server
in the Remote Host field.
9. Specify the remote TCP port of the Stateful Raw XML server in the Remote
Port field. The default is 12000.
10. Use the Terminate Session On Fault toggle to select the behavior of closing
TCP connections on a fault. If enabled (on), both the front and back TCP
connections are closed when the DataPower appliance generates a fault. If
disabled (off), the default, only a connection termination, timeout, or error
close the session.
11. Select an SSL Proxy Profile to assign from the SSL Proxy Profile list.
12. Select an Access Control List to apply from the Access Control List list.
93
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.
on all addresses.
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.
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:
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.
94
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 316.
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.
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.
95
v If blank, all incoming client request messages are transferred by the handler
to the server object for processing.
v If specified, only those client requests that match the criteria specified by
the expression are forwarded to the server object for processing. All other
messages are dropped from the GET queue.
The conditional expression does not operate on the body of the message,
rather it examines the required headers and properties (proprietary
user-created headers that could appear between the required headers and the
message body).
The following headers are required:
Destination
Contains the destination (queue) to which the message is being sent
DeliveryMode
Contains the delivery mode (PERSISTENT or NON_PERSISTENT)
Expiration
Contains a message TTL or a value of 0 indicating an unlimited TTL
Priority
Contains the message priority expressed as a digit from 0 (lowest
priority) to 9 (highest priority)
MessageID
Contains a unique message identifier starting with the ID: prefix or a
null value. A null value effectively disables the message ID
Timestamp
Contains the time the message was handed off for transmission, not
the time it was actually sent
CorrelationID
Contains a means of associating one message (for example, a
response) with another message (for example, the original request)
ReplyTo
Contains the destination (queue) to which a reply to this message
should be sent
Type
9.
10.
11.
12.
13.
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.
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.
96

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.
6. Specify the name of the GET queue in the Get Queue field. This queue
contains client-originated WebSphere JMS request messages.
The WebSphere JMS handler monitors the GET queue for incoming client
requests. On receipt, the handler forwards the extracted message to the a local
WebSphere JMS object that will gateway the message to a remote WebSphere
JMS default message provider.
7. Optionally specify the name of the PUT queue in the Put Queue field. This
queue contains server-originated WebSphere JMS reply messages.
These messages are originated by a remote WebSphere JMS default message
provider and put into this queue by a local WebSphere JMS object
If blank, no response is expected or wanted.
8. Select the WebSphere JMS object to associate from the WebSphere JMS Server
list.
9. Optionally specify a nondefault topic space in the WebSphere JMS Topic
Space for Request field. Use this property to disambiguate a topic if the
request destination is a topic whose name appears in multiple topic spaces.
10. Optionally specify a nondefault topic space in the WebSphere JMS Topic
Space for Reply field. Use this property to disambiguate a topic if the
response destination is a topic whose name appears in multiple topic spaces.
11. Optionally specify a an SQL-like expression to select messages from the GET
queue in the Selector field.
The message selector is a conditional expression based on a subset of SQL 92
conditional expression syntax. The conditional expression enables the handler
to identify messages of interest.
97
v If blank, all incoming client request messages are transferred by the handler
to the server object for processing.
v If specified, only those client requests that match the criteria specified by
the expression are forwarded to the server object for processing. All other
messages are dropped from the GET queue.
The conditional expression does not operate on the body of the message,
rather it examines the required headers and properties (proprietary
user-created headers that could appear between the required headers and the
message body).
The following headers are required:
Destination
Contains the destination (queue) to which the message is being sent
DeliveryMode
Contains the delivery mode (PERSISTENT or NON_PERSISTENT)
Expiration
Contains a message TTL or a value of 0 indicating an unlimited TTL
Priority
Contains the message priority expressed as a digit from 0 (lowest
priority) to 9 (highest priority)
MessageID
Contains a unique message identifier starting with the ID: prefix or a
null value. A null value effectively disables the message ID
Timestamp
Contains the time the message was handed off for transmission, not
the time it was actually sent
CorrelationID
Contains a means of associating one message (for example, a response)
with another message (for example, the original request)
ReplyTo
Contains the destination (queue) to which a reply to this message
should be sent
Type
Contains a message identifier provided by the application
Redelivered
Contains a Boolean indicating that the message has been delivered in
the past, but not yet acknowledged
98
Chapter 5. 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.
99
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 106.
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 106 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 106 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 108 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 109 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
100
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 110 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 111 for details.
Decrypt
A decrypt action performs full or field-level document decryption. Refer to
Adding a decrypt action on page 119 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 121 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 135 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 135 for details.
Filter
A filter action accepts or rejects check on incoming documents. Refer to

Filter actions on page 136 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
101
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 139 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 142 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 146 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
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 149 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 150 for
details.
Rewrite HTTP method
A rewrite-method action rewrites the HTTP method. Refer to Adding a
method rewrite action on page 150 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 151 and Adding a route with XPath
expression (route-action) action on page 151, respectively, for details.
102
Route with variables

A route-set action performs dynamic, variable-based routing. Refer to
Route with variables (route-set) action on page 152 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)
Sign
A sign action attaches a digital signature to the document. Refer to

Adding a sign action on page 153 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 155 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 155 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
156 for details.
Transform
An xform action transforms an XML document using a specified XSLT style
sheet. Refer to Transform-type actions on page 156 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 157 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 158 for details.
Validate
A validate action performs schema-based validation against XML
documents using a user-specified method. Refer to Adding a validate
103
Verify A verify action validates the digital signature on an incoming document.

Refer to Adding a verify action on page 164 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
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
104
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.
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 5 illustrates a rule that employs multiple actions. The
transform occurs before the validation. Changing the sequence of actions could
have significant impact on the results of this rule.
Figure 5. Rule Action ordering
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.
105
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 304 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
105 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 172 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).
106
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.
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.
107
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.
configuration path.
Adding a call processing rule (call) action

To add a call action, use the following procedure:
action types.
3. Click the Call Processing Rule radio button.
4. Click Next to display the Configure Call Processing Rule action window.
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 165.
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
168 for details.
9. Click Done to complete the action. The configuration path shows the Call
Processing icon.
configuration path.
After you click Apply or Apply Policy, the Call Processing icon expands to the
icons for the actions in the reusable rule.
108
Adding a checkpoint event (checkpoint) action

To add a checkpoint action, use the following procedure:
action types.
3. Click the Checkpoint Event radio button.
4. Click Next to display the Checkpoint Event action window.
6. From the Checkpoint Event list, select the type of event that triggers the
checkpoint.
Checkpoint Event icon.
configuration path.
Adding a conditional action

To add a conditional action, use the following procedure:
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.
109
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.
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.
configuration path.
Adding a convert query parameters to XML (convert-http)

action
To add a convert-http action, use the following procedure:
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.
6. From the Input Conversion list, select the map that contains the conversion
rules.
110

9. Click Done to complete the action. The configuration path shows the Convert
Query Param to XML icon.
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:
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
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.
111
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.
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.
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.
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.
112
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.
113
configuration path.
Verifying PKCS #7 signed documents

To define a cryptobin action that verifies PKCS #7 signatures, use the following
procedure:
action types.
3. Click the Crypto Binary radio button.
4. Click Next to display the Crypto Binary action window.
6. Check the PKCS#7 Verify radio button. The display refreshes with
operational-specific parameters.
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.
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
Binary icon.
configuration path.
Advanced settings: Use the Advanced screen to identify the style sheet and
define less commonly used settings.
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.
form.
114
of the window).
parameter.
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
115

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.
Binary icon.
configuration path.
Encrypting PKCS #7 documents

To define a cryptobin action that encrypts PKCS #7 documents, use the following
procedure:
action types.
4. Click Next to display the Crypto Binary Action (Basic) window.
6. Click the PKCS#7 Encrypt radio button to select document encryption, and
display operational-specific parameters.
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.
116
configuration path.
2.
3.
4.
5.
6.
Confirm the Input setting.

Confirm that the PKCS#7 Encrypt radio button is selected.
Use the Processing Control File field or specify the style sheet used by this
cryptobin encrypt action to perform document encryption.
form.

of the window).
parameter.
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.
Binary icon.
117
configuration path.
Decrypting PKCS #7 documents

To define a cryptobin action that decrypts PKCS #7 documents, use the following
procedure:
action types.
4. Click Next to display the Crypto Binary action window.
6. Click the PKCS#7 Decrypt radio button to select document encryption and
display operational-specific parameters.
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.
Binary icon.
configuration path.
2. Confirm the Input setting.
3.
4.
5.
6.

Confirm that the PKCS#7 Decrypt radio button is selected.
Use the Processing Control File field or specify the style sheet used by this
cryptobin decrypt action to perform document decryption.
form.
118
of the window).
parameter.
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.
Binary icon.
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.
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 285 for
more information.
119
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.
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
9. If the action is complete, click Done.
configuration path.
Advanced settings
Use the Advanced screen to identify the style sheet and define less commonly used
settings.
2. Use the Processing Control File field or select the style sheet used by this
decrypt action.
form.
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.
120

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.
4. Select WSSec Encryption from the Envelope Method list.
5. Select SOAP Message from the Message Type list.
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.
121
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.
122
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
123
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.
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
4) Specify the label of the derived key in the Label of the
Derived Key field.
124
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.
Derived Key field.
Key Identifier
(Default) A reference is made using a KeyIdentifier element with a
SubjectKeyIdentifier ValueType and content.
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.
125
4) Select whether a Key Derivation is needed and where to find the

key from the WS-SecureConversation DKT Derivation Base list.
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
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
c) If you removed the offset setting, specify which
sequence.
d) Specify the label of the derived key in the Label of the
Derived Key field.
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
126
b) If you removed the offset setting, specify which

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.
the DKT
v 1.1
v 1.2 (Default)
v 1.3
Derived Key field.
127

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.
the DKT
v 1.1
v 1.2 (Default)
v 1.3
128

Derived Key field.
Derived Key field.
X509IssuerSerial
A reference is made using an X509IssuerSerial element that
identifies a certificate by its X.509 issuer and serial number.
129
the DKT
v 1.1
v 1.2 (Default)
v 1.3
Derived Key field.
Derived Key field.
12. If you configured advanced properties, click the Basic tab.
configuration path.
Encrypting a SOAP message with XML encryption

To add an encrypt action to encrypt a SOAP message, use the following procedure:
4. Select Standard XML Encryption from the Envelope Method list.
5. Select SOAP Message from the Message Type list.
130

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.
list.
v Binary
v Default
v XML
h. Select the algorithm to use for encryption from the Encryption algorithm
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.
configuration path.
131
Encrypting a raw XML message with XML encryption

To add an encrypt action to encrypt a raw XML message, use the following
procedure:
4. Select Standard XML Encryption from the Envelope Method list.
5. Select Raw XML Document from the Message Type list.
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.
list.
v Binary
b.
c.
d.
e.
v Default
v XML
h. Select the algorithm to use for encryption from the Encryption algorithm
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.
132
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.
configuration path.
Encrypting select elements of a message

To add an encrypt action to encrypt select elements, use the following procedure:
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 285 for more information.
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.
list.
v Binary
v Default
v XML
133

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:
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.
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.
configuration path.
134
Adding an extract using XPath (extract) action

To add an extract action, use the following procedure:
action types.
3. Click the Extract Using XPath radio button.
4. Click Next to display the Extract using XPath action window.
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
10. Click Done to complete the action. The configuration path shows the Extract
using XPath icon.
configuration path.
Adding a fetch action

To add a fetch action, use the following procedure:
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 165 for details.
8. For HTTP protocols: From the Method list, select the HTTP method type.
10. Click Done to complete the action. The configuration path shows the Fetch
icon.
configuration path.
135
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.
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.
form.
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.
Specify or select the context for the data produced in the Output field.
Click Done to complete the action.
configuration path.
136
Adding a replay filter

To add a replay filter, use the following procedure:
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.
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.
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.
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.
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.
137
configuration path.
Adding a message layout filter

To add a message layout filter, use the following procedure:
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.
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.
configuration path.
Adding a conformance filter

To add a conformance filter, use the following procedure:
1.
2.
3.
4.
5.
6.
7.
8.
138
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 store:///conformance-filter.xsl style sheet with the
Processing Control File fields.
Select the conformance policy from the Conformance Policy list. Refer to
Conformance Policy on page 281 for details.
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 166 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:
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.
139
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:ProdID>78-697-24</joe:ProdID>
</joe:Item>
<joe:Item>
<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.
140
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 165 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">
</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.
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.
141
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:
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 165 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.
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.
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.
142
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:
action types.
3. Click the MQ Header radio button.
4. Click Next to display the MQ Header action window.
processing inserts the correct context identifier.
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.
configuration path.
143
Retrieving responses by message ID or by correlation ID

To retrieve response messages from the backend reply queue, use the following
procedure:
action types.
the service inserts the correct context identifier.
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
configuration path.
Modifying MQMD response headers

To modify MQMD header values for response messages placed to the backend
reply queue, use the following procedure:
action types.
the service inserts the correct context identifier.
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
144
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.
(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
configuration path.
Modifying the reply queue for responses

To change the destination reply queue for response messages, use the following
procedure:
action types.
5. Optionally select the Input context. If the default, the service inserts the
correct context identifier.
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.
the service to determine the output context.
configuration path.
145
Modifying the queue manager for responses

To change the destination MQ Queue Manager for response messages, use the
action types.
5. Optionally select the Input context. If the default, processing inserts the
correct context identifier.
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.
configuration path.
Adding an on-error action

To add an on-error action, use the following procedure:
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 152 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.
146
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 165.
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
168 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.
Click Done to complete the action. The configuration path shows the On
Error icon.
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 148 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 149 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
147
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 165 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 135 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
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.
148
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">
</tns:Item>
<tns:Item from="b">
</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.
configuration path.
Adding a results asynchronous (results-async) action

To add a results-async action, use the following procedure:
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 165 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
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.
149
Require All
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.
configuration path.
Adding a rewrite header (rewrite) action

To add a rewrite action, use the following procedure:
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 335 for more information.
7. Click Done to complete the action. The configuration path shows the Header
Rewrite icon.
configuration path.
Adding a method rewrite action

To add a method rewrite action, use the following procedure:
action types.
3. Click the Method Rewrite radio button.
4. Click Next to display the Method Rewrite action window.
6. Click Done to complete the action. The configuration path shows the Method
Rewrite icon.
configuration path.
150
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 152 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.
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.
form.
Note: The style sheet must use the dp:set-target() extension function to set the
routing destination.
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.
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:
151
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.
7. Optionally specify or select the context for the data produced in the Output
field.
configuration path.
Route with variables (route-set) action

To add a route with variables (route-set) action, use the following procedure:
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 165 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.
configuration path.
Adding a set variable (setvar) action

To add a setvar action, use the following procedure:
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 168 for details.
7. Specify the value for the variable in the Variable Assignment field.
152

9. Click Done to complete the action. The configuration path shows the Set
Variable icon.
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.
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.
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.
153
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 285 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.
154
configuration path.
Adding an SLM action

To add an slm action, use the following procedure:
action types.
3. Click the SLM radio button.
4. Click Next to display the Enforce SLM policy action window.
6. From the SLM Policy list, select the policy to monitor transactions. Refer to
Service level monitors on page 309 for details.
9. Click Done to complete the action. The configuration path shows the SLM
icon.
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:
action types.
Click the SQL radio button.
Click Next to display the SQL Action window.
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 315 for SQL Data Source
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
155
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.
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.
configuration path.
Adding a Strip Attachments action

To add a strip-attachments action, use the following procedure:
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.
7. Click Done to complete the action. The configuration path shows the Strip
Attachments icon.
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.
156
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.
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.
form.
6.
7.
8.
9.

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 335 for more information.
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:
157

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.
form.
6.
7.
8.
9.

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 335 for more information.
10. Click Done to complete the action. The configuration path shows The
Transform Binary icon.
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.
In the Processing Control File field, specify or select the style sheet to use.
form.

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 335 for more information.
Transform Using Processing Instruction icon.
158
configuration path.
Adding a SOAP refinement transform

To add a SOAP refinement transform action, use the following procedure:
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.
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.
159
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
160
Delete SOAP headers without checking for ID references.
11. Select the disposition table from the SOAP Header Disposition Table list.
This table contains a list of instructions that controls how to handle SOAP
headers, child elements, or both SOAP headers and child elements. Refer to
SOAP Header Disposition Table on page 314 for information.
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:
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 335 for more information.
configuration path.
Adding a conformance transform

To add a conformance transform action, use the following procedure:
161
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.
8. Select the conformance policy from the Conformance Policy list. Refer to
Conformance Policy on page 281 for details.
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.
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.
162
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 335 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.
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 308 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.
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.
163
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.
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
164
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
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
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 1 lists the actions that can specify the location of a resource on a remote
server, the name of the field as shown through the WebGUI, whether this
specification is required or optional, and the number of remote server from which
the resource can be retrieved or to which the data can be sent.
Table 1. Actions and remote resources
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)
165
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
167 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>
</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 168.
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">
166
</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 168.
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
167
# 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 6 is visible.
Figure 6. Variable builder for custom context variables
For the setvar action, you can create a custom context variable or select an existing
service, extension, or system variable. The created or selected variable must be a
write-only or read-write variable. After clicking Var Builder the area shown in
168
Figure 7 is visible.
Figure 7. Variable builder for custom context, service, extension, and system variables
After defining a custom context variable, click Use Custom. The variable builder
closes, and the field contains the defined variable.
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.
169
170

An Authentication, Authorization, Audit (AAA) policy, sometimes referred to as an
Access Control Policy, identifies a set of resources and procedures that can be used
to determine whether a requesting client is granted access to a specific service, file,
or document. AAA policies can be considered a type of filter in that they accept or
deny a specific client request.
AAA policies are powerful and flexible. They can support a range of authentication
and authorization mechanisms to include SAML, Netegrity, and RADIUS. Multiple
authentication and authorization mechanisms can be mixed and matched in a
single policy. For example, one AAA policy can use a single RADIUS server to
provide authentication and authorization services, while a second policy can use a
RADIUS server for authentication, use a local XML file to map the RADIUS
authentication credentials to an LDAP group name, and finally use an LDAP
server to authorize the LDAP group.
Figure 8 shows the basic processing for an AAA Policy. Initial processing (common
to all policies) consists of extracting the claimed identity of the service requester
and the requested resource from an incoming message and its protocol envelope.
As you define an AAA Policy, extraction methods are specified by a series of check
boxes that enable one or more identity and resource extraction methods. A wide
range of identity and resource extraction methods are supported. For example,
identity can be based on IP address, form (account name and password), SAML
assertion, or other criteria; while the requested resource can be specified by (among
others) an HTTP URL, a namespace, or a WSDL method.
Extract Identity
Extract Resource
Authenticate
Allow | Deny
Map Credentials
Map Resource
Authorize
Allow | Deny
Post Processing
Output
Message
Generate
Error
Figure 8. AAA Policy Processing
After extracting the service requester identity and resource, the policy authenticates
the claimed identity. Authentication is most commonly accomplished via an
external service (for example, a RADIUS or LDAP server), but other custom
processing methods, such as site-specific XML- or XPath-based solutions, are
readily supported. During policy definition, you select a single authentication
method from a menu of supported methods, and (depending upon the selected
method) provide a few items of additional required information, such as a server
address or the URL of a custom processing resource.
171
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
172
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>
173
<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
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>
174
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.
175
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>
176
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.
<message xmlns="http://www.example.com"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.example.com message.xml">
<to>Alice</to>
<from>Bob</from>
<subject>Important</subject>
<body>
Traveling to San Francisco, Honolulu, and Ashtabula.
See you in the sky.
</body>
<method>Fax</method>
<Signature xmlns="http://www.w3.org/2000/09/xmldsig#"
xmlns:wsse="http://schemas.xmlsoap.org/ws/2002/07/secext"
xmlns:SOAP="http://schemas.xmlsoap.org/soap/envelope/">
<SignedInfo>
...
</SignedInfo>
<SignatureValue>MBwxXIuY2...</SignatureValue>
<KeyInfo>
<X509Data>
<X509Certificate>MIICMjCCTfMCFB9mFK6vs= </X509Certificate>
<X509IssuerSerial>
<X509IssuerName>CN=jrb@somedomain.com</X509IssuerName>
<X509SerialNumber>0</X509SerialNumber>
</X509IssuerSerial>
</X509Data>
</KeyInfo>
</Signature>
</message>
If selected, the WebGUI displays the following properties:

Validation Credentials for Signing Certificate
Select a Validation Credentials to validate the presented
certificate. Refer to Validation credentials on page 22 for more
information.
Retrieve Remote Token
Select whether to retrieve the remote token. Refer to Security
token references on page 400 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:
177
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.
<to>Alice</to>
<from>Bob</from>
<body>
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 266 for information on
providing namespace binding properties.
Token Extracted as Cookie Value
The claimed identity of the requester is extracted from a Cookie value.
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.
178
Processing Metadata
Extract the identity from the processing metadata, such as protocol
headers, system variables, and other custom metadata sources. If
Processing Metadata Item
Select a Processing Metadata object to identify extracted items.
Refer to Processing Metadata on page 305 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).
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
22.
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:
179
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
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 296 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
180
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 286 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:
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 22 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
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
181
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
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
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
182
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 by a ClearTrust server. If selected, the
ClearTrust Server URL
Specify the URL used to access the ClearTrust server.
SSL Proxy Profile
connection.
Contact Netegrity SiteMinder
The requester is authenticated by a Netegrity server. If selected, the
Host
Specify the IP address or host name of the Netegrity server.
Port Specify the port number of the Netegrity server.
SSL Proxy Profile
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
183
connecting to the NSS server for SAF authentication. Refer to z/OS

NSS Client on page 396 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 273 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
SAML Artifact Responder URL
Specify the issuer of the artifact.
SSL Proxy Profile
connection.
SAML Version
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
184
certificate extracted from the WS-Security BinarySecurityToken

element. Refer to Validation credentials on page 22 for more
information.
Refer to the description in Defining identity extraction methods on page
173.
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
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
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 267 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.
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 278 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
185
XPath Expression
Specify an XPath expression to be applied to the incoming document
to extract the signed portion of the document.
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 266 for more
information.
Retrieve Remote Token
Select whether to retrieve the remote token. Refer to Security token
references on page 400 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
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 22 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.
186
Custom
Identifies a custom, credentials mapping resource; for example, a style
sheet. If selected, the WebGUI displays the following property:
Specify a URL
resource.
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
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
resource.
the file.
XPath Identifies an XPath expression as the mapping resource. If selected, the
XPath Expression
Specify an XPath expression to be applied to the value extracted
during the identity extraction phase.
Binding to provide namespace or prefix data. Refer to Setting
information.
187
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
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:
<S11:Envelope
xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/"
188
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:
<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
during the Resource Extraction step.
information.
For example, you could specify /*[local-name()="message"]/*[localname()="transitmethod"] for the following message:
<?xml version="1.0"?>
<to>Alice</to>
<from>Bob</from>
<body>
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:
189
Processing Metadata Item

Select a Processing Metadata object to identify extracted items. Refer
to Processing Metadata on page 305 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
Specify a URL
resource.
the file.
None
(Default) Resource mapping is not performed.
tivoli
Identifies a Tivoli style mapping resource. If selected, the WebGUI displays

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
Specify the name of the queue manager and the queue
separated by a forward slash (/). When implemented, the
/PDMQ/queue_manager/queue/mapped_resource_name
TFIM prefix
Indicates that the output of the mapped resource uses the prefix
190
style from Tivoli Federated Identity Manager (TFIM). If

Specify the name of the TFIM domain. When selected, the
/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
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
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 267 for more
information.
XPath
Identifies an XPath expression as the mapping resource. If selected,
the WebGUI displays the following property:
XPath expression
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 266 for
more information.
191
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.
(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 273 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 2.
Table 2. Example of TAM action map entries
Pattern
Action
*one*
x (execute)
*two*
r (read)
When an authorization request, whose resources are /resource/one

and /resource/two, the first authorizes the use of the execute action
and the second entry authorizes the use of the read action.
192
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 273 for more
information.
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
connecting to the NSS server for SAF authorization. Refer to z/OS
NSS Client on page 396 for more information.
Contact ClearTrust Server
The requester is authorized by a ClearTrust server. If selected, the WebGUI
Specify the URL used to access the ClearTrust Server
SSL Proxy Profile
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
resource.
the file.
Check for membership in an LDAP group
The requester is authorized by an LDAP server. If selected, the WebGUI
Host
Specify the IP address or host name of the LDAP server.
193
Port Specify the port number of the LDAP server.

SSL Proxy Profile
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.
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
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.
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.
194
Generate a SAML authorization query

The requester is authorized by a SAML authorization query. If selected, the
SAML Server URL
Specify the URL of the target SAML server.
SSL Proxy Profile
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 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 22.
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 17.
SAML message signing certificate
Select a Crypto Certificate to use for this transaction. For information
on creating a Crypto Certificate, refer to Defining Certificate objects
on page 13.
SAML message signing algorithm
If the SAML message that is generated for this policy will be digitally
signed, select the SignatureMethod for the signing algorithm. The
default is rsa.
SAML signing message digest algorithm
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
SAML Server URL
Specify the URL of the target SAML server.
195
SSL Proxy Profile

connection.
SAML Version
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).
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 266.
Must match all names
All Attribute names in the response from the SAML server must
match those configured on the SAML Attributes panel. To
page 266.
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 266.
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 266.
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 22 for
more information.
196
SAML message signing key

Select a Crypto Key to use for this transaction. Refer to Defining
Key objects on page 17 for more information.
SAML message signing certificate
Select a Crypto Certificate to use for this transaction. Refer to
Defining Certificate objects on page 13 for more information.
SAML message signing algorithm
signed, select the SignatureMethod for the signing algorithm. The
default is rsa.
SAML signing message digest algorithm
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
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).
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
page 266.
Must match all names
All Attribute names in the response from the SAML server must
match those configured on the SAML Attributes panel. To
page 266.
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 266.
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
197
SAML Attributes panel. To define SAML attributes, refer to

Defining SAML attributes on page 266.
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 279 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

XACML PDP
Select the PDP to provide authorization services for the
AAA Policy. Refer to Defining a XACML PDP on page
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.
198
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.
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
URL
resource.
the file.
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.
199
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
explicit value.
Minimum
Compares the explicit TTL with the received TTL, if any. If it is greater
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 234 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.
200
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.
201
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.
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.
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
202
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.
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.
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.
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.
203
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 274.
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.
204
Chapter 7. 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.
205
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
206

appliance itself. This subdirectory is available from the command
line only.
pubcerts
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:
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.
207
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:
utility on page 207 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:
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 207.
208
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:
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
209
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
207.
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:
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.
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 207.
Copying files
Use the following procedure to copy a file from one directory to another:
210
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.
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 207.
Renaming files
Use the following procedure to rename a file:
2. Navigate to the directory that contains the files to be copied.
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.
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 207.
Moving files
Use the following procedure to move a file from one directory to another:
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.
211
7. Click Confirm Move.

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 207.
Viewing files
Use the following procedure to view a text file:
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:
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:
2. Navigate to the directory that contains the files to be deleted.
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.
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 207.
212
Chapter 8. Managing the configuration of the appliance

This chapter provide information about managing the configuration of application
domains and importing and exporting configurations.
Creating Include Configuration File objects

Include Configuration File objects allow you to include configuration information
from an external configuration file in the local configuration information. This
external file can be stored on a centralized configuration server or another
DataPower appliance. The information in the Include Configuration File object is
appended to the local configuration information when the configuration of the
DataPower appliance is reloaded (such as during appliance reboot, firmware
reload, or domain restart).
An Include Configuration File object can include configuration information only.
On the other hand, an Import Configuration File object is a configuration package
that can include both configuration information and supporting files.
To append configuration information from an external file to the local
configuration information, perform the following procedure:
1. Select Objects Configuration Management Include Configuration File to
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.
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.
213

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
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.
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.
214
on
(Default) Overwrites objects of the same name.
off
Does not import the objects if an objects of the same name exists.
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 226.
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.
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
215
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:
2. Select Create a backup of one or more application domains and click Next to
display the selection screen.
216
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
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:
2. Select Export configuration and files from the current domain and click Next
to display the Export Configuration screen.
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.
217
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
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.
workstation.
218
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:
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,
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.
219
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
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
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.
220
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.
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.
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 222.
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 224.
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.
221
Rolling back to a configuration checkpoint

To load the configuration that is defined in the configuration checkpoint, use the
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.
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.
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.
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).
222
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 226.
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 224.
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.
223
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.
224
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.
225
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 227.
v For details about manually specifying the statement, refer to Specifying the
matching statement on page 228.
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.
226

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.
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.
227
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
228
Chapter 9. Managing monitors

This chapter describes how to create and manage message Web services monitors.
You can create and manage the following types of traffic or error monitors
(message monitors) using the Object Monitoring menu.
Message Count Monitor
Creates a count-based monitor
Message Duration Monitor
Creates a time-based monitor
Message Filter Action
Defines an administrative response to the overuse of resources
Message Matching
Creates a traffic definition
Message Type
Creates a monitored message type
You can create and manage Web services monitors by enabling statistics using the
Administration Device Statistic Settings menu and the configuring the
monitors using the Object Monitoring Web Services Monitor menu.
Monitor types
Monitors enable the definition of a message set, the specification of a count-based
or time-based threshold, and the design of administrative controls imposed when
the message set exceeds configured threshold values.
Monitors are of the following types:
v Message count monitors 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 234.
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 236.
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
238.
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
229
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 231.
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 233.
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 233.
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 234.
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.
230
For procedural details, refer to Configuring duration monitors on page 236.

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.
Admin State
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.
231
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.
*

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.

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

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.

6. Click Save.
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.
Admin State
Comments
Message Matchings
Add one or more traffic definitions to the message type.
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
233
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.
Admin State
Comments
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.
Configuring count monitors

To configure a message count monitor, use the following procedure:
1. Click Object Monitoring Message Count Monitor.
2. Click Add.
Admin State
234
Comments
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.
Name Specify the name of this threshold.
235
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
7. Click Save.
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.
236

Admin State
Comments
Message Type
Select the message type monitored by this message duration monitor.
Refer to Message Type on page 233 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.
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.
237
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 233
7. Click Save.
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.
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.
238
Admin State
Comments
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.
239

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
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
240
a.
b.
c.
d.
e.
Click Add.
Select Second Limit in Threshold Level.
Provide the Threshold Value.
Select the Threshold Action.
Click Save.

241
242
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.
Main tab
Admin State
Comments
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
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 234 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 22 for more information.
243
SAML Message Signing Key

authentication: Select the Crypto Key to sign SAML assertions. Refer to
Defining Key objects on page 17 for more information.
SAML Message Signing Certificate
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 13 for
more information.
SAML Signing Message Digest Algorithm
Select the hash algorithm for SAML signing message. The default is sha1.
SAML Message Signing Algorithm
Select the algorithm to sign SAML messages. RSA and DSA are supported
by older releases. rsa is same as rsa-sha1, and dsa is same as dsa-sha1. The
default is rsa.
LDAP Suffix
Optional if LDAP authentication or authorization is used by this AAA
policy. Specify an LDAP base DN.
LDAP-based authentication implementations require an X.500 DN (for
example, cn=Alice,dc=datapower,dc=com) and a password. When
configuring LDAP for authentication, it is typical to create a base DN (such
as dc=datapower,dc=com) and then create one entry under this base for each
user.
To make LDAP authentication more usable, the AAA policy provides the
LDAP suffix. Set the LDAP suffix to the base name under which user
entries are found. If the LDAP suffix is not an empty string, the AAA
Policy builds an X.509-compliant DN by prepending cn= to the surname
and appending a comma followed by the value of the LDAP suffix. Hence,
an LDAP suffix of dc=datapower,dc=com, the user name Alice is mapped to
the DN cn=Alice,dc=datapower,dc=com.
Log Allowed
By default, the AAA policy generates log messages at the indicated level
for every access allowed. Set to off to change this behavior.
Log Allowed Level
When Log Allowed set to on, change the default level. Log messages
generated for each access allowed by this AAA policy will be set at the
level selected.
Log Rejected
By default, the AAA policy generates log messages at the indicated level
for every access rejected. Set to off to change this behavior.
Log Rejected Level
When Log Rejected set to on, change the level. Log messages generated
for each access rejected by this AAA policy will be set at the level selected.
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.
244
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
245
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
UserName element (name and password) contained in a SOAP header.
BinarySecurityToken element from WS-Security header
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
246
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
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 266 for procedural and
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.
247
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.
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:
248
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.
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.
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 296 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.
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
249
LDAP Search Parameters

Select the LDAP Search Parameters from the list. Refer to
Defining LDAP Search Parameters objects on page 286
for detail.
v If off, the WebGUI removes the following fields:
LDAP Prefix
LDAP Suffix
Contact a SAML Server for a SAML Authentication Statement
The requester is authenticated by issuing a SAML Authentication Query
to the appropriate server. If selected, the WebGUI prompts for the
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
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
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.
250
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.
The requester is authenticated via a ClearTrust server. If selected, the
WebGUI prompts for the following properties:
Provide a local or remote URL that locates the authentication
resource.
SSL Proxy Profile
non-SSL connection.
The requester is authenticated by a Netegrity server. If selected, the
Host
Specify the IP address or domain name of the Netegrity

authentication server.
251
Port
Specify the Netegrity authentication server port number.
Netegrity Base URI

Specify the appropriate URI string.
SSL Proxy Profile
non-SSL connection.
Contact NSS for SAF Authentication
The requester is authenticated by the SAF. If selected, the WebGUI
connecting to the NSS server. Refer to z/OS NSS Client on page
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 273
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
non-SSL connection.
252
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
Use DataPower AAA Info File
The requester is authenticated by an XML file. If selected, the WebGUI
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
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 22 for
more information.
The following inputs are displayed for all methods.
253
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.
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
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:
254
TFIM Configuration
Select an existing TFIM object. Refer to Creating TFIM objects
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
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.
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
255
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
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
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
purposes.
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
256
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.
The requester is authorized via a ClearTrust server. If selected, the
Specify a local or remote URL that locates the authorization
resource.
SSL Proxy Profile
connection.
Custom Template
The requester is authorized by a custom/proprietary resource (for
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
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.
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.
257
LDAP Group Attribute

Specify a GroupAttribute string. The authorizing identity must be
presented as the value that corresponds to the attribute.
SSL Proxy Profile
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.
The requester is authorized by a Netegrity server. If selected, the WebGUI
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
connection.
Contact NSS for SAF Authorization
The requester is authorized by the SAF. If selected, the WebGUI prompts
for the following properties:
258

connecting to the NSS server. Refer to z/OS NSS Client on page
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.
259
SSL Proxy Profile

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
All

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
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
connection.
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 273 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
SAML Match
260
All

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

Policy Decision Point
Select the PDP to provide authorization services for the
AAA Policy. Refer to Defining a XACML PDP on page
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.
262
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
AAA Info File URL
Specify the location of the XML file used for authorization purposes.
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.
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
263
For more information about these activities, refer to Post processing activities on
page 201.
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.
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.
Prefix Specify the namespace prefix.
URI
Specify the namespace URI.
4. Click Save to return to the AAA Policy Configuration (Namespace Mapping).
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.
Namespace URI
Specify the attribute namespace URI.
Local Name
Specify the attribute name.
Attribute Value
Specify the appropriate value.
264
4. Click Save to return to the AAA Policy Configuration (SAML Attributes).

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 266 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.
265
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.
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
266
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.
tool allows you to load an XML document and build the expression by
selecting the desired node.
namespace data for XPath bindings on page 266 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"
</xsd:element>
<xsd:element name="MapResource" type="tns:MapResourceType"
</xsd:element>
<xsd:element name="Authorize" type="tns:AuthorizeType"
</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 268 for more information.
Note: The AAA Info file can be edited outside of the AAA Info file editor and
uploaded to the appliance.
267
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.
268
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
269
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.
270
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.
271
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
272
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.
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.
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.
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.
273
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.
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
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.
274
SAML 1.0
Indicates a SAML Assertion 1.0.
SAML 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
SAML 1.1
SAML 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.
275
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
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
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.

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
276
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.
Name
Admin State
277
Comments
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.
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.
Name
Admin State
Comments
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.
278
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.
In the Name field, enter the name for the object.

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
279
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.
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.
280
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.
281

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
in WS-I Basic Profile, version 1.1.
WS-I AP 1.0
in WS-I Attachments Profile, version 1.0.
WS-I BSP 1.0
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
BP1.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.
Failure
Warning
Always
282
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
Warning
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
off
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.
Failure
Warning
Always
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
Warning
failures.
283
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
off

Compile Options Policy objects

A Compile Options Policy object enables the appliance to measure and report
processing times for a set of style sheets as well as controls the compilation of
WSDL files. The appliance supports XSLT 1.0, XSLT 2.0 and XPath 2.0.
Note: XSLT 2.0 and XPath 2.0 support is currently limited to the decimal data
type. Specifically, numeric literals in the style sheet are interpreted as
decimals (instead of double-precision floating point numbers as in 1.0), and
the xs:decimal() constructor function is supported for converting other data
types to decimal.
You can enable streaming by setting a streaming rule. A streaming policy can and
should be used in production environments that require streaming to handle large
documents. Refer to Optimizing through Streaming for more information.
Refer to Compile Options Policy Configuration in the Command Reference for
detailed information about profiling a set of style sheets.
Test environments: For diagnostic purposes, you can enable a profiling policy, a
debug policy, or both policies in a test or development
environment. These policies provide diagnostics information
about the environment. Do not use these policies in a
production environment.
Configuring Compile Option Policy 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
1.
2.
3.
configure a Compile Options Policy object:

Select Objects XML Processing Compile Options Policy.
On the Main tab, define the basic policy.
4. On the WSDL Compiler Options tab, define WSDL properties. This tab is
available on all appliances except for DataPower XML Accelerator XA35
appliances.
After modifying the object, flush the stylesheet cache. For details, refer to
Flushing the stylesheet cache on page 396.
284
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.
Name Specify the name of the Document Crypto Map.
Admin State
Comments
Operation
Select the cryptographic action for this rule.
Decrypt
Specifies that this rule decrypts elements
Encrypt
Specifies that this rule encrypts elements
Encrypt (WS-Security)
Specifies that this rule uses the Web Services Security
Specification to encrypt elements
Sign (WS-Security)
Specifies that this rule uses the Web Services Security
Specification to sign elements
XPath Expression
Add XPath expressions to this rule. The XPath expression defines one
or more document elements subject to this rule. These are the
encrypted elements, not the unencrypted elements.
Click XPath Tool to use the graphically oriented XPath tool to construct
these expressions. You will need to upload an example of an encrypted
document to use this tool. Then you can simply click on the encrypted
elements to decrypt. The XPath expression is constructed automatically.
Note: The XPath expressions cannot exceed 330 characters. Use
Namespace Mapping entries to enable the ability to omit the
namespace URIs from the XPath expression.
Namespace Mappings tab

To add XML namespace information, use the following procedure:
1. Click the Namespace Mappings tab to display the Document Crypto Map
Configuration (Namespace Mappings) screen.
2. Click Add to display the Namespace Mappings Property window.
285
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.
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.
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 bob@example.com, the LDAP search
filter would be mail=bob@example.com.
9. Optionally specify the suffix of the LDAP filter expression in the LDAP Filter
Suffix field.
If the prefix is mail=, the suffix is )(c=US)), and the user name is
bob@example.com, the LDAP search filter would be
(&(mail=bob@example.com)(c=US)).
10. Select the depth of the search from the LDAP Scope list:
Base
Searches the entry level of the tree only.
One level
Searches the entry level of the tree and any object that is one-level
below the input.
286
Subtree
(Default) Search the entry level of the tree and all of its descendents.
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.
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.
on
Indicates a response message with a 4 byte LLLL header field.
287
(Default) Indicates a response message without the initial LLLL

header.
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.
off
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 64 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 64 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.
288
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.
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 9 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 9. 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.
289
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.
v On the deployment manager of a WebSphere Application Server cell, you need
to install the WebSphere On Demand Configuration (ODCInfo) application.
Figure 10 shows the required configuration.
DataPower
appliance
WebSphere
Cell
WebSphere Application Server

cell
Deployment
manager
ODCInfo
Load Balancer
Group
Figure 10. 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.
290
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.
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
First alive
Hash
Least connections
Round robin
Weighted least connections
v 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,
291
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.
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.
292
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.
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
293
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.
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
294
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
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.
295
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
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.
296
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.
Defining the base configuration

A base configuration create a load balancer group without members.
To define the base configuration:
Click Objects Network Load Balancer Group.
Click Add.
Retain the default setting for Admin State. To place in an inactive
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.
1.
2.
3.
4.
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.
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:
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.
297
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
g. Click Save.
5. Repeat the previous step to add another server as a static member.
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.
298
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:
2. Click the name of a load balancer group to modify.
3. Click the Health tab.
4. Set Enabled to on.
5. 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.
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.
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.
299
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.
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.
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.
300
5. Repeat the previous step to modify another member.

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
1.
2.
3.
disable specific members to not participate in load balancing decisions:

Click Objects Network Load Balancer Group.
Click the name of the load balancer group to modify.
Click the Members tab.
4. 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.
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
v
v
v
v
ODCInfo_ND60.war
ODCInfo_ND61.war
ODCInfoCheckInstall.jacl
ODCInfoDeploy.jacl
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.
301
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.
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.
302
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.
3. Navigate to the /bin directory under the deployment manager profile.
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.
3. Navigate to the bin directory of the deployment manager profile. For example:
303
4. Uninstall the application by entering:

./wsadmin.sh -f script_path/ODCInfoUninstall.jacl cellName
For example:
./wsadmin.sh -f /tmp/ODCInfoUninstall.jacl wasnode2Cell01 dmgr
ODCInfo
5. Verify by entering:
./wsadmin.sh -f script_path/ODCInfoCheckInstall.jacl cellName
The response indicates success or failure.
What to do next
Install the ODCInfo application.
Defining Matching Rule objects

To configure a Matching Rule, use the following procedure:
1. Select Objects XML Processing Matching Rule to display the catalog.
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.
off
b. Select the desired match type from the Matching Type list.
c. Define the matching criteria.
d. Click Save.
Repeat this step to define another matching rule.
304
Processing Metadata
A Processing Metadata object identifies items of metadata information from or
about a transaction, such as the value of a protocol header (such as HTTP Host) or
the size of the message. These items of information will be retrieved and returned
to the object referencing the Processing Metadata object, such as a AAA Policy.
For example, a business use case might require the DataPower appliance to
authenticate a user based on the user identity in an MQ protocol header, coupled
with the name of the MQ Queue Manager that holds the request message. The
AAA Policy that implements this solution would use a Processing Metadata object
to retrieve those two meta-items and return them in a nodeset to the AAA Extract
Identity step.
To add a Processing Metadata object, use the following procedure:
1. Select Objects XML Processing Processing Metadata to display the
Processing Metadata catalog.
2. Click Add to display the Processing Metadata object configuration screen.
3. Use the properties on the Main tab to define name of the object.
4. Use the controls on the Metadata Item tab to define the metadata items that
this object retrieves.
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
Comments
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.
305
To configure custom metadata for a system variable, select Custom Variable.

3. Select or specify the name of the metadata item. This name is the element name
of the item in the XML nodeset that is delivered to the referring object.
Whether you select or specify the name depends on the selected category.
v For all categories except Custom Header and Custom Variable, select the
desired metadata item from the Metadata Item list.
v For Custom Header and Custom Variable, specify the alphanumeric name of
the metadata item in the Metadata Item field.
4. For Custom Header and Custom Variable only, specify the exact name of the
protocol header or system variable to examine for the custom item in the
Custom Data Source field. For example, the desired custom HTTP header can
be ASN-Ob1.
5. Click Add.
Removing metadata items

To remove a metadata item, use the following procedure:
1. Click the Metadata Items tab.
2. Click the Remove link adjacent to the item in the list.
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.
Admin State
Comments
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.
306

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.
a. Click Add.
b. From the Match list, select a matching rule. Refer to Defining Matching
Rule objects on page 304 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.
Admin State
Comments
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.
307
If the message is not compressed using the selected algorithm, an error

will result. This is, in effect, a filter.
Output Filter
Select a compression algorithm to apply to the entire message payload
after the last action of the rule executes.
gzip
The message will be decompressed using the gzip algorithm.
PKZIP
The message will be decompressed using the pkzip algorithm.
The created archive contains only one file. If the message contains
attachments, the attachments are contained in the one file.
Non-XML Processing
Select whether to enable or disable the processing of non-XML
documents.
on
Enables the processing of non-XML documents.
off
(Default) Disables the processing of non-XML documents.
Unprocessed
Select whether to determine whether the actions of the rule will take
effect on the message. This duplicates the Request Type and Response
Type properties of the services.
Actions
Use the Add and Delete buttons, with the list of available processing
actions, to manage actions for this processing rule.
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.
Name Specify the name of the Schema Exception Map.
Admin State
Comments
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.
308
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.
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.
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.
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
309
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 313 for more
information.
To create an SLM Policy:
1. Click OBJECT Monitoring SLM Policy.
2. Click Add.
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 313 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 311 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 312 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
313 for information.
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 312 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.
310
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.
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.
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.
311
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.
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.
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
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.
312

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
1.
2.
3.
4.
create an SLM schedule:

Click OBJECT Monitoring SLM Schedule.
Click Add.
Retain the default setting for Admin State. To place in an inactive
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.
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.
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
1.
2.
3.
define a peer groups:

Click Objects Network Peer Groups.
Click Add.

6. In the Type field. retain the default value (SLM).
313
7. In the URL field, enter the URL to communicate with the peer member and
click Add.
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.
Name Specify the name of the SOAP Header Disposition Table.
Admin State
Comments
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.
Namespace URI
Specify the namespace URI of the SOAP header element. The default is
a blank string, which indicates no restriction.
Header Local Name
Specify the local name of the SOAP header element. The default is a
blank string, which indicates no restriction.
Child Element Local Name
Specify the local name of the direct child element of the SOAP header.
The default is a blank string, which indicates no restriction.
Refine Action
Select the refinement action to take. By default the processing rule,
defined by the SOAP specification, is used to remove the SOAP header,
to keep the SOAP header, or to issue a SOAP fault with the assumption
that all SOAP headers were processed by previous actions.
Processed
Take the default SOAP action, because the specified element
was processed.
Unprocessed
Take the default SOAP action, because the specified element
was not processed.
314
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.
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.
To create a SQL data source:
1. Click Objects Network Setting SQL Data Source.
2. Click Add.
3. 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.
Defining the base configuration

To define the base configuration for a SQL data source:
2. Click Add.
315

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.
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:
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.
TIBCO EMS servers

Note: TIBCO EMS is a licensed feature that is not available on all DataPower
appliances.
316
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 95.
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
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.
317
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:
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">

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

<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"/>
<xs:enumeration value="bytes"/>
<xs:enumeration value="string"/>
<xs:enumeration value="short_array"/>
<xs:enumeration value="int_array"/>
<xs:enumeration value="long_array"/>
<xs:enumeration value="float_array"/>
<xs:enumeration value="double_array"/>
<xs:enumeration value="map_message"/>
</xs:restriction>
</xs:simpleType>
</xs:attribute>
</xs:restriction>
</xs:complexContent>
</xs:complexType>
</xs:element>

<xs:element name="Array">
<xs:complexType>
<xs:sequence>
<xs:element ref="Element" maxOccurs="unbounded"/>
</xs:sequence>
318
</xs:complexType>
</xs:element>

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

<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>
<Message>
<Field name="int_array" type="int_array">
<Array>
<Element>100000</Element>
<Element>-2147483647</Element>
<Element></Element>
<Element>BOGUS</Element>
</Array>
</Field>
<Message/>
</Field>
<Field name="stringy" type="string">This is a quick brown fox.</Field>
</Message>
</Field>
<Message/>
</Field>
</Message>
</Field>

<Message>
<Field name="booly" type="bool">True</Field>
<Message/>
</Field>
<Field name="the_bytes" type="bytes">RnJvbSBNb3Njb3cgV2l0aCBMb3ZlCg==</Field>
</Message>
</Field>

<Field name="short_array" type="short_array">
<Array>
319
<Element></Element>
<Element>BOGUS</Element>
</Array>
</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.
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 service with a TIBCO EMS Front Side handler and a TIBCO EMS
backend URL.
320
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 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.
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.
321
Shared TIBCO EMS session in message fanout with commit

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 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.
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.
322
Configuring as a unique host

To configure a TIBCO EMS object as a unique host, use the following high-level
procedure:
catalog.
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
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
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.
323
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.
Enable the logging facility.
on
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.
Configuring for fault-tolerance

To configure a TIBCO EMS object as a pair of fault-tolerant hosts, use the following
high-level procedure:
catalog.
on
324
off
message headers.
Byte

byte array.

value.
Text

default is 5.
on
off
on
off
12. Specify the domain name or IP address in the TIBCO EMS Server Host field.
325
Note: This property is a required property, but it is ignored in this

configuration.
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.
backup server in the TIBCO EMS Backup Server Host field in the
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.
Configuring for load-balancing

To configure a TIBCO EMS object as a group of load-balanced hosts, use the
following high-level procedure:
catalog.
on
off
326
message headers.
Byte

byte array.

value.
default is 5.
Text
on
off
on
off
configuration.
14. Select the algorithm from the Load Balancing Algorithm list:
327
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:
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.
window.
d. Repeat step 15c for another server for load-balancing.
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:
catalog.
on
off
328

message headers.
Byte

byte array.
Text

value.

default is 5.
on
off
on
off
configuration.
329
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:
window.
c. Define the load balancing and fault-tolerance behavior:
primary member server in the TIBCO EMS Server Host field in the
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.
window.
d. Repeat step 15c for another server for load-balancing or for another
fault-tolerance primary-backup server pair.
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.
330
Universal Description, Discovery and Integration

Universal Description, Discovery and Integration (UDDI) is a platformindependent, XML-based registry. UDDI enables businesses to publish service
listings and discover each other and to define how the services interact.
Overview
A UDDI Subscription object defines a collection of UDDI version 3 subscriptions
available on a particular UDDI Registry. UDDI version 3 subscriptions pair a
persistent registry query with a notification mechanism to allow clients to be
notified when data that is matched by the query is updated. When WSDL services
are published in a UDDI Registry, properly configured UDDI subscriptions can be
used to capture the registry information needed to automatically configure a
service virtualization using Web Service Proxy via subscription notifications.
Background: UDDI and WSDL

When WSDL service data is published in a UDDI registry, basic metadata from the
WSDL definitions is incorporated into the UDDI registry by partially mapping the
WSDL data model onto the UDDI data model. This is typically done through
registry tooling to publish an existing WSDL document in to a registry. Several
conventions exist for mapping WSDL data onto the UDDI data model. The most
widely used conventions are based on the UDDI Best Practices document Using
WSDL in a UDDI Registry, Version 1.08, as well as the UDDI Technical Note Using
WSDL in a UDDI Registry, Version 2.02, which builds on the Best Practices
document. According to this model, WSDL service data is divided into a reusable
interface definition, including WSDL types, messages, portTypes, and bindings, and
a service-specific implementation definition, that includes WSDL services and ports.
Following normal WSDL construction procedures, these portions might be divided
into separate documents.
The interface portion of the WSDL data is represented with one or more tModels
in the UDDI registry. These tModels also directly reference the WSDL document
itself by URI. The implementation portion is represented with a UDDI
bindingTemplate. Unlike the interface tModels, the bindingTemplate does not
reference the WSDL document. The bindingTemplate, instead, references the
interface tModels. As such, it is also possible to register a WSDL that contains only
the interface description, and then build the actual service implementations directly
in the registry, without a concrete WSDL document that contains a service or port.
Note: For specific scenarios where the WSDL document is considered the
authoritative source for the whole service description, there also exist
alternate mappings in which the bindingTemplate can reference the WSDL
document directly, and in which there is no interface tModel. These are
described in Appendix A of UDDI Technical Note Using WSDL in a UDDI
Registry, Version 2.02, and in Appendix B.1.2 of UDDI Version 3.0.2. These
conventions are not typically supported by registry vendor WSDL
deployment tooling but could be registered manually.
Registry subscriptions
To configure the service virtualization in a Web Service Proxy, the DataPower
appliance needs access to both the interface tModel and the implementation
bindingTemplate. As these registry components can be updated separately, two
different subscriptions in the registry are required:
v One to retrieve the bindingTemplate
v One to retrieve the tModel
331
In the case of a deployment that follows the more detailed Technical Note
mapping, where the WSDL interface is represented with more than one tModel, the
DataPower appliance needs access to the tModel that represents the wsdl:binding.
Alternately for a deployment that follows one of the previous alternate mappings,
where there is no interface tModel, only the subscription for the bindingTemplate
is required.
The actual registry subscriptions that retrieves the tModel and bindingTemplate
could be configured in several ways. Because bindingTemplates are contained by
businessServices, it is possible to retrieve the bindingTemplate information either
with a bindingTemplate query or with a businessService query. Further, two
different queries are available to retrieve each object kind. Registry objects can be
retrieved directly by key using get queries (get_serviceDetail, get_bindingDetail,
and get_tModelDetail), or matched against a set of criteria using the find queries
(find_service, find_binding, and find_tModel). Get queries can be used as a
simple way to retrieve a particular service from the registry. In more complex
scenarios, it might be desirable to define service categorizations that can be
subscribed to in bulk with find queries, which allows the subscription process to
be de-coupled from the service registration precess. Consult you registry tooling on
how to establish and use custom categories in the registry.
In addition to using one of these queries as a filter, the subscription itself can be
configured for a specific notification interval and specific expiration date. The
subscription can be configured as either brief or verbose mode. The DataPower
appliance supports both modes. When brief is selected, the DataPower appliance
initiates requests back to the registry to retrieve any detailed information it
requires. To receive periodic update notifications, the subscriptions must be
configured to notify the subscription listener service on the XML Management
Interface of the DataPower appliance. Configuring the listener is typically done by
selecting a service endpoint as the notification type, and entering the URL for the
subscription listener service. For example:
https://192.168.1.25:5550/service/uddi-subscription
Note: The XML Interface of the DataPower appliance must be enabled, and the
UDDI Subscriptions box checked to allow the appliance to receive
subscription information notifications.
After the required subscriptions are created in the registry, their keys can be
added to one or more UDDI Subscription objects on the DataPower
appliance. Each UDDI Subscription object must contain all of the keys that
are needed to retrieve all of the required service information. In other
words, UDDI Subscription object will have at least two subscription keys.
UDDI Registry
To create a UDDI Registry object that specifies the location of a UDDI registry and
the information to access it, perform the following procedure:
1. Select Objects Configuration UDDI Registry to display the UDDI
Registry catalog.
2. Click Add to display the UDDI Registry Configuration screen.
6. Specify the domain name or IP address of the UDDI registry in the Host field.
332
7. Specify the port number for the SOAP over HTTP interface in the Port field.
This UDDI registry port is generally used for UDDI browsing. The default is
80.
8. Use the Use SSL radio buttons to select how to use SSL when accessing the
UDDI registry.
Publish
(Default) Specifies that publish requests to the UDDI registry use an
SSL connection.
Always
Specifies that all requests to the UDDI registry use an SSL connection.
9. Specify the port number for the SOAP over HTTPS interface of the UDDI
registry in the Port (SSL) field. This UDDI registry port is generally used for
UDDI inquiries. The default is 443.
10. Select the SSL profile to use for access to the UDDI registry from the SSL
proxy profile list.
11. Define the local path (URI) for the different types of requests to the UDDI
registry. Depending on the selection, the complete URL has one of the
following format:
URL for non-SSL access
http://hostname:port/uri
URL for SSL access
https://hostname:port_ssl/uri
a. Specify the URI to complete the URL for query requests in the Inquiry
URL field. The default is /uddi/inquiry.
b. Specify the URI to complete the URL for publish requests in the Publish
URL field. The default is /uddi/publish. Publish requests require SSL
access.
c. Specify the URI to complete the URL for subscribe requests in the
Subscription URL field. The default is /uddi/subscription.
d. Specify the URI to complete the URL for security requests in the Security
URL field. The default is /uddi/security.
12. Select the API version of the UDDI registry from the Version list.
UDDI Subscription
To create UDDI Subscription objects, perform the following procedure:
1. Select Objects Services UDDI Subscription to display the UDDI
Subscription catalog.
2. Click Add to display the UDDI Subscription Configuration screen.
Name Specify the name of the object. This must be unique among all UDDI
Subscription objects in this or any other application domain. The name
must contain only alphanumeric characters.
Admin State
333
Comments
Subscription Key
This is one or more keys for the subscription, which must already exist
in the UDDI registry. To track services that are modeled in UDDI using
both services and tModels (for example, when following UDDI Best
Practices), several subscriptions will be required to receive updates for
both the service and tModel components. All of these subscriptions
must use the same user name and password.
To include a key, specify the key value in the blank input field
alongside the Add button and click Add. A key value resembles the
following string:
uddi:89069b00-4a67-11db-8c9a-51a164e08c97
Username
Specify the user name used to authenticate with the Registry. This user
name must be defined on the Registry.
Password
Specify the password used to authenticate with the Registry.
Confirm Password
Repeat the password to confirm the value.
Publishing to a UDDI registry

To publish a Web service to a previously configured UDDI registry, use the
1. From the Control Panel, click the Web Service Proxy icon to display the Web
Service Proxy catalog.
2. Click the Web Service Proxy to modify to display the Web Service Proxy
Configuration (SLM) screen.
3.
4.
5.
6.
7.
8.
9.
Click the Services tab to display the list of configured Web services.
Click Publish to UDDI to display the UDDI Publish window.
Select the target registry from the UDDI Registry list.
Click Continue.
Specify the login name for registry access in the Username field.
Specify the password for the user in the Password field.
Click Continue.
Viewing the status of UDDI subscriptions

To view the status of the subscriptions included in any UDDI Subscription object,
expand the Status navigation area and select any of the UDDI-related status
displays in the Web Service grouping.
334
URL Map
A URL map contains a list of URLs or shell-style match expressions that define a
URL set. Incoming or cached documents can be evaluated against the match
expressions in the map to determine whether the document is granted specific
processing. For example, an XML manager might reference one or more URL maps
to determine whether a cached style sheet is refreshed periodically or whether it is
subject to a Compile Options Policy.
1. Select Objects XML Processing URL Map to display the URL Map catalog.
2. Click Add to display the URL Map Configuration (Main) screen.
Name Specify the name of this URL Map.
Admin State
Comments
URL Map Rule tab

1. Click the URL Map Rule tab to display the URL Map Configuration (URL Map
Rule) screen.
2. Click Add to display the URL Map Rule Property window.
Match Pattern
Specify a URL or URL set.
*

character.

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.

4. Click Save to return the URL Map Configuration (URL Map Rule) screen.
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
335
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.
Name Specify the name of this URL Rewrite Policy.
Admin State
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.
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.
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
336
match condition that triggers the rewrite rule. Depending on the rule
type, a candidate URL or specific HTTP header field is matched against
the expression.
v For absolute-rewrite, content-type, and post-body, defines the
expression to be matched against the URL.
.* or *
Matches any string.
(.*)xsl=(.*)\?(.*)
Matches a string of the following format:
a. A text subpattern.
b. Followed by xsl=.
c. Followed by a text subpattern.
d. Followed by ?. The backward slash (\) in the PCRE is a
URL escape.
e. Followed by a text subpattern.
(.*)&[Xx][Ss][Ll]=([^&]+)(.*)
Matches a string of the following format:
a. A text subpattern.
b. Followed by &.
c. Followed by X or x.
d. Followed by S or s.
e. Followed by L or l.
f. Followed by =.
g. Followed by a text subpattern that does not contain an
ampersand (&) character.
h. Followed by a text subpattern.
v For header-rewrite, defines the expression to be matched against the
contents of a specific HTTP header field. For example *.* matches
any value.
PCRE documentation is available at http://www.pcre.org.
Input Replace Expression
Specify a PCRE-style replacement that defines the rewritten URL, HTTP
header field, or HTTP POST body.
v For absolute-rewrite, defines the rewritten URL.
If the match pattern is .* or *, specify the complete replacement.
If the match pattern is (.*)xsl=(.*)\?(.*), specify the evaluation
replacement for any text subpattern or retain the original text
subpattern. To retain the first text subpattern, specify $1; to retain
the second text subpattern, specify $2, and so forth. To replace the
second text subpattern only, specify $1xsl=ident.xsl?$3.
If a rewritten URL begins with a host name or port that is different
from the configured remote address, the host name or port portion of
the rewritten URL is ignored.
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.
337
If the match pattern is (.*)xsl=(.*)\?(.*), specify the evaluation

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
subpattern. To retain the first text subpattern, specify $1; to retain the
second text subpattern, specify $2, and so forth. To retain the second
text subpattern only and not use the third text subpattern, specify
http://mantis:8000/$2.
Input URL Unescape
Select whether URL-encoded characters (for example, %2F) that occur in
the rewritten URL are replaced with literal character equivalents. This
option is available for absolute-rewrite or post-body only.
on
Enables the substitution of literal characters for URL-encoded

characters.
off
(Default) Disables the substitution of literal characters for

URL-encoded characters.
Stylesheet URL Unescape

Select whether URL-encoded characters (for example, %2F) that occur in
the replacement URL are replaced with literal character equivalents.
This option is available for absolute-rewrite or post-body only.
on
(Default) Enables the substitution of literal characters for

URL-encoded characters.
off
Disables the substitution of literal characters for URL-encoded

characters.
Header Name
Identifies the name of the header to have its value rewritten. The
header name must be entered exactly as it is defined in the message.
This option is for header-rewrite only.
URL Normalization
Select whether to enable normalization of URL strings. Normalizing a
URL compresses "." and ".." and converts backward slashes (\) to
forward slashes (/).
on
(Default) Enables normalization.
off
Disables normalization.
4. Click Save to return to the URL Rewrite Policy Configuration (Main) screen.
338
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.
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
339
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.
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.
12.
13.
14.
15.
16.
17.
18.
On the Basic-Auth Policy tab, define basic authentication policies.

On the Soap-Action Policy tab, define SOAP action policies.
On the Pubkey-Auth Policy tab, define public key authentication policies.
On the Allow-Compression Policy tab, define policies that disable
compression.
On the Header-Retention Policy tab, define header retention policies.
On the Restrict to HTTP 1.0 Policy tab, define HTTP 1.0 restriction policies.
On the Inject Header Policy tab, define header injection policies.
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.
Modifying the basic configuration

To
1.
2.
3.
modify the basic configuration of a user agent:

Click Network Other User Agent.
Click the name of an existing user agent.
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.
340
5. Optional: In the Timeout field, change the idle timeout to allow in seconds
before timing out and closing the connection.
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
1.
2.
3.
4.
add an HTTP proxy policy to a user agent:

Click the Proxy 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 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.
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 20 for more information.
To add an SSL proxy policy to a user agent:
1.
2.
3.
4.

Click the SSL Proxy Profile Policy tab.
Add a policy.
a. Click Add.
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.
341

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:
2. Click the name of an existing user agent.
3. Click the Basic-Auth Policy tab.
4. Add a policy.
a. Click Add.
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.
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.
add a SOAP action policy to a user agent:

Click the Soap-Action Policy tab.
4. Add a policy.
a. Click Add.
c. In the Soap Action field, enter the URI of the SOAP action.
342
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://user@server.com/images/*
v scp://user[a-c]@10.10.[0-4].23/inbound/*
To
1.
2.
3.
4.
add a private key authentication policy to a user agent:

Click the PubKey-Auth Policy tab.
Add a policy.
a. Click Add.
c. From the Private Key list, select the desired private key.

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 disable an allow compression policy for a user agent:
3. Click the Allow-Compression Policy tab.
4. Add a policy.
a. Click Add.
c. Set Allow Compression to off.
343
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.
add a header retention policy to a user agent:

Click the Header-Retention Policy tab.
4. Add a policy.
a. Click Add.
c. From the Header Retention list, select the check boxes for the headers to
retain.
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:
3. Click the Restrict to HTTP 1.0 Policy tab.
4. Add a policy.
a. Click Add.
c. Set Restrict to HTTP 1.0 to on.
344
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.
4.
add a header injection policy to a user agent:

Click the Inject Header Policy tab.
Add a policy.
a. Click Add.
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.
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
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 disable the chunked uploads policy for a user agent:
3. Click the Chunked Uploads Policy tab.
4. Add a policy.
a. Click Add.
c. Set Enable/Disable HTTP 1.1 Chunked Request Bodies to off.
345
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
1.
2.
3.
4.
add an FTP client policy to a user agent:

Click the FTP Client Policies tab.
Add a policy.
a. Click Add.
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.
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.

Creating Web Service Proxy objects

This section provides information about using the object configuration screens to
configure Web Service Proxy services. When you configure a Web Service Proxy
service, you provide one or more of the following:
v Local or remote WSDL file
346
v WSDL file from a UDDI subscription

v WSDL file form a WSRR subscription
Creating a new Web Service Proxy

To create and configure a working Web Service Proxy using these object screens, it
is necessary to do only the following:
1. On the Main screen, specify a Name for the Proxy.
2. Click the Dynamic Endpoint tab, set the Auto-Create Source Protocols
property to on.
3. Click the WSDL File tab to create at least one WSDL entry:
a. Click Add to open the WSDL Property window.
b. Specify the location of the WSDL file in the WSDL Source Location field.
This is a full URL.
c. Specify an alias for the WSDL file in the Local Name field.
d. Click Save to save the information and close the WSDL Property window.
Discovering listening ports

To discover the port on which the new Web Service Proxy listens, perform the
1. Select Status Main Object Status.
2. In the Object Status screen, select types from the View By list.
3. Under one of the Front Side Handler entries, look for AutoCreate.
4. Click the name of this Front Side Handler to view its port number. The IP
address is the IP address of the DataPower appliance.
You can gain greater control of the IP address and port by creating at least one
Front Side Handler and assigning it to the Web Service Proxy instead of using the
Auto-Create Source Protocols property.
Endpoint Rewrite Policy objects

This Front Side Handler must use the same address and port as defined in the
WSDL Services section. If any Local Endpoint Rewrite policy is applied, the Front
Side Handler must match the result of the rewrite.
For example, if the WSDL contains the following service definition, the Front Side
Handler must be set to use at least one of the IP addresses of the local DataPower
appliance (or 0.0.0.0 to indicate all addresses) and the default HTTP port (80).
<service name="SearchService">
<port name="SearchPort" binding="typens:SearchBinding">
<soap:address location="http://api.search.com/search/beta2"/>
</port>
</service>
If a Local Endpoint Rewrite policy alters the definitions in the WSDL, the Front
Side Handler must match the result of the rewrite. For example, if the Endpoint
Rewrite policy contains the following rewrite rule, the Front Side Handler must
use port 8010.
absolute-rewrite "(.*)://(.*?)/(.*)" "$1://0.0.0.0:8010/$3"
347
Specifying basic proxy operation

Select Objects Services Web Service Proxy to display the Web Service Proxy
catalog.
Click Add to display the Configure Web Service Proxy screen. Use this screen to
specify basic Proxy operation. For information about how to use these pages to
create a new Web Service Proxy, refer to Configuring Proxy settings on page 350.
Name Specify the name of this Proxy. This is required.
Admin State
Comments
XML Manager
Assign an XML manager. Refer to XML Manager on page 394 for more
information.
Load Balancer Hash Header
Specify the name of the HTTP header to use for calculating the hash for
load balancing traffic to the backend servers.
v When defined, the hash algorithm uses the value of the identified HTTP
header.
v When not defined, the hash algorithm uses the IP address of the client.
This property is relevant only when the value defined by the algorithm for
the Load Balancer Group is hash.
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
348
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.
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.
Type
Select the proxy type.

Dynamic Backend
Specifies support for multiple backend Web or application servers.
Server addresses and port numbers are extracted from incoming
client requests.
Static Backend
Specifies support for a single backend Web or application server.
The backend URL field then appears and is required.
Static from WSDL
(Default) Specifies that the backend is defined by the services
section of the WSDL.
Endpoint Rewrite Policy

An Endpoint Rewrite policy provides an easier method for determining the
addresses offered by the Web Service Proxy (or Local Endpoint) to calling
clients and also for determining the destination (or Remote Endpoint).
Refer to WS-Proxy Endpoint Rewrite on page 375 for more information.
Note: If you elect not to construct your own Front Side Handlers (which
determine the protocol, address and port on which the Web Service
349
Proxy listens) and you do use a Endpoint Rewrite Policy to set these
attributes, you must make sure to set Auto Generate Protocol
Handlers to on.
AAA Policy
Select an AAA Policy. All submitted traffic for all service endpoints will be
subjected to this authentication and authorization policy. This allows for
the creation and maintenance of a single policy used across service
endpoints. Refer to Creating AAA Policy objects on page 243 for more
information.
Processing Policy
Select a Processing Policy. Messages submitted to the Proxy will be
processed by this Policy. Refer to Defining Processing Policy objects on
Note: The service automatically validates message traffic as well-formed
SOAP XML, applies schema validation based on the WSDL, and
filters for correct operation names.
Kerberos Encryptor Principal
Specify the full name of the client principal when the Web Service Proxy
needs to decrypt automatically encrypted requests. Use this property when
the encryption uses a Kerberos session key or uses a key that was derived
from the session key.
Kerberos Decryptor Principal
Specify the full name of the server principal when the Web Service Proxy
needs to decrypt automatically encrypted responses. Use this property
when the encryption uses a Kerberos session key or uses a key that was
derived from the session key.
Kerberos Keytab
Select the Kerberos Keytab that contains the principals. The Web Service
Proxy uses these principals to decrypt automatically encrypted requests
and responses
Decrypt Key
Select a Cryptographic Key object. This key will be used to decrypt
encrypted payloads, if any are encountered. The resulting decrypted node
set will then be passed to the Processing Policy rules.
SOAP Action Policy
The service attempts to match requests to the appropriate WSDL using the
SOAPAction header. This setting controls the behavior of this operation.
Lax
(Default) An empty header or a header that contains the empty

string from the client is considered a match. The client can quote
the SOAP action header. For example, SOAPAction:"" is treated as a
match.
Strict
The client must provide the header as it is specified in the WSDL

file. The client can quote the SOAP action header.
Off
The header is ignored when issued by clients and is never

compared against the content in the WSDL.
Configuring Proxy settings

On the Proxy tab, provide the following inputs:
350
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.
SSL Proxy
Optionally assign an SSL Proxy Profile to this Proxy. Refer to SSL Proxy
Profile objects on page 20 for more information.
Crypto Credentials
Optionally assign a Crypto Credentials List to this service. Refer to
Defining Firewall Credentials objects on page 15 for more information.
Default parameter namespace
Optionally specify the default XML namespace for parameters made
available to this Proxy via the CLI or WebGUI.
The default namespace for such parameters is http://www.datapower.com/
param/config.
Query parameter namespace
Optionally specify the default XML namespace for parameters made
available to this Proxy via a URL query string.
The default namespace for such parameters introduced 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.
Strip

Streaming
Unprocessed
attachments.
Response attachment processing mode
When the response type is SOAP or XML, select how to process server
responses with attachments.
351

Strip

Streaming
Unprocessed
attachments.
Action when required root part is not first
When the attachment processing mode for requests or for responses is
Streaming, select the action to take when the MIME message root part is
not first.
Abort Stops the transaction and return an error.
Buffer To Root
Buffers attachments before the root part into memory. Then
processes the root part, buffered attachments, and subsequent
attachments.
Process In Order
(Default) Processes the attachments and root part in the order that
they appear in the original message. All parts are still processed in
streaming mode even though only attachments after the root will
be streamed from the network.
Front attachment processing format
Select how to interpret client requests with attachments.
Dynamic
(Default) The appliance reads the message and determines the
attachment format (DIME or MIME) from the content-type header.
Conversion between MIME and DIME is possible provided that
attachments are buffered.
MIME Messages adhere to the MIME format. Conversion to DIME is
possible provided that attachments are buffered.
DIME Messages adhere to the DIME format. Conversion to MIME is
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.
352
MIME Messages adhere to the MIME format. Conversion to DIME is

DIME Messages adhere to the DIME format. Conversion to MIME is
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 header processing
support. When on, MIME package headers can appear in the body of the
HTTP Post and these headers will be processed by the Proxy. MIME
support is enabled by default.
Back Side MIME Header Processing
Use the toggle to enable (on) or disable (off) MIME header processing
support. When on, MIME package headers can appear in the body of the
HTTP Post and these headers will be processed by the Proxy. MIME
support is enabled by default.
Stream Output to Back
Select the desired streaming behavior.
Buffer Messages
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
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.
Client Traffic Type
Characterize the client-originated request.
Non-XML
Does not directly characterize the client request. The request
message body is not filtered or transformed by the Proxy. The
service can take other actions, such as determining a route or
authenticating the message, before passing it to the backend.
SOAP Identifies the client request as a SOAP message.
353
Pass-Thru
Does not directly characterize the client request, but indicates that
the request is not filtered or transformed by the Proxy - it is passed
as is to the target server.
XML
Identifies the client request as unencapsulated XML.
Server Traffic Type

Characterize the server-generated response.
Non-XML
Does not directly characterize the client request. The request
message body is not filtered or transformed by the Proxy. The
service can take other actions, such as determining a route or
authenticating the message, before passing it to the client.
SOAP Identifies the server response as a SOAP message.
Pass-Thru
Does not directly characterize the server response, but indicates
that the response is not filtered or transformed by the Proxy - it is
passed as is to the target client.
XML
identifies the server response as unencapsulated XML.
SOAP Schema URL

When the traffic type is set to SOAP, the SOAP Schema URL field appears.
Use this field to set the URL to the schema used to validate the SOAP
schema used for SOAP-formatted messages. When a firewall is in SOAP
mode, either on the request or response side, it will validate the incoming
messages against a W3C Schema that defines what a SOAP message is
supposed to look like. It is possible to customize which schema is used by
changing this property; this can be used to accommodate nonstandard
configurations or other special cases. To use a custom schema, specify the
full URL.
Front Side Timeout
Specify an integer between 10 and 86400 indicating the number of seconds
a connection with a client can remain idle before it times out and is closed.
The default is 120 (2 minutes). This timeout applies during a transaction.
Back Side Timeout
a connection with a server can remain idle before it times out and is
closed. The default is 120 (2 minutes). This timeout applies during a
transaction.
Front Persistent Timeout
a connection with a client can remain idle before it times out and is closed.
The default is 120 (2 minutes). This timeout applies between transactions.
Back Persistent Timeout
a connection with a server can remain idle before it times out and is
closed. The default is 120 (2 minutes). This timeout applies between
transactions.
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,
354
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.
Setting HTTP options

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
Enable (on) or disable (off, the default) Proxy loop detection. Some
protocols allow for the detection of loops between services. Enable loop
detection to include the HTTP Via header.
Follow Redirects
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.
Rewrite Host Names When Gatewaying
Use the toggle to enabled (on) or disable (off) host rewriting. The default
is on.
v If enabled, the backend server receives a request that reflects the final
route. The final route is determined by the DataPower service. The final
route is not the one in the original, client submission.
v If disabled, the backend server receives a request that reflects the
information as it arrived at the DataPower appliance.
Some protocols have distinct name-based elements that are separate from
the URL to demultiplex. HTTP uses the Host header for this purposes.
Web servers that issue redirects might want to disable this feature. These
Web servers 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
355
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 IP Label

Specify a string to determine the name of the HTTP Header containing the
client IP address. This defaults to X-Client-IP.
Setting Parser Limits

Maximum Message Size
Optionally specify the maximum size (in kilobytes) of SOAP or XML
messages accepted by this service. Use an integer in the range of 0 through
2097151. The default is 0. A value of 0 specifies unlimited size.
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.
Proxy Parser Limits
The Proxy can impose limits on the size and depth of XML documents and
elements. Use the toggle to enable (on) or disable (off) Proxy-level limits.
The Proxy limits override any similar limits set by the XML Manager used
by the Proxy.
XML Element Depth
Specify an integer to set the maximum allowed element depth of a single
document. This defaults to 512. Only available when parser limits are
enabled.
XML Attribute Count
Specify an integer to set the maximum allowed number of attributes. This
defaults to 128. Only available when parser limits are enabled.
XML Attribute Max Node Size
Specify an integer to set the maximum allowed size, in bytes, of a single
element. This defaults to 33554432 (32K). For optimal performance, set this
value to a power of 2. Only available when parser limits are enabled.
XML External References
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.
356
Attachment Byte Count Limit

Specify an integer to set the maximum allowed number of bytes in an
attachment. This defaults to 2 gigabytes. Only available when parser limits
are enabled.
Assigning Monitors
Service Monitors
Optional: Use the list with the Add and Delete buttons to assign one or
more Web service monitors. Refer to Web services monitors on page 238
Count Monitors
more count monitors. Refer to Configuring count monitors on page 234
Duration Monitors
more duration monitors. Refer to Configuring duration monitors on page
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 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.
Enabling support for WS-Addressing

To enable support for Web Services Addressing (WS-Addressing), click the
WS-Addressing tab to display the WS-Addressing screen. Use this screen to
specify the WS-Addressing mode that this service is to provide. The level of
support is determined by the WS-Addressing capabilities of the associated clients
and servers. The DataPower service provides the mediation, if any, between the
clients and servers.
Support for a specific level of WS-Addressing does not preclude simultaneous
support for traditional addressing formats.
Select the mode from the WS-Addressing Mode list.
No WS-Addressing
(Default) Disables WS-Addressing support. Both clients and servers use
traditional addressing. Requires no additional configuration.
Synchronous Gatewayed to WS-Addressing
357
that use traditional addressing and servers that use WS-Addressing. Refer
to Configuring Traditional to WS-Addressing on page 48 for
WS-Addressing Gatewayed to Synchronous
that use WS-Addressing and servers that use traditional addressing. Refer
to Configuring Traditional to WS-Addressing on page 48 for
Pure WS-Addressing
and servers that use WS-Addressing. Refer to Configuring WS-Addressing
to WS-Addressing on page 51 for configuration details.
Configuring Dynamic Endpoints

Front Side Protocol
Select an existing Front Side Handler and click Add.
Front Side Handlers determine the network communication protocol,
address, port and other protocol-specific settings. Refer to Chapter 4,
Handler configuration, on page 69 for more information.
More than one Web Service Proxy can use a particular Front Side Handler
(unlike Multi-Protocol Gateway services). For all messages received by the
Front Side Handler, the first child of the SOAP Body node is examined to
determine which Web Service Proxy should handle a given message. If no
match is found, the Front Side Handler returns an error to the client.
Note: If you are using these object pages to create a new Proxy, it is
advisable to create at least one HTTP Front Side Handler for the
Proxy. The Protocol Handler can use the default address (0.0.0.0) and
must use the Port and URI specified by the WSDL (or alternatively
by the Local Endpoint URL in effect)
Autocreate Source Protocols
The front side ports that accept connections must have configured
source-protocols. If no source protocol is configured and autocreate is
enabled, a default source-protocol will be created. Currently only
auto-creates HTTP sources. Defaults to off.
When creating a new Proxy using these pages, this property can be set to
on. However, discovering the port number assigned to the Proxy requires
referencing additional pages. Create a Front Side Handler to control the IP
and port assignments.
Local Endpoint Rewrite
Select a URL Rewrite Policy object. This policy is applied to the wsdl:port
values found in the WSDL configuration source of the Proxy. The Proxy
will respond to the rewritten endpoint. If no policy is selected, the default
local address offered by the Proxy to clients uses the relative URI and the
original port number from the wsdl:port address specified in the WSDL.
For example, if no URL Rewrite Policy is defined and the WSDL contains
the following:
358
</port>
</service>
The address of the Web Service Proxy becomes the following:

http://DP_device_address/search/beta2
Remote endpoint rewrite

Select a URL Rewrite Policy object. This policy is applied to the wsdl:port
values found in the WSDL configuration source of the Proxy. As a result of
this rewrite policy, the backend service endpoint address and URI are
rewritten in accordance with the policy. If no policy is selected, the default
remote address is one defined as the address in the WSDL. The remote
endpoint URL, after rewrite, if any, will then be the URL to which the
Proxy forwards requests after processing when the type is set to Static
from WSDL.
When the type is set to Static Backend, all traffic is forwarded to a single
URL regardless of any Remote Endpoint Rewrite.
Similarly, when the type is set to Dynamic Backend, the address to which
traffic is forwarded might not be what is defined in the WSDL or by a
Remote Endpoint Rewrite policy.
Enabling Web Service Reliable Messaging

WS-ReliableMessaging
Enable or disables Web Services Reliable Messaging.
on
Enables Reliable Messaging.
off
(Default) Disables Reliable Messaging

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).
AAA Policy
Selects the AAA Policy to perform authentication of incoming Reliable
Messaging messages. This AAA Policy can be the same one that is used in
later processing by the request or response rule. The results are cached, so
it is not evaluated again.
While this is focused on protecting the Reliable Messaging control
messages, such as CreateSequence and TerminateSequence, it is also run on
incoming Reliable Messaging data messages, with a Sequence header. This
prevents unauthorized clients from using appliance resources by issuing
359
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.
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
Messaging queue beyond a gap in the received sequence numbers.
360

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.

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

Retransmission Interval property sets the initial timeout.
off


The default is 4.
The default is 30.
The default is 1.
by sending a CloseSequence SOAP message. Use any value of 10 3600. The default is 360.
Required on Request
361
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
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
off

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.

SOAP message.
on
362

timeout.
off


The default is 4.
The default is 10.
The default is 1.
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
off

SOAP message.
on
363

timeout.
off


The default is 4.
The default is 10.
The default is 1.
The default is 3.
Source Front Reply Point
client. The Front Side Protocol Handler must be associated with the same
is occurring.
This property controls whether a front-side Reliable Messaging source uses
a unique URL to receive asynchronous Acks from the client Reliable
Messaging destination or whether Acks are sent synchronously in future
requests to the front-side client.
v With a specified Front Side Protocol Handler and the client includes an
Offer in a CreateSequence SOAP message sent due to response
processing, there will be a non-anonymous URL specified in the AcksTo
element of the Accept element of the CreateSequenceResponse SOAP
reply.
v With a specified Front Side Protocol Handler and the front-side sends a
CreateSequence SOAP message to establish a reliable back channel, there
will be a non-anonymous URL specified in the AcksTo element of the
CreateSequence SOAP request.
v Without a Front Side Protocol Handler, the AcksTo elements has the
value http://www.w3.org/2005/08/addressing/anonymous, which
indicates synchronous Acks.
Source Back AcksTo Reply Point
364

server. The Front Side Protocol Handler must be associated with the same
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.
Adding a proprietary header

To add a proprietary header to the message stream, click theHTTP Header
Injection tab to display the HTTP Header Injection panel.
Click Add to display the Header Injection Property window.
Direction
Back
Front
Indicates a response that travels from the DataPower appliance to the
client
Header Name
Specify the name of the proprietary header.
Header Value
Specify the contents of the proprietary header.
Click Save to return to the Header Injection Panel.
Deleting a header from the message stream

To delete a header from the message stream, click the HTTP Header Suppression
tab to display the Proxy Header Suppression panel.
365
Click Add to display the HTTP Header Suppression window.

Direction
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 target header to delete.
Click Save to return to the Proxy Header Suppression panel.
Passing parameter-value pairs to style sheets

To pass parameter-value pairs to the style sheets that support this Proxy, click
Stylesheet Parameter to display the Proxy Stylesheet Parameter panel.
Click Add to display the Stylesheet Parameter Property window.
Parameter Name
Specify the name of the parameter.
Parameter Value
Specify the value of the parameter.
Click Save.
Refreshing WSDL Cache

The WSDL Cache Policy controls how often a WSDL is automatically refreshed. On
refresh of a WSDL, the configuration of the Proxy also refreshes to match the
refreshed WSDL.
Click Add to create a new Cache Policy. The WSDL Cache Policy Property window
is displayed.
URL Match Expression
Specify an expression used to match the URL of the WSDL (the WSDL
Location property).
366

character.

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.
TTL
The time-to-live, in seconds, for WSDL files that match the value of the
URL Match Expression property. After this time has expired, the file is
automatically refreshed. Any change in the file are reflected by changes in
the configuration of the Proxy.
Click Save.
Editing or adding WSDL files

Click the WSDL File tab to input or edit the WSDL files used as the basis for the
service.
Click Add to add a new WSDL file to the configuration.
WSDL Source Location
Specify the exact location (URL) of the WSDL file. The file can be stored on
the appliance or on a remote server (for example, local:///
searchservice.wsdl).
Local Name
Specify a mnemonic for the WSDL file. The mnemonic can be the file name
(for example, searchservice.wsdl) or an alias (for example, SearchSvc).
This value can be the value for the WSDL file property on the User Policy
tab.
Policy Attachments
Select the name of an existing Policy Attachment object. Policy attachments
associate WS-Policy with the different types of policy subjects (service,
endpoint, operation, message) in the WSDL file.
Defining a user policy for WSDL operations

Each WSDL operation of the Web services that is proxied by a Web Service Proxy
can have a user policy that is defined for that component.
Components are specified by the combination of Target Namespace, WSDL file,
Service, PortType, Binding, and Operation. For example, to specify all operations in
the target namespace MySvc, specify "MySvc" in the Target Namespace field and set
all other inputs to *. To specify one particular operation only, GetLottoPick for
example, specify wsdl:definitions//wsdl:operation/@GetLottoPick in the
Operations field and set all others to *.
The policy that is applied to the specified component consists of the following
options:
v Enable
v Publish
v Verify Faults
The User Policy configuration screen displays all policies that are established for
the WSDL operations that are identified by the WSDL files that the service uses.
Click the User Policy tab to access this information.
Note: If no User Policy is established, all operations that are defined in the WSDL
files for this service are enabled.
367
Click Add to create a new User Policy handled by this Proxy. Click the name of an
existing Operation to edit it.
Clicking Add displays the User Policy Property window.
Target Namespace
Specify a target namespace or * to designate all target name spaces defined
in the WSDL files used by the service. The target namespace is found in
the WSDL definitions element.
WSDL File
Specify the Local Name of a WSDL file (as defined on the WSDL File tab)
or * to designate all WSDL files.
Service
Specify a value of the form wsdl:definitions/wsdl:service/@name (for
example, wsdl:definitions/wsdl:service/@SearchService) to specify a
particular service, or specify * for any service. Here is an example service
defined in a WSDL:
</port>
</service>
PortType
Specify a value of the form wsdl:definitions/wsdl:portType/@name (for
example, wsdl:definitions/wsdl:portType/@SearchPort) or specify * for
any PortType. The following snippet is an example of a portType definition
from a WSDL:
<portType name="SearchPort">
<operation name="doSearch">
<input message="typens:doSearch"/>
<output message="typens:doSearchResponse"/>
</operation>
</portType>
Binding
Specify a value of the form wsdl:definitions/wsdl:binding/@name (for
example, wsdl:definitions/wsdl:binding/@SearchBinding) or specify * for
any Binding.
<binding name="SearchBinding" type="typens:SearchPort">
<soap:binding style="rpc"
transport="http://schemas.xmlsoap.org/soap/http"/>
<operation name="doSearch">
<soap:operation soapAction="urn:GoogleAction"/>
<input>
<soap:body use="encoded" namespace="urn:Search"
encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/>
</input>
<output>
<soap:body use="encoded" namespace="urn:Search"
encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/>
</output>
</operation>
</binding>
Operation
Specify a value of the form wsdl:definitions//wsdl:operation/@name (for
368
example, wsdl:definitions//wsdl:operation/@doSearch) or specify * for

any operation. Use the PortType and Binding selectors to limit the
operations selected for this policy.
Policy Toggles
Use check boxes to establish the policy applied to this component.
Enable this component
Enable this component. The Proxy will process traffic for this
component.
Publish in WSDL
Include this component in any published description (WSDL) of
the Proxy service.
Schema validate faults messages
Schema validate any fault messages generated.
Schema validate SOAP headers
Schema validate message headers.
No Request Validation
Do not schema validate request messages.
No Response Validation
Do not schema validate response messages.
Strict Fault Document Style
When enabled, schema for fault messages disallows RPC operation
wrapper. This setting applies to the full selected WSDL files.
Opt out of WS-Addressing
When enabled, does not use WS-Addressing.
Opt out of WS-ReliableMessaging
When enabled, does not use WS-ReliableMessaging.
Specifying UDDI Subscriptions

Identifies which UDDI subscriptions for which the Web Service Proxy loads and
proxies services.
Subscription
Select the UDDI Subscription.
Policy Attachment
Select the policy attachment.
WSRR Subscription tab

Identifies which WSRR subscriptions for which the Web Service Proxy loads and
proxies services.
Subscription
Select the WSRR Subscription.
Policy Attachment
Select the policy attachment.
Operation Priority tab

Click Add to define the operation priority.
369
Service Priority
Assigns a priority for scheduling or for resource allocation. Use one of the
following values:
High
Low
Normal
WSDL Component Type
Specifies the type of the WSDL component to match. Use one of the
following values:
All
(Default) Matches all inputs, which Includes or excludes all WSDL

component types (operation, port, service) to and from the match
criteria.
To disable all WSDL-based matching criteria, leave the field blank.
Disabling the matching criteria effectively creates a
document-based processing policy.
Operation
Matches when the identified operation is requested in the current
transaction.
Matches wsdl:binding/operation/@name when formatted as
{bindingNamespace}name, or matches wsdl:service/wsdl:port
when formatted as {serviceNamespace}port-name/operation-name.
Port
Matches when the operation requested in the current transaction is

included in the identified WSDL port.
Matches wsdl:service/wsdl:port/@name when formatted as
{serviceNamespace}port-name.
Service
included in the identified WSDL service.
Matches wsdl:service/@name when formatted as
{serviceNamespace}name.
Subscription
Matches an identified subscription key.
WSDL
defined in the identified WSDL file.
WSDL Component Value
Identifies the value of the WSDL-defined component. The value to specify
depends on the identified WSDL component type.
v If All, specify double quotation marks (""). This combination eliminates
the WSDL component from consideration.
v If Operation, specifies the name of the WSDL operation. Use the
wildcard character (*) to specify all operations.
v If Port, specifies the name of the WSDL port. Use the wildcard character
(*) to specify all ports.
v If Service, specifies the name of the WSDL service. Use the wildcard
character (*) to specify all services.
370
v If Subscription, specify double quotation marks (""). Any specified

value is ignored.
v If WSDL, specifies either a URL or the local name mnemonic that is
assigned to the WSDL file.
Subscription
Select the name of an existing Subscription object. The property is
meaningful only when the value of the component type is Subscription.
Operation Conformance Policy tab

Conformance Policy
Selects the Conformance Policy.
WSDL Component Type
following values:
All

criteria.
Operation
transaction.
Port

Service
Subscription
WSDL
371
value is ignored.
Subscription
Operation Policy Subject Opt Out tab

Ignored Subjects
Selects which subjects to ignore.
v Service Subject
v Endpoint Subject
v Operation Subject
v Message Input Subject
v Message Output Subject
WSDL Component Type
following values:
All

criteria.
Operation
transaction.
Port

Service
Subscription
372
WSDL
value is ignored.
Subscription
Policy Parameters tab

Parameters
Identifies the Policy Parameter object.
WSDL Component Type
following values:
All

criteria.
Operation
transaction.
Port

Service
373

Subscription
WSDL
value is ignored.
Subscription
Reliable Messaging tab

Reliable Messaging Options
Identifies the options for reliable messaging. Select any combination of the
following values:
v Reliable Messaging is optional
v RM Sequence must be bound to underlying transport-level protocol
v RM messages must be delivered in the same order as they have been
sent by the source
Reliable Messaging Delivery Assurance Type
Identifies the assurance type. Select the following value:
v Message must be delivered exactly once.
WSDL Component Type
following values:
All

criteria.
374
Operation
transaction.
Port

Service
Subscription
WSDL
value is ignored.
Subscription
WS-Proxy Endpoint Rewrite

A WS-Proxy Endpoint Rewrite policy can be used for the following purposes:
v Determine the local endpoints offered to clients by the Web Service Proxy (the
host, port and URI to which clients connect to obtain services).
v Determine the remote, or destination, endpoints used by the service to connect
to the application endpoints.
v Determine which redefined endpoints are published to UDDI repositories.
375
Note: The local endpoints that the Web Service Proxy uses might also be
determined with protocol handlers. Protocol Handlers override the settings
of an Endpoint Rewrite policy.
To create a WS-Proxy Endpoint Rewrite policy, perform the following procedure:
1. Select Objects Web Services WS-Proxy Endpoint Rewrite to display the
WS-Proxy Endpoint Rewrite catalog.
2. Click Add to display the WS-Proxy Endpoint Rewrite (Main) screen.
3. Define the configuration properties on the Main screen. For details, refer to
Main tab.
4. Click the Local Rewrite Rule tabs and define the configuration properties. For
details, refer to Local Rewrite Rule tab.
5. Click the Remote Rewrite Rule tabs and define the configuration properties.
For details, refer to Remote Rewrite Rule tab on page 378.
6. Click the Publish Rewrite Rule tabs and define the configuration properties.
For details, refer to Publish Rewrite Rule tab on page 379.
7. Click the Subscription Local Rewrite Rule tabs and define the configuration
properties. Valid when using UDDI or WSRR subscriptions. For details, refer
to Subscription Local Rewrite Rule tab on page 380.
8. Click the Subscription Remote Rewrite Rule tabs and define the
configuration properties. Valid when using UDDI or WSRR subscriptions. For
details, refer to Subscription Remote Rewrite Rule tab on page 381.
9. Click the Subscription Publish Rewrite Rule tabs and define the
configuration properties. Valid when using UDDI or WSRR subscriptions. For
details, refer to Subscription Publish Rewrite Rule tab on page 382.
Main tab
On the Main screen, provide the following inputs
Name Specify the name of this object.
Admin State
Comments
Local Rewrite Rule tab

Local Rewrite rules determine the address, port and URI used by clients to request
services through the WS-Proxy, rather than directly from the application endpoint.
To create a new rule, perform the following procedure:
1. Click Add.
Service Port Match Expression
A Perl-style regular expression to specify a Web services port. This rule
will apply to all Service Ports defined in the WSDL files underlying this
service.
For example, if the WSDL defines a service port as follows:
376
<service name="SomeSearchService">
<port name="SomeSearchPort" binding="typens:SomeSearchBinding">
<soap:address location="http://search.search.com/search/xml"/>
</port>
</service>
A Match expression might be SearchPort.

Local Endpoint Protocol
Select a protocol to establish the protocol used by the rewritten local
endpoint. This usually matches the protocol specified in the actual
WSDL definition, but is not required to do so. In the example shown
above, the protocol is HTTP. This could be reset to HTTPS if added
security is desired between the client and the Proxy.
Local Endpoint Host
Specify a host alias or IP address in this field. Use the default (0.0.0.0)
to listen on all configured interfaces of the appliance. To select a host
alias, click Select Alias.
Local Endpoint Port
Specify an integer to determine the TCP Port on which the Proxy will
listen for requests for this Service. A value of 0 will use the port that is
specified in the WSDL file. If the WSDL file does not specify a port, the
default HTTP port (80) is used. This number must be unique across the
entire appliance.
Local Endpoint URI
Specify a string to specify the URI, or local path. If this field is left
blank, the value from the WSDL will be used.
Local Endpoint Handler
Select a Front Side Handler. The selected Handler will then determine
the IP Address, Port and Protocol for this Proxy. This field appears only
when Use Local Endpoint Handler is set to on.
Use Local Endpoint Handler
Click on to use a Front Side Handler to determine the protocol, IP
address and port number of matched WSDL service port. Selecting this
mode will override the IP address, port and protocol values in this
rewrite rule.
Note: If you retain the default setting (off) for the Use Local Endpoint
Handler toggle, the Auto-Create Source Protocol Handlers
property on the Dynamic Endpoints tab must be set to on or the
Web Service Proxy cannot listen to the network.
Local Endpoint WSDL Binding Protocol
Select the WSDL binding protocol to use in the rewritten Web service.
default
(Default) Uses the binding protocol in the WSDL file.
HTTP GET
Uses the HTTP binding for WSDL 1.1 (http://
schemas.xmlsoap.org/wsdl/http/).
SOAP 1.1
Uses the SOAP 1.1 binding for WSDL 1.1 (http://
schemas.xmlsoap.org/wsdl/soap11/).
377
SOAP 1.2
Local Endpoint WSDL Port Name Suffix
Specify a suffix to add to the name of the WSDL port that will be used
to represent this service endpoint in the rewritten Web service. If
empty, rewrite the original port. The original port can only be rewritten
once.
Remote Rewrite Rule tab

Remote rewrite rules determine the destination to which to forward requests. By
default, the Web Service Proxy uses the remote endpoints that is defined in the
underlying WSDL files. By rewriting endpoint definitions, the Web Service Proxy
can route requests to another application server without changing the underlying
WSDL file. These rules can be useful for maintenance, upgrades, service moves, or
security.
1. Click Add.
service.
</port>
</service>

Remote Endpoint Protocol
Select a protocol to establish the protocol used by the rewritten remote
security is desired between the Proxy and the application server.
Remote Endpoint Host
Specify a host name or IP address of the remote host. If using load
balancers, specify the name of the Load Balancer Group that contains
the remote host.
Remote Endpoint Port
Specify an integer to determine the TCP Port to which the Proxy will
send requests for this Service. A value of 0 will use the port specified in
the WSDL. If the WSDL does not specify a port, the default HTTP port
(80) is used.
Remote Endpoint URI
Specifies the part of the URL from web service binding that specifies
the remote path. If this field is left blank, the value from the location
attribute of the soap:address element in the WSDL is used. For the
378
WebSphere MQ, TIBCO EMS, and WebSphere JMS protocols, the

Remote Endpoint URI must specify a RequestQueue parameter. For
most web services, the ReplyQueue parameter is required to receive the
SOAP response.
WebSphere MQ
Specify the URL portion of the rewritten web service binding that
specifies the WebSphere MQ Queue Manager object. This field is
required when the remote server is WebSphere MQ.
TIBCO EMS
specifies the TIBCO EMS object. This field is required when the remote
server is TIBCO EMS.
WebSphere JMS
specifies the WebSphere JMS object. This field is required when the
remote server is WebSphere Application Server.
Publish Rewrite Rule tab

Publish Rewrite rules rewrite the endpoint definitions published to UDDI
directories. If a Publish rule does not match an endpoint, then the rewritten local
endpoint is used. If no Local Endpoint Rewrite rule matches, then the values in the
original WSDL are used.
1. Click Add.
service.
</port>
</service>

Published Endpoint Protocol
Select a protocol to establish the protocol published for the endpoint.
This usually matches the protocol specified in any Local Endpoint
Rewrite rule established for the Service Port or the actual WSDL
definition.
Published Endpoint Host
Specify a host name or IP address. This value usually matches the
protocol of the Local Endpoint Rewrite rule that is established for the
service port or the actual WSDL definition.
Published Endpoint Port
379
(80) is used.
Published Endpoint URI
Specify a string to specify the URI, or local path. This usually matches
the protocol specified in any Local Endpoint Rewrite rule established
for the Service Port, or the actual WSDL definition. If this field is left
Subscription Local Rewrite Rule tab

Subscription Local Rewrite rules determine the address, port and URI used by
clients to request services through the WS-Proxy, rather than directly from the
application endpoint defined in the Subscription. Click the Subscription Local
Rewrite Rules tab.
1. Click Add.
Subscription
Select the desired UDDI Subscription. This subscription must match a
subscription in use by the Proxy employing this Endpoint Rewrite Rule.
Local Endpoint Protocol
Select a protocol to establish the protocol used by the rewritten local
Local Endpoint Host
Specify a host alias or IP address in this field. Use the default (0.0.0.0)
to listen on all configured interfaces of the appliance. To select a host
alias, click Select Alias.
Local Endpoint Port
Specify an integer to determine the TCP Port on which the Proxy will
listen for requests for this Service. A value of 0 will use the port
specified in the WSDL. If the WSDL does not specify a port, the default
HTTP port (80) is used. This number must be unique across the entire
appliance.
Local Endpoint URI
Local Endpoint Handler
Select a Front Side Handler. The selected Handler will then determine
the IP Address, Port and Protocol for this Proxy. This field appears only
when Use Local Endpoint Handler is set to on.
Use Local Endpoint Handler
Click on to use a Front Side Handler to determine the protocol, IP
address and port number of matched WSDL service port. Selecting this
mode will override the IP address, port and protocol values in this
rewrite rule.
380
Note: If you retain the default setting (off) for the Use Local Endpoint
Handler toggle, the Auto-Create Source Protocol Handlers
property on the Dynamic Endpoints tab must be set to on or the
Web Service Proxy cannot listen to the network.
Local Endpoint WSDL Binding Protocol
Select the WSDL binding protocol to use in the rewritten Web service.
default
(Default) Uses the binding protocol in the WSDL file.
HTTP GET
Uses the HTTP binding for WSDL 1.1 (http://
schemas.xmlsoap.org/wsdl/http/).
SOAP 1.1
SOAP 1.2
Local Endpoint WSDL Port Name Suffix
Specify a suffix to add to the name of the WSDL port that will be used
to represent this service endpoint in the rewritten Web service. If
empty, rewrite the original port. The original port can only be rewritten
once.
Subscription Remote Rewrite Rule tab

Subscription Remote Rewrite rules determine the destination to which the Web
Service Proxy forwards requests. By default, the Web Service Proxy uses the remote
endpoints that is defined in the underlying WSDL files. By rewriting these
endpoint definitions, it is possible to route requests to another application server
without changing the underlying WSDL file. This can be useful for maintenance,
upgrades, service moves or security.
1. Click Add.
Subscription
Select the desired UDDI Subscription. This subscription must match a
subscription in use by the Proxy employing this Endpoint Rewrite Rule.
Remote Endpoint Protocol
Select a protocol to establish the protocol used by the rewritten remote
security is desired between the Proxy and the application server.
Remote Endpoint Host
Specify a host name or IP address.
Remote Endpoint Port
381
(80) is used.
Remote Endpoint URI
Specify the part of the URL from web service binding that specifies the
remote path. If this field is left blank, the value from the location
attribute of the soap:address element in the WSDL is used. For the
WebSphere MQ, TIBCO EMS, and WebSphere JMS protocols, the
Remote Endpoint URI must specify a RequestQueue parameter. For
most web services, the ReplyQueue parameter is required to receive the
SOAP response.
WebSphere MQ
specifies the WebSphere MQ Queue Manager object. This field is
required when the remote server is WebSphere MQ.
TIBCO EMS
specifies the TIBCO EMS object. This field is required when the remote
server is TIBCO EMS.
WebSphere JMS
specifies the WebSphere JMS object. This field is required when the
remote server is WebSphere Application Server.
Subscription Publish Rewrite Rule tab

Subscription Publish Rewrite rules rewrite the endpoint definitions published to
UDDI directories. If a Publish rule does not match an endpoint, then the rewritten
local endpoint is used. If no Local Endpoint Rewrite rule matches, then the values
in the original WSDL are used.
1. Click Add.
Subscription
Select an existing UDDI Subscription object. The subscription keys
contained in the object determine the configuration of the proxy
services and operations.
Published Endpoint Protocol
Select a protocol to establish the protocol used by the rewritten
published endpoint. This usually matches the protocol specified in the
WSDL definition (returned from the subscription), but is not required to
do so. If the protocol is HTTP, it could be reset to HTTPS if added
Published Endpoint Host
Specify a host name or IP address. This value usually matches the
protocol of the Local Endpoint Rewrite rule that is established for the
service port or the actual WSDL definition.
Published Endpoint Port
Specify an integer to determine the published TCP Port on which the
Proxy will listen for requests for this Service. A value of 0 will use the
382
port specified in the WSDL (returned from the subscription). If the

WSDL does not specify a port, the default HTTP port (80) is used. This
number must be unique across the entire appliance.
Published Endpoint URI
blank, the value from the WSDL (returned from the subscription) will
be used.
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.
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:
383
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

successful send operation on the back side:
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
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.
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.
384
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

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.
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
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.
385
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.
Name Specify the name of this WebSphere JMS Server object.
Admin State
Comments
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.
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
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.
386
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)
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.
387
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.
WebSphere JMS Host
Specify the host name or IP address of a WebSphere bootstrap server.
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)
388
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.
7. Click Save to bootstrap server identification and to return to the WebSphere
JMS Endpoint catalog.
8. If necessary, repeat steps 5 on page 388 to 7 to identify additional bootstrap
servers.
9. 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.
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
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

389
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.
WebSphere Service Registry and Repository

WebSphere Service Registry and Repository (WSRR) is an IBM product that
provides advanced management and governance of business processes and
services. WSRR enables users to store, access, and manage service information and
metadata.
v As a registry, WSRR provides information about service availability and where
such services are stored
v As a repository, WSRR maintains information about service usage and
interaction
WSRR allows clients to store service definitions (WSDL files) and other XML-based
artifacts (schemas, style sheets, and policy documents).
From the point-of-view of the DataPower appliance, WSRR provides functional
equivalency to a UDDI registry as a source of Web Service Proxy configuration
data. For complete information on WSRR (including installation, configuration,
customization, and Administration), refer to the WebSphere Service Registry and
Repository Information Center accessible from the following Web site:
http://www.ibm.com/software/integration/wsrr/library/
Overview of configuring WSRR

WSRR configuration is a two-step procedure:
1. Configure a WSRR Server object to provide the basic information that is
required to contact the WSRR server to query for previously retrieved
resources.
2. Configure a WSRR Subscription object to provide the data that describes the
target resource (for example, a WSDL file) that is retrieved from the WSRR
server. Resources that are stored on the WSRR server are uniquely identified by
a namespace and a name, both of which are assigned when the resource is
added to the registry. Configuration of a WSRR Subscription object also
specifies the method to use to ensure that the local copy of the resource is
periodically synchronized with the copy (version) on the WSRR server.
390
Note: WSRR defines a basic subscription method that is based on email

notification. The DataPower appliance does not use this subscription model.
The DataPower subscription method uses a periodic WSRR query that
requests the previously retrieved resource. This approach ensures that the
local copy of the resource is synchronized with the resource on the WSRR
server on a routine basis.
WSRR Server
To configure a WSRR server, use the following procedure:
1. Select Objects Configuration WSRR Server to display the WSRR Server
catalog.
2. Click Add to display the WSRR Server configuration screen.
3. Provide the following input:
Admin State
Comments
SOAP URL
Specify the URL to access the SOAP API on the WSRR server. The URL
takes one of the following formats:
v http://host:port/URI
v https://host:port/URI
Where:
host
Specifies the host name of IP address of the WSRR server.
port
Specifies the default listening port on the WSRR server. For

HTTP, the default is 9080. For HTTPS, the default is 9443.
URI
Specifies the URI of SOAP API on the WSRR server.

URI for version 6.0.2
WSRRCoreSDO/Services/WSRRCoreSDOPort
URI for version 6.1
WSRR6_1/Services/WSRRCoreSDOPort
Because the URI differ by WSRR version, refer to your
version-specific WSRR documentation for additional
information.
http://www.ibm.com/software/integration/wsrr/library/
SSL Proxy Profile

Select the SSL Proxy Profile to assign for secure communication (when
using the HTTPS protocol).
Username
Specify the user name to authenticate with the WSRR server. Leave
blank if the WSRR server does not enforce authentication.
Password
Specify the password for the specified user. Leave blank if the WSRR
server does not enforce authentication.
391
Confirm Password
Specify the password again. Leave blank if the WSRR server does not
enforce authentication.
WSRR Server Version
Select the version of WSRR in use.
6.0
(Default) Uses WSRR Server, version 6.0.
6.1 or later
Uses WSRR Server, version 6.1 or later.
WSRR Subscription
To configure a WSRR subscription, use the following procedure:
1. Select Objects Services WSRR Subscription to display the WSRR
2. Click Add to display the WSRR Subscription configuration screen.
3. Provide the following input:
Admin State
Comments
WSRR Server
Select the WSRR Server object that stores the WSDL files and all
associated files that are needed by the Web Service Proxy service.
Namespace
Specify the resource namespace. The namespace is assigned when a
resource, such as a WSDL file, is loaded to a WSRR or when a
collection of resources is aggregated as a concept. This property in
conjunction with the Object Name property uniquely identify the
subscribed-to WSRR resource.
Subscription Object
Select the WSRR resource type.
WSDL Document
(Default) Indicates that the resource is a single WSDL file.
Concept
Indicates that the resource is a concept. A concept is a package
for metadata that is created and maintained by a WSRR
administrator. The package contains one or more WSDL files
with potentially any number of associated XSD schema files or
XML files.
Object Name
Specify the name of the object. The name is assigned when a resource,
such as a WSDL file, is loaded to a WSRR or when a collection of
resources is aggregated as a concept. This property in conjunction with
the Namespace property uniquely identify the subscribed-to WSRR
resource.
392
Synchronization Method
Select the method used to synchronize the local copy with the version
on the WSRR server.
Poll
(Default) Use a scheduled WSRR query to synchronize.
Manual
Require user-intervention to synchronize. Refer to Manually
synchronizing WSRR subscriptions on page 394 for details.
Refresh Interval
When the Synchronization Method is Poll, specify the interval, in
seconds, between scheduled WSRR queries. Use a value in the range of
Note: The special value of 0 disables synchronization.
Use WSDL Version
Use the toggle to specify whether the WSRR subscription service
should retrieve a WSDL file with a user-specified version number from
the registry.
on
Queries the registry for a specified WSDL file. If selected, enter

the Version number for the WSDL file in the WSDL Version
field.
off
(Default) Does not query the registry.
The WSRR registry maintains a Version attribute for WSDL files. The
Version is a user-defined suffix value that identifies different versions
of a WSDL file. For example, you might identify subsequent versions of
a WSDL file as WSDL 1, WSDL 1.1, WSDL 1.2, and so on. If you enable
Use WSDL Version, you must spell the Version correctly, for example
1.1, or the subscription service will not return the WSDL. The
following are some WSDL processing scenarios:
v If you do not enable Use WSDL Version, and there are multiple
versions of the WSDL in the registry, then the subscription service
uses its own internal sorting logic to retrieve one of the WSDL files.
v If you enable Use WSDL Version and leave the WSDL Version
blank (NULL) and there is a WSDL in the registry with a Version
number, then the subscription service will not retrieve the WSDL file.
v Do not enable Use WSDL Version if there is only a single WSDL file
in the registry.
Fetch Policy Attachments (WSRR 6.1 or later)
Use the toggle to specify whether the WSRR subscription service
should retrieve external Web Services Policy attachments that apply to
a WSDL file.
on
(Default) Retrieves external Web Services Policy attachments

from the registry.
off
Does not retrieve external Web Services Policy attachments

from the registry.
A Web Service Proxy service can retrieve external attachments under

the following conditions:
v The DataPower service uses the same subscription service
v The subscription service allows the attachment of external policy
v The subscription service uses WSRR server version 6.1 or higher
393

Manually synchronizing WSRR subscriptions

When the Synchronization Method property of a WSRR Subscription object is
Manual, you need to synchronize the local copy of the subscription with the
version on the server.
You can synchronize subscriptions in the following ways:
v From the WSRR Subscription configuration screen
v From the Status object for the WSRR subscription
Synchronizing from the configuration screen

To synchronize a WSRR Subscription object from the configuration screen, perform
1. Select Objects Services WSRR Subscription to display the WSRR
2. Click the name of the WSRR Subscription to display the WSRR Subscription
configuration screen.
3. Click Synchronize.
Synchronizing from the Status object

To synchronize a WSRR Subscription object from the Status object, perform the
1. Select Status Web Service WSRR Subscription Service Status to display
the WSRR Subscription Service Status screen.
2. Click the name of the WSRR Subscription to display the WSRR Subscription
configuration screen.
3. Click Synchronize.
4. Follow the prompts
XML Manager
The firmware creates a default XML Manager object in the default domain and in
each application. The default instance in each domain can be edited like any other
instance of an XML Manager object. The default instance in each domain operates
independently of each other.
An XML Manager object obtains and manages XML documents, style sheets, and
other document resources on behalf of one or more services. An XML Manager
also provides the following capabilities:
v Basic network configuration, such as load balancing and accessing remote
servers.
v Set manager-associated limits on the parsing of XML documents. By default, the
appliance imposes limits on various characteristics of XML documents. These
limitations provide for increased security and stability to protect against DoS
attacks or runaway data. Parser limits defined by the XML Manager object that
is associated with a service can be overridden by service-specific settings.
v Enable the caching of documents that this XML Manager object obtains. XML
Manager objects obtain documents via HTTP. The number of documents in the
cache depends on the availability of allocated memory.
394
v Define extension function mapping. An XML Manager object can automatically

map custom style sheet extension functions to DataPower extension functions.
This ability removes the need to alter or rewrite a style sheet for use by the
appliance. The most common example is the node-set() extension function. If a
service uses style sheets that reference the Microsoft node-set, Oracle node-set,
or Salon nodeset XSLT extension functions, you must map these extensions to
their DataPower equivalent. It is possible to map any extension function to a
DataPower extension function.
v Define the caching policy for documents. This policy allows an administrator to
determine how to cache documents. The policy defines the time-to-live, the
priority, and the type.
v Enable schema validation by defining schema-validation rules. These rules apply
to all documents that match predefined criteria. Alternatively, the appliance can
validate documents with a validate action in a processing rule. Do not mix and
match schema validation strategies. Policy-based schema validation is the
preferred strategy.
v Schedule processing rules. Certain applications might require the running of a
scheduled processing rule. Integration with a CA Unicenter Manager is
facilitated by a regularly scheduled processing rule that obtains relationship data
from the Unicenter Manager.
Configure XML Manager objects

The specification of the name completes the required configuration. The remaining
properties modify default values or implement enhanced behavior. For information
about the configuration properties, refer to the online help.
To configure an XML Manager:
1. Select Objects XML Processing XML Manager to display the catalog.
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.
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:
395
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
v
v
v
v
Remote Address
Remote Port
SSL Proxy Profile
Client ID
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:
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.
396
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.
6. Specify the IP address or hostname of the NSS server in the Remote Address
field.
7. Specify the port on which the NSS server listens in the Remote Port field.
8. Select an SSL Proxy Profile in the SSL Proxy field to provide a secure
connection to the remote authentication server.
9. Specify the client ID to be used for registration with the NSS server in the
Client ID field.
10. Specify the system name to identify the NSS client to the NSS server in the
System Name field.
11. Specify the user name to use to authenticate with the SAF in the User Name
field.
12. Specify the password to use to authenticate with the SAF in the Password
field.
13. Reenter the password in the Confirm Password field.
397
398
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.
399
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
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
the token data.
PKIPath Binary Security Token
the token data.
Subject Key Identifier
<wsse:KeyIdentifier> element that identifies the token with the value of
the X.509 version 3 Subject Key Identifier extension for the certificate. A
400
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
X.509 Thumbprint SHA-1A
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
the token data.
Subject Key Identifier
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
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
401
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.
402

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 412.
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 412.
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.
403
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 414.
Note: Refer to List of available variables on page 415 for the list of variables that
you can define for document processing.
Service variables
Service variables enable the setting and retrieval of pieces of state that usually
reflect the state of the current transaction.
The available service variables are separated alphabetically into the following
categories:
v Service variables that are available to all DataPower services
v Service variables that are available to only Multi-Protocol Gateway and Web
Service Proxy services
v Configuration services
v Load balancer service
v Legacy MQ-specific services
General service variables

This section contains information about general variables in alphabetic order by
permission category. General variables are available to all services. Table 3 lists the
names and permission for these variables.
Table 3. Names and permissions for variables that are available to all DataPower services
Variable name
Permission
var://service/soap-fault-response
Read-write
Read-write variables
Set when the response input rule is treated as a SOAP fault.
Multi-Protocol Gateway and Web Service Proxy service

variables
This section contains information about general service variables for Multi-Protocol
Gateway and Web Service Proxy services in alphabetic order by permission
category. Table 4 lists the names and permission for these variables.
Table 4. Names and permissions for general service variables that are available to only
Multi-Protocol Gateway and Web Service Proxy services
404
Variable name
Permission
var://service/mpgw/backend-timeout
Read-write
Table 4. Names and permissions for general service variables that are available to only
Multi-Protocol Gateway and Web Service Proxy services (continued)
Variable name
Permission
var://service/mpgw/skip-backside
Write-only
var://service/reply-to-q
Write-only
var://service/reply-to-qm
Write-only
Write-only variables
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.
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.
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.
Read and write the value in the ReplyToQMgr (Reply to Queue Manager)
MQ header. When read, shows the input message value. When write,
changes the dynamic routing.
Configuration services service variables

This section contains information about variables for configuration services in
alphabetic order by permission category. Table 5 lists the names and permission for
these variables.
Table 5. Names and permissions for variables that are available for configuration services
Variable name
Permission
var://service/config-param
Write-only
var://service/max-call-depth
Read-write
var://service/config-param/parameterName value
Sets the specified stylesheet parameter to the specified value.
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.
405
Load balancer service variables

This section contains information about load balancer variables in alphabetic order
by permission category. Table 6 lists the names and permission for these variables.
Table 6. Names and permissions for variables that are available for load balancers
Variable name
Permission
var://service/lbhealth/
Write-only
var://service/lbhealth/
Sets the member and state of a load balancer group.
Legacy MQ-specific service variables

This section contains information about MQ-specific variables in alphabetic order
by permission category. MQ-specific variables are available to only the legacy MQ
Host and MQ Proxy services. Table 7 lists the names and permission for these
variables.
Table 7. Names and permissions for service variables that are available to MQ Host and
MQ Proxy services
Variable name
Permission
var://service/correlation-identifier
Read-write
var://service/expiry
Read-write
var://service/format
Read-write
var://service/message-identifier
Read-write
var://service/message-type
Read-write
var://service/mq-ccsi
Write-only
var://service/mqmd-reply-to-q
Write-only
var://service/mqmd-reply-to-qm
Write-only
var://service/persistence
Read-write
var://service/priority
Read-write
Read-write
Read-write
var://service/report
Read-write
Sets the MQ message descriptor character set for an MQ Host or MQ
Proxy service.
Sets the output MQ message descriptor.ReplyToQ value for an MQ Host
or MQ Proxy service.
Sets the output MQ message descriptor.ReplyToQMgr value for an MQ
Host or MQ Proxy service.
406
Read and write the MQ value in the Correlation Identifier header for
MQ Host and MQ Proxy services.
Read and write the MQ value in the Expiry header for MQ Host and MQ
Proxy services.
Read and write the MQ value in the Format header for MQ Host and MQ
Proxy services.
Read and write the MQ value in the Message Identifier header for MQ
Host and MQ Proxy services.
Read and write the MQ value in the Message Type header for MQ Host
and MQ Proxy services.
Read and write the MQ value in the Persistence for MQ Host and MQ
Proxy services.
Read and write the MQ value in the Priority header for MQ Host and
MQ Proxy services.
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.
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.
Read and write the MQ value in the Report header for MQ Host and MQ
Proxy services.
Multistep variables
This section contains information about system variables in alphabetic order by
permission category. Multistep variables usually impact the behavior of specific
actions in the context of a processing rule. Table 8 lists the names and permission
for these variables.
Table 8. Names and permissions for variables that are available to all services
Variable name
Permission
var://service/log/soapversion
Read-write
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.
407
Supports the following values:

soap11 Uses SOAP 1.1.
soap12 (Default) Uses SOAP 1.2.
Transaction variables
The available transaction variables are separated alphabetically into the following
categories:
v Asynchronous transactions
v Error handling
v Headers
v Persistent connections
v Routing
v URL
v Web Services Management (WSM)
Asynchronous transaction variables

This section contains information about asynchronous transaction variables in
alphabetic order by permission category. Table 9 lists the names and permission for
these variables.
Table 9. Names and permissions for variables that are available for asynchronous
transactions
Variable name
Permission
var://service/soap-oneway-mep
Read-write
var://service/transaction-key
Write-only
var://service/transaction-name
Write-only
var://service/transaction-timeout
Write-only
Sets the token for asynchronous transactions.
Sets the name for asynchronous transactions.
Sets the timeout for asynchronous transactions.
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
408
assumes that this is a one-way MEP and notifies the service layer by
setting this value of this variable to true.
This variable is not needed for Web Service Proxy services, as one-way
MEPs are identified by reviewing the specifics of the port operation.
Error handling transaction variables

This section contains information about error handling variables in alphabetic
order by permission category. Table 10 lists the names and permission for these
variables.
Table 10. Names and permissions for variables that are available for error handling
Variable name
Permission
var://service/error-code
Read-write
var://service/error-ignore
Read-write
var://service/error-message
Read-write
var://service/error-protocol-reason-phrase
Write-only
var://service/error-protocol-response
Write-only
var://service/error-subcode
Read-write
var://service/strict-error-mode
Read-write
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.
Sets the protocol-specific response for an error. This variable overwrites the
protocol-specific response code in an error condition.
Gets or sets the assigned error code from the Result Code table.
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.
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.
409
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.
Gets or sets the strict error mode. This variable controls the error mode for
multistep processing.
v If the value is set, an invocation of the dp:reject extension element
stops multistep processing.
v If the value is not set, an invocation of the dp:reject extension element
logs a message but does not stop multistep processing.
Headers transaction variables

This section contains information about header variables in alphabetic order by
permission category. Table 11 lists the names and permission for these variables.
Table 11. Names and permissions for variables that are available for headers
Variable name
Permission
var://service/append-request-header/
Write-only
var://service/append-response-header/
Write-only
var://service/set-request-header/
Write-only
var://service/set-response-header/
Write-only
var://service/append-request-header/
Appends to the protocol request header.
var://service/append-response-header/
Appends to the protocol response header.
var://service/set-request-header/
Sets the protocol request header. This variable directly correlates to the
dp:set-request-header() extension function. Setting the
var://service/set-request-header/FOO variable to the value BAR would
set the request header FOO to BAR.
var://service/set-response-header/
Sets the protocol response header. This variable directly correlates to the
dp:set-response-header() extension function. Setting the
var://service/set-response-header/FOO variable to the value BAR would
set the response header FOO to BAR.
Persistent connection transaction variables

This section contains information about persistent connection variables in
alphabetic order by permission category. Table 12 lists the names and permission
for these variables.
Table 12. Names and permissions for variables that are available for persistent connections
410
Variable name
Permission
var://service/connection/note
Read-write
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
Table 13. Names and permissions for variables that are available for routing
Variable name
Permission
var://service/routing-url
Write-only
var://service/routing-url-sslprofile
Write-only
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.
Sets the SSL proxy profile for the routing URL (dynamic route). Use this
variable when the ssl property for the DataPower service is not sufficient
for the route to be selected. Use this variable before using the
var://service/routing-url variable.
URL-based transaction variables

This section contains information about URL-based transaction variables in
alphabetic order by permission category. Table 14 on page 412 lists the names and
permission for these variables.
411
Table 14. 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
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 15 lists the names and
permission for these variables.
Table 15. Names and permissions for variables that are available to WSM
Variable name
Permission
var://service/wsa/timeout
Read-write
var://service/wsa/genpattern
Read-write
var://service/wsm/wsdl-error
Write-only
var://service/wsm/wsdl-warning
Write-only
Sets the WSDL error.
Sets the WSDL warning.
Gets or sets the timeout value for the WS-Addressing asynchronous reply.
Gets or sets the pattern for the WS-Addressing asynchronous reply.
Extension variables
permission category. Extension variables usually impact the behavior of specific
actions, particularly fetch, results, and results-async actions. Table 16 lists the
names and permission for these variables.
Table 16. Names and permissions for extension variables
412
Variable name
Permission
var://local/_extension/allow-compression
Write-only
var://local/_extension/donot-follow-redirect
Write-only
var://local/_extension/header/
Write-only
Table 16. 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
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.
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"
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.
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:
413
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
Table 17. Names and permissions for system variables
Variable name
Permission
var://system/map/debug
Read-write
var://system/tasktemplates/debug
Read-write
Gets or sets the debugging level for role-based management (RBM).
Gets or sets the debugging level for task templates.
414
List of available variables

Table 18 lists the variables that you can define for document processing.
Table 18. All available variables
Short variable name
Full variable name
Category
allow-compression
Extension
append-request-header
var://service/append-request-header
Transaction,
headers
append-response-header
var://service/append-response-header
Transaction,
headers
backend-timeout
Service, general
config-param
var://service/config-param
Service,
configuration
correlation-identifier
Service, MQ
debug
System
donot-follow-redirect
Extension
error-code
Transaction, error
handling
error-ignore
Transaction, error
handling
error-message
Transaction, error
handling
error-protocol-reason-phrase
Transaction, error
handling
error-protocol-response
Transaction, error
handling
error-subcode
Transaction, error
handling
expiry
Service, MQ
format
Service, MQ
genpattern
Transaction, WSM
header
var://local/_extension/header
Extension
http-10-only
Extension
lbhealth
var://service/lbhealth
Service, load
balancer
max-call-depth
Service,
configuration
message-identifier
Service, MQ
message-type
Service, MQ
mq-ccsi
Service, MQ
mqmd-reply-to-q
Service, MQ
mqmd-reply-to-qm
Service, MQ
note
Transaction,
persistent
connection
415
Table 18. All available variables (continued)

Short variable name
Full variable name
Category
persistence
Service, MQ
prevent-persistent-connection
var://local/_extension/prevent-persistentconnection
Extension
priority
Service, MQ
reply-to-q
Service, MQ
reply-to-qm
Service, MQ
report
Service, MQ
routing-url
Transaction,
routing
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
Service, general
soap-fault-response
Service, general
soap-oneway-mep
Transaction,
asynchronous
soapversion
Service, multistep
sslprofile
Extension
strict-error-mode
Transaction, error
handling
timeout
Transaction, WSM
transaction-key
Transaction,
asynchronous
transaction-name
Transaction,
asynchronous
transaction-timeout
Transaction,
asynchronous
URI
var://service/URI
Transaction, URL
wsdl-error
Transaction, WSM
wsdl-warning
Transaction, WSM
416
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 418
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.
417
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.
418
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.
419
Other company, product, and service names may be trademarks or service marks
of others.
420
Index
Special characters
?wsdl URI 68
... button
list of referenced object 3
referenced object 2
.java.policy file 209
[configuration-database] stanza, file
entry 272
[ldap] stanza, ssl-keyfile-pwd entry 272
[manager] stanza, replica entry 272
<results> element 168
<url> element 168
+ button
referenced object 2
A
AAA
authentication
search parameters 286
TFIM 274
aaa action
dictionary attack, protection 64
purpose 100
AAA action
defining 106
AAA Info file
Authenticate element 268
Authorize element 268
editor
authenticated identities 269
authorized access to
resources 271
confirmation 271
credentials 269
default credential 268
file information 271
map credentials 270
map resources 270
overview 268
unauthenticated identity 268
MapCredentials element 268
MapResource element 268
overview 267
AAA Info File
authentication 185
authorization, AAA 199
credentials mapping, AAA 187
resources mapping, AAA 191
AAA Policy
AAA Info file
Authenticate element 268
Authorize element 268
MapCredentials element 268
MapResource element 268
overview 267
authentication
AAA info file 185
AAA Policy (continued)

authentication (continued)
BinarySecurityToken 184
ClearTrust 183
custom 184
Kerberos AP-REQ 185
LDAP 180
LTPA token 179
Netegrity 183
none 184
RADIUS 185
SAML assertion, artifact 184
SAML assertion, valid
signature 179
SAML assertions, remote 401
SAML server 181
signer certificate 185
SSL certificate, connection
peer 186
TAM 184
context 184
WS-Trust server 182
X.509 certificates, remote 400
z/OS NSS authentication 183
authorization
AAA Info File 199
always 192
any authenticated 192
ClearTrust 193
custom 193
LDAP 193
Netegrity 193
SAML attribute from
authentication 197
SAML attribute query 195
SAML authorization query 195
TAM 192
XACML PDP 198
z/OS NSS authorization 193
changing authentication caching
policy 188
changing authorization caching
policy 199
configuring 171
creating 172
credentials mapping
AAA Info file 187
custom 186
from identity extraction 187
none 187
TFIM 187
WS-SecureConversation 187
defining authentication method 179
defining authorization method 192
defining identity extraction
method 173
defining resource extraction
methods 188
file editor
authenticated identities 269

file editor (continued)
authorized access to
resources 271
confirmation 271
credentials 269
default credential 268
file information 271
map credentials 270
map resources 270
overview 268
unauthenticated identity 268
identity extraction
BinarySecurityToken, WS-Security
Header 174
client IP address 177
custom 179
derived-key UsernameToken,
WS-Security Header 174
extracted token, cookie value 178
extracted token, message 178
HTTP Authentication Header 173
Kerberos AP-REQ, SPNEGO 175
Kerberos AP-REQ, WS-Security
Header 175
LTPA token 178
name, SAML
AttributeStatement 176
name, SAML authentication
assertion 176
password-carrying
UsernameToken, WS-Security
Header 173
Processing Metadata 178
SAML artifact 177
subject DN, certificate in message
signature 177
Token Subject DN (SSL),
connection peer 176
Identifier 174
WS-Trust Base 175
WS-Trust Supporting 175
LTPA, adding user attributes 266
mapping authentication
credentials 186
mapping resources 190
namespace mappings
XPath bindings 266
object pages
Authenticate 248
Authorize 257
creating 243
Identity 246
LTPA Attributes 265
Main 243
Map Credentials 254
Map Resource 256
Namespace Mapping 264
421

object pages (continued)
Post Processing 263
Resource 255
SAML Attributes 264
Transaction Priority 265
post processing
Authorized Counter 200
available activities 201
CICS Transaction Server 204
Count Monitors 200
custom style sheet 201
ICRX token 204
Kerberos AP-REQ 202
logging access attempts 200
LTPA 203
Rejected Counter 200
SAML assertion 201
SPNEGO 203
TFIM 203
WS-Security UsernameToken 203
WS-Trust 202
z/OS identity propagation 204
resource extraction
HTTP operations 189
local name of request element 189
URI of top-level element 188
URL from client 188
URL to backend 188
XPath from request 189
resources mapping
AAA Info File 191
custom 190
none 190
TAM 190
TFIM 190
XPath from resource
extraction 191
SAML attributes
defining 266
z/OS NSS Client 396
AAAInfo.xsd file 267
Accept-Encoding header, retaining 344
accepted configuration
deployment policy 226
actions
aaa
purpose 100
AAA
defining 106
antivirus
defining 106
purpose 100
call
defining 108
defining reusable rules 165
purpose 100, 168
checkpoint
defining 109
purpose 100
conditional
defining 109
purpose 100
contexts
input 104
output 104
422
actions (continued)
convert-http
defining 110
purpose 101
cryptobin
defining 111
purpose 101
decrypt
defining 119
Encrypted tokens 399
purpose 101
defining 106
encrypt
defining 121
ID references 399
purpose 101
SOAP message with
WS-Security 121
SOAP message with XML
encryption 130
XML message with XML
encryption 132
event-sink 134
purpose 101
extract
defining 135
purpose 101
fetch
attachment protocol 167
defining 135
locating remote resources 165
purpose 101
query parameters 167
specifying remote locations 166
filter
conformance filter 138
defining 136
purpose 101
replay filter 137
required elements filter 137
standard filter 136
WS-Security message layout
filter 138
for-each 139
purpose 101
for-each action
specifying multiple URLs 166
log
defining 142
purpose 102
method rewrite
defining 150
MQ Header
modifying reply queue 145
modifying reply queue
manager 146
modifying request message
headers 143
modifying response message
headers 144
overview 142
retrieving responses with
correlation ID 144
actions (continued)
MQ Header (continued)
retrieving responses with message
ID 144
on-error
defining 146
purpose 102
variable builder 168
purpose 100
results
defining 148
purpose 102
results-async
defining 149
purpose 102
rewrite header
purpose 102
rewrite header (rewrite)
defining 150
rewrite method
purpose 102
route-action
defining with style sheet 151
defining with XPath
expression 151
purpose 102
route-set
defining 152
purpose 102
specifying remote location 166
setvar
defining 152
purpose 103
sign
defining 153
generating signature
confirmation 402
ID references 399
purpose 103
verifying signature
confirmation 402
slm
defining 155
purpose 103
sql
defining 155
purpose 103
strip-attachments
defining 156
purpose 103
supported protocols 165
validate 162
purpose 103
actions (continued)
verify
adding 164
confirmation 402
Kerberos AP-REQ tokens,
remote 401
purpose 103, 164
verifying signature
confirmation 402
xform
defining 157
defining buffer attachment
transform 161
defining conformance
transform 161
defining SOAP refinement
transform 159
purpose 103
xformbin
defining 157
purpose 103
xformpi
defining 158
purpose 103
Add button
admin account
exporting configuration data 215
Administration menu 1
administrative states, objects 6
allow compression policy, user
agent 343
antivirus (antivirus) action
defining 106
antivirus action
purpose 100
AP-REQ message, Kerberos 276
appliance configuration
backing up 215, 216
comparing 224
configuration checkpoints 220
copying
files 219
objects 219
exporting 215
select objects and files 217
importing configuration 222
managing configuration changes 224
moving
files 219
objects 219
reading change report 225
reverting changes 225
undoing changes 225
appliance-wide log
location 205
application domains
backing up configuration 216
Apply button 4
asymmetric signatures
verifying 164
asynchronous transaction variables
service/transaction-timeout 408
asynchronous transactions variables

listing 408
service/transaction-key 408
service/transaction-name 408
asynchronous variables
service/soap-oneway-mep 408
attachment protocol
actions 167
attachments
buffering transform 161
Attachments Profile 1.0
Conformance Policy 281
audit log
location 205
viewing 205
audit: directory 205
Authenticate element, AAA Info file 268
authentication
LDAP 286
authentication caching policy,
changing 188
authentication policy
user agent
basic 342
public key 343
SCP protocol 343
SFTP protocol 343
authentication, AAA
AAA info file 185
available methods 179
ClearTrust 183
connection peer
SSL certificate 186
custom 184
Kerberos AP-REQ 185
LDAP 180
LTPA token 179
Netegrity 183
none 184
RADIUS 185
SAML assertion
artifact 184
valid signature 179
SAML server 181
signer certificate 185
TAM 184
WS-SecureConversation context 184
WS-Trust server 182
z/OS NSS authentication 183
authorization caching policy,
changing 199
Authorization header, HTTP 342
authorization, AAA
AAA Info File 199
always 192
any authenticated 192
ClearTrust 193
custom 193
LDAP 193
Netegrity 193
authorization, AAA (continued)

SAML attribute from
authentication 197
SAML attribute query 195
SAML authorization query 195
TAM 192
XACML PDP 198
z/OS NSS authorization 193
Authorize element, AAA Info file 268
auto-config.cfg file 4
B
backend-timeout variable 405
basic configuration
MQ Front Side Handler 88
Basic Profile 1.0
Basic Profile 1.1
Basic Security Profile 1.0
BinarySecurityToken
authentication, AAA 184
identity extraction, AAA 174
binding
Web Service Proxy 33
bold typeface xii
buffer-attachments.xsl style sheet 161
builder
buttons
... 2
+ 2
Apply 4
Cancel 4
Delete 5
Edit 3
Logout 1
Save Config 1, 4
Undo 5
View 3
C
CA Unicenter Manager 394
caches
flushing
document cache 395
stylesheet cache 396
caching policy
AAA Policy
authentication 188
authorization 199
call action
defining 108
purpose 100
call processing rule (call) action
call processing rule action
See call action
Cancel button 4
cert: directory 205
certificate files
location 205
Index
423
Certificate objects
export packages 215
certificates
DER 9
exporting 11
generating 10
importing 12
PEM 9
PKCS #12 9
PKCS #8 9
security
location, shared 206
location, Web browsers 206
supported formats 9
uploading 209
checkpoint action
purpose 100
checkpoint configuration files
location 205
checkpoint event (checkpoint) action
defining 109
chkpoints: directory 205
clear pdp cache CLI 280
clear xsl cache CLI 280
ClearTrust
client-to-server rule 100
Clone link 6
commands
clear pdp cache 280
clear xsl cache 280
web-mgmt 1
Compile Options Policy
object pages 284
compression policy, user agent 343
conditional action
defining 109
purpose 100
config: directory 205
configuration
managing appliance
configuration 213
configuration checkpoints
defining number to allow 220
deleting 222
listing 221
loading 222
overwriting 221
rolling back 222
saving 221
configuration data
applying 4
backing up
WebGUI 215, 216
backing up application domains 216
comparing
WebGUI 224
configuration checkpoints 220
copying
files 219
objects 219
different release level 215
exchanging 215
exporting
location of files 205
424
configuration data (continued)

exporting (continued)
select objects and files 217
WebGUI 215
files not included 215
importing
WebGUI 215, 222
managing changes 224
moving
files 219
objects 219
objects not included 215
reading change report 225
reading changes 225
saving 4
undoing changes 225
configuration files
exported, location 205
location 205
TAM
ASCII 272
creating 273
modifying 272
obfuscated 272
configuration service variables
listing 405
service/config-param/ 405
service/max-call-depth 405
configuration states, objects 6
Conformance Policy
filter actions 281
object pages 281
WS-I Attachments Profile 281
WS-I Basic Profile 281
WS-I Basic Security Profile 281
conformance transform 161
conformance-filter.xsl style sheet 138
conformance-xform.xsl style sheet 161
Content-Length header 345
contexts
actions
input 104
output 104
keywords
INPUT 104
NULL 104
OUTPUT 104
PIPE 104
processing policies 104
processing rules 104
Control Panel
File Management 207
convert query parameters to XML
(convert-http) action
defining 110
convert query parameters to XML action
See convert-http action
convert-http action
defining 110
purpose 101
Count Monitor
post processing, AAA 200
count monitors
configuring 234
Count Monitors
credentials
identification
configuring 15
creating 15
credentials mapping
LDAP 286
credentials mapping, AAA
AAA Info file 187
custom 186
from identity extraction 187
none 187
TFIM 187
WS-SecureConversation 187
crypto binary (cryptobin) action
defining 111
crypto binary action
See cryptobin action
Crypto Certificate
configuring 13
creating 13
object pages 13
Crypto Firewall Credentials
object pages 15
Crypto Identification Credentials
object pages 15
Crypto Key
configuring 16
creating 16
object pages 16
Crypto Profile
configuring 18
creating 18
object pages 18
Crypto Tools
exporting certificates 11
exporting keys 11
generating certificates 10
generating keys 10
importing certificates 12
importing keys 12
Crypto Validation Credentials
object pages 22
cryptobin action
defining 111
purpose 101
cryptography
shared secrets 20
customer support
contacting 418
obtaining fixes 417
searching knowledge bases 417
D
dashboard 1
DataPower discussion forum xi
DataPower product Web site xi
debugging
decrypt action
defining 119
decrypt action (continued)

purpose 101
decrypt.xsl file 120
default log
location 205
Delete button 5
denial-of-service, protection
multiple message (MMXDoS) 61
single message (XDoS) 60
deployment policy
accepted configuration 226
creating 226
filtered configuration 226
modified configuration 226
using the builder 227
Deployment Policy
object pages 226
deployment policy builder
creating matching statements 227
DER
certificate format 9
key format 9
developerWorks Web site xi
directories
audit: 205
available 205
cert: 205
chkpoints: 205
config: 205
displaying contents 207
dpcert: 205
export: 205
hiding contents 207
image: 205
local: 205
logstore: 205
logtemp: 205
managing 205
pubcert: 206
refreshing contents 208
sharedcert: 206
store: 206
tasktemplates: 207
temporary: 207
disabled administrative state 6
discussion forum, DataPower xi
Document Crypto Map
object pages
Main 285
Namespace Mappings 285
documentation conventions,
typefaces xii
Domain list 1
down operation state 6
dpcert: directory 205
dpmq protocol 165
dptibems protocol 165
dpwasjms protocol 165
dpwasjmss protocol 165
DSA signatures
verifying 164
duration monitors
configuring 236
Duration Monitors
Web Service Proxy
Dynamic Endpoints
Web Service Proxy
357
358
E
Edit button 3
elements
EncryptedData element 399
SecurityTokenReference 400
SignatureConfirmation 401
enabled administrative state 6
encoding, chunked content 345
encrypt action
defining 121
ID references 399
purpose 101
SOAP message with WS-Security 121
SOAP message with XML
encryption 130
XML message with XML
encryption 132
encrypt-soap.xsl file 130
encrypt-wssec.xsl file 121
encrypt.xsl file 132
encrypted tokens
Endpoint Rewrite Policy
description 375
error code rule 99
error handling variables
listing 409
service/error-code 409
service/error-ignore 409
service/error-message 409
service/error-protocol-reasonphrase 409
service/error-protocol-response 409
service/error-subcode 409
service/strict-error-mode 410
error rule 100
event-sink action
defining event-sink 134
purpose 101
examples
specifying dual thresholds 240
Export link 5
export packages
admin account 215
files not included 215
objects not included 215
permission 215
export: directory 205
Extensible Access Control Markup
Language
See XACML PDP
extension functions
node-set() 394
set-target() 151
xs:decimal() 284
extension variables
listing 412
local/_extension/allowcompression 413
extension variables (continued)

local/_extension/donot-followredirect 413
local/_extension/header/ 413
local/_extension/http-10-only 413
local/_extension/prevent-persistentconnection 413
local/_extension/sslprofile 413
local/_extension/timeout 414
external resources, accessing xi
extract action
defining 135
purpose 101
extract using XPath (extract) action
defining 135
extract using XPath action
See extract action
F
fault-tolerance
TIBCO EMS 324, 328
fetch action
defining 135
purpose 101
file entry, [configuration-database]
stanza 272
File Management utility, launching 207
file system
See directories
files
.java.policy 209
AAAInfo.xsd 267
auto-config.cfg 4
certificates
location 205
checkpoint configurations
location 205
configurations
location 205
copying 210
remote URL 210
decrypt.xsl 120
deleting 212
editing
during configuration 4
File Management utility 212
encrypt-soap.xsl 130
encrypt-wssec.xsl 121
encrypt.xsl 132
exported, location 205
fetching 210
managing 205
moving 211
not in export packages
firmware files 215
log files 215
pkcs7-decrypt.xsl 118
pkcs7-encrypt.xsl 116
pkcs7-sign.xsl 112
pkcs7-verify.xsl 114
Index
425
files (continued)
private keys
location 205
renaming 211
SQL-Injection-Filter.xsl 62
SQL-Injection-Patterns.xml 62
TAM
ASCII configuration 272
creating configuration 273
modifying configuration 272
obfuscated configuration 272
SSL key 272
SSL stash 272
tibco.conf 330
uploading
JKS 209
remote 210
workstation 208
viewing
during configuration 4
File Management utility 212
filter action
defining 136
purpose 101
replay filter 137
required elements filter 137
SQL injections, protection 62
standard filter 136
WS-Security message layout
filter 138
filter-accept-all.xsl style sheet 136
filter-reject-all.xsl style sheet 136
filtered configuration
Firewall Credentials
configuring 15
creating 15
firmware files
between release levels 215
export packages 215
firmware images
location 205
fixes, obtaining 417
flash drive
See directories
for-each
purpose 101
for-each action
defining for-each 139
use cases 139
Front Side Handler
object pages
FTP Poller 69
FTP Server 72
HTTP 83
HTTPS 85
IMS Connect 86
MQ 87
NFS Poller 90
Stateful Raw XML 93
Stateless Raw XML 94
TIBCO EMS 95
WebSphere JMS 97
426
FTP client
command channel
encrypting 346
stopping encryption after
authentication 346
data (ASCII, binary) 346
encrypting file transfers 346
NAT compatibility 346
passive mode 346
sending command to server 346
unique file names (STOU, STOR) 346
user agent 346
FTP Poller
Front Side Handler 69
ftp protocol 165
FTP Server
Front Side Handler 72
G
general variables
listing 404
service/soap-fault-response
GET requests
WSDL file 68
404
H
HEAD requests
WSDL file 68
header injection policy, user agent 345
header retention policy, user agent 344
heartbeat detection, TIBCO 330
HMAC signatures
verifying 164
HTTP 1.0 restriction policy, user
agent 344
HTTP 1.1
chunked contents 345
Content-Length header 345
HTTP Front Side Handler 83
HTTP header
HTTP Header Injection
HTTP header matching rule 99
HTTP header parameters
Web Service Proxy
configuring 46
injection parameters 46
suppression parameters 47
HTTP Header Suppression
HTTP headers
Accept-Encoding, retaining 344
Authorization 342
Content-Length 345
MQMD, retaining 344
Range, retaining 344
request-header 340
SoapAction 342
TE, retaining 344
HTTP method matching rule 99
HTTP operations
resource extraction, AAA 189
HTTP Options
http protocol 165
HTTP proxy policy
securing with SSL proxy policy
user agent 341
HTTPS Front Side Handler 85
https protocol 165
341
I
IBM Tivoli Access Manager
See TAM
IBM Tivoli Federated Identity Manager
See TFIM
ICRX token 204
ID references
encrypt action 399
sign action 399
Identification Credentials
configuring 15
creating 15
identity extraction
AAA
BinarySecurityToken, WS-Security
Header 174
identity extraction, AAA
client IP address 177
connection peer
Token Subject DN, SSL 176
custom 179
extracted token
as cookie value 178
from message 178
HTTP Authentication Header 173
LTPA token 178
SAML artifact 177
SAML assertion
AuthenticationStatement 176
SPNEGO
Kerberos AP-REQ 175
subject DN
certificate in message
signature 177
SSL certificate 176
Identifier 174
WS-Security Header
Kerberos AP-REQ 175
UsernameToken, derived-key 174
UsernameToken,
password-carrying 173
WS-Trust
Base 175
Supporting 175
image: directory 205
Import Package
creating 214
IMS Connect
object pages
Main 287
URL builder 64
Kerberos keytab
configuring 278
definition 276
Kerberos Keytab File
object pages 278
Key Distribution Center
See KDC
Key objects
export packages 215
key-certificate pairs
creating 9
keys
DER 9
exporting 11
generating 10
importing 12
PEM 9
PKCS #12 9
PKCS #7 9
supported formats 9
keywords
contexts
INPUT 104
NULL 104
OUTPUT 104
PIPE 104
knowledge bases
searching 417
IMS Connect Handler 86

ims protocol 165
imsssl protocol 165
Include Configuration File
creating 213
object pages 213
input context, actions 104
INPUT keyword 104
installation images
See firmware images
intellectual property 419
intermediary service provider,
SOAP 159
italics typeface xii
J
J2RE (j2re1.4.2) 209
j2re1.4.2 (J2RE) 209
j2sdk1.4.2 (SDK) 209
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 209
JCE
See SunJCE
JCEKS 209
JetStream Formats and Protocols
See JFAP
JKS
crypto extension 209
granting permissions 209
java.security package 209
keytool utility 209
managing 209
required software 209
uploading certificates 209
working with 209
K
KDC, Kerberos 276
Kerberos
AP-REQ message 276
configuring KDC server 277
KDC 276
keytab 276
principal 276
signature verification 164
Kerberos AP-REQ
SPNEGO 175
WS-Security Header 175
verify action 401
Kerberos AP-REQ tokens, remote
Kerberos KDC server
configuring 277
creating 277
object pages 277
401
LDAP
authentication
credentials mapping
licensing
sending inquiries 419
links
Clone 6
Export 5
Show Probe 7
View Logs 5
View Status 6
load balancer group
adding members 297
basic configuration 297
creating 289, 296
health
convalescent (down) 294
healthy (up) 294
quarantined (softdown) 294
health checks
enabling 299
overriding port 297
health of members 294
members
assigning weight 300
disabling members 301
server state 289
Load Balancer Group
example
DataPower service 67
replacing back-end server 67
load balancer service variables

listing 406
service/lbhealth/ 406
load-balancing
TIBCO EMS 326, 328
local: directory 205
local/_extension/allow-compression
variable 413
local/_extension/donot-follow-redirect
variable 413
local/_extension/header/ variable 413
local/_extension/http-10-only
variable 413
local/_extension/prevent-persistentconnection variable 413
local/_extension/sslprofile variable 413
local/_extension/timeout variable 414
log action
defining 142
purpose 102
log files
export packages 215
log/soapversion variable 407
logging
post processing, AAA
access attempts 200
Logout button 1
logs
appliance-wide
location 205
audit
location 205
viewing 205
default
location 205
viewing configuration-specific logs 5
viewing from catalog 5
viewing from configuration pane 5
logstore: directory 205
logtemp: directory 205
LTPA
adding user attributes, AAA
Policy 266
M
map message
TIBCO EMS 95
MapCredentials element, AAA Info
file 268
MapResource element, AAA Info
file 268
Matching Rule
object pages 304
matching rules
error code 99
HTTP header 99
HTTP method 99
URL 99
XPath 99
Index
427
matching statements
deployment policy builder 227
deployment policy, manual 228
message catalogs 206
message layout filter, WS-Security 138
message monitors
configuring 230
count monitors 234
duration monitors 236
filter action 233
message type 233
traffic definition 231
messages
validating conformance 281
method rewrite action
defining 150
MMXDoS, protection 61
modified configuration
Modified configuration state 6
monitoring statistics, enabling 238
monitors
count monitors
configuring 234
duration monitors
configuring 236
message monitors
configuring 230
count monitors 234
duration monitors 236
filter action 233
message type 233
traffic definition 231
types 229
configuring 238
enabling 238
overview 238
monospaced typeface xii
MQ
URL builder 65
advanced configuration 90
basic configuration 88
configuration 87
properties and headers
configuration 89
publish and subscribe
configuration 89
MQ Get Message Options (GMO)
MQGET options 88
MQGMO_* 88
MQ header action
modifying
reply queue 145
reply queue manager 146
request message headers 143
response message headers 144
overview 142
retrieving responses
with correlation ID 144
with message ID 144
MQ Host variables
listing 406
service/correlation-identifier 407
428
MQ Host variables (continued)

service/expiry 407
service/format 407
service/message-identifier 407
service/message-type 407
service/mq-ccsi 406
service/mqmd-reply-to-q 406
service/mqmd-reply-to-qm 406
service/persistence 407
service/priority 407
service/reply-to-q 407
service/reply-to-qm 407
service/report 407
mq protocol 165
MQ Proxy variables
listing 406
service/expiry 407
service/format 407
service/mq-ccsi 406
service/report 407
MQ request messages
modifying message headers 143
specifying correlation ID 144
specifying message ID 144
MQ response messages
modifying headers 144
modifying reply queue 145
modifying reply queue manager 146
MQMD header, retaining 344
Multi-Protocol Gateway
service variables
backend-timeout 405
skip-backside 405
multistep variables
log/soapversion 407
multistep/loop-count service
variable 141
multistep/loop-iterator service
variable 141
N
namespace mappings, AAA Policy
NAT
FTP clients 346
navigation
Network menu 1
Objects menu 1
Services menu 1
Status menu 1
Netegrity
Network Address Translation
See NAT
266
Network menu 1
New configuration state 6
NFS Poller Front Side Handler 90
node-set() extension function 394
notices 419
NULL keyword 104
O
object pages
AAA Policy
Authenticate 248
Authorize 257
Identity 246
LTPA Attributes 265
Main 243
Map Credentials 254
Map Resource 256
Namespace Mapping 264
Post Processing 263
Resource 255
SAML Attributes 264
Transaction Priority 265
Compile Options Policy 284
Crypto Certificate 13
Crypto Firewall Credentials 15
Crypto Identification Credentials 15
Crypto Key 16
Crypto Profile 18
Crypto Validation Credentials 22
Deployment Policy 226
Document Crypto Map
Main 285
Namespace Mappings 285
Front Side Handler
FTP Poller 69
FTP Server 72
HTTP 83
HTTPS 85
IMS Connect 86
MQ 87
NFS Poller 90
Stateful Raw XML 93
Stateless Raw XML 94
TIBCO EMS 95
WebSphere JMS 97
IMS Connect
Main 287
Include Configuration File 213
Kerberos KDC server 277
Kerberos Keytab File 278
Matching Rule 304
Processing Metadata
Main 305
Metadata Items 305
Processing Policy
Main 306
Policy Maps 307
Processing Rule 307
Main 308
Rules 309
SLM Action 312
SLM Credentials Class 311
SLM Resource Class 312
SLM Schedule 313
object pages (continued)

Main 314
SOAP Header Refine
Instruction 314
SSL Proxy Profile 20
TAM 273
TFIM 274
TIBCO EMS 316
UDDI Registry 332
UDDI Subscription 333
URL Map
Main 335
URL Map Rule 335
URL Rewrite Policy
Main 335
URL Rewrite Rule 336
Web Service Proxy
Dynamic Endpoints 358
HTTP Header Injection 365
HTTP Header Suppression 365
HTTP Options 355
Main 348
Monitors 357
Operation Conformance
Policy 371
Operation Policy Subject Opt
Out 372
Operation Priority 369
Parser Limits 356
Policy Parameters 373
Proxy Settings 350
Reliable Messaging 374
Stylesheet Parameter 366
User Policy 367
WS-Addressing 357
WS-ReliableMessaging 359
WSDL Cache Policy 366
WSDL File 367
WSRR Subscription 369
WebSphere JMS server 383
Local Rewrite Rules 376
Main 376
Publish Rewrite Rule 379
Remote Rewrite Rule 378
Subscription Local Rewrite
Rule 380
Subscription Publish Rewrite
Rule 382
Subscription Remote Rewrite
Rule 381
WSRR Server 391
XACML PDP 279
XML Manager 394
objects
administrative state 6
configuration state 6
not in export packages
Certificate 215
Key 215
User 215
operational state 6
referenced
... button 2
objects (continued)
referenced (continued)
+ button 2
creating 2
modifying 2
selecting 2
status 6
TFIM 274
Objects menu 1
on-error
on-error action
defining 146
purpose 102
Operation Priority
operational states, objects 6
output context, actions 104
OUTPUT keyword 104
P
parameters, HTTP header
Web Service Proxy
configuring 46
parameters, style sheets
Web Service Proxy
defining 47
Parser Limits
patents 419
peer group
defining 313
PEM
key format 9
persistent connections variables
listing 410
service/connection/note 411
PIPE keyword 104
PKCS #12
key format 9
PKCS #7
decrypting documents 118
encrypting documents 116
signing documents 111
verifying signed documents 114
PKCS #8
key format 9
pkcs7-decrypt.xsl file 118
pkcs7-encrypt.xsl file 116
pkcs7-sign.xsl file 112
pkcs7-verify.xsl file 114
Policy Decision Point
See XACML PDP
portType
post processing, AAA
available activities 201
Count Monitors 200
post processing, AAA (continued)

custom style sheet 201
ICRX token 204
Kerberos AP-REQ 202
logging access attempts 200
LTPA 203
SAML assertion 201
SPNEGO 203
TFIM 203
WS-Security UsernameToken 203
WS-Trust 202
z/OS identity propagation 204
principal, Kerberos 276
private key files
location 205
private keys
uploading 209
Processing Metadata
object pages
Main 305
Metadata Items 305
resource extraction, AAA 189
processing policies
contexts 104
creating 105
debugging 169
defining 99
matching rules 99
processing rules 100
Processing Policy
object pages
Main 306
Policy Maps 307
Processing Rule
object pages 307
processing rules
client-to-server 100
contexts 104
direction 100
error 100
server-to-client 100
two way 100
product documentation Web site xi
product Web site, DataPower xi
protocol threats, protection 62
protocols
supported 165
Proxy Settings
advanced 43
basic 41
pubcert: directory 206
publish
Q
query parameters
actions 167
queues
TIBCO EMS 94
WebSphere JMS 96
Index
429
R
RADIUS
Range header, retaining 344
Redbooks Web site xi
referenced objects
... button 2
+ button 2
creating 2
modifying 2
selecting 2
referenced objects, lists
... button 3
+ button 3
Add button 3
adding 3
creating 3
Delete button 3
deleting 3
modifying 3
selecting 3
registry objects
UDDI Registry
configuring 332
Rejected Counter Tool 200
replay filter 137
replay-filter.xsl style sheet 137
replica entry, [manager] stanza 272
request-header, HTTP 340
required-elements-filter.xsl style
sheet 137
resource extraction, AAA
HTTP operations 189
local name of request element 189
URI of top-level element 188
URL from client 188
URL to backend 188
XPath from request 189
resources mapping, AAA
AAA Info File 191
custom 190
none 190
TAM 190
TFIM 190
XPath from resource extraction 191
restriction policy for HTTP 1.0, user
agent 344
results action
<url> element 168
defining 148
purpose 102
results asynchronous action
See results-async action
results-async
defining 149
results-async action
<url> element 168
430
results-async action (continued)

purpose 102
rewrite header (rewrite) action
defining 150
rewrite header action
See also rewrite header action
purpose 102
rewrite method action
See also rewrite method action
purpose 102
RFC 2616 345
route action
overview 151
with style sheet 151
with variables 152
with XPath expression 151
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 151
with XPath expression 151
purpose 102
route-set action 166
defining 152
purpose 102
RSA signatures
verifying 164
S
S11:actor SOAP attribute 159
S11:mustUnderstand SOAP attribute 159
S12:mustUnderstand SOAP attribute 159
S12:notUnderstood SOAP attribute 159
S12:relay SOAP attribute 159
S12:role SOAP attribute 159
SAML assertion
authentication, AAA
artifact 184
valid signature 179
AuthenticationStatement 176
SAML assertions 401
AAA Policy
authentication 401
identity extraction 401
verify action 401
SAML attributes
defining, AAA Policy 266
SAML server
authorization, AAA
attribute query 195
authorization query 195
Save Config button 1, 4

Saved configuration state 6
object pages
Main 308
Rules 309
schemas
location 206
SCP protocol
authentication policy, user agent 343
public keys 343
SDK (j2sdk1.4.2) 209
search parameters, LDAP 286
security certificates
shared
location 206
Web browsers
location 206
Security Token Reference
See STR
SecurityContextToken, WS-Trust
SecurityTokenReference element 400
server pool
See load balancer group
server state
load balancer group 289
server-to-client rule 100
service level monitors
See SLM
Service Monitors
service variables
listing 404
multistep/loop-count 141
multistep/loop-iterator 141
types 404
service/append-request-header/
variable 410
service/append-response-header/
variable 410
service/config-param/ variable 405
service/connection/note variable 411
service/correlation-identifier
variable 407
service/error-code variable 409
service/error-ignore variable 409
service/error-message variable 409
service/error-protocol-reason-phrase
variable 409
service/error-protocol-response
variable 409
service/error-subcode variable 409
service/expiry variable 407
service/format variable 407
service/lbhealth/ variable 406
service/max-call-depth variable 405
service/message-identifier variable 407
service/message-type variable 407
service/mq-ccsi variable 406
service/mqmd-reply-to-q variable 406
service/mqmd-reply-to-qm variable 406
service/persistence variable 407
service/priority variable 407
service/protocol-method variable 412
service/reply-to-q variable 405, 407
service/reply-to-qm variable 405, 407
service/report variable 407

service/routing-url variable 411
service/routing-url-sslprofile
variable 411
service/set-request-header/ variable 410
service/set-response-header/
variable 410
service/soap-fault-response variable 404
service/soap-oneway-mep variable 408
service/strict-error-mode variable 410
service/transaction-key variable 408
service/transaction-name variable 408
service/transaction-timeout variable 408
service/URI variable 412
service/wsa/genpattern variable 412
service/wsa/timeout variable 412
service/wsm/wsdl-error variable 412
service/wsm/wsdl-warning
variable 412
Services
Services menu 1
set variable (setvar) action
defining 152
set variable action
See setvar action
set-target() extension function 151
setvar action
<url> element 168
defining 152
purpose 103
SFTP protocol
authentication policy, user agent 343
public keys 343
Shared Secret Key
configuring 20
creating 20
shared secrets 20
sharedcert: directory 206
Show Probe link 7
sign action
defining 153
confirmation 402
ID references 399
purpose 103
verifying signature confirmation 402
signature confirmation 401
SignatureConfirmation element 401
signatures
verifying 164
signed documents, PKCS #7
decrypting 118
encrypting 116
signing 111
verifying 114
skip-backside variable 405
SLM
overview 309
slm action
defining 155
purpose 103
SLM action
See slm action
SLM Action
creating 312
object pages 312
SLM Credentials Class
creating 311
object pages 311
SLM Peer Group
SLM policy
adding statements 310
creating 310
creating SLM actions 312
SLM Policy
creating SLM Credentials Class
objects 311
creating SLM Resource Class
objects 312
creating SLM schedules 313
SLM Resource Class
creating 312
object pages 312
SLM Schedule
creating 313
object pages 313
SLM statements
adding to policy 310
overview 309
smtp protocol 165
SOAP attributes
S11:actor 159
S11:mustUnderstand 159
S12:mustUnderstand 159
S12:notUnderstood 159
S12:relay 159
S12:role 159
object pages
Main 314
SOAP Header Refine
Instruction 314
SOAP refinement transform 159
SOAP service provider type 159
soap-refine.xsll style sheet 159
SoapAction header 342
SPNEGO
Kerberos AP-REQ 175
sql action
defining 155
purpose 103
SQL action
See sql action
SQL Data Source
adding configuration parameters 316
base configuration 315
defining 315
high-level configuration 315
SQL injections, protection 62
sql protocol 165
SQL-Injection-Filter.xsl style sheet 62
SQL-Injection-Patterns.xml file 62
SSL
client proxy, creating 20
forward proxy, creating 20
reverse, proxy, creating 21
server proxy, creating 21
two-way proxy, creating 21
SSL authentication 18
SSL proxy policy, user agent 341
SSL Proxy Profile
creating
client proxy 20
forward proxy 20
reverse proxy 21
server proxy 21
two-way proxy 21
object pages 20
ssl-keyfile-pwd entry, [ldap] stanza 272
Stateful Raw XML Handler 93
Stateless Raw XML Handler 94
statistics, enabling 238
Status menu 1
store: directory 206
STR dereference transform 400, 401
strip-attachments action
defining 156
purpose 103
style sheets
buffer-attachments.xsl 161
conformance-filter.xsl 138
conformance-xform.xsl 161
filter-accept-all.xsl 136
filter-reject-all.xsl 136
flushing the cache 396
location 206
replay-filter.xsl 137
required-elements-filter.xsl 137
soap-refine.xsl 159
wssecurity-message-layoutfilter.xsl 138
Stylesheet Parameter
stylesheet parameters
Web Service Proxy
defining 47
subdirectories
creating 207
deleting 208
subscribe
SunJCE
JCEKS 209
support
See customer support
symmetric signatures
verifying 164
Synchronous to WS-Addressing
Mode 48
system variables
listing 414
system/map/debug 414
system/tasktemplates/debug 414
system/map/debug variable 414
system/tasktemplates/debug
variable 414
Index
431
T
TAM
ASCII configuration file 272
authorization server replicas 273
configuration, general 272
configuring TAM objects 273
creating configuration files 273
creating TAM objects 273
licensing 271
modifying configuration files 272
obfuscated configuration file 272
object pages 273
refreshing certificates 273
security 272
SSL key file 272
SSL stash file 272
tasktemplates: directory 207
tcp protocol 165
tcps protocol 165
TE header, retaining 344
temporary: directory 207
TFIM
AAA 274
object 274
object pages 274
TFIM endpoint
WS-Trust messages 274
threat protection
denial-of-service
multiple message 61
single message 60
dictionary attack 64
protocol 62
SQL injections 62
XML virus (X-Virus) 63
TIBCO EMS
fault-tolerant hosts 324, 328
heartbeat detection 330
load-balanced hosts 326, 328
map message 317
object pages 316
tibco.conf 330
transactional messaging 320
unique host 323
URL builder 66
TIBCO EMS Front Side Handler
map message 95
purpose 94
queues 94
support 94
topic spaces 94
TIBCO Rendezvous 94
TIBCO SmartSockets 94
tibco.conf file 330
Tivoli Access Manager
See TAM
topic spaces
TIBCO EMS 94
WebSphere JMS 97
trademarks 419
432
transaction headers variables

listing 410
service/append-request-header/ 410
410
service/set-request-header/ 410
service/set-response-header/ 410
transaction routing variables
listing 411
service/routing-url 411
service/routing-url-sslprofile 411
transaction URL variables
listing 411
service/protocol-method 412
service/URI 412
transaction variables
listing 408
types 408
transform action
See also xform action
attachments
buffering 161
transform 161
defining conformance transform 161
transform 159
defining standard transform
non-XML messages 157
XML messages 157
overview 156
processing instruction-based
transform 158
SOAP messages
refinement transform 159
XML messages
conformance 161
defining 157
processing instruction-based 158
Transform binary action
See xformbin action
Transform using processing instruction
action
See xformpi action
two way rule 100
typeface conventions xii
U
UDDI registry
publishing to 334
UDDI Registry
configuring 332
object pages 332
UDDI subscription
viewing status 334
UDDI Subscription
configuring UDDI Subscription
objects 333
creating UDDI Subscription
objects 333
object pages 333
UDDI subscriptions
ultimate service provider, SOAP 159
Undo button 5
up operational state 6
URI, ?wsdl 68
URL builder
IMS Connect 64
MQ 65
TIBCO EMS 66
WebSphere JMS 67
URL Map
object pages
Main 335
URL Map Rule 335
URL matching rule 99
URL Rewrite Policy
object pages
Main 335
URL Rewrite Rule 336
use cases
for-each action 139
User Agent
creating 340
default configuration 339
modifying basic configuation 340
overview 339
policies
allow-compression policy 343
basic authentication 339, 342
chunked upload 345
chunked uploads, HTTP 1.1 339
compression 339
compression policy 343
FTP client 339, 346
header injection 339, 345
header retention 339, 344
HTTP 1.0 restriction policy 344
HTTP proxy 339
HTTP proxy policy 341
public key authentication 339, 343
restriction, HTTP 1.0 339
SOAP action 342
SOAPAction 339
SSL proxy 339
SSL proxy policy 341
User objects
export packages 215
user policy
User Policy
UsernameToken
derived-key 174
utilities
keytool 209
V
validate action 162
purpose 103
Validation Credentials
creating
non expiring, non-passwordprotected certificates 22
select certificates 23
types of lists 22
variables
asynchronous
service/soap-oneway-mep 408
asynchronous transactions
listing 408
service/transaction-key 408
service/transaction-name 408
service/transaction-timeout 408
configuration service
listing 405
service/config-param/ 405
service/max-call-depth 405
error handling
listing 409
service/error-code 409
service/error-ignore 409
service/error-message 409
service/error-protocol-reasonphrase 409
service/error-protocolresponse 409
service/error-subcode 409
service/strict-error-mode 410
extension
listing 412
local/_extension/allowcompression 413
local/_extension/donot-followredirect 413
local/_extension/header/ 413
local/_extension/http-10-only 413
local/_extension/preventpersistent-connection 413
local/_extension/sslprofile 413
local/_extension/timeout 414
general
listing 404
service/soap-fault-response 404
list, all available 415
load balancer service
listing 406
service/lbhealth/ 406
MQ Host
listing 406
service/expiry 407
service/format 407
service/mq-ccsi 406
service/report 407
MQ Proxy
listing 406
service/expiry 407
service/format 407
service/mq-ccsi 406
variables (continued)
MQ Proxy (continued)
service/report 407
Multi-Protocol Gateway
backend-timeout 405
skip-backside 405
multistep
log/soapversion 407
persistent connections
listing 410
service/connection/note 411
service
listing 404
type 404
system
listing 414
system/map/debug 414
system/tasktemplates/debug 414
transaction
listing 408
type 408
transaction headers
listing 410
service/append-request-header/
410
410
service/set-request-header/ 410
service/set-response-header/ 410
transaction routing
listing 411
service/routing-url 411
service/routing-url-sslprofile 411
transaction URL
listing 411
service/protocol-method 412
service/URI 412
types 403
using 403
Web Service Proxy
backend-timeout 405
skip-backside 405
WSM
listing 412
service/wsa/genpattern 412
service/wsa/timeout 412
service/wsm/wsdl-error 412
service/wsm/wsdl-warning 412
verify action
adding 164
confirmation 402
Kerberos AP-REQ tokens, remote 401
purpose 103, 164
verifying signature confirmation 402
View button 3
View Logs link 5
View Status link
W
Web Management Interface 1
Web Service Proxy
basic configuration
UDDI subscriptions 25
WSDL files 25
WSRR subscriptions 25
configuring 25
configuring processing policies 32
configuring SLM peer group 31
configuring SLMs 29
configuring user policy 39
configuring Web Service Proxy
objects 346
creating 25
creating Web Service Proxy
objects 346
HTTP header
configuring parameters 46
minimal working configuration 347
object pages
Dynamic Endpoints 358
HTTP Header Injection 365
HTTP Header Suppression 365
HTTP Options 355
Main 348
Monitors 357
Operation Conformance
Policy 371
Operation Policy Subject Opt
Out 372
Operation Priority 369
Parser Limits 356
Policy Parameters 373
Proxy Settings 350
Reliable Messaging 374
Stylesheet Parameter 366
User Policy 367
WS-Addressing 357
WS-ReliableMessaging 359
WSDL Cache Policy 366
WSDL File 367
proxy settings
advanced 43
basic 41
publishing to UDDI registry 334
reading traffic graphs 30
service description 346
service variables
backend-timeout 405
skip-backside 405
show portType and binding
nodes 33
style sheets
defining parameters 47
threat protection 60
WS-Addressing
configuring 48
Index
433
Web Service Proxy (continued)

configuring 54
configuring 238
enabling 238
overview 238
Web sites
DataPower product xi
developerWorks xi
discussion forum xi
product documentation xi
Redbooks xi
web-mgmt command 1
WebGUI
accessing 1
applying configuration changes 4
canceling changes 4
cloning services 6
common tasks 4
dashboard 1
deleting objects 5
Domain list 1
exporting objects 5
logging in 1
Logout button 1
Network menu 1
Objects menu 1
resetting configuration 5
reverting changes 5
Save Config button 1
saving configuration changes 4
Services menu 1
Status menu 1
viewing configuration-specific logs 5
viewing object status 6
viewing probe data 7
Welcome screen 1
WebSphere JMS
transactional messaging 383
URL builder 67
WebSphere JMS Front Side Handler
purpose 96
queues 96
support 96
topic spaces 97
WebSphere JMS server
object pages 383
WebSphere Service Registry and
Repository
See WSRR
WebSphere Transformation Extender
See WTX
Welcome screen 1
workstation
uploading files 208
WS-Addressing
Synchronous to WS-Addressing 48
configuring 48
WS-Addressing to Synchronous 49
WS-Addressing to
WS-Addressing 51
WS-Addressing to Synchronous
Mode 49
434
WS-Addressing to WS-Addressing 51
WS-Proxy
Endpoint Rewrite 375
Local Rewrite Rule 376
object pages
Local Rewrite Rules 376
Main 376
Subscription Local Rewrite
Rule 380
Rule 382
Rule 381
Subscription Local Rewrite Rule 380
Rule 382
Rule 381
configuring 54
WS-Security
message layout filter 138
WS-Security Header
UsernameToken, derived-key 174
UsernameToken,
WS-Security Management
See WSSM
WS-Trust
WS-Trust messages
TFIM endpoint 274
WSDL
GET method 68
HEAD method 68
retrieving 68
verify as live 68
WSDL Cache Policy
WSDL File
WSM variables
listing 412
service/wsa/genpattern 412
service/wsa/timeout 412
service/wsm/wsdl-error 412
service/wsm/wsdl-warning 412
WSRR
configuration overview 390
overview 390
server configuration 391
subscription configuration 392
WSRR Server
object pages 391
WSRR Subscription
concept 392
object pages 392
synchronizing, manual
from configuration screen 394
from Status object 394
WSRR subscriptions
wssecurity-message-layout-filter.xsl style
sheet 138
WTX
xformbin action 157
X
X-Virus, protection 63
X.509 certificates 400
AAA Policy
authentication 400
identity extraction 400
verify action 400
XACML PDP
configuring 279
object pages 279
XDoS, protection 60
xform
defining standard transform 157
XML messages 157
xform action
defining 157
transform 161
defining conformance transform 161
transform 159
purpose 103
xformbin action
defining 157
purpose 103
xformpi action
defining 158
purpose 103
XML Manager
caches
flushing the document cache 395
flushing the stylesheet cache 396
configuring 394
document cache, flushing 395
Load Balancer Group
DataPower service 67
modifying 394
object pages 394
XML virus, protection 63
XPath bindings
AAA Policy 266
XPath matching rule 99
xs:decimal() extension function 284
Z
z/OS identity propagation
204
z/OS NSS authentication

z/OS NSS authorization
z/OS NSS Client
creating 397
overview 396
Index
435
436

Printed in USA

Web Service Proxy Developers Guide

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Web Service Proxy Developers Guide

Uploaded by

Copyright:

Available Formats

WebSphere DataPower XML Integration Appliance XI50