MultiProtocolGatewayDevelopersGuide Xi50

WebSphere DataPower Integration Appliance XI50
Version 3.8.1
Multi-Protocol Gateway Developers

Guide
WebSphere DataPower Integration Appliance XI50

Version 3.8.1
Multi-Protocol Gateway Developers

Guide
Note
Before using this information and the product it supports, read the information in Notices and trademarks on page 389.
Third Edition (August 2011)

This edition applies to version 3, release 8, modification 1 of IBM WebSphere DataPower Integration Appliance XI50
and to all subsequent releases and modifications until otherwise indicated in new editions.
Copyright IBM Corporation 2002, 2011.
US Government Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract
with IBM Corp.
Contents
Chapter 1. Introduction . . . . . . . . 1
Intended audience . . . . . . . . .
File naming guidelines . . . . . . . .
Object naming guidelines . . . . . . .
Typeface conventions . . . . . . . .
Purpose of Multi-Protocol Gateway services .
Support for Web 2.0 configurations . . . .
REST principals in Web 2.0 . . . . .
Web 2.0 and JSON . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
Defining Key objects . . . . . . .

Defining cryptographic profiles . . . . .
Defining shared secret keys . . . . . .
SSH client profiles . . . . . . . . .
Creating an SSH Client Profile . . . .
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 . . . . . . .
Validation methods . . . . . . . .
PKIX validation . . . . . . . . .
Creating for specific certificates . . . .
1
1
2
2
2
3
3
5
Chapter 2. WebGUI basics . . . . . . . 7

Objects on the appliance . . . . . . . . . . 7
Working with objects . . . . . . . . . . . 7
Accessing the WebGUI . . . . . . . . . . . 7
Welcome screen . . . . . . . . . . . . . 7
Common WebGUI conventions . . . . . . . . 8
Working with referenced objects . . . . . . . 8
Working with lists of referenced objects . . . . 9
Viewing and editing local files during configuration 9
Viewing local files . . . . . . . . . . . 10
Editing local files . . . . . . . . . . . 10
. .
. .
. .
. .
. .
. .
. .
pane
. .
. .
. .
. .
. .
. .
. .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
11
11
11
12
12
12
12
12
12
13
13
14
14
14
14
Chapter 4. Securing communication . . 17

Supported cryptographic formats . . . .
Working with keys and certificates . . .
Creating key-certificate pairs . . . .
Generating keys and certificates . . .
Exporting keys and certificates . . . .
Importing keys and certificates . . . .
Converting keys to specific formats . .
Converting certificates to specific formats
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 . . . . . .
Copyright IBM Corp. 2002, 2011
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
17
17
17
18
19
20
20
21
21
21
22
23
24
25
25
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
25
27
28
29
29
29
30
30
31
32
.
.
.
.
.
.
.
.
.
.
.
.
32
32
33
33
Chapter 5. Multi-Protocol Gateway

configuration . . . . . . . . . . . . 35
Chapter 3. Common WebGUI tasks. . . 11

Applying and saving changes . . . . .
Canceling changes . . . . . . . . .
Resetting objects . . . . . . . . . .
Deleting objects . . . . . . . . . .
Exporting objects . . . . . . . . .
Viewing configuration-specific messages. .
Viewing messages from the catalog . .
Viewing messages from the configuration
Viewing object status . . . . . . . .
Cloning services . . . . . . . . . .
Accessing probe captures . . . . . . .
Quiescing a handler . . . . . . . .
Unquiescing a handler. . . . . . . .
Quiescing a service . . . . . . . . .
Unquiescing a service . . . . . . . .
.
.
.
.
.
.
.
.
.
.
Creating a Multi-Protocol Gateway service . .

Available properties . . . . . . . . .
XML threat protection . . . . . . . . .
Protecting against single message XML
denial-of-service attacks . . . . . . .
Protecting against multiple message XML
denial-of-service attacks . . . . . . .
Protecting against message tampering . .
Padding oracle protection . . . . . .
Protection against SQL injections . . . .
XML virus . . . . . . . . . . . .
Protecting against dictionary attacks . . .
URL builders . . . . . . . . . . . .
Building an IMS Connect URL . . . . .
Building a TIBCO EMS URL. . . . . .
Building a WebSphere JMS URL . . . .
Building a WebSphere MQ URL . . . .
Scenario: Defining a load balancer group as the
destination . . . . . . . . . . . .
.
.
.
. 36
. 37
. 41
. 41
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 48
42
43
43
44
44
45
45
46
46
47
47
Chapter 6. Handler configuration . . . 51

Configuring an FTP poller handler . . .
Configuring an FTP server handler . . .
Defining as transparent . . . . . .
Defining as virtual ephemeral . . . .
Defining as virtual persistent . . . .
Configuring an HTTP handler . . . . .
Configuring an HTTPS handler . . . . .
Configuring an IMS Connect handler . . .
Configuring an NFS poller handler . . .
Configuring an SFTP poller handler . . .
Configuring an SFTP server handler . . .
Configuration considerations . . . .
Authentication and authorization . . .
SSH metadata variables . . . . . .
URL specifications with an SFTP handler
Configuring an SFTP Server handler . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
51
54
55
58
61
65
66
67
68
71
74
74
74
74
75
75
iii
Configuring a stateful raw XML handler. . . . .

Configuring a stateless raw XML handler . . . .
Configuring a TIBCO EMS handler . . . . . .
Using topic spaces . . . . . . . . . . .
Using map message . . . . . . . . . .
Configuring a TIBCO EMS handler . . . . .
Configuring a WebSphere JMS handler . . . . .
Using topics spaces . . . . . . . . . . .
Configuring a WebSphere JMS 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 . . . . .
77
78
78
78
79
79
81
81
81
83
83
83
84
85
85
Chapter 7. Processing policies . . . . 87

Matching rules . . . . . . . . . . . .
Processing rules . . . . . . . . . . . .
Processing actions . . . . . . . . . . .
Contexts . . . . . . . . . . . . . .
Context in processing rules . . . . . . .
Context keywords . . . . . . . . . .
Processing rule builder . . . . . . . . .
Creating a processing policy . . . . . . . .
Defining processing actions . . . . . . . .
Adding an AAA action . . . . . . . .
Adding an antivirus action . . . . . . .
Adding a call processing rule (call) action . .
Adding a checkpoint event (checkpoint) action
Adding a conditional action . . . . . . .
Adding a convert query parameters to XML
(convert-http) action . . . . . . . . .
Cryptographic binary (cryptobin) action . . .
Adding a decrypt action. . . . . . . .
Adding an encrypt action . . . . . . .
Adding an event-sink action . . . . . .
Adding an extract using XPath (extract) action
Adding a fetch action. . . . . . . . .
Filter actions. . . . . . . . . . . .
For each (for-each) action . . . . . . .
Adding a log action . . . . . . . . .
MQ header action . . . . . . . . . .
Adding an on-error action . . . . . . .
Results actions . . . . . . . . . . .
Adding a rewrite header (rewrite) action . .
Adding a method rewrite action . . . . .
Route-type actions. . . . . . . . . .
Adding a set variable (setvar) action . . .
Adding a sign action . . . . . . . . .
Adding an SLM action . . . . . . . .
Adding an SQL action . . . . . . . .
Adding a Strip Attachments action . . . .
Transform-type actions . . . . . . . .
Adding a validate action . . . . . . .
Verify actions . . . . . . . . . . .
Defining reusable rules . . . . . . . . .
Locating remote resources in actions. . . . .
Supported protocols in attachments . . . .
Specifying the location of remote resources .
iv
.
.
.
.
.
.
.
.
.
.
.
.
87
88
88
92
92
92
93
94
95
95
95
97
97
. 98
. 99
. 99
. 107
. 109
. 115
116
. 116
. 117
. 119
. 122
. 123
. 126
. 127
. 130
. 130
. 130
. 132
. 133
. 135
. 135
. 136
. 137
. 142
. 144
. 145
. 145
. 146
. 146
Attachment protocol . . .
Format of the <results> element
Using the variable builder . .
Debugging processing policies.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
Chapter 8. AAA Policy configuration
.
.
.
.
147
148
148
149
151
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 with only
authentication statement. . . . . . . . .
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 . . . . . . . . . . . . .
Generating a SAML assertion or response . . .
152
153
159
167
168
168
170
172
180
180
180
180
181
181
181
181
182
182
182
182
183
183
183
184
184
184
Chapter 9. Managing files . . . . . . 187

Directories on the appliance . . . . .
Launching the File Management utility . .
Displaying directory contents . . . . .
Creating a subdirectory . . . . . . .
Deleting a directory . . . . . . . .
Refreshing directory contents . . . . .
Uploading files from the workstation . .
Working with Java Key Stores . . . . .
Required software . . . . . . . .
Granting permissions. . . . . . .
Types of key stores . . . . . . .
Uploading a file from a Java Key Store .
Fetching files . . . . . . . . . .
Copying files . . . . . . . . . .
Renaming files . . . . . . . . . .
Moving files . . . . . . . . . . .
Viewing files . . . . . . . . . .
Editing files . . . . . . . . . . .
Deleting files . . . . . . . . . .
WebSphere DataPower Integration Appliance XI50: Multi-Protocol Gateway Developers Guide
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
187
189
189
189
190
190
190
191
191
191
191
191
192
192
193
193
194
194
194
Chapter 10. Managing the

configuration of the appliance . . . . 195
Creating Include Configuration File objects .
Creating Import Configuration File objects .
Backing up and exporting configuration data.
Backing up the entire appliance . . . .
Backing up domains . . . . . . . .
Exporting select objects . . . . . . .
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
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
195
196
197
198
198
199
200
202
.
.
.
.
.
.
.
.
.
.
.
.
.
.
202
202
203
203
203
204
205
206
206
207
207
208
209
209
Chapter 11. Managing monitors. . . . 211

Message monitors . . . . . . .
Traffic definitions . . . . . .
Message Type . . . . . . .
Message Filter Action. . . . .
Configuring count monitors . .
Configuring duration monitors .
Web services monitors . . . . .
Configuring Web services monitors
Specifying dual thresholds . . .
Enabling statistics . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
211
212
213
213
214
216
217
217
218
219
Appendix A. Referenced objects . . . 221

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 for authorization
Adding LTPA user attributes . . . . .
Using an AAA Info file . . . . . . .
IBM Tivoli Access Manager Integration . .
IBM Tivoli Federated Identity Manager
Integration . . . . . . . . . . .
Kerberos objects . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
221
221
224
226
233
234
235
235
242
243
243
244
245
245
245
246
246
251
.
.
. 253
. 255
|
|
|
Using SAML attributes for post processing . .

XACML Policy Decision Point . . . . . . .
Conformance Policy . . . . . . . . . . .
Document Crypto Map . . . . . . . . . .
HTTP Input Conversion Map . . . . . . . .
Input Encoding tab . . . . . . . . . .
IMS Connect . . . . . . . . . . . . .
Defining LDAP Search Parameters objects . . . .
Load balancer groups . . . . . . . . . .
Intelligent load distribution. . . . . . . .
Algorithms for making load balancing decisions
Membership . . . . . . . . . . . . .
Health checks . . . . . . . . . . . .
Session affinity . . . . . . . . . . . .
Configuring a load balancer group . . . . .
Modifying to use workload management
information . . . . . . . . . . . . .
Assigning weight to members . . . . . . .
Disabling members . . . . . . . . . .
Enabling the retrieval of workload management
information . . . . . . . . . . . . .
Enabling the retrieval of workload management
information for non-WebSphere application
servers . . . . . . . . . . . . . .
Defining matching rules . . . . . . . . . .
MTOM Policy . . . . . . . . . . . . .
Multi-Protocol Gateway object. . . . . . . .
Configuring basic operations . . . . . . .
Proxy Settings tab . . . . . . . . . . .
Monitors tab . . . . . . . . . . . .
Parser Limits tab . . . . . . . . . . .
HTTP Options tab . . . . . . . . . . .
HTTP Header Injection tab . . . . . . . .
HTTP Header Suppression tab . . . . . .
WS-Addressing tab . . . . . . . . . .
WS-ReliableMessaging tab . . . . . . . .
Stylesheet Parameter tab. . . . . . . . .
Policy Parameters . . . . . . . . . . . .
Main tab . . . . . . . . . . . . . .
Policy Parameters tab . . . . . . . . .
Defining Processing Action objects . . . . . .
Named Inputs tab . . . . . . . . . . .
Named Outputs tab . . . . . . . . . .
Stylesheet Parameters tab . . . . . . . .
Processing Metadata . . . . . . . . . . .
Main tab . . . . . . . . . . . . . .
Metadata Items tab . . . . . . . . . .
Defining Processing Policy objects . . . . . .
Policy Maps tab . . . . . . . . . . .
Defining Processing Rule objects . . . . . . .
RADIUS Settings . . . . . . . . . . . .
NAS-identifier . . . . . . . . . . . .
Configuring RADIUS Settings . . . . . . .
Schema Exception Map . . . . . . . . . .
Rules tab . . . . . . . . . . . . . .
Service level monitors . . . . . . . . . .
Creating an SLM policy . . . . . . . . .
Creating an SLM credentials class . . . . .
Creating an SLM resource class . . . . . .
Defining an SLM action . . . . . . . . .
Defining an SLM schedule . . . . . . . .
258
259
261
263
263
264
264
266
267
268
271
273
274
274
276
285
290
290
291
291
293
298
299
300
301
301
302
302
308
308
309
309
309
317
318
318
318
319
319
320
320
321
322
322
322
323
324
324
325
326
327
327
328
Contents
280
281
281
281
|
|
|
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 . . . . .
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 . . . . .
Adding an SFTP client policy . . . . .
WebSphere Cell . . . . . . . . . .
Selecting the update method . . . . .
Creating a WebSphere Cell . . . . . .
WebSphere JMS servers . . . . . . . .
Transactional messaging . . . . . . .
Configuring a WebSphere JMS server . .
XML Manager . . . . . . . . . . .
Document cache policy URL matching
expression . . . . . . . . . . .
Configure XML Manager objects . . . .
vi
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
328
329
329
330
331
331
332
332
332
335
338
338
339
341
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
343
345
345
346
348
350
350
351
351
352
352
353
353
354
354
355
355
356
356
357
357
358
359
359
362
366
.
.
. 367
. 367
Flushing the document cache

Flushing the stylesheet cache
NSS Client . . . . . . .
Creating the NSS Client . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
368
368
368
369
Appendix B. Cryptographic support in

actions . . . . . . . . . . . . . . 371
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
.
.
.
.
.
.
.
.
.
371
371
372
372
373
373
373
374
374
375
Service variables . . . . . . . . . . . .
General service variables . . . . . . . .
Multi-Protocol Gateway and Web Service Proxy
service variables . . . . . . . . . . .
Configuration 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 . . . . . . . . .
376
376
376
377
378
378
379
380
380
381
382
383
383
384
384
385
386
387
Notices and trademarks . . . . . . . 389

Trademarks .
. 389
Index . . . . . . . . . . . . . . . 391
Chapter 1. Introduction
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.
Intended audience
This document is intended for Developers who manage the configuration of
Multi-Protocol Gateway services, objects, and associated referenced objects on the
IBM WebSphere DataPower appliance. Developers should have the following
knowledge:
v Network architecture and concepts
v Internet protocols, including HTTP, TCP/IP, MQ
v Lightweight Directory Access Protocol (LDAP) and directory services
v Authentication and authorization
v XML and XSLT
v Web Services
v Web Services Security
Developers should also be familiar with SSL protocol, key exchange (public and
private), digital signatures, cryptographic algorithms, and certificate authorities.
This document assumes that an Administrator has installed and initially
configured the appliance as described in the IBM WebSphere DataPower SOA
Appliances: 9003: Installation Guide or in the IBM WebSphere DataPower SOA
Appliances: Type 9235: Installation Guide, depending on the model type.
File naming guidelines

The maximum length for a file name can be approximately 4128 characters. The
name of the base file can be up to 128 characters in length. The base file is the part
after the name of the DataPower directory. Examples of directories are local:,
store:, and temporary:.
If the directory (or domain) supports subdirectories, the path to the file can have a
length of 4000 characters. When you create a domain, its name is the base file
name in several DataPower directories when viewed from the default domain.
The following characters are valid in directory and file names:
v a through z
v A through Z
v 0 through 9
v _ (underscore)
v - (dash)
v . (period)
Note: Names cannot contain two consecutive periods (..).
Object naming guidelines

The object name must be unique in the object namespace. The following characters
are valid 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.
Purpose of Multi-Protocol Gateway services

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

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

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

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

payload with a request
Results
Results asynchronous
Log
Method rewrite
Allows you to rewrite an HTTP method to

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

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

Client
Application server
DataPower appliance
Response A (6)
Response A (5)
Response B (3)
Request A (4)
Request B (2)
Request A (1)
Accounting
services
Figure 1. DataPower appliance as a proxy
Message flow
Figure 1 shows a typical proxy implementation.
1. The client sends a Request A (1) to the DataPower appliance.
2. The DataPower appliance receives Request A (1) and sends a Request B (2) to a
RESTful accounting Web service.
3. The Accounting Services receive Request B (2) and sends a Response B (3) back
to the DataPower appliance.
4. The DataPower appliance forwards the Request A (4) to the application server.
5. The application server receives the Request A (4) and sends a Response A (5) to
DataPower appliance.
6. The DataPower appliance forwards Response A (6) to the client.
Implementation details
There are many ways to implement a proxy with a RESTful service for your
DataPower appliance. One way to implement a proxy, as shown in Figure 1, would
be to:
1. Configure your service
2. Configure a processing policy with a results or fetch action.
3. Change the HTTP Method to support your Accounting Service
4. Add a remote Web service IP address and port.
REST bridge deployment scenario

You can use a DataPower appliance as a bridge to transform messages and
protocols from one format to another. Figure 2 on page 5 illustrates a bridge
scenario. For example, a client sends requests in plain old XML (POX) but the
application server uses a SOAP protocol. You can specify a processing policy that
transforms a request into a protocol or message format that the application server
understands.
REST client
Application server
DataPower appliance
1
Request A (POX)
Request A (SOAP)
Response A (POX)
Response A (SOAP)
SOAP
Web service
Figure 2. A DataPower appliance as a bridge
Message flow
Figure 2 shows a typical proxy implementation.
1. A RESTful client sends Request A (POX) to a SOAP Web service on an
application server.
2. The DataPower appliance receives Request A (POX) and transforms it to SOAP
using a transform action.
3. In addition, a URL rewrite policy and SOAPAction HTTP header can be used to
transform the message Request A 1 (SOAP).
4. The Web service on the application server receives Request A1 (SOAP) and
sends a Response A1 (SOAP) to the DataPower appliance.
5. The DataPower appliance transforms Response A1 (SOAP) to Response A (POX)
using a transform action.
6. The DataPower appliance forwards Response A (POX) to the client.
There are many ways to implement a bridge scenario. One way to implement the
bridge scenario, as shown in Figure 2, would be to:
Configure your service with a HTTP front side handler.
Choose the appropriate HTTP methods for your front side handler.
Define your request type.
Configure your processing policy data conversion such as converting Plain Old
XML (POX) to SOAP.
1.
2.
3.
4.
Web 2.0 and JSON

A DataPower appliance can transform JSON to JSONx or JSONx to JSON. JSONx is
an IBM standard format used to represent JSON as XML. A DataPower appliance
uses a parser to convert a JSON payload to XML (JSONx). You have the option of
using the jsonx2json.xsl built-in stylesheet to transform JSONx to JSON. In
addition, you can validate JSONx using the jsonx.xsd built-in schema.
|
|
|
JSON can be specified in any of the following configuration options:

v The request type of Multi-Protocol Gateway or of XML Firewall services
v The response type of Multi-Protocol Gateway or of XML Firewall services

v The default encoding in conversion actions of a processing policy
|
|
In all of these cases, when a DataPower service or processing action processes a

JSON message, the message is made available as JSONx.
|
|
In Multi-Protocol Gateway or in XML Firewall services, you can specify JSON as

the request type and as the response type. The JSON input is validated as
|
|
|
well-formed JSON as described in RFC 4627. The service converts the message to
JSONx and makes the converted JSONx available as input to a processing policy in
the __JSONASJSONX context.
|
|
|
|
If you are not using JSON as the request type or the response type, to transform a
JSON payload to JSONx, use the convert-http processing action. When you add an
input conversion map to the processing action, you must select JSON as the default
input encoding for the DataPower service.
JSON deployment scenario

A DataPower appliance can act as a bridge between an AJAX client and a SOAP
Web service. In Figure 3, a DataPower appliance transforms requests and responses
from JSON to SOAP and SOAP to JSON acting as a bridge between an AJAX client
and the SOAP application server.
AJAX client
Application server
DataPower Appliance
1
Request A (JSON)
Request A (SOAP)
Response A (JSON)
Response A (SOAP)
SOAP
Web service
Figure 3. A DataPower appliance using JSON and JSONx
Message flow
Figure 3 shows a typical data transformation implementation.
1. The AJAX client sends a Request A (JSON) to a SOAP Web service on an
application server.
2. The DataPower appliance receives the Request A (JSON) and transforms
Request A from JSON to JSONx to SOAP.
3. The DataPower appliance forwards the transformed Request A1 (SOAP) to the
SOAP Web service.
4. The Web service receives the Request A1 (SOAP) and sends a Response A1
(SOAP) to the DataPower appliance.
5. The DataPower appliance receives and transforms Response A1 (SOAP) to
JSONx to JSON and forwards the transformed Response A (JSON) to the AJAX
client.
There are many ways to implement JSON to JSONx data transformations. One way
to implement the JSON scenario, as shown in Figure 3, would be to:
1. Configure your service with an HTTP front side handler
2. Configure the processing policy with a convert to XML action that specifies
JSON as the default encoding.
3. Configure a transform action to convert JSONx to SOAP
Chapter 2. WebGUI basics

The WebGUI is the primary interface for managing the appliance itself and for
configuring services.
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 enables 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:
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 4 illustrates this
type of input field.
Input
Figure 4. Input field for referenced objects
When the WebGUI displays this type of input field, you can specify the referenced
object in the following ways:
v Select the name of an existing referenced object from the list.
v Use the + button to create a new referenced object. When created, the input field
contains the name of the newly created referenced object.
v Use the ... button to modify the referenced object whose name is in the input
field. When modified, the input field retains the name of the referenced object.
When you click the + button or ... button, the WebGUI launches a new window
that displays the configuration screen for that type of object.
Working with lists of referenced objects

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

As you use the WebGUI to select a local file during configuration, the
configuration screen might display the View and Edit buttons beside the selection
lists.
Working with files in this way has the following advantages:
v Ensure that the file is the one that you want
v Ability to edit the file to address errors found while defining a configuration
v Use a single session instead of opening another session to manage files through
the File Management utility
You cannot view or edit remote files.
Chapter 2. WebGUI basics
Viewing local files

To
1.
2.
3.
view a local file:

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:
1.
2.
3.
4.
5.
10
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.
Chapter 3. Common WebGUI tasks

The majority of objects provide the following common tasks. Not all objects have
these tasks available.
v Applying and saving configuration changes
v Canceling changes before saving to the running configuration
v Resetting changes to an object
v Deleting an object
v Exporting the configuration of an object
v
v
v
v
v
Viewing configuration-specific messages of an object

Viewing status of an object
Cloning a service
Accessing probe captures
Quiescing and unquiescing
Applying and saving changes

As you use the WebGUI to manage 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 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, click Cancel to not save the current changes to the
running configuration. If you click Cancel, you return to the 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.
To revert changes to a specific object:
1.
2.
3.
4.
Display the catalog for the object.

Click the name of the object to reset.
Click Undo.
Follow the prompts.
11
Deleting objects
You might want to delete objects that are no longer needed. If no 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 in use by a higher-level object.
To
1.
2.
3.
4.
delete an object:
Click the name of the object to delete.
Click Delete.
Follow the prompts.
Deleting an object deletes that object only. Deleting an object does not delete
referenced objects.
Exporting objects
To export an object:
1. Display the catalog for the object.
2. Click the name of the object to export.
3. Click Export.
4. Follow the prompts.
Viewing configuration-specific messages

During developing, 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 logs.
Viewing messages from the catalog

To view configuration-specific messages from the catalog:
2. Click the magnifying glass icon.
Viewing messages from the configuration pane

To view configuration-specific messages from the configuration pane:
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.
12
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
To
1.
2.
3.
view the status for an object:

Click the name of the object to view.
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.
To clone a service:
Display the catalog for the service.
Click the name of the service to clone.
Click Clone.
When the screen refreshes, specify the name of the clone.
In the Device Address field, specify the Ethernet interface that the service
monitors for incoming client requests. Use the default address (0.0.0.0) to
specify all interfaces.
6. In the Device Port field, specify the Ethernet port that the service monitors for
incoming client requests.
7. As necessary, edit the other properties.
1.
2.
3.
4.
5.
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.
To
1.
2.
3.
access probe captures:

Display the catalog for the service.
Click the name of the service.
Click Show Probe.
4. Click the magnifying glass icon.

13
For complete details about using the probe, refer to the IBM WebSphere DataPower
SOA Appliances: Problem Determination Guide.
Quiescing a handler
You can quiesce either a listening or a polling protocol handler to transition the
operational state of the handler to the down state in a controlled manner.
To quiesce a protocol handler:
1. Click Objects Protocol Handlers and the type of handler.
2. Click on the name of the handler.
3.
4.
5.
6.
7.
Click Quiesce.
Specify the Timeout in seconds.
Click Quiesce.
Click Confirm.
Click Close.
Unquiescing a handler
You can unquiesce a quiesced listening or polling handler to transition the handler
to the up operational state.
To unquiesce a handler:
1. Click Objects Protocol Handlers and the type of handler.
2. Click on the name of the handler.
3. Click Unquiesce.
4. Click Confirm.
5. Click Close.
Quiescing a service
You can quiesce a service to transition the operational state of the service and all
handlers associated with the service to the down state in a controlled manner.
To quiesce a service:
1.
2.
3.
4.
5.
Click Objects Service Configuration and the type of service.

Click on the name of the service.
Click Quiesce.
Specify the Timeout in seconds.
Click Quiesce.
6. Click Confirm.
7. Click Close.
Unquiescing a service
You can unquiesce a quiesced service to transition the service to the up operational
state. All quiesced handlers associated with the service are also placed in the up
operational state.
To unquiesce a service:
1. Click Objects Protocol Handlers and the type of service.
14
2.
3.
4.
5.
Click
Click
Click
Click
on the name of the service.

Unquiesce.
Confirm.
Close.
15
16
Chapter 4. Securing communication

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

Private key objects support the following formats:
v DER
v PEM
v PKCS #8
v PKCS #12
Certificate objects support the following formats:
v DER
v PEM
v PKCS #7
v PKCS #12
Neither key objects nor certificate objects directly support JKS or KDB formats.
Working with keys and certificates

The DataPower appliance provides actions that allow you to work with keys and
certificates. With the provided cryptographic tools, you can perform the following
actions:
v Create key-certificate pairs
v Generate keys and certificates
v Export keys and certificates
v Import keys and certificates
v Convert keys to specific formats
v Convert certificates to specific formats
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 Tools to create the key and CSR
2. Store the private key on the box and create a Key object that references it.
17
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.
Optionally, create an Identification Credentials object that references the Key and
Certificate objects. When you create the Identification Credentials, 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 edited. If a file is stored in the
local: directory or in the temporary: directory, it can be edited.
To generate a key:
1. Click Administration Miscellaneous Crypto Tools.
2. Define the LDAP entry.
a. Set LDAP (reverse) Order of RDNs to indicate whether to create the
LDAP entry in reverse RDN order.
on
b.
c.
d.
e.
f.
g.
3.
4.
5.
6.
Creates the entry in reverse RDN order.
off
(Default) Creates the entry in forward RDN order.
Optional: In the Country Name (C) field, enter a country name.
Optional: In the State or Province (ST) field, enter a state name or a
province name.
Optional: In the Locality (L) field, enter a locality name.
Optional: In the Organization (O) field, enter the name of an organization.
Optional: In the Organizational Unit (OU) field, enter the name of an
organizational unit.
Optional: In the Organizational Unit 2 (OU), Organizational Unit 3 (OU),
and Organizational Unit 4 (OU) fields, enter the names of additional
organizational units.
h. In the Common Name (CN) field, enter a common name.

From the RSA Key Length list, select the key length. This defaults to 1024.
In the File Name field, enter the name of the key file to generate. The value
takes the directory:///name form. Leave blank to allow the action to create
the name.
In the Validity Period field, enter the number of days that the key is valid.
In the Password field, enter a password to access the key file. The password
must be at least six characters in length.
7. In the Password Alias field, enter a password alias to access the key file.
8. Set Export Private Key to indicate whether the action writes the key file to the
temporary: directory.
18
on
Writes the key file to the temporary: directory.
off
(Default) Does not write the key file to the temporary: directory.
9. Set Generate Self-Signed Certificate 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. Set Export Self-Signed Certificate 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. Set Generate Key and Certificate Objects 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. In the Object Name field, enter the name to use for the Key object and for the
Certificate object. Leave blank to allow the action to generate the names from
the input information (based on the Common Name (CN) or File Name
property).
13. In the Using Existing Key Object field, enter the name of an existing key. 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.
19
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.
To
1.
2.
3.
export a key or certificate:

Click Administration Miscellaneous Crypto Tools.
Click the Export Crypto Object tab.
From the Object Type list, select the type of object to export. Any appliance can
export certificates. Devices with HSM hardware can export private keys.
4. In the Object Name field, enter the exact name of the private key. To view a
list of all such objects, select Objects Crypto Objects Cryptographic
Certificate (or Key).
5. In the Output File Name field, enter the name of a file into which to export the
key. The name cannot have a file extension. This file is in the temporary:
directory of the local file storage area.
6. Click Export Crypto Object.
The selected cryptographic object is exported to the identified file. A new file with
the name given is created in the temporary: directory. This file can then be copied
from the appliance.
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.
To import a key or certificate:
2. Click the Import Crypto Object tab.
3. From the Object Type list, select the type of object to import. Any appliance
can import certificates. Devices with HSM hardware can import private keys.
4. In the Object Name field, enter the name of the object to create. This name
must be unique in the object namespace.
5. In the Input File Name field, select the export package. If the file does not
reside on the DataPower appliance, click Upload or Fetch to transfer the file.
6. Click Import Crypto Object.
An object with the specified name is created. Otherwise, an error is returned.
Converting keys to specific formats

Use the Convert Crypto Key Object tab of the Crypto Tools screen to convert a
private key object to a specific output format and write it to a file.
20
If the output format includes private fields of the key, the file must be in the same
directory as the configured file of the private key object. The OpenSSH public key
format, which is used in authorized_keys files, does not contain any private fields.
It contains only public fields.
To convert a key object:
Click Administration Miscellaneous Crypto Tools.
Click the Convert Crypto Key Object tab.
From the Key Name list, select the name of the key object to be converted.
In the Output File Name field, enter the name of the output file. Use the
temporary:///mykey.pub format.
5. From the Output Format list, select the format of the output file.
6. Click Convert Crypto Key Object to convert the specified key object to the
specified format.
1.
2.
3.
4.
Converting certificates to specific formats

Use the Convert Crypto Certificate Object tab of the Crypto Tools screen to
convert a certificate object to a specific output format and write it to a file.
To convert a certificate object:
2. Click the Convert Crypto Certificate Object tab.
3. From the Certificate Name list, select the name of the certificate object to be
converted.
4. In the Output File Name field, enter the name of the output file. Use the
temporary:///mycert.pub format.
5. From the Output Format list, select the format of the output file.
6. Click Convert Crypto Certificate Object to convert the specified certificate
object to the specified format.
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 an NSS client object. The 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
NSS client object, see NSS Client on page 368.
21
To access and use z/OS certificates, the 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
1.
2.
3.
create and configure a Certificate, use the following procedure:

Select Objects Crypto Configuration Crypto Certificate.
Click Add to display the configuration pane.
Provide the following inputs:
Name Specify the name of the object.
Administrative State
Identifies the administrative state of the configuration.
v To make inactive, click disabled.
v To make active, click enabled.
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.
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
22
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
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

Allow the creation of a certificate prior to its activation date (the
NotBefore value in the certificate) or after its expiration date (the
NotAfter value in the certificate).
off
(Default) Prevents the creation of certificates outside of their

internal expiration values.
on
Creates the certificate and places it in the up state. Although the

certificate is in the up state, objects that reference the certificate
use the internal expiration values. In other words, the certificate
itself is in the up state, but Validation Credentials, Firewall
Credentials, or Identification Credentials that references the
certificate adhere to the internal expiration values.
In other words, the certificate itself is in the up state, but

Validation Credentials, Firewall Credentials, or Identification
Credentials that references the certificate adhere to the internal
expiration values. If the certificate is used for a certificate chain
validation from a Validation Credentials and the certificate is
not valid, validation fails. Similarly, if the certificate is used
from an Identification Credentials, the DataPower appliance
sends the certificate to the SSL peer for an SSL connection, but
the peer can reject the certificate as not valid.
Defining Firewall Credentials objects

A Firewall Credentials object consists of a list of Key and Certificate objects.
Certificates and keys that are not referenced in the Firewall Credentials object are
unavailable. If no Firewall Credentials object exists, all keys and certificates that are
stored locally are available.
To create a Firewall Credentials object, use the following procedure:
1. Click Objects Crypto Configuration Crypto Firewall Credentials.
2. Click Add to display the configuration pane.
3. Provide the following inputs:
23
Private Key
Select Key objects to add. Refer to Defining Key objects on page 25
for more information.
Shared Secret Key
Select Shared Secret Key objects to add. Refer to Defining shared
secret keys on page 28 for more information.
Certificates
Select Certificate objects to add. Refer to Defining Certificate objects
on page 22 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 create an Identification Credentials object, use the following procedure:
1. Select Objects Crypto Configuration Crypto Identification Credentials.
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 25
Certificate
Access a list of all Certificate objects, and select the Certificate object for
this Identification Credentials. Refer to Defining Certificate objects on
page 22 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.
24
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
v
v
v
v
Retrieve private keys from z/OS

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 certificate's private key
Submit requests to z/OS to generate a digital signature using a certificate's
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 an
NSS client object. The NSS client object must be defined and in the up operational
state when you create key objects.
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 NSS client object
must be in the up operational state when using remote key objects. For more
information about the NSS client object, see NSS Client on page 368.
To access and use z/OS keys, the 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
1.
2.
3.
create and configure a Key object, use the following procedure:

Select Objects Crypto Configuration Crypto Key.
Click Add to display the configuration pane.
Name
Specify the name of the object.
25

File Name
Specify the local private key file or the remote z/OS private key file.
For a local key file, access a list of files, contained in the cert: file
repository, and select the file that contains the private key aliased by this
Key object. Click Upload or Fetch to transfer the file.
Note: Keys can be retrieved from a Java Key Store residing on the local
workstation. Click Java Key Store on the Upload field. Refer to
Uploading files from the workstation on page 190 for more
information.
For a remote z/OS key file, specify the location and the file name.
v Select saf-key:// or saf-remote-key:// from the File Name list.
v Specify the file name using the following format:
nssclient/ZOSKEYLABEL
nssclient
Specifies an existing NSS client object.
ZOSKEYLABEL
Specifies the label name of an existing SAF key residing on the
z/OS system. A saf-key:// must be a SAF key that is not stored
in ICSF. A saf-remote-key:// must be a SAF key that is stored in
ICSF.
Password
Depending on business security policies, provide one of the following:
v If local security policies provide for password-protected keys, specify
the password (or a password alias).
v If local polices do not support password protection, leave blank.
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
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.
26
Defining cryptographic profiles

A Crypto Profile identifies a collection of SSL resources that support SSL
connections with remote peer appliances.
To create and configure a Crypto Profile:
1. Click Objects Crypto Crypto Profile.
2. Click Add.
Name
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 24 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 32 for more information.
Ciphers
Use the field to identify the symmetric key-encryption algorithms for this
Profile object. Common cipher values are as follows:
ALL
Includes all cipher suites, except the eNULL ciphers.
DEFAULT
Includes all cipher suites, except for the following ciphers and
cipher suites:
v eNULL ciphers
v Cipher suites that use DH authentication
v Cipher suites that contain the RC4, RSA, and SSL version 2
ciphers
HIGH Includes all high encryption cipher suites. These ciphers
support a key length in excess of 128 bits.
MEDIUM
Includes all medium encryption cipher suites. These ciphers
support a key length of 128 bits.
LOW
Includes all low encryption cipher suites. These ciphers support

a key length of 56 or 64 bits, but exclude EXPORT cipher suites.
27
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.
v To allow SSL and TLS renegotiation, which is vulnerable to a
man-in-the-middle (MITM) attack documented in CVE-2009-3555, click
Permit insecure SSL renegotiation.
Send Client CA List
Enable or disable 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.
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.
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
1.
2.
3.
create a shared secret key:

Click Objects Crypto Configuration Crypto Shared Secret Key.
Click Add.
In the Name field, enter the name for the object.
4. Set Administrative State to identify the administrative state of the

configuration.
28

5. From the File Name list, select the file that contains the key material.
SSH client profiles

An SSH Client Profile defines the authentication type and credentials to use for an
SSH client connection. Authentication can be public key or password or both
public key and password. If the configuration includes both authentication
methods, public key authentication is attempted first.
Creating an SSH Client Profile

To create an SSH Client Profile:
1. Click Objects Crypto Configuration SSH Client Profile.
2. Click Add.
3. In the Name field, enter the name for the object.
configuration.
5. In the User name field, enter the name of the user.
6. In the User Authentication field, specify an authentication type.
v For public key authentication: In the User Private Key list, select a key.
v For password authentication: In the Password field, enter and confirm the
password for the user.
7. Optional: Set Persistent Connections to specify whether to enable or disable
persistent connections.
8. If using persistent connections: In the Persistent Connection Idle Timeout
field, specify the idle timeout.
9. Optional: Set Strict Host Key Checking to specify whether the SSH client
rejects or accepts an incoming key for host authentication.
10. If using strict host key checking: Click Add SSH Known Host, and define the
host.
a. In the SSH Client Profile list, select the name of the SSH client profile.
b. In the Host field, specify the fully-qualified host name or IP address for
the SSH peer.
c. In the Type field, specify the key type for the SSH peer.
d. In the Key field, specify the host key value for the SSH peer.
e. Click Add SSH Known Host.
f. Click Confirm.
g. Click Close.
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:
29
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.
configuration.
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. Set Client-side Session Caching to enable or disable client side caching.
Creating a reverse (or server) proxy

To create a reverse SSL Proxy Profile, use the following procedure:
catalog.
configuration.
5.
6.
7.
8.
9.
10.
30

Select Reverse from the SSL Direction list.
Select the profile that defines SSL service to frontend clients from the Reverse
(Server) Crypto Profile list.
Set Server-side Session Caching to enable or disable server side caching.
Specify the time that session-specific state data is maintained in the server
cache in the Server-side Session Cache Timeout field.
Specify the maximum size of the server-side cache in the Server-side Session
Cache Size field.
Set Client Authentication is optional to control when SSL client
authentication is optional.
on
Client authentication is not required. When there is no client

certificate, the request does not fail.
(Default) Requires client authentication only when the server

cryptographic profile has an assigned Validation Credentials.
11. Set Always Request Client Authentication to control when to request SSL
client authentication.
off
on
Always requests client authentication.
(Default) Requests client authentication only when the server

off
Creating a two-way proxy

To create an SSL Proxy Profile, use the following procedure:
catalog.
configuration.
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. Set Server-side Session Caching to enable or disable server side caching.
9. Specify the time that session-specific state data is maintained in the server
cache in the Server-side Session Cache Timeout field.
10. Specify the maximum size of the server-side cache in the Server-side Session
Cache Size field.
11. Set Client-side Session Caching to enable or disable client side caching.
12. Set Client Authentication is optional 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

13. Set Always Request Client Authentication to control when to request SSL
client authentication.
on
Always requests client authentication.
(Default) Requests client authentication only when the server

off
31
Validation credentials
Validation credentials consists of a set of certificates. Validation credentials validate
the authenticity of received certificates and digital signatures. You can create
validation credentials from the following types of certificates:
v All non-expiring, non-password-protected certificates
v Specific certificates
Creating for non-expiring, non-password-protected certificates

You can create a validation credentials for all valid, non-expired,
non-password-protected certificates in the pubcert: directory. The process silently
creates a Certificate object for each valid certificate file in the pubcert: directory.
To create the pubcert validation credentials for non-expiring, non-passwordprotected certificates:
1. Click Objects Crypto Configuration Crypto Validation Credentials.
2. Click Create Validation Credential from pubcert:.
If the validation credentials is in the down operational state, one or more certificates
might be expired or otherwise unusable. If this occurs, access the pubcert
validation credentials and click View Status.
Validation methods
When creating a validation credentials from specific certificates, you must define
the validation method. Validation can use one of the following methods:
Match to an exact certificate or immediate issuer
Validates uses the certificates in the validation credentials. The validation
credential contains either the exact peer certificate to match or the
certificate of the immediate issuer. The certificate could be an intermediate
CA or a root CA. This mode is useful to match the peer certificate exactly,
but that certificate is not a self-signed (root) certificate.
Full certificate chain checking, or PKIX
Validation checks the complete certificate chain from subject to root.
Validation succeeds only if the chain ends with a root certificate in the
validation credentials. Nonroot certificates in the validation credentials are
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).
When using this validation method, self-signed certificates are considered
to be trusted roots assuming that they are correctly designated as CA
certificates by their Basic Constraints extension and Key Usage extension, if
present. Non-self-signed certificates are considered untrusted intermediates.
The validation credentials must not contain more than one certificate with
a given subject name. During client certificate validation, the client can
present a set of other certificates to be considered when building the
certification chain. Only non-self-signed CA certificates are used from this
set and are treated as candidate untrusted intermediate certificates.
32
PKIX validation
When the validation method is PKIX, the following extensions for CA certificates
can be marked as critical. A certificate that contains any other critical extension
causes the certificate to be rejected. When a certificate contains other noncritical
extensions, these extensions are ignored.
v Key Usage This extension is not required to be present. If present, it must
indicate that the key is suitable for certificate signing.
v Subject Alternative Name This extension is not used. Regardless of its
criticality, validation does not reject a certificate if it contains the extension.
v Basic Constraints This extension is required in a CA certificate. There is an
exception for X509 V1 root certificates. However, all V3 CA certificates must
have the extension. Only V3 certificates can be used as intermediates. Fully
implemented in accordance to RFC 3280.
v Certificate Policies Fully implemented in accordance to RFC 3280.
v Authority Information Access This extension is used for only Online Certificate
Status Protocol (OCSP).
v Policy Constraints Fully implemented in accordance to RFC 3280.
v Inhibit Any-Policy Fully implemented in accordance to RFC 3280.
Creating for specific certificates

You can create a validation credentials for existing Certificate objects.
To create a validation credentials for existing certificates:
1. Click Objects Crypto Configuration Crypto Validation Credentials.
2. Click Add.
configuration.
5.
6.
7.
8.

From the Certificates list, add select certificates to the validation credentials.
From the Certificate Validation Mode list, select the method for certificate
validation.
Set Use CRLs to control whether each Certificate Revocation List (CRL) is
checked during the processing of the certificate chain.
When CRLs are checked during certificate chain processing, define controls.
a. Set Require CRLs to control whether processing fails when CRLs are
unavailable.
b. From the CRL Distribution Points Handling list, select how to handle
X.509 extensions.
9. For PKIX validation, define policy sets.

a. In the Initial Certificate Policy Set field, specify the unique object
identifiers for the certificate policy. RFC 3280 refers to the certificate chain
validation input variable as the user-initial-policy-set. This set of object
identifiers specifies the allowable values of certificate policies at the end of
chain processing.
The default is 2.5.29.32.0, which is the object identifier for anyPolicy.
33
b. If you defined an initial policy set, enable Require Explicit Certificate

Policy. Otherwise, these policy sets will be used only when there are
Policy Constraints extensions in the certificate chain.
34
Chapter 5. Multi-Protocol Gateway configuration

This chapter describes the Multi-Protocol Gateway service. A Multi-Protocol
Gateway service can accept client-originated messages in a variety of protocols.
The service can subsequently pass messages to a back-end server using a variety of
protocols. The protocols that the client side uses do not need to be the same
protocols as those on the back side. A Multi-Protocol Gateway service supports the
following protocols:
FTP
The service acts as either an FTP client, which polls a remote FTP server
for requests, or as an FTP server, which accepts incoming FTP connections.
HTTP Including GET and POST. POST can contain XML, SOAP, DIME, SOAP
with Attachments. This protocol is available on all appliances.
HTTPS
Including GET and POST. POST can contain XML, SOAP, DIME, SOAP
with Attachments. This protocol is available on all appliances.
IMS
The service can accept incoming IMS protocol requests and can initiate
IMS connections on the back side.
MQ
The service can use GET and PUT queues to communicate with MQ
queues. This protocol requires the MQ license.
NFS
The service can poll an NFS-mounted directory for the presence of new
files and can place responses on an NFS mounted directory.
SFTP
The service acts as either an SFTP client on the back-side, which connects
to a remote SFTP server for request, or as an SFTP server on the front-side,
which allows SFTP clients to post to and retrieve files from a back-end file
system.
Stateful Raw XML

A stateful implementation that allows messages to flow from client to
back-end server and back again using persistent connections.
Stateless Raw XML
A stateless implementation that allows messages to flow from client to
back-end server and back again using persistent connections.
TIBCO EMS
Supports TIBCO Enterprise Messaging Service (EMS) messaging. This
protocol requires the TIBCO-EMS license.
WebSphere JMS
Supports the WebSphere JMS messaging. This protocol requires the
WebSphere-JMS license.
A Multi-Protocol Gateway service can support more than one client, or front side,
protocol. Similarly, the service can support more than one back-end, or server,
protocol.
Figure 6 on page 36 provides an illustration of the static back-end architecture that
the service supports.
35
HTTP
HTTPS
MQ
Multi-Protocol Gateway
HTTP or
HTTPS or
MQ
Back End Server
Figure 6. Static back-end architecture
Multi-Protocol Gateway services can accept client requests through any of the
protocol handlers that are shown (HTTP, HTTPS, or MQ). A static URL determines
the destination for all traffic. This server-side traffic can employ one of the
protocols that are shown (HTTP, HTTPS, or MQ).
When the back-end service endpoint is dynamically determined, the gateway
supports a Stateful Raw XML protocol handler. Because the connection is stateful,
this protocol handler can only communicate with a back-end service that also
employs the same protocol. Figure 7 shows other protocol handlers that the same
gateway can use to dynamically route to the other protocols.
HTTP
HTTP
HTTPS
HTTPS
MQ
MQ
Stateful
Stateful
Back End Servers
Figure 7. Dynamic back-end architecture
The messages can be processed and routed using any of the standard processing
actions that are available to a service.
Creating a Multi-Protocol Gateway service

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

Reliable Messaging.
10. Optional: On the XML Threat Protection tab, configure XML threat protection.
Available properties
This section provides details about the fields available:
v General
v Advanced
v Style sheet parameters
v Headers
v Monitors
v Web Services Addressing
v Web Services Reliable Messaging
Table 2. Properties available on the General tab
Name
Purpose
Name
Specify the gateway name.
Summary
Optional: Specify a brief description.
Type
Select the gateway type.
XML Manager
Assigns an XML manager. See XML Manager on page

366
Policy
Assigns a processing policy. Refer to Chapter 7, Processing

policies, on page 87.
URL Rewrite Policy
Optional: Assigns a URL rewrite policy. Refer to URL

Rewrite Policy on page 345.
Backend URL
Specifies the URL of the static, remote server. To use a load

balancer, specify the name of an existing Load Balancer
Group object.
Front Side Protocol
Assigns one or more handlers. Refer to Chapter 6, Handler

configuration, on page 51.
SSL Client Crypto Profile
Optional: Assigns an instance of SSL Crypto Profile.
Response Type
Characterizes the server-generated response.
Flow Control
Specifies the flow control behavior.
Back Attachment processing

format
Specifies the attachment format.
Back Side Timeout
Specifies the number of seconds that a connection with a

server can remain idle.
Stream Output to Back
Specifies the streaming behavior.
HTTP Version to Server
Specifies the HTTP protocol version for server-side

connections.
Propagate URI
Indicates the URI propagation behavior.
Compression
Controls GZIP compression negotiation with the remote

server.
Request Type
Characterizes the client-generated request.

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

Name
Purpose
Front attachment processing

format
Specifies the attachment format.
Front Side Timeout
Specifies the number of seconds that a connection with a

client can remain idle.
Stream Output to Front
Specifies the streaming behavior.
Table 3. Properties available on the Advanced tab

Name
Purpose
Persistent Connections
Optional: Controls HTTP persistent connections.
Loop Detection
Optional: Controls loop-detection between hosts with the

Via: header field.
Follow Redirects
Optional: Controls server-side redirects (such as HTTP 302).
Allow Chunked Uploads
Optional: Controls the ability to send content-type,

chunked-encoded documents.
Process Backend Errors
Optional: Controls the processing of errors from the remote

server.
Front Persistent Connection

Timeout
Optional: Specifies the number of seconds that a persistent

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

Timeout
Optional: Specifies the number of seconds that a persistent

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

Processing
Optional: Controls support for MIME (Multi-Purpose

Internet Mail Extensions) header processing on the server
side.
MIME Front Header

Processing
Optional: Controls support for MIME header processing on

the client side.
Gateway Credentials
Optional: Assigns firewall credentials. See Defining

Firewall Credentials objects on page 23.
Default parameter
namespace
Optional: Specifies the default XML namespace for

parameters.
Query parameter namespace
Optional: Specifies the default XML namespace for

parameters made available via a URL query string.
SOAP Schema URL
Optional: Specifies the full URL to the schema to validate

the SOAP schema for SOAP-formatted messages.
Message Processing Modes
Optional: Identifies one or more modes for message

processing.
Process Message Whose

Body is Empty
Optional: Whether to force the processing of XML messages

when their message body is empty or missing in RESTful
Web services.
Table 4. Properties available on the Stylesheet Params tab
38
Name
Purpose
Parameter Name
Specifies the name of a common parameter used by the

supplied style sheets for cryptographic processing.
Custom Name
Specifies the name of an unlisted parameter.
Table 4. Properties available on the Stylesheet Params tab (continued)

Name
Purpose
Parameter Value
Specifies the value for the parameter.
Table 5. Properties available on the Headers tab for header injection

Name
Purpose
Direction
Indicates the direction of the message.
Header Name
Specifies the name of the header to inject.
Header Name
Specifies the value for the header.
Table 6. Properties available on the Monitors tab

Name
Purpose
Message Count Monitor
Assigns count monitors. Refer to Configuring count

monitors on page 214.
Message Duration Monitor
Assigns duration monitors. Refer to Configuring duration

Gateway Service Level

Monitor
Assigns Web service monitors. Refer to Configuring Web

services monitors on page 217.
Monitors Evaluation Method Indicates how monitors interact with each other when the
service uses more than one monitor.
Table 7. Properties available on the WS-Addressing tab
Name
Purpose
WS-Addressing Mode
Specifies the mode of WS-Addressing.
Strip WS-Addressing
Headers
Controls whether to remove all WS-Addressing headers

from server-generated responses before forwarding them to
the client.
WS-Addressing Message
Generation Pattern
Specifies the request/response transmission model between

the service and the remote server.
Asynchronous HTTP
Response Code
Specifies the HTTP response code sent to a client prior to

transmitting the actual asynchronous server response to
close the original client channel.
WS-Addressing
Asynchronous Reply Point
Specifies the name of the handler object that receives

asynchronous server responses and forwards responses to
the original client.
WS-Addressing
Asynchronous Reply
Timeout
Specifies the maximum period of time to wait for an

asynchronous response before abandoning the transaction.
Rewrite WS-Addressing
Reply To Header
Specifies the name of the URL Rewrite Policy object to

rewrite the contents of the WS-Addressing ReplyTo header.
Rewrite WS-Addressing
Fault To Header

rewrite the contents of the WS-Addressing FaultTo header.
Rewrite WS-Addressing To
Header

rewrite the contents of the WS-Addressing To header.
Default WS-Addressing
Reply-To
Forces the inclusion of the optional ReplyTo header in

WS-Addressing messages.
Default WS-Addressing
Fault-To
Forces the inclusion of the optional FaultTo header in

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

Name
Purpose
Force Incoming
WS-Addressing
Forces the inclusion of WS-Addressing headers into

server-originated traditionally addressed messages.
Table 8. Properties available on the WS-ReliableMessaging tab

Name
Purpose
Use WS-ReliableMessaging
Indicates whether to use Web Services Reliable Messaging
Target Sequence Expiration

Interval
Sets the target expiration lifetime in seconds for all Reliable

Messaging sequences.
AAA Policy
Specifies the name of an AAA Policy object to perform

authentication of incoming Reliable Messaging messages.
This AAA Policy can be the same one that is used in later
processing by the request or response rule. The results are
cached, so it is not evaluated again.
SSL session binding
Indicates whether to use an SSL session binding to protect

sequence lifecycle messages.
Destination Accept Incoming Indicates whether to accept incoming CreateSequence

CreateSequence
SOAP requests and create a Reliable Messaging destination
when one is received.
Destination Maximum
Simultaneous Sequences
Sets a limit on the maximum number of simultaneously

active sequences to Reliable Messaging destinations of this
DataPower service. Attempts by clients to create sequences
in excess of this limit result in a SOAP Faults.
Destination InOrder
Delivery Assurance
Indicates whether to enable InOrder delivery assurance for

Reliable Messaging destinations in addition to the standard
ExactlyOnce delivery assurance.
Destination Accept Two-Way Indicates whether to accept offers for two-way Reliable
Offers
Messaging in CreateSequence SOAP requests. If the request
includes an offer, the creation of a Reliable Messaging
destination creates a Reliable Messaging source to send
responses to the client.
40
Required on Request
Indicates whether to require the use of Reliable Messaging

for all SOAP messages that request rules process. The client
must establish a sequence with a CreateSequence SOAP call
and must include a Sequence in each SOAP header. Any
SOAP message without a Sequence results in a SOAP fault.
Required on Response
Indicates whether to require the use of Reliable Messaging

for all SOAP messages that response rules process. Any
SOAP message without a Sequence results in a SOAP fault.
Source Create Sequence on

Request
Indicates whether to create a Reliable Messaging source

from the back side to the server when there is SOAP data
to sent to the server and when there is no Reliable
Messaging source that was created by a MakeOffer from the
server. The Reliable Messaging source is created by sending
a CreateSequence SOAP request to the server address.
Source Create Sequence on

Response
Indicates whether to create a Reliable Messaging source

from the front side to the client when there is SOAP data to
send to the client and there is no Reliable Messaging source
that was created by a MakeOffer from the client by sending
a CreateSequence SOAP request to the WS-Addressing
ReplyTo address.
Table 8. Properties available on the WS-ReliableMessaging tab (continued)

Name
Purpose
Source Front Reply Point
Specifies the name of the handler object that receives the

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

Point
Specifies the name of the handler object that receives the

asynchronous Reliable Messaging SequenceAcknowledgement
SOAP responses from the server. This handler must be
associated with the same DataPower service where the
corresponding Reliable Messaging sequence is occurring.
Source Maximum
Simultaneous Sequences
Specifies a limit on the maximum number of

simultaneously active sequences from Reliable Messaging
sources of this DataPower server. Each remote Reliable
Messaging destination endpoint reference (URL) requires
one sequence. Transactions that request the creation of
sequences in excess of this limit result in a SOAP Fault.
XML threat protection

Using a coordinated set of configurations, you can maximize protection against
XML threats. Threats are malicious attempts to disrupt service. The DataPower
service provides the ability to protect against the following XML threats:
v Single message XML Denial-of-Service (XDoS)
v Multiple message XML Denial-of-Service (MMXDoS)
|
v
v
v
v
v
To
1.
2.
3.
4.
Message tampering
Padding oracle
SQL injections
XML viruses (X-Virus)
Dictionary attacks
protect against XML threats, perform the following steps:
Click the XML Threat Protection tab.
Defines all of the properties for threat protection, as needed.
Click Apply to save the changes to the running configuration.
Optional: Click Save Config to save the changes to the startup configuration.
Protecting against single message XML denial-of-service

attacks
These settings provide protection against a denial-of-service (DoS) attack when a
single malicious XML message is sent to the service. Many of the parameters that
provide this protection are set in the XML Manager object associated with the
service. This pane offers the opportunity to override the settings in the XML
Manager object with service-level settings.
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.
41
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:
42
Max Duration for a Request

Specify an integer setting the maximum number of milliseconds allowed
for processing any one request.
Interval for Measuring Request Rate from Host
Specify an integer setting the interval, in milliseconds, used for measuring
the rate of requests from any given host. The default of 1000 measures how
many requests per second are received from any given host.
Max Request Rate from Host
Specify an integer setting the maximum number of requests that can be
received, in the interval period, from any one host.
Interval for Measuring Request Rate for Firewall or Interval for Measuring
Request Rate for Gateway
Specify an integer setting the interval, in milliseconds, for measuring the
request rate for the entire service. The default of 1000 sets the interval at
requests per second.
Max Request Rate for Firewall or Max Request Rate for Gateway
Specify an integer setting the maximum number of requests that can be
received, in the interval period, by the service.
Block Interval
Specify an integer setting the period of time, in milliseconds, that the
service will block access after one of the other thresholds have been
reached.
Log Level
Select the log level at which log messages are generated by these threat
protection thresholds. When a threshold is reached, the service generates a
log message. This level determines the severity. Log targets capture
messages at or above a configured level. The default level for the default
log is notify.
Protecting against message tampering

Message tampering protection employs schema validation. Validation is performed
against submitted messages. Validation prevents messages that have been altered
and that no longer pass validation from reaching the back-end service endpoints.
To protect against message tampering, create a validate action. You can add this
action to an existing or new processing policy. Refer to Adding a validate action
|
Padding oracle protection
|
|
|
|
|
|
Protection against padding oracle prevents attackers from using error messages to
discover the plaintext data. Error messages after a decryption action can provide
an attacker who is using the padding oracle attack method with enough
information to determine the contents of the plaintext data. When enabled, the
appliance manipulates error messages to avoid revealing internal cryptographic
states.
|
|
|
|
|
Rewrite Error Messages

Controls whether to rewrite error messages to avoid providing a padding
oracle. When enabled, the default, the client receives error messages
without the internal information that could lead to a discovery. When
disabled, the client receives the original message with this information.
43
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 117 for more information.
XML virus
Viruses are typically contained in message attachments. XML Virus Protection sets
parameters that handle the following types of attacks in attachments:
v XML virus attacks
v XML encapsulation attacks
v Payload hijack attacks
v Binary injection attacks
First determine whether to process attachments. If you process attachments, define
an antivirus action to check attachments for viruses.
Controlling the processing of attachments

When the message type is SOAP or XML, configure how to process attachments in
the message. To configure a service for XML virus protection, provide the
following inputs:
Request attachment processing mode or Request Attachments
Specifies the processing mode for attachments in client requests.
Allow Processes the message root and needed XML and non-XML
attachments. Needed attachments are buffered. Attachments that
are not needed might be streamed directly to output.
Reject Rejects messages that contain attachments.
Strip
(Default) Removes attachments from the message and changes the

value of the Content-Type header to that of the root part.
Streaming
Provides limited processing of XML attachments, and streams XML
and non-XML attachments to output.
Unprocessed
Allows messages that contain attachments, but does not process
attachments.
For additional information about streaming attachments, refer to
Optimizing through Streaming.
Response attachment processing mode or Response Attachments
Specifies the processing mode for attachments in server responses.
44

Strip

Streaming
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 95 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. See Configuring count monitors on page 214.
See Adding an AAA action on page 95.
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, see
Building an IMS Connect URL on page 46.
v For information about using the utility to build a TIBCO EMS URL, see
Building a TIBCO EMS URL on page 46.
v For information about using the utility to build a WebSphere JMS URL, see
Building a WebSphere JMS URL on page 47.
45
v For information about using the utility to build a WebSphere MQ URL, see
Building a WebSphere MQ URL on page 47.
Building an IMS Connect URL

To
1.
2.
3.
use the IMS Connect URL builder for assistance in the construction of a URL:
Click IMS Connect Helper.
From the IMS Connect Config list, select an IMS Connect configuration.
In the Transaction Name field, specify the transaction name for the connection.
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
See the url-open extension element in the IBM WebSphere DataPower SOA
Appliances: Extension Elements and Functions Catalog for details about changing the
URL for a secure connection or for adding other query parameters.
Building a TIBCO EMS URL

To use the TIBCO EMS builder for assistance in the construction of a URL:
1. Click TIBCO EMS Helper.
2. From the Server list, select the TIBCO server.
3. In the Request Queue field, identify the queue or topic space for the request.
v To specify a queue, use the queue format.
v To specify a topic space, use the topic:topic-space format.
4. 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.
5. In the Selector field, specify an SQL 92 conditional expression to identify
messages of interest.
6. Set Request Reply Queue to indicate whether to use a temporary queue for the
reply from the server.
7. Set Transactionality to indicate whether the service enforces transactional
session in the communication. When enabled, 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.
8. Click Build.
dptibems://server/?RequestQueue=queue&ReplyQueue=queue&
Selector=expression&RequestReply=queue&Transactional=true
46
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. Set Request Reply Queue to indicate whether to use a temporary queue for
the reply from the server.
10. Set Transactionality to indicate whether the service enforces transactional
session in the communication. When enabled, 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.
11. Click Build.
dpwasjms://server/?RequestQueue=queue&ReplyQueue=queue&
Selector=expression&RequestTopicSpace=topic-space&
ResponseTopicSpace=topic-space&TimeOut=timeout&RequestReply=queue&Transactional=true
Building a WebSphere MQ URL

When constructing a service that uses WebSphere MQ for the back 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:
1. Click MQ Helper.
2. From the Queue Manager list, select an MQ Queue Manager.
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.
47
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. Set Transactionality 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. Set User Identifier to indicate whether to set the UserIdentity value in the
MQ header.
v If enabled, the builder inserts PMO=2052 in the URL. This value assumes the
following MQPMO options:
MQPMO_NO_SYNCPOINT (decimal 4, hexadecimal 0x00000004)
MQPMO_SET_ALL_CONTEXT (decimal 2048, hexadecimal 0x00000800)
v If disabled, the builder does not insert a value. The service assumes
MQPMO_NO_SYNCPOINT only.
11. Set ReplyToQ to indicate whether to set the ReplyToQ value in the MQMD
header for a request message.
v If enabled, inserts SetReplyTo=true in the URL. The processing policy
overwrites the ReplyToQ value with the value of the ReplyQueue option.
v If disabled, 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.
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.
Note: Load Balancer Group configurations is not supported when SSH FTP
Protocol is the back-end destination.
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 276 for more
information.
48
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
367 for more information.
3. Create a DataPower service, for example the LBFirewall XML Firewall, and
configure the following properties:
a. Select the LBManager XML Manager from the XML Manager list.
b. Specify LBGroup (the Load Balancer Group) as the address of the 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 267.
49
50
Chapter 6. Handler configuration

You can create and manage the following handler objects:
FTP Poller Front Side Handler
Creates an FTP poller handler to poll for available input.
FTP Server Front Side Handler
Creates an FTP traffic handler.
HTTP Front Side Handler
Creates an HTTP traffic handler
HTTPS (SSL) Front Side Handler
Creates an HTTPS traffic handler
IMS Connect Handler
Creates an IMS traffic handler.
MQ Front Side Handler
Creates an MQ traffic handler
NFS Poller Front Side Handler
Creates an NFS poller handler to poll for available input.
SFTP Poller Front Side Handler
Creates an SFTP poller handler to poll for available input.
SFTP Server Front Side Handler
Creates an SFTP traffic handler
Stateful Raw XML Handler
Creates a nonsecure TCP-based relay or forwarding service.
Stateless Raw XML Handler
Creates a secure SSL-based relay or forwarding service.
TIBCO EMS Front Side Handler
Creates a TIBCO EMS traffic handler
WebSphere JMS Front Side Handler
Creates a default WebSphere JMS traffic handler
These handlers can be used with a DataPower service. To access these handlers,
use the Objects Protocol Handlers menu.
Configuring an FTP poller handler

An FTP Poller Handler manages the polling of the remote FTP server for available
input with DataPower services.
To configure an FTP Poller Front Side Handler:
1. Click Objects Protocol Handlers FTP Poller Front Side Handler.
2. Click Add.
configuration.
51

5. Optional: In the Comments field, enter a descriptive summary.
6. Specify the directory to poll in the Target Directory field. The path must end
in a slash. The slash denotes a directory.
For an absolute path to the root directory
ftp://user:password@host:port/%2Fpath/
Note: If the user name or password contains the characters :, @,
or /, use their URL-encoded values in accordance with the
specification.
For a relative path to the home directory of the specified user
ftp://user:password@host:port/path/
Do not configure one FTP poller to point at a host name that is a virtual name
of a load balancer group. This configuration is not the correct way to poll
multiple hosts. To poll multiple hosts, use the same DataPower service and
configure one FTP poller object for each real host.
7. Specify the number of milliseconds to wait after the completion of one poll
before starting the next interval in the Delay Between Polls field.
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:
NNNNNN.processing.serial.domain.poller.timestamp
52
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. Set Delete File on Success to indicate 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. Set Delete File on Processing Error to indicate 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. Set Generate Result File to indicate 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. When 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
integer in the range of 0 through 1000. The default is 0.
53
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.
14.
15.
16.
17.
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.
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. The value 0 means unlimited number of connections
based on available system resources.
Configuring an FTP server handler

An FTP server handler manages FTP protocol communications with DataPower
services.
An FTP server handler 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
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.
54
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.
Defining as transparent
To configure an FTP Server Handler to access a transparent file system:
1. Select Objects Protocol Handlers FTP Server Front Side Handler to
display the catalog.
55
2. Click Add to display the configuration screen.

configuration.
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.
8. Select an instance of the Access Control List object to apply from the Access
Control List list.
9. Define secure connection.
a. Set Require TLS to indicate 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.
b. Select an instance of the SSL Proxy Profile object to assign from the SSL
Proxy list.
10. Define user authentication.
a. Select an instance of the AAA Policy object from the Password AAA
Policy list. This instance performs authentication of user names and
passwords provided to the FTP server by the client with the USER and
PASS commands. If the authentication succeeds, the FTP client can use all
of the features of the FTP server. If the authentication fails, a 530 error is
returned, and the user can attempt to authenticate again. If no Password
AAA Policy is configured, any user name and password is accepted.
b. Select an instance of the AAA Policy object from the Certificate AAA
Policy list. This instance performs secondary authentication of the
information in the TLS/SSL certificate that is provided during TLS
negotiation after the AUTH TLS command to the FTP server. Primary
authentication is done by the SSL Proxy Profile, which can completely
reject a certificate. This authentication stage controls whether an FTP
password will be demanded or not. If the result of this authentication
succeeds, the FTP client will only have to use the USER command to login
after the AUTH TLS. If this authentication fails, the FTP client will have to
56
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. Set Allow CCC Command to indicate 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.
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, set Limit Port Range for Passive
Connections 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.
b) Specify the upper end of the range in the Maximum Passive Port
field.
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) Set Disable Passive Data Connection (PASV) IP Security Check to
specify whether to disable the IP security check that verifies that the
incoming data connection comes from the already connected client.
5) Set Disable Active Data Connection (PORT) IP Security Check to
specify whether to disable the IP security check that verifies that
outgoing data connections can only connect to the client.
6) Define behavior for alternate IP address support.
a) Set Use Alternate PASV IP Address to select the behavior for
alternate IP address support.
b) If allowing support, use the Alternate PASV IP Address field to
specify the numeric IP address.
c. Set Enable LIST command support to specify whether the FTP server
distinguishes between the LIST command and the NLST command. Disable
this option to respond to either command with an NLST command. This
option only applies to transparent file systems.
d. Set Enable delete support to specify whether file delete commands are
allowed on the FTP server. This option only applies to transparent file
systems.
e. Select the use of encryption for data connections (file transfers) from the
File Transfer Data Encryption list. Data encryption is controlled by the
FTP PROT P command. The default is Allow Data Encryption.
57
f. Set Allow Compression to specify 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.
g. Define behavior for unique file names
1) Set Allow Unique File Name (STOU) to specify whether the FTP client
can use the FTP STOU command. When enabled, the FTP server
generates a unique file name for each transferred file.
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

To configure an FTP Server Handler to access a virtual ephemeral file system:
1. Click Objects Protocol Handlers FTP Server Front Side Handler.
2. Click Add.
configuration.
systems.
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
58
Control List list.
a. Set Require TLS to specify 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.
Proxy list.
a. Set Allow CCC Command to specify whether the FTP CCC command can
field.
59
field.
Idle Timeout field.
a) Set Use Alternate PASV IP Address to specify the behavior for
c. Select the use of encryption for data connections (file transfers) from the
FTP PROT P command. The default is Allow Data Encryption.
d. Set Allow Compression to select whether the FTP client can use FTP
e. Define behavior for unique file names
1) Set Allow Unique File Name (STOU) to select whether the FTP client
an empty string.
closes the control connection. Defaults to 0, which disables the timeout.
13. Define response behavior and storage for responses.
a. Select how to make response files available for gateway transactions
started the FTP STOR or SOUT operation from the Response Type list.
b. If FTP Client, which indicates that the response is written by the FTP
client:
1) Specify the suffix to add when generating response files in the
Response Suffix field. The directory separator (/) is not allowed. The
suffix should be in the ^[^/]*$ format. Defaults to an empty string.
2) specify the URL to use when generating response files in the Response
URL field. This URL enables a response to be written using FTP
commands. The URL must be an FTP URL that starts with ftp://. The
URL should include a directory, but not a file name. The URL cannot
include query parameters. The URL should be in the
^(|ftp://[^/]+(/[^/]+)*)$ format. The default is to have no response
generated (an empty string).
3) Specify the maximum size in megabytes for the temporary file system
in the Temporary Storage Size field.
60
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.
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.
Defining as virtual persistent

To configure an FTP Server Handler to access a virtual persistent file system:
1. Click Objects Protocol Handlers FTP Server Front Side Handler.
2. Click Add.
configuration.
61
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.
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
Control List list.
a. Set Require TLS 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.
Proxy list.
62

a. Set Allow CCC Command to select whether the FTP CCC command can
field.
field.
Idle Timeout field.
a) Set Use Alternate PASV IP Address to specify the behavior for
c. Select the use of encryption for data connections (file transfers) from the
FTP PROT P command.
d. Set Allow Compression to select whether the FTP client can use FTP
e. Define behavior for unique file names
1) Set Allow Unique File Name (STOU) to select whether the FTP client
63
an empty string.
f. Define the restart behavior:
1) Set Allow Restart (REST) to indicate whether to support the REST
command to continue the transfer of a file after an interruption in the
data transfer.
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.
closes the control connection. The value 0 disables the timeout.
13. Define response behavior and storage for responses.
a. Select how to make response files available for gateway transactions
started the FTP STOR or SOUT operation from the Response Type list.
The default is No Response.
b. If FTP Client, which indicates that the response is written by the FTP
client:
1) Specify the suffix to add when generating response files in the
Response Suffix field. The directory separator (/) is not allowed. The
suffix should be in the ^[^/]*$ format. Defaults to an empty string.
2) specify the URL to use when generating response files in the Response
URL field. This URL enables a response to be written using FTP
commands. The URL must be an FTP URL that starts with ftp://. The
URL should include a directory, but not a file name. The URL cannot
include query parameters. The URL should be in the
^(|ftp://[^/]+(/[^/]+)*)$ format. The default is to have no response
generated (an empty string).
3) Specify the maximum size for the temporary file system in the
Temporary Storage Size field.
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.
64
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.
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.
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 handler manages HTTP protocol communications with DataPower
services.
To configure an HTTP handler:
1. Click Objects Protocol Handlers HTTP Front Side Handler.
2. Click Add.
configuration.
v
v
To make inactive, click disabled.

To make active, click enabled.

a. In the Local IP Address field, enter the host alias or IP address on which
the service listens. The default value is 0.0.0.0, which indicates that the
service is active on all IP addresses.
systems.
b. In the Port Number field, enter the listening port. The default value is 80.
65
7. From the HTTP Version to Client list, select the HTTP version to use on the
client connection.
8. Set the Allowed Methods and Versions check boxes to select the allowed
methods and versions for incoming HTTP requests.
9. Set Persistent Connections to enable or disable the negotiation of persistent
connections.
10. Set Compression to enable or disable the negotiation of GZIP compression.
11. Define HTTP header and URL limits.
a. In the Maximum Allowed URL Length field, enter the length of the
longest incoming URL to accept in bytes. The length includes any query
string or fragment identifier.
b. In the Maximum Allowed Total Header Length field, enter the maximum
aggregate byte size of incoming HTTP headers.
c. In the Maximum Number of HTTP Request Headers Allowed field, enter
the maximum number of headers allowed in the request message. The
value 0 means unlimited.
d. In Maximum Allowed Length of HTTP Header Name field, enter the
maximum length of the name part of a header. Each HTTP Header is
expressed as a name-value pair. The value 0 means unlimited.
e. In Maximum Allowed Length of HTTP Header Value field, enter the
maximum length of the value part of a header. Each HTTP Header is
f. In Maximum Allowed Length of HTTP Query String field, enter the
maximum length of the query string. The value 0 means unlimited.
12. From the Access Control List list, select the Access Control List to apply.
Configuring an HTTPS handler

An HTTPS handler manages HTTPS protocol communications with DataPower
services.
To configure an HTTPS handler:
1. Click Objects Protocol Handlers HTTPS Front Side Handler.
2. Click Add.
configuration.
v
v


a. In the Local IP Address field, enter the host alias or IP address on which
the service listens. The default value is 0.0.0.0, which indicates that the
service is active on all IP addresses.
systems.
66
b. In the Port Number field, enter the listening port. The default value is 443.
7. From the HTTP Version to Client list, select the HTTP version to use on the
client connection.
8. Set the Allowed Methods and Versions check boxes to select the allowed
methods and versions for incoming HTTP requests.
9. Set Persistent Connections to enable or disable the negotiation of persistent
connections.
10. Set Compression to enable or disable the negotiation of GZIP compression.
11. Define HTTP header and URL limits.
a. In the Maximum Allowed URL Length field, enter the length of the
longest incoming URL to accept in bytes. The length includes any query
string or fragment identifier.
b. In the Maximum Allowed Total Header Length field, enter the maximum
aggregate byte size of incoming HTTP headers.
c. In the Maximum Number of HTTP Request Headers Allowed field, enter
the maximum number of headers allowed in the request message. The
value 0 means unlimited.
d. In Maximum Allowed Length of HTTP Header Name field, enter the
maximum length of the name part of a header. Each HTTP Header is
e. In Maximum Allowed Length of HTTP Header Value field, enter the
maximum length of the value part of a header. Each HTTP Header is
f. In Maximum Allowed Length of HTTP Query String field, enter the
maximum length of the query string. The value 0 means unlimited.
12.
13.
14.
15.
From the SSL Proxy list, select the SSL Proxy Profile to assign.
From the Access Control List list, select the Access Control List to apply.
Configuring an IMS Connect handler

An IMS Connect Handler manages IMS protocol communications with DataPower
services.
To configure an IMS Connect Handler, use the following procedure:
1. Click Objects Protocol Handlers IMS Connect Handler.
2. Click Add.
configuration.
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.
67
7.
8.
9.
10.
Host Alias allows you to specify a locally configured alias that resolves to a
static IP address. Aliasing can help when moving configurations across
systems.
Specify the port that the IMS listener monitors in the Port Number field. The
default is 3000.
Select an SSL Proxy Profile to assign from the SSL Proxy list.
Set Persistent Connections to enable or disable persistent connections on the
frontend, when appropriate.
Set EBCDIC Input Header Encoding 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 the maximum segment size in KB.
The value 0 disables segmentation.
v A Maximum Segment Size of 0 disables IMS message segmenting. With
message segmenting disabled, you must use a policy to handle an IMS
message with a segmented payload and with LL and ZZ segment headers.
v A Maximum Segment Size in the range from 1 to 32 enables message
segmenting and specifies the maximum segment size. Request side
processing receives an incoming multi-segment IMS message and strips the
LL and ZZ segment headers to send a message with one continuous payload
to the request side policy. Response side processing splits the message into
multiple segments of the specified size and adds the appropriate LL and ZZ
segment headers after the response side policy processing finishes. The
headers are handled the same for a message with a payload smaller than
the Maximum Segment Size.
Note: The Maximum Segment Size specifies the maximum segment size in
KB into which a message is split when sending to an IMS client. This
does not limit the segment size of a request message. The DataPower
appliance can accept a request message up to a maximum segment
size of 64 KB from an IMS client.
Configuring an NFS poller handler

An NFS Poller Handler manages the polling of the remote NFS server for available
input with DataPower services.
To configure an NFS Poller Handler:
1. Click Objects Protocol Handlers NFS Poller Front Side Handler.
2. Click Add.
configuration.
v
68

6. Specify the directory to poll in the Target Directory field. The path must end
in a slash. The slash denotes a directory. For example, dpnfs://static-mountname/path/. Do not configure one NFS poller to point at a host name that is a
virtual name of a load balancer group. This configuration is not the correct
way to poll multiple hosts. To poll multiple hosts, use the same DataPower
service and configure one NFS poller object for each real host.
7. Specify the time to wait after the completion of one poll before starting the
next interval in the Delay Between Polls field.
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
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
match pattern.
where:
filename
serial

poller
timestamp
The timestamp.
Note: File renaming cannot be used with an NFS server that supports only 8.3
file names.

10. Define the process for deleting files on success.
a. Set Delete File on Success to select whether to delete the input file after
successful processing.
on
Deletes the input file.
off
(Default) Renames the input file using the renaming pattern

specified by the Success File Renaming Pattern property.
69
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
../processed/$1.
a. Set Delete File on Processing Error to select whether to delete the input or
processing rename file when it could not be processed.
on
Deletes the file.

property.
a. Set Generate Result File to select whether to create a result file after
off
on
off
b. If 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
../result/$1.
in the processing state in the Processing Seize Timeout field. Use an
integer in the range of 0 through 1000. The default is 0.
70
the timestamp.
14. Select the XML Manager that contains the User Agent configuration to use
15. In the Maximum File Transfers Per Poll Cycle field, specify the number of
concurrent connections. The 0 means an unlimited number of connections
based on available system resources.
Configuring an SFTP poller handler

An SFTP Poller Handler manages the polling of the remote SFTP server for
available input with DataPower services.
To configure an SFTP Poller Handler:
1. Click Objects Protocol Handlers SFTP Poller Front Side Handler.
2. Click Add.
configuration.
v
v


6. In the Target Directory field, specify the directory to poll. The path must end
in a slash. The slash denotes a directory.
For an absolute path to the root directory
sftp://host:port/path/
For a relative path to the home directory of the specified user
sftp://host:port/~/path/
Do not configure one 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 poller object for each real host.
7. In the Delay Between Polls field, specify the number of milliseconds to wait
after the completion of one poll before starting the next interval.
8. In the Input File Match Pattern field, specify the PCRE to use to match the
contents of the directory being polled. If there is file-renaming or there is a
be ([0-9] {6})\.input.
9. Optional: In the Processing File Renaming Pattern field, specify the PCRE to
use to rename a file that is being processed. This functionality allows multiple
71
match pattern.
where:
filename
serial

poller
timestamp
The timestamp.
Note: File renaming cannot be used with an SFTP server that supports only
8.3 file names.

10. Optional: In the Delete File on Success field, define the process for deleting
files on success. When enabled the input file is deleted after successful
processing. When disabled 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
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.
a. Set Delete File on Processing Error to select whether to delete the input or
processing rename file when it could not be processed.
on
Deletes the file.

property.
a. Set Generate Result File to select whether to create a result file after
off
72
on
off
b. When 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
../result/$1.
in the processing state in the Processing Seize Timeout field. Enter any
value of 0 - 1000. The default is 0.
the timestamp.
14. Select the XML Manager that contains the User Agent configuration to use
15. In the Maximum File Transfers Per Poll Cycle field, specify the number of
concurrent connections. The value 0 means an unlimited number of
connections based on available system resources. To avoid the consumption of
all the systems resources, enter a value other then 0.
16. In the SSH Client Connection field, specify the name of an existing SSH
Client Profile. The SSH Client Profile describes how SSH connections are
made from the SSH client to an SSH server.
73
Configuring an SFTP server handler

An SFTP Server Handler manages SSH File Transfer Protocol (SFTP)
communications protocol communications with DataPower services. These services
support client-side, SFTP communications when configured with an instance of the
SFTP Server Front Side Protocol Handler object. SFTP uses Secure Shell version 2,
which is known as SSH-2. This program provides the secure channel between the
SFTP client and the SFTP Server Front Side Handler associated with a DataPower
service.
Configuration considerations
Consider the following settings when configuring a Multi-Protocol Gateway
service:
v When transferring large files, use the streaming setting. To support bidirectional
streaming, set both Stream Output to Back and Stream Output to Front to
Stream Messages. For complete information, see Optimizing through Streaming.
v For large files, set the back and front timeout values appropriately with the Back
Side Timeout and Front Side Timeout fields, respectively.
Authentication and authorization

Authentication is handled by the AAA Policy configured for the SFTP Server Front
Side Handler. The AAA Policy uses the information from the SSH key exchange.
Without an AAA Policy, any user is authenticated.
Authentication of the SFTP client with the SFTP Server Front Side Handler can be
either password or public key or both password and public key. If the
configuration includes both authentication methods, public key authentication is
attempted first.
v Host authentication public/private key needs to be and are stored on the
appliance.
v Keys used as host private keys cannot be password protected.
v If a configuration does not specify the public/private key for host
authentication, the configuration uses the keys that are shipped with the
appliance.
Because at connection time the client does not specify which resource to access,
this AAA Policy can perform authentication only, not authorization.
To provide authorization, configure an AAA Policy in a processing rule. For this
AAA Policy, extract the identity using the ssh-password-metadata instance of the
Processing Metadata object.
SSH metadata variables

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

information from the SSH client to the handler.
The username and password variables are also available as processing metadata for
custom authentication in an AAA Info file.
None of these variables can be used by processing actions.
URL specifications with an SFTP handler

The use of SFTP URLs within custom style sheet is supported for communication
between the SFTP client and the SFTP Server Front Side Handler.
The URL has the following syntax:
sftp://address:port/path
Where:
address The IP address of the DataPower Ethernet interface
port
The SFTP Server Front Side Handler listening port
path
The fully qualified name of the file to transfer
When the client requests a directory listing, the URL contains a query parameter to
flag the request type. For example, a DIR request might generate the following
URL:
sftp://host.example.com:22/;type=d
The ;type=d query parameter is appended to the URL to designate the DIR request.
v If the Multi-Protocol Gateway service uses a static backend, the service adds the
?Listing=LIST query parameter before forwarding the request to the remote FTP
server.
v If the Multi-Protocol Gateway service uses either a dynamic backend or
Propagate URI is set to off, use a custom style sheet to modify the URL before
passing the request to the remote FTP server. For example, the style sheet might
test whether the value of the var://service/URI variable contains ;type=d. If it
contains this query parameter, the style sheet replaces ;type=d with
?Listing=list and sets the value of the var://service/routing-url variable to
the resultant URL.
v When the client requests to delete a file and the Allow Delete is enabled, the
URL contains a query parameter to flag the request type. For example:
sftp://host.example.com:22/orders.xml?Delete=true. The Delete=true query
parameter is appended to the URL to designate that the file named orders.xml
will be deleted.
Configuring an SFTP Server handler

To configure SFTP Server Handler:
1. Click OBJECTS Protocol Handlers SFTP Server Front Side Handler.
2. Click Add.
configuration.
75

a. Specify the IP address on which the SFTP server listens in the Local IP
systems.
b. Specify the port that the SFTP Server service monitors in the Port Number
field. This port is the port on which SSH connections can be established.
The default is 22.
7. Select an Access Control List from the Access Control List list.
8. Define the user authentication method.
a. Optionally, use the Host Private Keys controls to assign one or more Key
objects to use for host authentication. Keys used as host private keys
cannot be password protected.
If the appliance has HSM hardware, the Crypto Key objects can be HSM
generated keys specified as hsm:// in the key object.
Without keys, the configuration uses the default RSA and DSA keys
shipped on the appliance. Keys highest in the list are used first. There is a
limit of 256 keys. Only SSH-2 RSA and DSA keys are allowed.
b. Select Public Key or Password for the SSH User Authentication methods
available to the client. At least one method is required. If both are selected,
public key authentication is attempted first.
9. Set Allow Backend Listings to specify whether to allow directory listings of
the remote FTP server.
10. Set Allow Delete to specify whether to delete files on the remote FTP server.
11. Select the AAA policy from the AAA Policy list.
Note: Although optional, without an AAA Policy, all users are authenticated.
a. In the Filesystem Type list, specify the file system type.
b. In the Default Directory field, specify the initial directory on the SFTP
server (after users connect and authenticate). The default is the root
directory (/).
13. In the Idle Timeout field, specify the number of seconds that the SSH
connection can be idle. After the specified duration elapses, the SSH server
closes the connection. The default is 0, which disables the timeout.
14. If Filesystem Type is Virtual Ephemeral, complete the following steps:
b. Click Add.
c. In the Virtual Directory field, specify the directory in the virtual file
system of the SFTP server.
d. Click Apply.
15. If Filesystem Type is Virtual Persistent, complete the following steps:
a. In the Persistent Filesystem Timeout field, specify the timeout value in
seconds.
b. Click the Virtual Directories tab.
76
c. Click Add.
d. In the Virtual Directory field, specify the directory in the virtual file
system of the SFTP server.
e. Click Apply.
Configuring a stateful raw XML handler

A Stateful Raw XML Handler manages 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. Click Objects Services Stateful Raw XML Handler.
2. Click Add.
configuration.
v
v


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. Set Terminate Session On Fault to select the behavior of closing TCP
connections on a fault.
v If enabled, both the front and back TCP connections are closed when the
DataPower appliance generates a fault.
v If disabled, 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.
77
Configuring a stateless raw XML handler

A Stateless Raw XML Handler manages 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.
Click Objects Services Stateless Raw XML Handler.
Click Add.
Set Administrative State to identify the administrative state of the
configuration.
on all addresses.
1.
2.
3.
4.
7.
8.
9.
10.
11.
12.
systems.
Specify the port monitored by the handler in the Port Number field. The
default is 4000.
Set Persistent Connections to enable or disable persistent TCP connections.
When enabled, 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.
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.
Configuring a TIBCO EMS handler

A TIBCO EMS Front Side Handler object enables support for the processing of
messages in TIBCO EMS format. TIBCO EMS supports queues and topic spaces.
This handler requires the TIBCO-EMS license and is available on the following
appliances only:
v Integration Appliance XI50
v B2B Appliance XB60
v Low Latency Appliance XM70
While the protocol handler does not provide native support for TIBCO
Rendezvous and TIBCO SmartSockets (TIBCO legacy messaging systems), TIBCO
EMS has built-in transports for these messaging implementations, which enables
message transfers.
Using topic spaces

A topic space is a hierarchy of topics used for publish-subscribe messaging. Topics
with the same name can exist in multiple topic spaces, but there can be only one
topic space with a given name in a service integration bus.
78
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 332.
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.
configuration.
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.
79
The message selector is a conditional expression based on a subset of SQL 92

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

A WebSphere JMS Front Side Handler object enables support for the processing of
messages in default WebSphere JMS format. WebSphere JMS supports queues and
topic spaces.
This handler is available on the following appliances only:
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.
configuration.
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.
81
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.
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
82
Configuring a WebSphere MQ handler

An MQ Front Side Handler object handles MQ protocol communications with
DataPower services.
This handler is available on the following appliances only:
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. See Defining the basic
configuration for details.
4. Define the publish and subscribe configuration. These fields are only supported
with WebSphere MQ V7 queue managers. See Defining the publish and
subscribe configuration on page 84 for details.
5. Define the properties and headers configuration. See Defining the properties
and headers configuration on page 85 for details.
6. Define the advanced configuration. See Defining the advanced configuration
on page 85 for details.
Defining the basic configuration

To define the basic configuration for an MQ Front Side Handler:
configuration.
3.
4.
5.
6.
7.
8.

Optional: In the Comments field, enter a descriptive summary.
From the Queue Manager list, select a queue manager.
In the Get Queue field, specify the name of the GET queue.
In the Put Queue field, specify the name of the PUT queue.
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.
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).
83
See the MQGMO_* (Get Message Options) topic in the Constants section
of the WebSphere MQ Information Center for details.
When a message is too large for a queue, an attempt to put the message on
the queue fails. Segmentation is a technique that allows the queue manager or
application to split the message into smaller pieces, and place each segment
on a queue as a separate physical message. The application that retrieves the
message can either handle the multiple segments one-by-one, or request the
queue manager to reassemble the segments into a single message that is
returned by the MQGET call. The reassembly request is achieved by
specifying the MQGMO_COMPLETE_MSG option (65536) on the MQGET call, and by
providing a buffer large enough to accommodate the entire message.
Note: Ensure that the associated queue manager supports the
MQGMO_COMPLETE_MSG option. On z/OS, MQ queue managers do not
support segmentation. On other operating systems, MQ queue
managers might not be configured to support segmentation.
9. In the Polling Interval field, specify the number of seconds before an
MQGET operation returns if no messages are available. The next attempt will
be performed immediately. Setting a low value will help to detect quickly
network connectivity issues and queue manager power shutdown. At the
same time, a low value will increase network traffic. The minimum is 1. The
default is 30.
10. Use the Retrieve Backout Settings field to determine whether to retrieve the
backout threshold and backout queue name from the MQ server.
on
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.
(Default) Do not retrieve backout settings from the MQ server. If these

properties already exist in the MQ Queue Manager object, the
appliance use those values.
11. Use the Use Queue Manager in URL field to determine whether the
var://service/URL-in variable returns the name of MQ Queue Manager or
the name of the MQ Queue Manager Group when this configuration defines a
queue manager group as the queue manager.
off
on
The variable returns the name of the queue manager
off
(Default) The variable returns the name of the queue manager group.
12. In the CCSI field, specify the Coded Character Set Identifier (CCSID) that the
remote MQ queue manager converts output data. The default CCSID is for
ISO-8859-1 (latin-1). For a list of CCSID, see the following web site:
http://www.ibm.com/software/globalization/ccsid/ccsid_registered.jsp
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.
84
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)
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:
85
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.
86
Chapter 7. 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 policy builder 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.
87
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 95.
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. See Adding an AAA
action on page 95 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. See Adding an antivirus action on page 95 for details.
Call processing
A call action invokes a named, reusable rule. After the action completes,
processing continues to the next action, if any. See Adding a call
processing rule (call) action on page 97 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. See Adding a
checkpoint event (checkpoint) action on page 97 for details.
Conditional
A conditional action implements programmatic if-then-else processing. If an
XPath expression returns true when applied to the input context of the
action, a designated processing action runs. Any number of if-then clauses
can be configured. A final else clause that uses an empty XPath expression
() runs a designated action when no other XPath expression matches the
input. You can designate a call action. The call action provides the ability
88
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. See Adding a convert query
parameters to XML (convert-http) action on page 99 for details.
Crypto binary
A cryptobin action signs, verifies, encrypts, or decrypts binary data. This
action uses the syntax and methodologies that are described in RFC 2311,
S/MIME Version 2 Message Specification, dated March 1988, and RFC 2315,
PKCS #7: Cryptographic Message Syntax 1.5, dated March 1998. This action
requires that the appliance has the PKCS7-SMIME feature. See
Cryptographic binary (cryptobin) action on page 99 for details.
Decrypt
A decrypt action performs full or field-level document decryption. See
Adding a decrypt action on page 107 for details.
Encrypt
An encrypt action performs complete or field-level document encryption
using either WS-Security or XML encryption standards. See Adding an
encrypt action on page 109 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. See Adding an extract using XPath
(extract) action on page 116 for details.
Fetch
A fetch action uses a user agent to retrieve a document from a specified

location. See Adding a fetch action on page 116 for details.
Filter
A filter action accepts or rejects check on incoming documents. See Filter

actions on page 117 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
89
results in a separate output context. These output contexts are available to

any other action in the processing policy. See For each (for-each) action
Log
The log action is for transaction logging, not event logging to a log target.
This action takes a copy of a particular message payload and sends it to a
log destination for auditing purposes. This action requires a destination
URL and will send the input context to the defined endpoint. The message
is wrapped in the same schema as the SOAP log target. The message
contains all the standard log metadata fields (timestamp, category, client IP
address, and so forth), and the payload is inserted into the message field.
The contents are sent with the defined log priority and log category. The
response, if any, is stored in the output context, if one is defined. See
Adding a log action on page 122 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.
See Adding an on-error action on page 126 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. See Adding a results
action on page 128 for details.
Results asynchronous
A results-async action asynchronously sends a message to a URL. This
action does not support sending a message to an output context. With this
action, processing continues without waiting for a response. See Adding a
results asynchronous (results-async) action on page 129 for details.
Rewrite header
A rewrite action rewrites HTTP headers or URLs using a URL rewrite
policy. See Adding a rewrite header (rewrite) action on page 130 for
details.
Rewrite HTTP method
A rewrite-method action rewrites the HTTP method. See Adding a method
rewrite action on page 130 for details.
Route with style sheet or XPath
A route-action action performs style sheet-based routing or XPath
90
expression-based routing. See Adding a route with style sheet

(route-action) action on page 131 and Adding a route with XPath
expression (route-action) action on page 131, respectively, for details.
Route with variables
A route-set action performs dynamic, variable-based routing. See Route
with variables (route-set) action on page 132 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. See Adding a set variable (setvar) action
Sign
A sign action attaches a digital signature to the document. See Adding a

sign action on page 133 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. Refer to Adding an
SLM action on page 135 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 feature. See Adding an SQL action on page 135 for details.
Strip attachments
A strip-attachments action removes all or specified MIME attachments from
a specified context. See Adding a Strip Attachments action on page 136
for details.
Transform
An xform action transforms an XML document using a specified XSLT style
sheet. See Transform-type actions on page 137 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 feature. See Adding a transform (xformbin) for non-XML
messages on page 138 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.
See Adding a processing instruction-based transform for XML messages
91
Validate
A validate action performs schema-based validation against XML
documents using a user-specified method. See Adding a validate action
Verify A verify action validates the digital signature on an incoming document.
See Adding a verify action on page 144 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.
Note: When not using a two-way rule, contexts persist between request and
response.
When using attachments and the output context already exists, the transform will
not create attachments for the output context. However, if the output context does
not exist prior to the transform, the new output context will contain the
attachments from the input context, subject to any processing from the action.
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.
92
v For a server-to-client rule, the OUTPUT context is the data that is sent to
the client.
NULL
Can be used as an input or output.

v As the input for an action, the NULL context indicates that the action
processes an empty XML document.
v As the output for an action, the NULL context indicates that the action
discards any data that it receives from processing.
PIPE
The output of an action becomes the input to the next action. As such, any
action that uses the PIPE context as output must be followed by an action
that uses the PIPE context as input. The PIPE context is useful in certain
instances to reduce processing latency. The PIPE context is the correct
choice for streaming operations.
__JSONASJSONX
Valid as the input to an action when the service request type or response
type is JSON. The __JSONASJSONX context contains the data that is
associated with the request or the response after the data is validated as
well-formed JSON as described in RFC 4627 and converted to JSONx. As
with any other XML, the processing policy actions can manipulate JSONx.
If it is necessary to convert back to JSON, an explicit transformation action,
possibly specifying jsonx2json.xsl, can be applied.
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 rule's directives. The Matching action acts as a gatekeeper at the start
of the rule to determine which documents the rule should handle. Matches can be
based on HTTP header tag values, URLs, XPath expressions, or error codes.
Rules are maintained in a particular order in a single policy. Candidate documents
presented to the processing policy are sequentially evaluated against each of the
rules in the policy. Consequently the order of rules is critical to ensure the
intended behavior.
Error rules are the exception to this behavior. Regardless of where the error rule is
in the processing policy, an error rule runs last and only when there are errors
during the processing of any the other rules.
For example, Figure 8 on page 94 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.
93
Figure 8. Action order of processing rule
Creating a processing policy

To create a processing policy:
1. Display the processing policy catalog for the DataPower service:
v For an XML Firewall, click Services XML Firewall XML Firewall Policy
v For a Multi-Protocol Gateway, click Services Multi-Protocol Gateway
Multi-Protocol Gateway Policy
2. Click Add New Policy to display the processing policy configuration screen.
3. In the Policy Name field, specify the name of the processing policy.
4. In the Rules section, click New Rule to define a processing rule for this
Processing Policy. For Web Service Proxy services, click Add Rule. The Rule
Name field contains an auto-generated name.
5. Modify the name of the rule as appropriate.
6. Select the directory of the rule or indicate that the rule is an error-handling rule
from the Rule Direction list.
Both Directions
The rule applies to all traffic going through the service.
Error
Identifies the rule as an error-handling rule. This rule is invoked only

when an error occurs during processing.
Client to Server
The rule applies to client-generated requests that go through the
service. Client requests arrive at front addresses to the service.
Server to Client
The rule applies to server-generated responses that go through the
service. Server responses arrive at back addresses to 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 rules on page 290 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.
94
To add additional processing rules to the processing policy, repeat step 4 on page
94 through step 9 on page 94.
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 152 for complete information about creating an AAA policy.
5. Set Asynchronous to indicate whether to process asynchronously. If enabled,
the action does not need to complete before the rule starts processing its next
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 for the rule, click Apply Policy. Otherwise, drag another
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).
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.
action.
7. Determine the type of antivirus scan with the Anti-Virus Scan Type radio
buttons.
v To scan the message body and attachments, click Scan Entire Message.
v To scan attachments only, click Scan All Attachments.
v To scan attachments only when the Content-Type header matches a PCRE:
a. Click Scan Attachments by Content Type
b.
v To
a.
b.
v To
Specify the PCRE in the Attachment Content-Type (PCRE) field.

scan attachments only when the URI matches a PCRE:
Click Scan Attachments by URI
Specify the PCRE in the Attachment URI (PCRE) field.
scan only the contents of a message that matches an XPath expression:
95
a. Click Scan by XPath Expression

b. Specify the XPath expression in the XPath field.
For assistance in creating the XPath expression, click XPath Tool. This
tool allows you to load an XML document and build the expression by
selecting the desired mode.
8. Determine which ICAP Host to use for the Virus Scanner server with the
ICAP Host Type radio button.
v To use a Clam ICAP host on a Virus Scanner server, click Clam.
v To use a Symantec ICAP host on a Virus Scanner server, click Symantec.
v To use a Trend Micro ICAP host on a Virus Scanner server, click Trend
Micro.
v To use a Webwasher ICAP host on a Virus Scanner server, click Webwasher.
v To use a Custom ICAP client on a Virus Scanner server:
a. Click Custom.
b. (Scroll to the top of the screen.) Use the Processing Control File field or
specify the style sheet to perform document filtering and
transformations.
If the style sheet is not stored on the appliance, specify its location or
a variable that expands to a URL. If a variable, use the
var://context/name form.
If the style sheet is in the store: or local: directory, select the style
sheet.
You can click Upload or Fetch to obtain the file.
9. Specify the host name of the Virus Scanner in the Remote Host Name field.
10. Optionally specify the Remote Port of the Virus Scanner in the Remote Port
field.
11. Optionally specify the Remote URI of the Virus Scanner in the Remote URI
field.
12. Determine the behavior of the Antivirus Policy with the AntiVirus Policy
radio buttons:
v To have the Antivirus Policy log but not reject messages or strip
attachments, click Log.
v To have the Antivirus Policy reject the message, click Reject.
v To have the Antivirus Policy strip offending attachments, click Strip.
13. Determine the behavior of the Antivirus Error Policy with the AntiVirus Error
Policy radio buttons.
v To have the Antivirus Error Policy log but not reject messages or strip
attachments, click Log.
v To have the Antivirus Error Policy reject the message, click Reject.
v To have the Antivirus Error Policy strip offending attachments, click Strip.
14. Use the Log Category list to assign a Log Category.
15. Specify or select the context for the data produced in the Output field.
16. Click Done to complete the action. The configuration path shows the
Antivirus icon.
96
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 145.
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
148 for details.
action.
9. Click Done to complete the action. The configuration path shows the Call
Processing icon.
After you click Apply or Apply Policy, the Call Processing icon expands to the
icons for the actions in the reusable rule.
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.
action.
8. Click Done to complete the action. The configuration path shows the
Checkpoint Event icon.
97
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.
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.
98

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.
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.
action.
9. Click Done to complete the action. The configuration path shows the Convert
Query Param to XML icon.
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

By default, the signing PKCS #7 documents uses the pkcs7-sign.xsl style sheet. To
use another style sheet, use the Advanced tab to identify the style sheet and any
parameter that this style sheet requires.
99
To define a cryptobin action to sign PKCS #7 documents, 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 Sign radio button to select document signature.
action.
8. Define the Signers settings. Use the Signers list with the Add and Delete
buttons to identify the document signatories.
PKCS supports one or multiple document signatories; add the Identification
Credentials Set for each signer to the Signers list.
9. Set Include Content Data to specify an enveloped or detached signature.
on
(Default) Specifies the commonly-used enveloped signature in which

the signed data is included in the PKCS #7 SignedData type.
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.
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. Set Binary Data 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.
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.
off
100
14. If the action is complete, click Done. The configuration path shows the Crypto
Binary icon.
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.
c. Click Submit to return to the Advanced window, which now lists the
newly defined parameter.
Repeat this step to define each additional parameter.
8. Confirm the Signers setting.
9. Confirm the Include Content Data setting.
10. Confirm the Input Encoding Format setting.
11. Confirm the Output Encoding Format setting.
12. Confirm the Binary Data setting.
13. If necessary, define the following settings:
Include text/plain Header
When the Output Encoding Format is S/MIME and the Binary Data
is off, adds a Content-Type:text/plain MIME header to the input
data prior to the signature process. The added header is part of the
signed data.
By default, the header is not added. Some S/MIME clients, however,
require such a header as part of the data.
Include Signer's 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.
101
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.
Verifying PKCS #7 signed documents

By default, the verifying PKCS #7 signed documents uses the pkcs7-verify.xsl style
sheet. To use another style sheet, use the Advanced tab to identify the style sheet
and any parameter that this style sheet requires.
To define a cryptobin action to verify PKCS #7 signatures, use the following
procedure:
action types.
6. Check the PKCS#7 Verify radio button. The display refreshes with
operational-specific parameters.
action.
8. Select the validation credentials list that contain certificates for all signatories
from the Validation Credential list.
102
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.
Binary icon.
9.
Advanced settings: Use the Advanced screen to identify the style sheet and
define less commonly used settings.
4. Confirm that the PKCS#7 Verify radio button is selected.
6. Use the Processing Control File field or select the style sheet used by this
cryptobin verify action to perform signature verification.
form.
of the window).
parameter.
parameter.
8. Confirm the Validation Credential 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 CA's
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.
103
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 included
in the PKCS #7 SignedData type. However, 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
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.
Encrypting PKCS #7 documents

By default, the encrypting PKCS #7 documents uses the pkcs7-encrypt.xsl style
To define a cryptobin action that encrypts PKCS #7 documents, use the following
procedure:
action types.
3.
4.
5.
6.
104
Click the Crypto Binary radio button.

Click Next to display the Crypto Binary Action (Basic) window.
Specify or select the context for the data to be processed in the Input field.
Click the PKCS#7 Encrypt radio button to select document encryption, and
display operational-specific parameters.

action.
8. Select the encryption method from Encryption Algorithm list and click
9. Select the format to characterize the data to be encrypted from the Input
Encoding Format list.
10. Select the format to characterize the encrypted PKCS #7 object (EnvelopedData
type produced by the encryption process) from the Output Encoding Format
list.
11. Set Binary Data 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.
13. If the action is complete, click Done to complete the action. The configuration
path shows the Crypto Binary icon.
4. Confirm that the PKCS#7 Encrypt radio button is selected.
6. 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.
105
8.
9.
10.
11.
12.
Confirm the Encryption Algorithm setting.

Confirm the Input Encoding Format setting.
Confirm the Output Encoding Format setting.
Confirm the Binary Data setting.
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.
Decrypting PKCS #7 documents

By default, the decrypting of PKCS #7 documents uses the pkcs7-decrypt.xsl style
To define a cryptobin action that decrypts PKCS #7 documents, use the following
procedure:
action types.
6. Click the PKCS#7 Decrypt radio button to select document encryption and
display operational-specific parameters.
action.
8. From the Input Encoding Format list, select the input format to characterize
the encrypted PKCS #7 object (EnvelopedData type) to be decrypted.
9. From the Output Encoding Format list, select to output format of the
decrypted data.
10. Specify the Recipients settings. Use the Add and Delete buttons to select the
ID credentials, certificate, and private key for each message recipient. The
private key decrypts the key wrapping key.
Binary icon.
106
4. Confirm that the PKCS#7 Decrypt radio button is selected.
6. Use the Processing Control File field or specify the style sheet used by this
cryptobin decrypt action to perform document decryption.
form.
of the window).
parameter.
parameter.
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.
Adding a decrypt action

By default, the decrypting of documents uses the decrypt.xsl style sheet. To use
another style sheet, use the Advanced tab to identify the style sheet and any
parameter that this style sheet requires.
107
This action might require that certain parameters be supplied during the
configuration of the service.
To
1.
2.
3.
add a decrypt action, use the following procedure:

Drag the Decrypt icon to the configuration path (the horizontal line).
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 263 for
more information.
action.
7. Optional: If the Message Type is Entire Message/Document, 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.
9. If the action is complete, click Done.
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. Set Optimize Element Description 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.
108
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).
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.
off
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

You can define encrypt action to encrypt a SOAP message (with or without
attachments) with WS-Security encryption. When configured, this action encrypts
the child element of the SOAP body.
To define this type of encrypt action:
1. Drag the Encrypt icon to the configuration path (the horizontal line).
Double-click the Encrypt icon.
In the Input field, specify the context of the message to process.
From the Envelope Method list, select WSSec Encryption.
From the Message Type list, select SOAP Message.
Set Asynchronous to indicate whether to process asynchronously. If enabled,
action.
7. Define recipient certificates.
2.
3.
4.
5.
6.
a. Set Use Dynamically Configured Recipient Certificate to indicate

whether to use the certificate in the signature from the remote client.
109
b. From the Recipient Certificate list, select the certificate that contains the
public key for the intended recipient.
8. Define the encryption scope, WS-Security version, and encryption keys.
a. From the Messages and Attachment Handling list, select the encryption
scope.
b. When the encryption scope includes messages: From the Encryption Key
Type list, select the bulk encryption key and how it is protected.
c. When using a symmetric key, define whether to use key derivation and, if
derived, how to derive the key.
1) Set Use WS-SC Key Derivation to indicates whether to use a derived
key as the symmetric key for data encryption or to wrap the ephemeral
key.
2) Determine the key and controls.
v When using key derivation: From the WS-SecureConversation DKT
Derivation Base list, select the type of key derivation to use or the
base token to use to derive the key.
Derive Key from WS-Sec Kerberos Token
If selected, specify the Encryptor principal, Decryptor principal,
and the keytab that contain these principals.
Derive Key from Encrypted Ephemeral Key
Derive Key from EncryptedKeySHA1
Derive Key from Existing DKT Token
If selected, specify the name of the base token.
Use Key Derivation if a SCT Token is Available
Use Symmetric SAML HoK Token from Recipient
v When not using key derivation: From the Symmetric Key
Encryption Source list, select the source for the key.
Use a Key in SecurityContext
Use a Random Key and Encrypt it for the Recipient
Use an Existing DKT Token
If selected, specify the name of the base token.
Use an EncryptedKeySHA1 for Recipient
Use Static Shared Secret Key
If specified, select the Shared Secret Key.
Use the Kerberos Session
If selected, specify the Encryptor principal, Decryptor principal,
and the keytab that contain these principals.
Use the Symmetric SAML HoK Token from the Recipient
d. From the WS-Security Version list, select the version of WS-Security.
e. Set One Ephemeral Key to indicate whether to use the same ephemeral
key for all encryptions.
9. Optional: Click the Advanced tab to configure advanced properties.
a. In the Processing Control File field, specify the encryption style sheet. By
default, this action uses the encrypt-wssec.xsl file in the store: directory.
b. From the Output Type list, select how to interpret the server response.
c. From the Symmetric Encryption Algorithm list, select the algorithm.
d. If the encryption type is asymmetric: define the key transport algorithm.
110
e.
f.
g.
h.
1) From the Key Transport Algorithm list, select the algorithm.

2) If the algorithm is OAEP: In the OAEP Parameters field, specify the
base-64 encoded string that contains the parameters.
3) If the algorithm is OAEP: From the OAEP Digest Algorithm list, select
the algorithm for padding.
Set Include SOAP mustUnderstand to indicate whether the security
header contains the mustUnderstand SOAP attribute. When enabled, the
security header includes the SOAP:mustUnderstand="1" attribute.
From the WS-Sec ID Reference Type list, select how to generate the ID
type for the new element node.
For WS-Security 1.0 or 1.1: In the SOAP Actor/Role Identifier field,
specify the identifier for the SOAP 1.1 actor or SOAP 1.2 role in processing
a WS-Security security header.
From the Token Reference Mechanism list, select the method to reference
the security token.
v 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.
For WS-Security version 1.0 or 1.1: From the X.509 Token Profile 1.0:
BinarySecurityToken ValueType list, select how to control the value of
BinarySecurityToken/@ValueType and SecurityTokenReference/
Reference/@ValueType when referring to a BinarySecurityToken that is
an X.509 token. 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.
v EncryptedKeySHA1 Although the online help shows this option, it is
no longer available.
v Key Identifier A reference is made using a KeyIdentifier element
with a SubjectKeyIdentifier ValueType and content. When using a key
identifier, you need to define it.
1) For WS-Security 1.0: From the X.509 Token Profile 1.0: KeyIdentifier
ValueType list, select how to control the value of
KeyIdentifier/@ValueType. Because of differences among the final
WS-Security 1.0 standards and the multiple draft versions of its
errata documents, different WS-Security implementations use
different values of the ValueType attribute.
2) For WS-Security version 1.0 and 1.1: From the SKI type list, select
the form of the Subject Key Identifier.
v For WS-Security 1.1 ThumbPrintSHA1 or ThumbprintSHA1 A
reference is made using a KeyIdentifier element with a ThumbPrintSHA1
or ThumbprintSHA1ValueType and content.
v X509IssuerSerial A reference is made using an X509IssuerSerial

element that identifies a certificate by its X.509 issuer and serial number.
i. Based on key, define additional controls.
v For Kerberos tokens: From the WS-Security BinarySecurityToken
Kerberos ValueType list, select the ValueType to use. If derived:
1) From the DKT Namespace Version if Unknown list, select the
WS-SecureConversation specification to use when it outputs a
wsc:DerivedKeyToken.
111
2) Define the offset or generation of the derived key in the key

sequence.
For offset: In the Offset of the Derived Key in the key sequence
field, specify where the derived key starts in the byte stream.
For generation: In the Generation of the Derived Key in the Key
Sequence field, specify which generation of the key to use. The
generation is the index number of the fixed key in the lengthy key
sequence. To display this field, remove the value from the Offset
of the Derived Key in the key sequence field
3) In the Label of the Derived Key field, specify the label string for the
v For ephemeral or random keys:
If wrapped: From the Symmetric Key Wrap Algorithm list, select the
algorithm. Useful when the bulk encryption key is itself encrypted by
a symmetric key.
If derived:
1) From the DKT Namespace Version if Unknown list, select the
WS-SecureConversation specification to use when it outputs a
sequence.
- For offset: In the Offset of the Derived Key in the key
sequence field, specify where the derived key starts in the byte
stream.
- For generation: In the Generation of the Derived Key in the
Key Sequence field, specify which generation of the key to use.
The generation is the index number of the fixed key in the
lengthy key sequence. To display this field, remove the value
from the Offset of the Derived Key in the key sequence field
3) In the Label of the Derived Key field, specify the label string for
the wsc:DerivedKeyToken.
If derived from EncryptedKeySHA1 From the DKT Namespace
Version if Unknown list, select the WS-SecureConversation
specification to use when it outputs a wsc:DerivedKeyToken.
If derived from an existing DKT Define the offset or generation of
the derived key in the key sequence.
- For offset: In the Offset of the Derived Key in the key sequence
field, specify where the derived key starts in the byte stream.
- For generation: In the Generation of the Derived Key in the Key
Sequence field, specify which generation of the key to use. The
generation is the index number of the fixed key in the lengthy key
sequence. To display this field, remove the value from the Offset of
the Derived Key in the key sequence field
If using derivation from an SCT:
sequence.
- For offset: In the Offset of the Derived Key in the key
sequence field, specify where the derived key starts in the byte
stream.
- For generation: In the Generation of the Derived Key in the
Key Sequence field, specify which generation of the key to use.
112
The generation is the index number of the fixed key in the

lengthy key sequence. To display this field, remove the value
from the Offset of the Derived Key in the key sequence field
2) In the Label of the Derived Key field, specify the label string for
the wsc:DerivedKeyToken.
If using an SAML HoK token from recipient From the DKT
Namespace Version if Unknown list, select the WSSecureConversation specification to use when it outputs a
j. Set Include xenc:ReferenceList in wsse:Security to indicate whether to
include the xenc:ReferenceList element in the security header.
k. For WS-Security version 1.1: In the EncryptedKeySHA1 Cache Lifetime
for Derived Key field, specify the lifetime to cache the generated key.
l. From the WS-Security Policy Security Policy Layout list, select which
layout rules to apply when adding items to the security header.
10. In the Output field, specify the context of the message after processing.
11. Click Done.
Encrypting a SOAP message with XML encryption

To add an encrypt action to encrypt a SOAP message:
2. Double-click the Encrypt icon.
3. In the Input field, specify the context of the message to process.
4. From the Envelope Method list, select Standard XML Encryption.
5. From the Message Type list, select SOAP Message.
action.
default, this action uses the encrypt-soap.xsl file in the store: directory.
d. From the Key Transport Algorithm list, select the algorithm.
e. From the Encryption Type list, select the form of encryption.
10. Click Done.
113
Encrypting a raw XML message with XML encryption

To add an encrypt action to encrypt a raw XML message:
4. From the Envelope Method list, select Standard XML Encryption.
5. From the Message Type list, select Raw XML Document.
action.
default, this action uses the encrypt.xsl file in the store: directory.
d. From the Key Transport Algorithm list, select the algorithm.
e. From the Encryption Type list, select from of encryption.
f. When the form of encryption is element: Set Use SAML Encryption for
SAML Elements to indicate whether to generate SAML encryption for
SAML elements.
v For SAML 1.x, generates EncryptedData directly. The SAML 1.x schema
does not define EncryptedAssertion or EncryptedAttribute types, so the
standard XML Encryption is applied.
v For SAML 2.0, generates the EncryptedAssertion or EncryptedAttribute
element for Assertions or Attributes, respectively.
10. Click Done.
Encrypting select elements of a message

To add an encrypt action to encrypt select elements:
4. From the Envelope Method list, select whether to use XML or WS-Security
encryption.
5. From the Message Type list, select Selected Elements (Field-level).
6. From the Document Crypto Map list, select the map that identifies the fields
to encrypt. The list contains maps that conform to the envelope method. In
the map, the Operation property must agrees with the envelope method.
114

action.
8. Optional: Define how to interpret the server response.
a. Click the Advanced tab.
10. Click Done.
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.
115
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
action.
10. Click Done to complete the action. The configuration path shows the Extract
using XPath icon.
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 145 for details.
action.
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.
116
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.
form.
You can click Upload or Fetch to retrieve the file.
action.
Adding a replay filter

To add a replay filter, use the following procedure:
117
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
Double-click the Filter icon to display the Filter action window.

Click the Advanced tab.
Select the Replay Filter radio button from the Filter Method list.
Retain the value of store:///replay-filter.xsl in the Processing Control
File field.
action.
Select the type of filter from the Replay Filter Type list:
v WS-Security Password Digest Nonce
v WS-Addressing Message ID (Default)
v Custom XPath
Specify, in milliseconds, the duration to use the extracted value in the Replay
duration field. Use an integer greater than 0.
If the filter type is Custom XPath, specify the XPath expression in the Custom
XPath Expression field.
For assistance in creating the XPath expression, click XPath Tool. This tool
allows you to load an XML document and build the expression by selecting
the desired mode.
Specify or select the context for the data produced in the Output field.

Defining a required elements filter

To add a required elements filter, use the following procedure:
4. Click the Advanced tab.
5. Select the Required Elements Filter radio button from the Filter Method list.
6. Retain the value of store:///required-elements-filter.xsl in the Processing
Control File field.
action.
8. Specify the XPath expression in the XPath Expression field.
For assistance in creating the XPath expression, click XPath Tool. This tool
allows you to load an XML document and build the expression by selecting
the desired mode.
118
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.
action.
8. Select which WS-Security assertion to apply from the WS-Security Message
Layout Policy list. This policy determines whether to accept or request
documents based on the order of elements in the WS-Security header.
Lax
Does not require that tokens be declared before use.
Lax - Timestamp First

Requires that the timestamp be the first element in the header.
Lax - Timestamp Last
Requires that the timestamp be the last element in the header.
Strict
Requires that tokens, in general, be declared before use.
Adding a conformance filter

To add a conformance filter, use the following procedure:
1.
2.
3.
4.
5.
6.
7.
8.
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.
action.
Select the conformance policy from the Conformance Policy list. Refer to
Conformance Policy on page 261 for details.
Click Done to complete the action.
For each (for-each) action

The for-each action supports the following use cases:
119
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 146 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.
action.
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. Enter any value of 1 32768.
120
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://joe.com">
<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.
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
121
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. Set Use Multiple Outputs 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
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.
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.
var://service/multistep/loop-count
This variable returns the number of times the loop has iterated.
Adding a log action

A log action is for transaction logging, not event logging to a log target. A log
action takes a copy of a particular message payload and sends it to a log
destination for auditing purposes. This action requires a destination URL and will
122
send the input context to the defined endpoint. The message is wrapped in the
same schema as the SOAP log target. The message contains all the standard log
metadata fields (timestamp, category, client IP address, and so forth), and the
payload is inserted into the message field.
To add a log action:
action types.
3. Click the Log radio button.
4. Click Next to display the Log action window.
5. Optional: Select the Input context. If auto, processing sets the context
identifier. The contents of input context are sent to the defined destination.
6. In the Destination field, specify a valid URL. Refer to Locating remote
resources in actions on page 145 for details.
7. From the Log Level list, select a priority. The priority might be meaningful to
the entity that receives the log message.
8. From the Log Type list, select a logging category.
action.
11. Optional: Select the Output context or specify a new context name. Select auto
to allow the processing policy to set the output context. If left blank, no
response is captured from the log action.
The configuration path shows the Log icon.
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.
123
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:
2. Double-click the Advanced icon.
3. Click the MQ Header radio button.
4. Click Next.
5. Optional: Specify the input context. If auto, processing inserts the correct
context identifier.
action.
7. Select request as the MQ Processing Type.
8. Select MQMD for Put from the MQ Request Header Processing list.
9. Set Override Existing MQMD to choose a mode for overriding the MQMD
headers in the request message:
10. Specify an override value for the following MQMD header fields:
v Message Id
v Correlation Id
v Character Set Id
v Format Name
v ReplyToQ
v ReplyToQMgr
11. Select an output context. If auto, processing inserts the output context.
12. Click Done.
Retrieving responses by message ID or by correlation ID

To retrieve response messages from the backend reply queue:
4. Click Next.
context identifier.
action.
7. Select request as the MQ Processing Type.
124
8. Select MQMD for Get from the MQ Request Header Processing list.
9. Define how the service pulls messages from the backend reply queue.
v In the Message Id field, specify the message ID. The service pulls messages
from the backend reply queue with the specified message ID.
v In the Correlation Id field, specify the correlation ID. The service pulls
messages from the backend reply queue with the specified correlation ID.
11. Click Done.
Modifying MQMD response headers

To modify MQMD header values for response messages placed to the backend
reply queue:
4. Click Next.
context identifier.
action.
7. Select response as the MQ Processing Type.
8. Select MQMD from the MQ Response Header Processing list.
9. Set Override Existing MQMD to choose a mode for overriding the MQMD
headers in the response message.
10. Specify an override value for the following MQMD header fields:
v Message Id
v Correlation Id
v Character Set Id
v Format Name
v ReplyToQ
v ReplyToQMgr
12. Click Done.
Modifying the reply queue for responses

To change the destination reply queue for response messages:
4. Click Next.
context identifier.
125

action.
8. Select ReplyToQ from the MQ Response Header Processing list.
9. From the ReplyToQ Processing Type list, select the processing method for the
response message.
10. Optional: In the ReplyToQMgr field, specify a value.
12. Click Done.
Modifying the queue manager for responses

To change the destination MQ Queue Manager for response messages:
4. Click Next.
context identifier.
action.
8. Select ReplyToQM from the MQ Response Header Processing list.
9. From the ReplyToQM Processing Type list, select the processing method for
the response message.
10. Optional: In the ReplyToQMgr field, specify a value.
12. Click Done.
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 132 for more
information.
5. From the Error Mode list, select the operational response to an error
condition.
126
Cancel
Stop the processing of the current processing rule.
Alternative
Invoke an alternative processing rule.
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 145.
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
148 for details.
7. Optionally use the Error Input field or select the input context to the invoked
error rule. If no input context is specified, the input context of the failed
action is provided as a default context to the error rule.
8. Optionally use the Error Output field or select the output context from the
invoked error rule. If no output context is specified, the output context of the
failed action is provided as a default context to the error-rule.
Select OUTPUT to transmit the error message to the requesting client.
action.
10. Click Done to complete the action. The configuration path shows the On
Error icon.
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 128 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 129 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.
127
Because a results-async action does not support an output context, the results
action provides the following options that are not available for a results-async
action. These options are meaningful only when processing in synchronous mode
or when processing in asynchronous mode and the processing rule contains a
subsequent event-sink action.
v The ability to create multiple output contexts.
v The ability to control the aggregation of multiple output contexts.
v The ability to control the interpretation of the server response, if any.
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 145 for details.
5. Retain the setting off for Asynchronous.
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 116 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
128
XML or does not exist, parses the response as XML. For any other
value, treats the response as Binary and stores the response
without parsing.
XML Parses the response as XML.
b. Set Use Multiple Outputs 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 Use Multiple Outputs is set to on.
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 145 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.
129
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.
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 345 for more information.
action.
7. Click Done to complete the action. The configuration path shows the Header
Rewrite icon.
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.
Route-type actions
A processing policy provides three routing implementations using two actions to
select the destination:
130
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 132 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.
action.
7. Optionally specify or select the context for the data produced in the Output
field.
8. Click Done to complete the action and return to the rule configuration window.
Adding a route with XPath expression (route-action) action

To add a route with XPath expression (route-action) action, use the following
procedure:
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.
131

action.
7. Optionally specify or select the context for the data produced in the Output
field.
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 145 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.
action.
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 148 for details.
7. Specify the value for the variable in the Variable Assignment field.
action.
9. Click Done to complete the action. The configuration path shows the Set
Variable icon.
132
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, including SAML for Enveloped
The message is in raw XML format. Enveloped and enveloping
signature methods are supported. If the target is a SAML element for
Enveloped signing method, the SAML enveloped signing is not
applied.
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.
action.
7. When the Envelope Message is enveloped or enveloping and the Message
Type is SOAP Message or Raw XML Document, including SAML for
Enveloped, select an instance of the Key object from the Key list.
8. When the Envelope Message is enveloped or enveloping and the Message
Type is SOAP Message or Raw XML Document, including SAML for
Enveloped, select an instance of the Certificate object from the Certificate list.
133
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 263 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 Key's 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, set
Use WS-SC Key Derivation 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. In the XPath Expression field, enter the XPath expression that identifies the
elements on which to sign. This field is available only when the signature
method is enveloped and the message type is Raw XML Document, including
SAML for Enveloped.
v Click Add to add the expression to those included in the map. If no XPath
Expression is defined, the entire XML document is signed.
v Click XPath Tool to use the graphically oriented XPath Tool to construct the
message. You must upload an example document to use this tool.
12. Use the Output field to specify the destination context for the signed XML.
13. 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.
134
For details about other advanced settings, refer to the online help.
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 324 for details.
action.
9. Click Done to complete the action. The configuration path shows the SLM
icon.
Adding an SQL action

An SQL action retrieves data from an SQL data source for further processing by
the processing policy. An SQL action requires that the DataPower appliance is
licensed for SQL-ODBC.
To add an sql action, use the following procedure:
action types.
3. Click the SQL radio button.
4. Click Next to display the SQL Action window.
6. Provide the context name, the string PIPE (for streaming mode) or the string
INPUT (identifies the original input into this rule).
7. Retain the default value (auto) to allow the processing policy to determine the
input context needed to connect this action to the previous output.
8. Use the SQL Data Source list to identify the database accessed by this sql
action. Refer to SQL Data Source on page 330 for SQL Data Source
configuration details.
9. Use the SQL Input Method list to identify the source of the SQL statement
that is invoked by the SQL Action.
Static
(Default) Indicates that the SQL statement is contained in the SQL Text
field.
135
Stylesheet
Indicates that the SQL statement is derived by executing the style
sheet specified by the Transform field against the contents on the
context specified by the Input field.
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.
action.
Optionally specify or select the context for the data produced in the Output
field.
Click Done to complete the action. The configuration path shows the SQL
icon.
Note: If the SQL action successfully queries the data source, the query produces
standard SQL schema output messages. In some instances, query errors also
produce standard SQL schema output messages. However, if the query fails
for one of the following reasons, a generic SOAP fault is reported:
v The SQL data source name is invalid, missing, or incorrect.
v The SQL data source is disabled.
v The SQL data source is not in the up operational state.
v The SQL query is not resolvable.
v The data source is read-only, and you attempt to run a non-SELECT
query.
v The size-limit property of the data source was exceeded.
v Other unexpected errors.
A more descriptive SQL error message can still be found in the log.
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.
136
5. In the Attachment URI field, specify the attachment to strip. If omitted, all
attachments are stripped from the specified context.
action.
7. Click Done to complete the action. The configuration path shows the Strip
Attachments icon.
Transform-type actions
A processing policy provides the following transform implementations:
Transform for XML messages
Uses the xform action to transform XML documents. The action identifies
the XSLT style sheet to use to perform the transform.
Transform for non-XML messages
Uses the xformbin action to transform non-XML documents. The action
identifies the XSLT style sheet to use to perform the transform.
Processing instruction-based transform for XML messages
Uses the xformpi action to transform XML documents. The XML document
is the source of the processing instruction. The action uses the processing
instruction in the presented XML documents to perform the transform.
SOAP refinement transform
Transforms the SOAP header and child elements of a SOAP document in
accordance with the defined SOAP Header Disposition table. This
transform uses the soap-refine.xsl style sheet in the store: directory.
Buffer attachments transform
Transforms an attachment manifest to ensure that all attachments are
buffered, not streamed. This transform uses the buffer-attachments.xsl style
sheet in the store: directory.
Conformance transform
Transforms an XML document to conform to the define Conformance
Policy. This transform uses the conformance-xform.xsl style sheet in the
store: directory.
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.
137
6. Optional: From the URL Rewrite Policy list, select the rewrite policy to rewrite
the style sheet URL that is extracted from the incoming document. Refer to
URL Rewrite Policy on page 345 for more information.
action.
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:
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.
form.
6. In the WTX Map File field, specify the URL of the map file that you
previously uploaded. Use this field only when you are using a map file that
was generated by WebSphere Design Studio.
7. 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 345 for more information.
action.
10. Click Done to complete the action. The configuration path shows The
Transform Binary icon.
Adding a processing instruction-based transform for XML

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

Drag the Transform icon to the configuration path (the horizontal line).
Double-click the Transform icon to display the Transform action window.
form.
5.
6.
7.
8.

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 345 for more information.
action.
Click Done to complete the action. The configuration path shows the
Transform Using Processing Instruction icon.
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.
action.
9. Set Enforce One SOAP Actor/Role 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.
139
http://www.w3.org/2003/05/soap-envelope/role/next
Everyone, including the intermediary and ultimate receiver,
receives the message and should be able to process the
security header.
http://www.w3.org/2003/05/soap-envelope/role/ultimateReceiver
(Default) The ultimate receiver can process the security
header.
Blank or an empty string
No actor/role identifier is configured. The ultimate receiver
is assumed when processing the message, and no actor/role
attribute is added when generating the security header.
Note: There should not be more than one security header that
omit the actor/role identifier.
USE_MESSAGE_BASE_URI
Indicates that the actor/role identifier is the base URI of the
message. If the SOAP message is transported using HTTP, the
base URI is the request-URI of the HTTP request.
Any other string
Indicates the actor or role of the security header.
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:
140
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. Set Detect ID References while Deleting 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
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 329 for information.
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:
Drag the Transform icon to the configuration path (the horizontal line).
Double-click the Transform icon to display the Transform action window.
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.
1.
2.
3.
4.
141
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 345 for more information.
action.
Adding a conformance transform

To add a conformance 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:///
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.
action.
8. Select the conformance policy from the Conformance Policy list. Refer to
Conformance Policy on page 261 for details.
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
142
Validate Document via Schema Attribute

(Default) Specifies that candidate documents are verified in
accordance with validation instructions contained with the document.
Documents that lack such instructions are considered to be validated.
Validate Document via Attribute Rewrite Rule
Rewrites the schema reference (if any) contained in the XML
document undergoing validation, and then validates the document
against the rewritten schema reference. The rewritten reference usually
points to the location of a local trusted copy of the schema.
Validate Document with Encrypted Sections
Uses a schema exception map to validate a partially encrypted
document. The Schema Exception Map contains a reference to a base
schema used with the map to generate the dynamic schema required
for this action.
Validate Document via WSDL URL
Uses a WSDL file to validate the message, When selected, a WSDL
URL field is displayed.
5. If the schema validation method is Validate Document via Attribute Rewrite
Rule, from the Policy list, select the URL Rewrite Policy to rewrite the internal
schema reference. Refer to URL Rewrite Policy on page 345 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.
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 323 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.
143
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.
action.
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
1.
2.
3.
4.
add a verify action:

Drag the Verify icon to the configuration path (the horizontal line).
Double-click the Verify icon.
In the Input field, enter or select the context for the data to process.
action.
5. From the Signature Verification Type list, select the types of signature to
verify.
6. Optional: For RSA/DSA signatures, define certificates.
a. In the Optional Signer Certificate field, enter the certificate to use when
processing cannot retrieve the key information.
144
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
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
Defining reusable rules

A reusable rule is a Processing Rule object that a call or on-error action can
define as its processing rule to perform the configured series of action.
To define a reusable rule within the context of defining the processing policy, use
the following procedure:
1. Select an existing rule in the policy.
2. Click Create Reusable Rule. The cursor changes to a + shape.
3. Click and drag the cursor around one or more actions in the current rule. A
blue highlighted box is drawn around the selected action.
4. Depending on the DataPower service, click Apply or Apply Policy to create the
reusable rule.
After the screen redraws, the reusable rule is displayed as a highlighted group in
the policy hierarchy.
Locating remote resources in actions

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

Action type
WebGUI label
Optional or
Required
Number of servers
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)
v dpwasjms (not secure) or dpwasjmss (secure)
v
v
v
v
v
v
v
ftp
http
https
ims (not secure) or imsssl (secure), if licensed
mq (MQ protocol to a dynamic back end)
smtp
sql, if licensed
v tcp
v tcps
v 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
147 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>
146
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 148.
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">
</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 148.
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
v
v
v
Encode=base64 or Encode=hexbin
Compress=gzip
Archive=tar or Archive=zip
Filename=file_name
The results and results-async actions support the following query parameters:
v
v
v
v
v
v
Decode=base64
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
147
strip-attachments INPUT
# add archive-base64 as a new attachment to input and decode
results
archive-base64
attachment://INPUT/cid:archive-zip?Decode=base64
# fetch binary file into context x
fetch
http://zoostation/clitest-importpackage.zip
new-file-to-add
# add file to archive
results
new-file-to-add
attachment://INPUT/cid:archive-zip?Archive=zip&Filename=testfile
# return context with new archive (3 files)
results INPUT
exit
Format of the <results> element

The XML for the <results> element can be stored as value in a variable, whose
name, in turn, can be specified as the destination of a result or result-async
action. The XML can be store as the value, for example in var://context/foobar/
dest variable, through either a style sheet or setvar action. Then, the
var://context/foobar/dest variable can be specified as the destination of a result
action. The result action will then parse the XML in the variable and act
accordingly.
The <results> element can have the following attributes:
<results mode="first-available | require-all | attempt-all"
transactional="true | false"
retry-interval="duration"
asynchronous="true | false"
multiple-outputs="true | false">
<url>...</url>
<url>...</url>
<results>
The <url> element can have the following attributes:

<url retry-count="count"
asynchronous="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)
148
For the call and on-error actions, you can create a custom context variable only.
After clicking Var Builder the area shown in Figure 9 is visible.
Figure 9. Variable builder for custom context variables
For the setvar action, you can create a custom context variable or select an existing
service, extension, or system variable. The created or selected variable must be a
write-only or read-write variable. After clicking Var Builder the area shown in
Figure 10 is visible.
Figure 10. Variable builder for custom context, service, extension, and system variables
After defining a custom context variable, click Use Custom. The variable builder
closes, and the field contains the defined variable.
Debugging processing policies

The DataPower appliance provides a powerful debugging utility for use during the
development of processing policies. This utility is called the 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. See
IBM WebSphere DataPower SOA Appliances: Problem Determination Guide for more
information.
149
150

An Authentication, Authorization, Audit (AAA) policy, sometimes referred to as an
Access Control Policy, identifies a set of resources and procedures that can be used
to determine whether a requesting client is granted access to a specific service, file,
or document. AAA policies can be considered a type of filter in that they accept or
deny a specific client request.
AAA policies are powerful and flexible. They can support a range of authentication
and authorization mechanisms to include SAML, Netegrity, and RADIUS. Multiple
authentication and authorization mechanisms can be mixed and matched in a
single policy. For example, one AAA policy can use a single RADIUS server to
provide authentication and authorization services, while a second policy can use a
RADIUS server for authentication, use a local XML file to map the RADIUS
authentication credentials to an LDAP group name, and finally use an LDAP
server to authorize the LDAP group.
Figure 11 shows the basic processing for an AAA Policy. Initial processing
(common to all policies) consists of extracting the claimed identity of the service
requester and the requested resource from an incoming message and its protocol
envelope. As you define an AAA Policy, extraction methods are specified by a
series of check boxes that enable one or more identity and resource extraction
methods. A wide range of identity and resource extraction methods are supported.
For example, identity can be based on IP address, form (account name and
password), SAML assertion, or other criteria; while the requested resource can be
specified by (among others) an HTTP URL, a namespace, or a WSDL method.
Extract Identity
Extract Resource
Authenticate
Allow | Deny
Map Credentials
Map Resource
Authorize
Allow | Deny
Post Processing
Output
Message
Generate
Error
Figure 11. AAA Policy Processing
After extracting the service requester identity and resource, the policy authenticates
the claimed identity. Authentication is most commonly accomplished via an
external service (for example, a RADIUS or LDAP server), but other custom
processing methods, such as site-specific XML- or XPath-based solutions, are
readily supported. During policy definition, you select a single authentication
method from a menu of supported methods, and (depending upon the selected
method) provide a few items of additional required information, such as a server
address or the URL of a custom processing resource.
151
Successful server-based authentication generates a set of credentials attesting to the

service requester's 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 document
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 user's identity from an incoming request
v Defining the method to authenticate the user
v Define the method to map credentials
152
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>
153
<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 token's 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>
154
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.
155
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>
156
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 Message's 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 32 for more
information.
Retrieve Remote Token
Select whether to retrieve the remote token. Refer to Security
token references on page 372 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:
157
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 245 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.
158
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 318 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
Optional: 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
32.
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:
159
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 276 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
160
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.
Search for DN
Indicate whether to perform an LDAP search retrieve the DN of the
user.
on
Enables an LDAP search for the user's 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 user's DN.
(Default) Disables an LDAP search for the user's group. The

login name of the user along with the LDAP prefix and the
LDAP suffix will be used to construct the user's 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 266 for detail.
off
v If off, the WebGUI removes the LDAP Prefix and LDAP Suffix
fields:
LDAP Prefix
Optional: 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
Optional: 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.
User Auxiliary LDAP Attribute
Define the list of LDAP attributes as the auxiliary information for
AAA. Use a comma as the delimiter. For example,
email,cn,userPassword. Results are appended to the context variable
var://context/ldap/auxiliary-attributes. The LDAP attributes are
synchronized to the AAA authentication cache.
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:
Optional: 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 32 for more information.
SAML Authentication Query Server URL
Specify the URL of the SAML Authentication server to use to retrieve
a SAML authentication statement.
161
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
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
through 128. The default is 32.
Require Server Entropy
Indicates whether to require server entropy in the WS-Trust
response.
on
Requires server entropy. The WS-Trust server must return

an entropy element to the DataPower appliance as part of
the security token request exchange.
off
(Default) Does not require server entropy.
When required, specify the minimum allowable size of the received

entropy material in bytes in the Server Entropy Size field. The size
162
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
Optional: 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
Optional: 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/.
163
<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:
NSS Client Configuration
Select the NSS Client object that specifies the details for connecting to
the NSS server for SAF authentication. Refer to NSS Client on page
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 252 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.
164
Use an Established WS-SecureConversation Security Context

The requester is authenticated by reference to an established
WS-SecureConversation security context. This context must already exist.
Use certificate from BinarySecurityToken
The requester is authenticated by a certificate included with a
BinarySecurityToken. If selected, the WebGUI displays the following
property:
X.509 BinarySecurityToken Validation Credential
Select the Validation Credentials set used to validate the X.509
certificate extracted from the WS-Security BinarySecurityToken
element. Refer to Validation credentials on page 32 for more
information.
Refer to the description in Defining identity extraction methods on page
153.
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 246 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
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:
Server's Kerberos Keytab
Select the Kerberos Keytab File. Refer to Configuring a Kerberos
keytab file on page 257 for more information.
165
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
Optional: 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
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 245 for more
information.
Retrieve Remote Token
Select whether to retrieve the remote token. Refer to Security token
references on page 372 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 32 for more information.
After select one authentication method, continue with the Map Credentials phase
of the AAA Policy definition.
166
Mapping authentication credentials

After obtaining a set of credentials that attest to the identity of the client, an AAA
policy can map these credentials to a more useful format by performing custom
processing on the received credentials.
Select the credentials mapping method from the Method list.
Custom
Identifies a custom, credentials mapping resource; for example, a style
sheet. If selected, the WebGUI displays the following property:
Specify a URL
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.
167

Binding to provide namespace or prefix data. Refer to Setting
information.
Changing the authentication caching policy

The authentication cache stores authentication data to minimize the overhead of
re-authenticating the same identity. Each entry in the cache must have a unique
key. This key is the output from the identity extraction phase plus any ancillary
data for the defined authentication method. When there is a match against a
unique key, the cache returns the results from the previous authentication of this
identity.
By default, the cache contains authentication data for three seconds.
To modify the caching policy:
1. Click Advanced.
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. In the TTL field, specify the explicit TTL in seconds.
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
168
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/"
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>
169
<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:
Processing Metadata Item
Select a Processing Metadata object to identify extracted items. Refer
to Processing Metadata on page 318 for more information.
You must use custom style sheet for authentication.
Mapping requested resources

After extracting the resource request, the AAA Policy can 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
170
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
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

Optional: 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 246 for more
information.
XPath
Identifies an XPath expression as the mapping resource. If selected,
the WebGUI displays the following property:
171
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 245 for
more information.
Click Next to display the Authorization window.
Defining the authorization method

After authenticating a service requester and identifying the requested resource, an
AAA Policy references an external service or object to authorize the service
requester; that is determining whether or not this requester is cleared for access to
the requested resource.
Use the Authorization window to provide required details.
Use the radio buttons to select a single authorization method.
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
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)
Resource/Action map
Select an existing action map file.
172
(Trace)
(View)
(Password)
(Execute)
This type of action map allows a single AAA policy to use different
ACL actions during authorization based on the requested resource.
For example, you could have a TAM action map with the entries
listed in Table 10.
Table 10. Example of TAM action map entries
Pattern
Action
*one*
x (execute)
*two*
r (read)
When an authorization request, whose resources are /resource/one

and /resource/two, the first authorizes the use of the execute action
and the second entry authorizes the use of the read action.
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 252 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
Optional: 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
Select the NSS Client object that specifies the details for connecting to
the NSS server for SAF authorization. Refer to NSS Client on page
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
173

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.
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.
Optional: 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.
174
LDAP Search Filter

Optional: 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.
User Auxiliary LDAP Attribute
email,cn,userPassword. Results are appended to the context variable
var://context/ldap/auxiliary-attributes. The LDAP attributes are
synchronized to the AAA authorization cache.
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
Optional: 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 32.
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 25.
175
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 22.
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.
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 for
authorization on page 245.
Must match all names
All Attribute names in the response from the SAML server must
match those configured on the SAML Attributes panel. To
176
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 for authorization
on page 245.
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 for authorization on page 245.
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 32 for
more information.
SAML message signing key
Select a Crypto Key to use for this transaction. Refer to Defining
Key objects on page 25 for more information.
SAML message signing certificate
Select a Crypto Certificate to use for this transaction. Refer to
Defining Certificate objects on page 22 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
177
must match one configured on the SAML Attributes panel. To

Must match all names
All Attribute names in the response from the SAML server must
match those configured on the SAML Attributes panel. To
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 for authorization
on page 245.
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 for authorization on page 245.
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 259 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
Indicates the location of the PDP.
on
178
(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
Set to force the use of the SAML2.0 Profile. Meaningful
only when the XACML version is 2.0.
SOAP Enveloping
Set 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.
179
Changing the authorization caching policy

By default, authorization information from remote resources is cached for a period
of three seconds.
To modify the caching policy:
1. Click Advanced.
2. Use the Policy radio buttons to specify the authorization caching strategy.
Absolute
(Default) Caches all authorization data with an explicit TTL (specified
in the TTL field).
Disabled
Disables caching of authorization data.
Maximum
Compares the explicit TTL with the received TTL, if any. If it is less
explicit value.
Minimum
Compares the explicit TTL with the received TTL, if any. If it is greater
explicit value.
3. In the TTL field, specify the explicit TTL in seconds.
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. See
Configuring count monitors on page 214.
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.
180
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.
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 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
v
v
v
v
Generate an LTPA token

Generate a Kerberos SPNEGO token
Request a Tivoli Federated Identity Manager (TFIM) token map
Generate an ICRX token for z/OS identity propagation
Generate a SAML assertion or response that can contain one or all of the
following assertion types: an authentication statement, an attribute statement,
and an authorization decision statement
181
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 with only authentication

statement
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.
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
182
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
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.
183
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.
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 253.
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.
Generating a SAML assertion or response

An AAA policy provides the flexibility to include one or all of the following
assertion types: an authentication statement, an attribute statement, and an
authorization decision statement.
v The scenario for which the SAML assertion is generated
v The output method for wrapping up the result
v The actor or role identifier for the WS-Security security header
v The SAML version
v The SAML assertion type
v The subject confirmation method for the SAML assertion
v Peer settings
The identity of the assertion originator (Issuer)
The optional SAML audience for the assertion
The optional Recipient of the subject confirmation data in the generated
SAML assertion
Whether the generated token contains a name identifier
- The optional NameQualifier as defined by the SAML protocol version, if the
generated token contains a name identifier
- The optional Format of the name identifier in the generated SAML query, if
the generated token contains a name identifier
v Session-control settings
The assertion validity, in seconds
Whether the assertion was valid in the past
184
The skew time, in seconds

Whether the generated token is to be used only once
v Proxy-restriction settings
Whether a SAML proxy restriction is required
- The proxy audience, if a proxy restriction is required
- The proxy count, if a proxy restriction is required
v The SAML attributes definition for the SAML assertion post processing method,
if an attribute statement is a specified assertion type
v The action for the SAML authorization decision, if an authorization decision
statement is a specified assertion type
If you want to sign a SAML assertion, you must define a sign action. For more
information, refer to Adding a sign action on page 133. Select Raw XML Document,
including SAML for Enveloped.
185
186
Chapter 9. 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 from the WebGUI, click 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 list files in this
directory, but you cannot view or modify these files. 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. During an upgrade, the operation deletes the
contents of this directory.
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.
During an upgrade, the operation deletes the contents of this directory.
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
187
can move log files to the logstore: directory. Each application domain
contains one logstore: directory. This directory is not shared across
domains.
logtemp:
This directory is the default location of log files, such as the
appliance-wide default log. This directory can hold only 13 MB. This
directory cannot be the destination of a copy. Each application domain
contains one logtemp: directory. This directory is not shared across
domains.
pubcert:
This encrypted directory contains the security certificates that are used
commonly by Web browsers. These certificates are used to establish
security credentials. Each appliance contains only one pubcert: directory.
This directory is shared across domains.
sharedcert:
This encrypted directory contains security certificates that are shared with
partners. Each appliance contains only one sharedcert: directory. This
directory is shared across domains. However, you must be in default
domain to create or upload keys and certificates.
store:
This directory contains example style sheets, default style sheets, and
schemas that are used by the local appliance. Do not modify the files in
this directory.
Each appliance contains only one store: directory. By default, this directory
is visible to all domains. You can make changes to the contents of this
directory from the default domain only.
The store: directory has the following subdirectories:
meta
This encrypted subdirectory contains files that are used by the

appliance itself.
msgcat
This subdirectory contains the message catalogs.
policies
This subdirectory contains the following subdirectories. The
contents of these subdirectories affect Web services policy.
custom
This subdirectory contains custom style sheets.
mappings
This subdirectory contains mapping style sheets.
templates
This subdirectory contains XML files.
profiles
This subdirectory contains style sheets that are used by DataPower
services.
schemas
This subdirectory contains schemas that are used by DataPower
services.
dp
188

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. During an upgrade, the operation deletes the
contents of this directory.
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. Click Create Subdirectory. The File Management screen displays.
4. Enter the name of the new subdirectory in the directory Name field.
5. Click Confirm Create. The File Management screen refreshes.
6. Click Continue. The File Management screen displays the top-level directories
only.
189
Deleting a directory
Directories can only be deleted in the local: directory or one of its subdirectories.
Follow these steps to delete a directory under the local: directory or one of its
subdirectories:
utility on page 189 for details.
2. From the Action column, click Actions aligned with the directory to be deleted.
3. Click Delete Directory. The File Management screen displays.
4. Click Confirm Delete. The File Management screen refreshes.
5. Click Continue. The File Management screen displays the top-level directories
only.
Refreshing directory contents

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

Use the following procedure to upload a file from your workstation to the
appliance:
2. Navigate to the directory into which you want to upload the file.
3. Click Actions in that row to open the Directory Actions menu.
4. Click Upload Files to display the File Upload screen.
5. Specify the path-qualified name of the workstation file in the File to upload
field, or click Browse to locate the file on the workstation.
6. Specify the file name in the Save as field.
Note: If you used browsing to select the file or if you navigated to this field
using the tab key, the field contains the file name.
7. To add another file to be uploaded:
a. Click Add.
b. Repeat steps 5 and 6.
8. If one of the files already exists in the selected directory and you want to
overwrite this file, check the Overwrite Existing Files check box. If you do
not select this check box and the file already exists, the file is not uploaded.
9. Click Upload.
10. When the appliance reports success (or an error is the file already existed),
click Continue to return to the File Management screen.
The target directory now contains the uploaded files. To verify, use the procedure
described in Displaying directory contents on page 189.
190
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
191
Applet is running. If the applet cannot be accessed, you cannot upload

JKS files. Ensure that your browser is enabled to use the Java 1.4.2
applet.
6. Specify the full path to the target JKS in the Java key store field or click
Browse.
7. Specify JKS or JCEKS (the JKS type) in the Key store type field.
8. If the type is JCEKS, specify SunJCE (the provider name) in the Key store
provider field. Otherwise, leave blank.
9. Specify the JKS password in the Key store password field.
10. Identify the files to upload with the Key to upload list. Use the Refresh
button, if necessary.
11. Specify the key-specific password in the Key password field.
12. Specify the file name in the Save as field.
13. If the file already exists in the selected directory and you want to overwrite
this file, check the Overwrite Existing Files check box. If you do not select
this check box and the file already exists, the file is not uploaded.
14. Click Upload.
15. When the appliance reports success, click Continue to return to the File
Management screen.
The target directory now contains the uploaded key or certificate. To verify that the
file exists, use the procedure described in Displaying directory contents on page
189.
If the upload fails, look at the Java Console of the browser to determine whether
an exception was thrown.
Fetching files
Use the following procedure to retrieve a file from a remote URL (fetch) and store
that file in a specified directory on the appliance:
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 189.
Copying files
Use the following procedure to copy a file from one directory to another:
192
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 189.
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 189.
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.
193
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 189.
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 189.
194
Chapter 10. 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:
1. Click Objects Configuration Management Include Configuration File.
2. Click Add.
configuration.
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. Set Execute on Startup to indicate whether to import the configuration
package at startup.
on
(Default) Imports the configuration package at startup. The

configuration is marked external and cannot be saved to the startup
configuration. This behavior is equivalent to always importing the
configuration.
off
Imports the configuration package when manually triggered. The

configuration is not marked external and can be saved to the startup
configuration. This behavior is equivalent to importing the
configuration one time.
8. When retrieving the configuration file, select when to retrieve the

configuration file with Interface Detection.
on
Retrieves the configuration file after the local interface is up.
(Default) Retrieves the configuration file at appliance reload without

waiting for the local interface to be up.
off
195
Note: Unless you click Save Config, the included configuration file will not take
affect when the appliance is started.
Creating Import Configuration File objects

Import Configuration File objects allow you to import a configuration package
from an external configuration file into the local configuration information. The
external file can be stored on a centralized configuration server or another
DataPower appliance. The configuration data and files in the configuration file is
added to the local configuration information when the configuration of the
DataPower appliance is reloaded (such as during appliance reboot, firmware
reload, or domain restart). The default configuration of an Import Configuration
File object does not provide warnings about conflicts with existing files and
objects.
An Import Configuration File object is a configuration package that can include
both configuration information and supporting files. On the other hand, an Include
Configuration File object can include configuration information only.
To import a configuration package from an external file to the local configuration
information, perform the following procedure:
1. Select Objects Configuration Management Import Configuration File to
display the catalog.
2. Click the name of an existing configuration package to edit it, or click Add to
create a new one. The Import Configuration File configuration screen is
displayed.
configuration.
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.
8. Set Overwrite Files to control the overwrite behavior.
9. Set Overwrite Objects to control the overwrite behavior.
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 207.
11. Set Local IP Rewrite to indicate whether to rewrite local IP addresses on
import. When rewriting, for example, a service in the configuration package
that binds to eth1 is rewritten to bind to eth1 when imported.
12. Set Import on Startup to indicate whether to import the configuration
package at startup.
196
v If enabled, the configuration is marked external and cannot be saved to the

startup configuration. This behavior is equivalent to always importing the
configuration.
v If disabled, the configuration is not marked external and can be saved to
the startup configuration. This behavior is equivalent to importing the
configuration one time.
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 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
To ensure that all other objects and files are exported, use the admin account.
On XI50z use the dp-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
197
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 Comments field, enter a descriptive summary.
b. Optional: 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
download this file to your workstation. The Import Configuration utility
requires that the export file resides on your workstation.
3. Optional: 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.
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
download the export file to your workstation. The Import Configuration utility
198
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.
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.
199
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.
download the export file to your workstation. The Import Configuration utility
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. Optional: Create or select the name of a Deployment Policy to accept, filter,
b. Use Delete After Export to indicate whether the operation is a copy or
move operation.
200
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.
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.
201
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.
On XI50z, the configuration checkpoint data is not configurable. None of the
administrative accounts for XI50z have the necessary permissions to alter these
settings.
When saved, a ZIP formatted file for the configuration checkpoint is written the
chkpoints: directory for that application domain. During an upgrade, the operation
deletes the contents of this directory.
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.
On XI50z, the configuration checkpoint data is read-only. None of the
administrative accounts for XI50z have the necessary permissions to alter these
settings. The options on this page are disabled.
To define the number of checkpoint to allow for an application domain:
1. Click Administration Configuration Application Domain.
2. Click the specific application domain.
3. Click the Configuration tab.
4. In the Configuration Checkpoint Limit field, specify the number of checkpoint
configuration to allow.
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.
202
To save a configuration checkpoint:

1. Click Administration Configuration Configuration Checkpoints.
2. In the Checkpoint Name field, specify the name of the configuration
checkpoint.
3. Click Save Checkpoint.
4. Respond to prompts.
A ZIP-formatted configuration file of the specified name is written to the
chkpoints: directory. During an upgrade, the operation deletes the contents of this
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, see Deleting configuration checkpoints.
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, click 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, see Comparing
configurations on page 206.
Listing from the File Management utility

To view from the File Management utility:
1. Select the File Management icon from the Control Panel.
2. Expand the chkpoints: directory.
Rolling back to a configuration checkpoint

To
1.
2.
3.
4.
load the configuration that is defined in the configuration checkpoint:

Click Administration Configuration Configuration Checkpoints.
Click the checkpoint to which to roll back.
Click Rollback.
Respond to prompts.
Deleting configuration checkpoints

You can delete configuration checkpoints in one of the following ways:
v From the Configuration Checkpoints screen
203
v From the File Management screen
Deleting from the Configuration Checkpoints screen

To
1.
2.
3.
4.
delete from the Configuration Checkpoints screen:

Click Administration Configuration Configuration Checkpoints.
Click the checkpoint to delete.
Click Remove.
Respond to prompts.
Deleting from the File Management screen

To
1.
2.
3.
delete from the File Management screen:

Click the File Management icon from the Control Panel.
Expand the chkpoints: directory.
Select the check box beside the checkpoint file.
4. Click Delete.
5. Respond to prompts.
Importing configuration data

The import utility copies specified configuration data from your workstation to the
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 Rewrite Local Service
Addresses (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).
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.
To import configuration data:
1. Click Administration Configuration Import Configuration.
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.
204
d. Retain the selection of (none) for the Use Deployment Policy list. For more
information, refer to the Deployment policies on page 207.
e. Set Rewrite Local Service Addresses to control whether to substitute IP
addresses:
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.
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 or dp-admin account on XI50z. 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.
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
205
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.
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.
206
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.
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 among imported configuration
packages.
Depending on the clause type, the deployment policy can perform the following
types of configuration management against the new configuration package. The
processing sequence of clauses is as follows:
1. Accepted configuration, the white list, to always include resources that match.
2. Filtered configuration, the black list, to always delete resources that match.
3. Modified configuration to change the resources based on the defined action
type.
207
A modify clause supports the following actions:

v Adding the identified property with the identified value.
v Changing the value for the identified property.
v Deleting the identified property.
|
|
|
|
|
|
When adding properties, you can only add simple properties.

v If you define a clause to add a complex property, the addition will not be
successful. A complex property is one that has more than one parameter.
v If you define a clause to add an item to an existing vector property, the addition
might not be successful. A vector property is one that can contain more than one
entry.
|
|
|
To verify whether the deployment policy added the property:

v Check the error logs to make sure that the operation was successful
v Access those configurations, and view their current configuration
Creating deployment policies

A deployment policy is a sequence of clauses that include, exclude, or change
configuration data during the import. When defining matching statements, you can
use the builder or enter the statement.
v For details about using the builder, see Using the deployment policy builder
on page 209.
v For details about entering statements, see Specifying the matching statement
on page 209.
Note: You cannot modify the administrative state of a deployment policy.
To create a deployment policy:
1. Click Objects Configuration Management Deployment Policy.
2.
3.
4.
5.
Click Add.
Define accept clauses.
a. In the Accepted Configuration field, specify the matching statement, or
click Build.
b. Click Add.
Repeat this step to define another accept clause.
6. Define filter clauses.

a. In the Filtered Configuration field, specify the matching statement, or click
Build.
b. Click Add.
Repeat this step to define another filter clause.
7. On the Modified Configuration tab, define modify clauses.
a. Click Add.
b. In the Configuration Match field, specify the matching statement for the
modify clause, or click Build.
c. From the Modification Type list, select the type of modification.
d. If adding a property: In the Configuration Property field, specify the
property name.
208
e. If adding or changing a property: In the Configuration Value field, specify

the property value.
f. Click Save.
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 after clicking Add on the Modified Configuration tab
To use the builder to create a matching statement:
1. Click Build.
2. In the Device Address field, specify the IP address or host alias. The value *
matches all IP addresses.
3. From the Application Domain list, select the name of the domain. Selecting
(none) matches all domains.
4. From the Resource Type list, select the resource type. Selecting (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 resources. 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 property.
This property limits the matching statement to resources with the specified
property.
7. Optional: In the Configuration Value Match (PCRE) field, specify the value for
the property. This property limits the matching statement to resources with the
specified value. Use a PCRE to select groups of 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 enter 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.
209
resource
Specifies the resource type. The value * matches all resource types.
Name=resource-name
Optional: Specifies a name match for a resource. This property limits the
match statement to resources of the specified name. Use a PCRE to select
groups of resources. For example, foo* would match all resources with
names that start with foo.
Property=property-name
Optional Specifies the name of the property. This property limits the match
statement to resources of the specified property. If changing a value, set
property-name to a null string.
Value=property-value
Optional: Specifies the value for the property. This property limits the
match statement to resources of the specified property. Use a PCRE to
select groups of values.
For information about define a PCRE, go to the PCRE documentation on the web.
210
Chapter 11. Managing monitors

Monitors allows you to define a message set, the specification of a count-based or
time-based threshold, and the administrative controls to impose when the message
set exceeds the configured thresholds.
You can define the following types of monitors:
Count monitors
Count monitors measure traffic volume. Using a count monitor, you can
track all requests for a specific URL or set of URLs that originate from an
identified subnet and limit such requests to a specific traffic rate. For
details, see Configuring count monitors on page 214.
Duration monitors
Duration monitors measure appliance processing time and latency. Using a
duration monitor, you can measure the average server response time and
impose sanctions if the average time exceeds a configured threshold. For
details, see Configuring duration monitors on page 216.
Web services monitors
Web services monitors are WSDL-based and combine the properties of
count and duration monitors. Web services monitors observe traffic that
flows to and from a particular Web services endpoint. Web service
monitors implement a dual-threshold scheme where, for example, a
first-level threshold can generate a log message and a second-level
threshold can throttle traffic. For details, see Configuring Web services
Message monitors
You build message monitors from the ground up. This approach breaks down
complex configuration into simple, constituent parts. You can reuse these part to
address the requirements for your environment.
The parts, from the ground up, are as follows:
Traffic definition
A traffic definitions identifies which traffic streams are subject to
administrative monitoring and control. Traffic definitions are message
matching templates that describe traffic streams in terms of IP addresses,
requested URL, and HTTP headers. For details, see Traffic definitions on
page 212.
Message type
A message type assigns traffic definitions to a message monitor. A message
type enables a single message monitor to exercise administrative control
over multiple, possibly related, traffic streams. For details, see Message
Type on page 213.
Filter action
A filter action specifies the administrative actions to take in response to the
overuse of appliance or network resources. Filter actions can be cautionary
or stringent. For details, see Message Filter Action on page 213.
211
Message monitor
A message monitor consists of thresholds, a message type, and a filter
action. You can create the following message monitors:
v A count monitor uses an counter to track specific occurrences. It
activates a filter when the number of occurrences exceeds a threshold.
For details, see Configuring count monitors on page 214.
v A duration monitor is clock-based and measures the duration that
transactions take to complete. It activates a filter when the average
completion times exceeds a threshold. For details, see Configuring
duration monitors on page 216.
After configuring a message monitor, activate the monitor by associating it with
one or more DataPower services.
Traffic definitions
Traffic definitions identify traffic streams that are subject to administrative
monitoring and control.
Traffic definitions are message matching templates that describes traffic streams in
terms of the following criteria:
v Included and excluded source IP addresses
v Requested URL
v HTTP method
v Included and excluded HTTP headers
To configure a message matching template:
1. Click Object Monitoring Message Matching.
2. Click Add.
configuration.
6. In the IP Addresses field, enter a contiguous range of source IP addresses to
include. If blank, includes all source IP addresses.
7. In the Excluded IP Addresses field, enter a contiguous range of source IP
addresses to exclude. If blank, excludes all source IP addresses.
8. From the HTTP Method list, select the type of HTTP method to include. The
value any includes all HTTP methods.
9. In the Request URL field, enter a literal or wildcard expression to define the
URL set to include. If blank, includes all URLs.
10. Optional: Define HTTP headers to include.
a. Click the HTTP Headers tab.
b. Define an HTTP header to include.
1) Click Add.
2) Define the name-value pair for the header.
3) Click Save.
c. Repeat the previous to define another HTTP header.
212
11. Optional: Specify HTTP headers to exclude.

a. Click the Excluded HTTP Headers tab.
b. Define an HTTP header to exclude.
1) Click Add.
2) Define the name-value pair for the header.
3) Click Save.
c. Repeat the previous to define another HTTP header.
Message Type
Message types assign traffic definitions for use by a message monitor. 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.
Even if the message type consists of a single definition, you should assign a traffic
definition to a message type.
To
1.
2.
3.
4.
configure a message type:

Click Object Monitoring Message Type.
Click Add.
configuration.
6. In the Message Matchings list, add one or more traffic definitions.
Message Filter Action

Message filter actions specify the administrative actions to take in response to the
overuse of appliance or network resources by a monitored message type. Filters
can be cautionary or stringent.
You can define compound filters that activate a cautionary response at a low
threshold and a stringent response at a higher threshold. A cautionary response
would be generating a log message, and a stringent response would be the
temporary denial of service. All filter actions generate log messages at the
configured priority. These messages will be written to a log only if there is a log
target with an event subscription with the Monitor (or All) class and a priority
equal to or lower than the priority set by the filter.
To configure a filter action:
1. Click Object Monitoring Message Filter Action.
213
2. Click Add.
configuration.
6. From the Type list, select the action to enforce.
7. From the Log Priority list, select the severity of the message to write to the
log target.
8. Optional: In the Block Interval field when the action is reject or shape, enter
the blackout period to deny service for over-threshold messages. A value of 0
indicates that the monitor drops over-threshold messages but does not impose
service denial penalty.
Configuring count monitors

A count monitor uses an counter to track specific occurrences. It activates a filter
when the number of occurrences exceeds a threshold.
The counter advances based on one of the following criteria:
v
v
v
v
The service receives a client request.

The service receives a server response
The service receives an HTTP error response or processes an error rule.
The processing policy for the service uses a style sheet with the
dp:increment-integer extension element. For the monitor1 count monitor, the
style sheet must contain the following statement:
<dp:increment-integer name="/monitor-count/monitor1"/>
When defining the measurement interval, it works with the rate and burst limits to
define the conditions that activate the filter. For example, the following
combination imposes administrative sanctions when the monitored messages
exceed 50 transactions per second:
v The interval is 1000
v The rate limit is 50
v The burst limit is 100
To configure a count monitor:
1. Click Object Monitoring Message Count Monitor.
2. Click Add.
configuration.
6. From the Message Type list, select the message type that defines the traffic
definitions to use.
214
7. From the Measure list, select the action that advances the counter.
8. From the Source list, select how to aggregate source IP addresses based on the
associated traffic definitions.
9. In the Header field, enter the HTTP header that contains IP address
information. Generally, retaining X-Client-IP as the value is sufficient.
10. In the Maximum Distinct Sources field, enter the number of distinct IP
addresses to track. When the monitor observes too many distinct counts, the
monitor discards addresses not observed in the longest amount of time.
11. Define thresholds and filters.
a. Click the Threshold/Filters tab.
b. Define a threshold and filter.
1) Click Add.
2) In the Name field, enter the name for the threshold.
3) In the Interval field, enter the measurement interval.
4) In the Rate Limit field, enter the threshold value as message count.
5) In the Burst Limit field, enter the allowed burst value. For details
about setting this value, see Understanding the burst limit for count
monitors.
6) From the Action list, select the filter to trigger when the message type
exceeds thresholds. See Message Filter Action on page 213.
7) Click Save.
c. Repeat the previous step to define another threshold and filter.
After creating a monitor, activate it by assigning it to one or more DataPower
services.
Understanding the burst limit for count monitors

When setting the burst limit, the 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 defined burst limit.
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 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 to at least 1000 milliseconds, and set the allowed burst value to
approximately twice the threshold value.
215
Configuring duration monitors

A duration monitor is clock-based and measures the duration that transactions take
to complete. It activates a filter when the average completion times exceeds a
threshold.
Each measure represents a portion of the roundtrip timeline from the client request
to the server response.
v The values for requests and responses are internal to the appliance.
When the value is requests, the measure is the time the appliance uses to
process a client request. In other words, the measure is the interval between
the receipt of a client request and its transmission to the target server.
When the value is responses, the measure is the time the appliance uses to
process a server response. In other words, the measure is the interval between
the receipt of a server response and its transmission to the target client.
v The values for server and messages are external processing, specifically the
processing performed by the remote web or application server.
When the value is server, the measure is the server processing time. In other
words, the measure is the interval between the transmission of a client
request to the server and the receipt of the server response.
When the value is messages, the measure approximates the sum of requests,
server, and responses values. In other words, the measure is the time interval
between the receipt of a client request and the transmission of the server
response to the target client.
To configure a duration monitor:
1. Click Object Monitoring Message Duration Monitor.
2. Click Add.
configuration.
6. From the Message Type list, select the message type to monitor. See Message
Type on page 213.
7. From the Measure list, select a portion of the transaction cycle to measure.
8. Define filters.
a. Click the Filters tab.
b. Define a filter.
1) Click Add.
2) In the Name field, enter the name for the threshold.
3) In the Type field, retain the default value.
4) In the Value field, enter the threshold value. For details about setting
this value, see Understanding filters for duration monitors on page
217.
5) From the Action list, select the action to trigger when the message type
exceeds thresholds. SeeMessage Filter Action on page 213.
6) Click Save.
c. Repeat the previous step to define another filter.
216

After creating a monitor, activate it by assigning it to one or more DataPower
services.
Understanding filters for duration monitors

The value property works with the measure property to define the conditions that
activate a filter.
For example, the following combination imposes administrative sanctions when the
average interval between the receipt of a client request and the transmission of the
associated server response for the monitored message type exceeds 100
milliseconds:
v The measure is messages
v The value is 100

Web services monitors can monitor activity and provide logging and alerts based
on errors and transaction rate. For example, a bank might offer account query, loan
processing, and wire transfer services to its business partners. The traffic for every
business partner passes through a DataPower service that can be configured to
monitor traffic for each service that the bank offers. When errors or transaction rate
are met, the service can post messages to the log. With this information, the bank
can summarize and monitor the health of its offerings.
Web services monitors read a WSDL file and provides the ability to configure
monitors based on the services in the WSDL file.
Note: Web services monitors require the activation of statistics. By default,
statistics are administratively disabled.
Configuring Web services monitors

To configure a Web services monitor:
Click Object Monitoring Web Services Monitor.
Click Add.
configuration.
6. In the WSDL URL field, enter the URL of the WSDL file that defines the
endpoints, transport, and operations. The WSDL file can reside on the
appliance or on the network. Example values are local:///service.wsdl and
https://www.service.com/Services/service.wsdl.
7. In the Endpoint field, enter the name of the endpoint as defined in the WSDL
file. Using the following excerpt from a WSDL file, the field would have
BoodleSearchService as the value.
1.
2.
3.
4.
217
<service name="BoodleSearchService">
<port name="BoodleSearchPort" binding="typens:BoodleSearchBinding">
<soap:address location="http://api.boodle.com/search/beta2"/>
</port>
</service>
8. In the Endpoint URL field, enter the URL of the endpoint as defined in the
WSDL file. Using the excerpt shown for the Endpoint field, the Endpoint
URL field would have http://api.boodle.com/search/beta2/ as the value.
9. In the Front End URL field, enter the URL that the client uses to access the
endpoint. This URL can be different from the Endpoint URL, which might be
the case when the firewall rewrites the URL during processing. You can use a
wildcard (*) as the value. For example, /search/* could be the value.
10. From the Transport Type list, select the transport that the endpoint uses. This
value should match the transport identified in the WSDL file. Using the
following excerpt from a WSDL file, the choice would be SOAP-RPC.
<soap:binding style="rpc" transport="http://schemas.xmlsoap.org/soap/http"/>
11. Define the operations to monitor. To monitor both error count and transaction
rate, create two operations. Create one operation for error count, which
monitor the errors that occur at the front (or client request) URL. Create
another operation for transaction rate, which monitors the transaction rate for
the entire Web service.
a. Click the Operations to Monitor tab.
b. Define an operation to monitor.
1) Click Add.
2) In the Operation Name field, retain the default value. The current
implementation supports monitoring all operations in the WSDL file.
3) From the Target to Monitor list, select the target.
4) From the Threshold Level list, select the threshold level.
5) In the Threshold Value field, enter the count required to trigger the
action.
6) In the Threshold Action field, select the action to take when reaching
the threshold.
c. Repeat the previous step to define another operation to monitor.
Specifying dual thresholds

A Web service monitor can define a low threshold action and a high threshold
action. The low threshold action is generally cautionary, and the high threshold
action is generally stringent.
By default, first limit (low) messages are sent to the log target as warning
messages, and second limit (high) messages are sent to the log target as error
messages.
Log targets can be set to record messages based on severity. In the large target is
set to error, low messages would not be included in the log.
To specify dual thresholds:
1. Define the low threshold.
a. Click Add.
b. Select First Limit as the threshold level.
218
c. Provide the threshold value.

d. Select the threshold action.
e. Click Save.
2. Define the high threshold.
a. Click Add.
b. Select Second Limit as the threshold level.
c. Provide the threshold value.
d. Select the threshold action.
e. Click Save.
Enabling statistics
To enable statistics:
1. Click Administration Device Statistics Settings.
2. Set Administrative State to enabled.
219
220
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
Comments
Optional: Enter a descriptive summary.
Authorized counter
Optional: Select a message-count monitor. This object monitors and
controls incoming messages authorized by this AAA Policy. This counter
should Measure type XPath to allow the AAA Policy to increment the
counter on successful authorization. See Configuring count monitors on
page 214.
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. See Configuring count monitors on page 214.
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. See
Validation credentials on page 32.
221
SAML Message Signing Key

authentication: Select the Crypto Key to sign SAML assertions. See
Defining Key objects on page 25.
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. See Defining Certificate objects on page 22.
SAML Signing Message Digest Algorithm
Select the hash algorithm for SAML signing message.
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.
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.
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.
222
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 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.
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. 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 Message's 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
only process the wsse:Security header for the designated Actor/Role
Identifier. This setting takes effect for all AAA processing except post
processing.
WS-Sec Actor/Role Identifier
When enforcing WS-Security Actor/Role, specify the identifier.
223
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.
HTTP's 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:
HTTP's 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 token's 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
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.
224
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 client's IP address is used for identity extraction.
Subject DN from the certificate in the message's 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 245 for procedural and
configuration details.
Token extracted as Cookie value
The claimed identity of the requester is extracted from a Cookie value. If
selected, the WebGUI prompts for the following property:
Cookie name
Specify the cookie name.
LTPA Token
The claimed identity of the requester is extracted from an LTPA (Lightweight
Third Party Authentication) token value. LTPA tokens, which are opaque
signed and encrypted strings, are carried via HTTP, specifically in the
Set-Cookie response and Cookie request headers.
Refer to Understanding LTPA for more information.
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.
225
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 pane to designate the authentication
method.
1. Click the Authenticate tab.
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.
Skew Time
Specify the skew time (the difference, in seconds, between the
appliance clock time and other system times) that the SAML
assertion expiration takes into account when the appliance
consumes SAML tokens for the following conditions:
NotBefore
Uses the current time minus the skew time.
NotOnOrAfter
Uses the current time plus the skew time.
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:
226
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 276 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 user's 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
user's DN.
(Default) Disables an LDAP search for the user's group.

The login name of the user along with the LDAP prefix
and the LDAP suffix will be used to construct the user's
DN.
v If on, the WebGUI displays the following field.
off
227
LDAP Search Parameters

Select the LDAP Search Parameters from the list. Refer to
Defining LDAP Search Parameters objects on page 266
for detail.
v If off, the WebGUI removes the following fields:
LDAP Prefix
LDAP Suffix
User Auxiliary LDAP Attributes
email,cn,userPassword. Results are appended to the context
variable var://context/ldap/auxiliary-attributes. The LDAP
attributes are synchronized to the AAA authentication cache.
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.
Skew Time
NotBefore
NotOnOrAfter
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.
228
The following properties are relevant for attaching WS-Policy, not for
AAA authentication.
Require Client Entropy
Indicates whether to require client entropy as key material in the
WS-Trust request.
on
Requires client entropy. The DataPower appliance sends

an entropy element to the WS-Trust server as part of the
security token request exchange. Use the WS-Trust
Encryption Certificate property to determine how to
include the key material in the request.
off
(Default) Does not require client entropy.
When required, specify the size of the client entropy in bytes in

the Client Entropy Size field. The size refers to the length of the
client entropy before Base64 encoding. Use an integer in the range
of 8 through 128. The default is 32.
Require Server Entropy
Indicates whether to require server entropy in the WS-Trust
response.
on
Requires server entropy. The WS-Trust server must return

an entropy element to the DataPower appliance as part of
the security token request exchange.
off
(Default) Does not require server entropy.
When required, specify the minimum allowable size of the

received entropy material in bytes in the Server Entropy Size
field. The size refers to the length of the client entropy before
Base64 encoding. Use an integer in the range of 8 through 128.
The default is 32.
Require RequestSecurityTokenCollection
Indicates whether to generate a WS-Trust RequestSecurityToken or
a WS-Trust RequestSecurityTokenCollection as part of the security
token request exchange.
on
Generates a WS-Trust RequestSecurityTokenCollection.
off
(Default) Generates a WS-Trust RequestSecurityToken.
Require AppliesTo SOAP Header

Indicates whether to generate a WS-Addressing AppliesTo header
as part of the security token request exchange.
on
Generates a WS-Addressing AppliesTo header.
off
(Default) Does not generate a WS-Addressing AppliesTo

header.
When required, specify the value for the AppliesTo header in the
AppliesTo Header field.
WS-Trust Encryption Certificate
Optional: 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.
229

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.
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
Select the NSS Client object that specifies the details for
connecting to the NSS server. Refer to NSS Client on page 368
The requester is authenticated by 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 252
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:
230
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.
Skew Time
NotBefore
NotOnOrAfter
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:
231
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 32 for
more information.
The following inputs are displayed for all methods.
Cache authentication results
Select the caching strategy.
The authentication cache stores authentication data to minimize the
overhead of re-authenticating the same identity. Each entry in the cache
must have a unique key. This key is the output from the identity
extraction phase plus any ancillary data for the defined authentication
method. When there is a match against a unique key, the cache returns
the results from the previous authentication of this identity.
By default, the cache contains authentication data for three seconds.
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.
Skew Time
Specify the skew time (the difference, in seconds, between the appliance
232
clock time and other system times) that the SAML assertion expiration
takes into account when the appliance consumes SAML tokens for the
following conditions:
NotBefore
NotOnOrAfter
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:
TFIM Configuration
Select an existing TFIM object. Refer to Creating TFIM objects
Credentials from WS-SecureConversation Token
The authentication credentials are mapped via a WSSecureConversation 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.
233
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
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
234
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
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
pane to designate the authorization method.
1. Click Authorize.
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
235

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.
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
236
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.
User Auxiliary LDAP Attributes
email,cn,userPassword. Results are appended to the context
variable var://context/ldap/auxiliary-attributes. The LDAP
attributes are synchronized to the AAA authorization cache.
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:
Select the NSS Client object that specifies the details for
connecting to the NSS server. Refer to NSS Client on page 368
Default Action
Select the default action to specify the access level to the resource.
The default is r (Read). The value specified by this property can
be programmatically overridden by setting the
var://context/AAA/az-zosnss-operation variable to one of the
valid values.
a (Alter)
r (Read)
237
c (Control)
u (Update)
Always Allow
All messages are forwarded to the backend server.
Generate a SAML Attribute Query
The requester is authorized by a SAML attribute query/response
exchange between the DataPower appliance and a SAML server. If
selected, the WebGUI prompts for the following properties:
URL
Specify the location of the SAML server.
SAML Match
Select the minimum authorization criteria.
All
Authorization requires the presence of all configured SAML

attributes
All-Values
Authorization requires that all configured attribute names
and values be present in the SAML attribute statement
Any
Authorization requires the presence of a single SAML

attribute
Any-Value
Authorization requires that a single configured attribute
name and value be present in the SAML attribute statement
XPath Authorization requires that SAML server responses are
evaluated with an XPath expression
SAML XPath
If SAML Match is XPath, specify the operative XPath expression.
SAML Name Qualifier
Optionally specify the value of the NameQualifier attribute of the
NameIdentifier in the generated SAML query. Some SAML
implementations require this value to be present.
SAML Version
Select the SAML protocol version to use when employing SAML for
authorization. Versions 1.0, 1.1 and 2.0 are supported. The version
selected affects the format of the messages sent to SAML authorities.
SSL Proxy Profile
connection.
Skew Time
NotBefore
NotOnOrAfter
238
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.
Skew Time
NotBefore
NotOnOrAfter
The requester is authorized by Tivoli Access Manager (TAM). A TAM
object must exist for this method to succeed. Refer to Creating Tivoli
Access Manager objects on page 252 for more information.
239
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
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.
240
Any other XACML response results in the client's 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
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 client's
authorization.
Use On Box PDP
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
Force the use of the SAML2.0 Profile. Meaningful only
when the XACML version is 2.0.
SOAP Enveloping
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.
241
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, the cache contains authorization
data for three seconds.
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.
Skew Time
Specify the skew time (the difference, in seconds, between the appliance
clock time and other system times) that the SAML assertion expiration
takes into account when the appliance consumes SAML tokens for the
NotBefore
NotOnOrAfter
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
242
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
v Generate a SAML assertion or response that can contain one or all of the
following assertion types: an authentication statement, an attribute statement,
and an authorization decision statement
For more information about these activities, refer to Post processing activities on
page 181.
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 authorization.
243
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.
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 245 for more
information.
244
Transaction Priority tab

Note: You might need to use the probe to determine the string for the mapped
credential.
Define transaction priority:
1. Click the Transaction Priority tab.
2. Define the priority.
a. Click Add.
b. In the Credential Name field, specify the name of the mapped credential.
c. From the Transaction Priority list, select the priority of the transaction.
d. Set Require Authorization to indicate whether to require authorization.
e. Click Save.
3. Repeat the previous step to define another priority.
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 for authorization

To define SAML attributes that can be used for authorization, 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 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.
245
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
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 245 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>
246
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 for more information.
Note: The AAA Info file can be edited outside of the AAA Info file editor and
uploaded to the appliance.
Authenticate element: The Authenticate element or elements contain the
database of identities that can be authenticated by this file. Identities can be
identified by one or more of the following attributes:
v User name
v Password
v IP address or host name
v IP network
v Distinguished name (DN)
v Custom token
Each identity is given a credential by this element.
MapCredentials element: The MapCredentials element takes in a credential string
and maps it to another. The input can be matched by a PCRE regular expression.
This element can be fed directly from an Authenticate element contained in this
file. Usually, however, this element is used to map an identity extracted from a
message to another identity more meaningful to the authorization method.
MapResource element: The MapResource element takes in a resource string
extracted from the message and maps it to another, perhaps more meaningful to
the authorization method. Input resources can be one or more of the following
types:
v
v
v
v
v
v
Original (client) URL

URL sent to server (target URL)
SOAP Operation Namespace (request URI)
SOAP Operation Name (request operation)
HTTP method
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.
247
The AAA Info file editor has the following pages:

v Default credential (unauthenticated identity)
v Credentials (authenticated identities)
v Map credentials
v Map resources
v Authorized access to resources
v File information
At any point, click Cancel to abandon all changes and close the file editor.
Default credential (unauthenticated identity): The initial screen presents the
opportunity to set the default credentials for unauthenticated identities. This is the
credential assigned to identities for which no other credential can be found in the
Authenticate section. If left blank, all unauthenticated identities are denied access.
Credentials (authenticated identities): The authenticated identities page provides
a list of identities that are authenticated by this file. When creating a new file, none
are initially listed.
Click Next if this file will not be used for authentication. Click Add to create new
identities that this file can authenticate. A new window opens with a form for
adding identities.
Host Name or IP Address
The host name or IP address of the client that submitted the message. The
IP address takes dotted decimal form w.x.y.z. The entry 0.0.0.0 (or 0) is
not allowed.
v Use this field only when the identity extraction method is set to Client
IP address.
v If this field is used, you cannot use the IP Network field.
IP Network
The IP network of the client that submitted the message. This entry takes
the form x.y.z.a/b (for example 192.168.2.25/24).
v Use this field only when the identity extraction method is set to Client
IP address.
v If this field is used, you cannot use the Host Name or IP Address field.
User name
The user name extracted from the message. User names can be extracted
from messages in a number of ways, including HTTP Basic Authentication,
WS-Security UserName, and Name from SAML headers. If those AAA
Policy identity extraction methods are not used, do not use this field.
Password
The password extracted from the message. Passwords can be extracted
from messages by HTTP Basic Authentication and WS-Security UserName.
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
248
extraction methods Token extracted from the message and Token extracted
as cookie value return this value. If those methods are not used for
extraction, do not use this field.
Credential Name
The credential returned by the authentication. This can be the same as the
extracted identity or different. The value should be meaningful either to
the AAA Policy Map Credentials method or to the AAA Policy Authorize
method.
All of the fields that contain information must be matched for the authentication to
succeed. If the identity extraction method returns only a user name (such as with
SAML) and the Authenticate Identity entry contains both user name and password,
authentication will fail. The AAA policy, however, tests an extracted identity
against all entries in the order in which they are listed, stopping after it finds a
complete match. It is possible to create one entry for user name Bob that also has a
password of foo and another with no password entry. Should the extraction
method only retrieve the user name and not the password, Bob will still
authenticate.
Map credentials: The Map Credentials page presents a list of all credential maps
contained in the file. When creating a new file, this list is empty.
Click Next to move to the next page if this file will not be used for mapping
credentials. Click Add to create a new credential map.
Input Credential
The credential input to the mapping. This field accepts PCRE expressions,
allowing a single expression to match more than one input credential.
Entering foo causes the AAA policy to match all input credentials that
contain the string foo.
Credential Name
The credential to output in place of the input credential. This is the value
to which the input credential is mapped. This is not a regular expression.
Click Submit to add the new map to the list of maps. Create as many mapping
entries as needed by clicking Add for each new entry.
Note: If this file is used for mapping credentials, any input credential that does
not match a map is converted to a blank credential for the purposes of
authorization.
Map resources: The Map Resource page presents a list of all resource mappings
contained in the file. Resource mapping is used to map the resource identifier
extracted from the message to something else. If the AAA Policy uses more than
one resource extraction method, all methods will be executed.
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.
249
Request URI
The Namespace URI of the action or method requested in the body of the
SOAP message. This is identified as the topmost element in the SOAP:Body
element.
Request Operation
The name of the operation requested in the body of the SOAP message.
HTTP Method
Select the desired method. Select any to allow any method.
Result of XPath Expression
Any value that is extracted from the message by an XPath expression. This
is a PCRE expression.
Resource
The resource string to which the input resource is mapped. This field is
required.
Note: If this file is used for mapping resources, any resource that does not mapped
by the file will be converted to a blank resource for the purposes of
authorization.
Authorized access to resources: The Authorize page presents a list of all
authorization pairs contained in this file. Authorization is based on an input
credential (after mapping, if any) and an input resource (after mapping, if any).
If this file is not used for authorization, click Next. To create an authorization entry,
click Add.
Credential
The credential to match for authorization. This field accepts PCRE
expressions.
Resource
The resource to match for authorization. This field accepts PCRE
expressions.
Access
Select allow or deny as the authorization result.
Note: When this file is used for authorization, access is denied by default. Any
unmatched entries result in denied access. Access is allowed only if a match
is found and the Access for that match is allow.
File Information: The file information page provides a means to name the file
and add a comment if desired.
This file is typically placed in the local: directory.
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.
250
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.
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) or
Microsoft Active 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 LDAP directories or Microsoft Active Directory server.
Although the configuration files allow specifications for Lotus Domino, the
appliance does not support this directory servers.
Tivoli Access Manager security

The TAM client supports LDAP or Active Directory registries 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.
Note: The Tivoli Access Manager configuration files should be used in only one
Tivoli Access Manager object. Do not share the Tivoli Access Manager
configuration, key, or stash files between objects. Every object must have its
own set of files and its own application ID. This restriction avoids issues
when refreshing the keystore password and stash files, and ensures that all
Tivoli Access Manager objects are associated with a unique identifier.
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 registry configuration file (.conf extension) (Active Directory only)
v The TAM SSL key file (.kdb extension)
251
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
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.
252
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. Click the Refresh Tivoli Access Manager Client Certificate tab.
3. Define the operational properties. Refer to the online help for details.
4. Click Refresh Tivoli Access Manager Client Certificate.
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
1.
2.
3.
create and configure TFIM access:

Click Objects Access Settings IBM Tivoli Federated Identity Manager.
Click Add.
Use this pane to specify operational parameters.
a. Specify the name for the object in the Name field.
b. Set Administrative State to identify the administrative state of the
configuration.
c. Optional: In the Comments 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.
253
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.
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.
254
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.
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. Set Schema Validate Response 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.
Kerberos objects
A basic description of the Kerberos authentication protocol is helpful for
understanding the support provided by the DataPower appliance.
255
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 Alice's shared secret
v A ticket for the FTP service
The ticket contains:
v
v
v
v
The idobj for Alice

The idobj for the FTP service
A ticket lifetime
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.
256
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
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

A Kerberos keytab file contains the keys to decrypt the ticket presented by a client
that is 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 configuration identifies the file that contains the keys to decrypt the
ticket.
257
To configure a Kerberos keytab file:

1. Click Objects Crypto Kerberos Keytab.
2. Click Add.
configuration.
6. From the File Name list, select the keytab file in the cert: or sharedcert:
directory of the appliance. If the file does not exist on the appliance, you can
upload or fetch the file.
Note: This file is not generated on the DataPower appliance. It is generated
through the Kerberos system itself.
7. Set Use Replay Filter to determine whether to cache Kerberos authenticators
on tickets destined for Kerberos principals in the keytab file.
8. Set Generate GSS-API Checksum in AP-REQ to determine whether to
generate a GSS-API checksum when generating AP-REQ tokens with the
keytab.
|
|
|
|
|
|
9. If generating a checksum, set or clear the GSS-API Checksum Flags check

boxes to identify which flags to set in GSS-API checksum when generating
AP-REQ tokens with the keytab file. See RFC 4121 for flag definitions.
Using SAML attributes for post processing

To use SAML attributes for post processing, use the following procedure:
1. Select Objects XML Processing SAML Attributes.
2. Click Add to display the SAML attributes catalog.
3. To create new SAML attributes, click Add.
4. Define the following properties:
Data Source Type
The data source to retrieve the value for each SAML attribute.
Name The name of the SAML attribute that is being generated.
Attribute NameSpace/Format
The namespace URI for the SAML 1.x attribute that is being generated
and the NameFormat value for the SAML 2.0 attribute that is being
generated.
Data for Attribute Value
The data source type that retrieves the value of the SAML attribute.
The data source type can be the name value from a variable, such as
the default variable var://context/ldap/auxiliary-attributes that
enables LDAP user attributes; a value from an input XML message with
an XPath setting; or a static value.
Supplemental Data
If the data source type is retrieved from a variable, the value that
matches the name attribute of the attribute-value elements of the
variable. If the data source type is a static value, the static string value.
258
Friendly Name
A meaningful name for the SAML attribute.
5. Click Apply to save the configuration.
6. Repeat step 3 on page 258 through step 5 to define as many SAML attributes as
needed.
7. After defining all SAML attributes, click Apply.
XACML Policy Decision Point

During the authorization phase of an AAA Policy, you can select Use XACML
Authorization Decision. The AAA Policy acts as an XACML Policy Enforcement
Point (PEP). The PEP allows the XACML Policy Decision Point (PDP) to decide
whether or not to authorize access.
The DataPower appliance supports the mandatory to implement and optional
specifications that are listed in Section 10.2.8 of the OASIS Standard, eXtensible
Access Control Markup Language (XACML) Version 2.0, dated February 1, 2005.
Defining a XACML PDP

To configure an XACML Policy Decision Point (PDP):
1. Click Objects Access Settings XACML Policy Decision Point.
2. Click Add.
configuration.
6. Set Evaluate Individual Policies Equally to signal the presence of a
comprehensive top-level XACML policy-set. A top-level set is the general
policy file.
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
259
policy conditions evaluate unambiguously to permit or deny,

evaluation is immediately halted, and the policy combination
evaluates to the effect of that individual policy. If the individual policy
evaluates the target as FALSE or the policy conditions as
NotApplicable, then the next policy in the order is evaluated; if no
further policy exists in the order, the policy combination evaluates to
NotApplicable.
Only One Applicable
The only-one-applicable policy combining algorithm evaluates each
policy in the order that it appears in the XACML policy set; unlike the
other policy combining algorithms, only-one-applicable must evaluate
all policies to render a final evaluation. If after evaluating all policies,
no policy is considered applicable by virtue of its target (the requested
resource), the policy combination evaluates to NotApplicable. If after
evaluating all policies, more than one policy is considered applicable
by virtue of its target, the policy combination evaluates to
Indeterminate. If after evaluating all policies, only one single policy is
considered applicable by virtue of its target, the policy combination
evaluates to the result of evaluating that single policy.
Permit Overrides
The permit-overrides policy combining algorithm evaluates each
policy in the order that it appears in the XACML policy set. If any
policy in the set evaluates to permit, the policy combination evaluates
immediately to permit. In other words a single permit takes
precedence over other policy evaluations. If all policies are determined
to be NotApplicable, the policy combination evaluates to
NotApplicable.
This property is meaningful only if Evaluate Individual Policies Equally is
set to on.
9. Use the Dependent Policy Files field 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 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, specify the time to maintain
compiled XACML policies in the PDP cache. A 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
260
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.
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.
261

configuration.
6. Use the Profiles check boxes to select the profiles against which to check
messages for conformance.
7. Use the Ignored Requirements controls to define which requirements to
ignore. Specify a string in the profile:reqid format to define the requirement:
profile
Specifies the literal representation for the name of the profile.
BP1.0
Indicates WS-I Basic Profile, version 1.0
BP1.1
Indicates WS-I Basic Profile, version 1.1
BSP1.0
Indicates WS-I Basic Security Profile, version 1.0
AP1.0
Indicates WS-I Attachment Profile, version 1.0
reqid
Specifies the identifier of the requirement in that profile. This identifier
follows the naming convention in the profile documentation.
To specify requirement R4221 in the WS-I Basic Security Profile, version 1.0,
add BSP1.0:R4221 to the list.
8. Use the Corrective Stylesheets controls to specify which style sheets to invoke
after conformance analysis. These style sheets can transform the analysis
results to repair instances of nonconformance. Corrective style sheets cannot
be applied to filter actions.
9. From the Record Report list, select the degree of nonconformance to cause a
conformance report to be recorded.
10. When reporting nonconformance: In the Destination field, specify the target
URL to which to send conformance reports.
11. From the Reject nonconforming messages list, select the degree of
nonconformance to cause the message to be rejected.
12. When rejecting nonconforming messages: Set Include error summary to
indicate whether to include the summary for the conformance analysis in the
rejection message for requests.
13. Set Use analysis as results to indicate whether to deliver a conformance
analysis.
14. Set Distinct response behavior to determine whether to define a distinct set
of logging and rejection parameters for responses or requests.
15. From the Record Report (response direction) list, select the degree of
nonconformance to cause a conformance report to be recorded for responses.
Never (Default) Never records conformance reports.
Failure
Records conformance reports that indicate conformance failures.
262
Warning
Records conformance reports that indicate conformance warnings or
conformance failures.
Always
Always records conformance reports.
16. (Optional) For all nonconformance reporting levels except Never, specify the
target URL to which to send conformance reports for responses in the
Destination field.
17. From the Reject non-confirming response messages list, selects the degree of
nonconformance to cause the response message to be rejected.
Never (Default) Never reject messages.
Failure
Rejects messages with conformance failures.
Warning
Rejects messages with conformance warnings or with conformance
failures.
18. Set Include response error summary 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.
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.
To create a document map:
1. Click Objects XML Processing Document Crypto Map.
2. Click Add.
3. On the Main tab, define the basic configuration.
4. On the Namespace Mappings tab, define namespace prefixes and the
associated URI for each.
For information about properties, see the online help.
HTTP Input Conversion Map

HTTP Input Conversion Maps enable the translation of non-XML input (for
example, an HTML form) to XML format.
1. Select Objects XML Processing HTTP Input Conversion Map to display
the HTTP Input Conversion Map catalog.
2. Click Add to display the HTTP Input Conversion Map Configuration (Main)
screen.
Name Specify the name of the HTTP Input Conversion Map.
263
Comments
Input Encoding tab

1. Click the Input Encoding tab to display the HTTP Input Conversion Map
Configuration (Input Encoding) screen.
2. Click Add to display the Input Encoding Property window. Use this screen to
define conversion rules.
Input Match
Select the input content subject to this conversion rule. Specify a PCRE
(Perl-compatible regular expression). PCRE documentation is available
at http://www.pcre.org.
Encoding
Select the input format.
Base 64
Input is treated literally. Processing adds encoding="base64"
attribute to input element
Plain
XML escape the output
URL-encoded
URL unescape, then XML escape the output
XML (Default) Input is treated literally, no processing
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 define the connection to an IMS Connect server:
1. Click Objects Network IMS Connect.
2. Click Add.
configuration.
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.
264
8. Set EBCDIC Header Conversion 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. Set Expect LLLL Response Header 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.
on
Indicates a response message with a 4 byte LLLL header field.
off
(Default) Indicates a response message without the initial LLLL

header.
12. In the Sync Level field, specify whether to use an IMS Sync Level of 0x00 or
0x01. The default is 0x00 which disables the sending of an ACK.
v A Sync Level of 0x00 identifies that the IMS Sync Level is set to NONE.
v A Sync Level of 0x01 identifies that the IMS Sync Level is set to CONFIRM.
When communicating with the IMS Connect server on the backend and a
transaction is specified with the Sync Level of 0x01, the client must send an
ACK (successful) or a NAK (unsuccessful) after processing the response.
The IMS Connect server then sends DEALLOCATE CONFIRM (successful)
or DEALLOCATE ABORT (unsuccessful) back to the client. The DataPower
appliance always sends an ACK upon receiving the response and then
checks for the DEALLOCATE CONFIRM.
13. Override default IMS Connect configuration value. All the properties on the
Default Headers tab are default values. Some of them can be overridden in
the URL, and others through header injection.
a. Click the Default Headers tab.
b. Specify the exit program to use for all IMS connections in the Exit
Program field.
c. Specify the name of the IMS client identifier in the Client ID field. If
blank, the user exit must generate it.
d. Specify the transaction code to invoke in the Transaction Code field. This
value can be overridden by specifying it in the backend URL. Refer to
Building an IMS Connect URL on page 46 for more information.
265
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 46 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.

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.
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.
266
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.
configuration.
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.
Subtree
(Default) Search the entry level of the tree and all of its descendents.
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.
267
Figure 12 shows the load balancer group with four members
DataPower
appliance
Load Balancer
Group
Application
server A
Application
server B
Application
server C
Application
server D
Figure 12. Load balancer group with static members to support load balancing
Depending on the algorithm that makes load-balancing decisions, each load

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

Intelligent load distribution uses a load balancer group to distribute workload
more efficiently across application servers by providing the ability to dynamically
change configuration data about membership, weight of members, and session
affinity.
Note: The ability to use intelligent load distribution requires the Option for
Application Optimization feature.
To get the full benefit of 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 13 on page 269 shows the required configuration.
268
DataPower
appliance
WebSphere Application Server

cell
WebSphere
Cell
Deployment
manager
ODCInfo
Load Balancer
Group
Figure 13. Configuration to support intelligent load distribution
The communication between the DataPower appliance and the cell in the
WebSphere environment is as follows:
1. The ODCInfo application retrieves data about the application servers in the cell.
2. The WebSphere cell configuration retrieves the information from the ODCInfo
application and updates the data in the load balancer group.
3. The load balancer group uses this data to adapt to changing traffic conditions
and application server capabilities to optimally distribute traffic among the
application servers in the cell.
If your application server must maintain session affinity, you can configure session
affinity to override load balancing decisions.
|
Application intelligence
|
|
|
|
|
|
|
|
Application intelligence is an extension of intelligent load distribution. With

application intelligence, the load balancer group is designed to use application
specific information from the application servers to optimize routing decisions.
Specifically, the following application information is used to make routing
decisions:
v Virtual host group information
v Web module information
v Application and application edition information
v Routing rules
|
|
|
|
|
|
|
|
Using this information, the load balancer group can ensure that a request is
targeted to a specific application and the application is running. If application
edition rollout is used, the request is routed to the new edition when it comes
online. If a request is for an application that is not available on any of the
application servers, the appliance rejects the request and returns a 404 or Not
Found error response to indicate that there is no matching application. This saves
processing on the application server. If the application is found, but is not active
on a server, a 500 or Internal Server error response is returned.
|
|
Application intelligence supports the following two main aspects:

v Application routing
269
|
|
|
|
|
Provides load balancing based on application knowledge on the back end.

v Application rollout
Provides the ability to replace a running application edition with a new edition
with little or no traffic loss. Supports atomic and group rollout in a WebSphere
Virtual Enterprise cluster with full quiescent capabilities.
|
|
|
|
|
|
|
Application routing uses application knowledge about the back-end servers to

make routing decisions. For example, assume an application is running on a subset
of a cluster. Without application routing, requests would be distributed to all
servers including the ones not running that application. This would put additional
pressure on the back-end servers to redirect traffic. This scenario is one that occurs
during the rollout of an application. There are periods of time where an
application is running on some subset of the servers in a cluster.
|
|
|
|
|
|
|
|
|
|
The application routing decision is made based on the Host: header and the URI
of the incoming HTTP request to route the request to the appropriate application
server. For a request to be properly routed, the Host: header must contain a value
that matches the vHostGroup host and port information defined in the WebSphere
Cell. And, the URI must match the URI information defined in the WebSphere Cell
WebModules and WebRouteWorkClasses. If the matching is unsuccessful, a 404
response code is returned. With application routing disabled, the appliance cannot
respond with a 404 response. Instead, it forwards the request to one of the servers
in the Cell regardless of the active applications on that server. HTTP/1.0 requests
that typically do not contain Host: headers will be answered with 404 responses.
|
|
|
|
Application rollout, a feature available on WebSphere Virtual Enterprise, replaces

an active edition of an application with a new edition. For additional information
on application editions, see the WebSphere Virtual Enterprise documentation on
application edition management.
|
|
|
|
|
The DataPower appliance supports the following types of application rollout:

v Group rollout
Performs a rollout of a new edition using a defined group size that specifies the
number of nodes to process at a time.
v Atomic rollout
|
|
|
Performs a rollout of a new edition replacing the edition on half of the cluster
members at a time. Serves all user requests with a consistent edition of the
application.
Two settings are used to enable application intelligence in the load balancer group:
|
|
|
v In the load balancer group, enable application routing

v In the WebSphere Cell object, set the update method to subscribe so that the
appliance receives faster notification of state changes
See the tasks for configuring these objects for additional information.
Required software
For full support of dynamic membership and weights, 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.
|
|
270
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.
|
|
|
|
|
|
Backend servers other than WebSphere Application Server Network Deployment or

WebSphere Virtual Enterprise support a smaller feature set. Non-WebSphere
application servers can be used in the following configurations:
v As members of a WebSphere Virtual Enterprise cluster
v As members of an application server cluster whose membership, weights, and
session affinity are controlled with a custom application
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 Application routing that provides the ability to route based on URI or host
values
v Edition rollout that provides rollout of a new edition of an application in a
seamless fashion
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 least connection 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 dynamically update membership when using a custom application
that provides the workload management information. 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 when using a custom application that provides the workload
management information.
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
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.
271
Load balancer groups support weighted and non-weighted algorithms:

v First alive
v Hash
v Least connections
v Round robin
v 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,
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.
272
Weighted least connections

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

The weighted round robin algorithm maintains a weighted list of servers and
forwards new connections in proportion to the weight (or preference) of each
server.
This algorithm uses more computation times than the round robin algorithm.
However, the additional computation results in distributing the traffic more
efficiently to the server that is most capable of handling the request.
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
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
273
membership and weight of application server members in the load balancer group
so that the load balancer group can route traffic to the application server that can
best handle the load.
As new servers are brought online or as existing servers are taken offline, the
membership information in the load balancer group adapts to these changes.
Health checks
A health check is essentially a scheduled rule that sends the same request to each
member. The successful completion of the health check requires that the server
passes normal TCP and HTTP connection criteria. Optionally, the health check
contains a filter to test the response from the server. The expected response is
always valid XML. The response is analyzed using the defined XPath expression. 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.
274
Session affinity enhances application performance by using in-memory caching, not

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

A load balancer group supports the following types (or modes) of session affinity:
v Passive
v Active
v Active-conditional
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.
275
In active-conditional mode, the DataPower appliance recognizes when an

application server establishes session affinity by comparing the Set-Cookie header
in the response to a list of cluster-specific cookie names.
v If the response header contains a Set-Cookie header from the list, the appliance
inserts in the response an additional Set-Cookie header with routing
information.
v If the response header does not contain a Set-Cookie header from the list, the
appliance does not insert a Set-Cookie header.
Session affinity modes and where to configure

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

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

Active session affinity can be configured from the DataPower appliance or from
the WebSphere Administrative Console. For active session affinity the application
servers can be WebSphere or non-WebSphere servers
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.
276
5.
6.
7.
8.
v Required for groups of non-WebSphere servers.

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:
1.
2.
3.
4.
Click Objects Network Load Balancer Group.

Click Add.
configuration.

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.
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 on page 278.
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.
277
Adding static members

To
1.
2.
3.
4.
add static members to an existing load balancer group:

Click the name of the load balancer group to modify.
Click the Members tab.
Add static members.
a. Click Add.
b. In the Actual Host field, enter the IP address or the domain-qualified host
name of the member.
c. For weighted algorithms: In the Weight field, enter the relative weight
(preference). The greater the value, the more likely this server is to receive a
connection request.
d. In the Mapped Server Port field, enter the member-specific target port or
retain the default value to use the DataPower service-defined port.
By default, member servers are contacted on the DataPower service-defined
port. However, if you have services running on different ports for different
member servers, explicitly identify the member-specific target port. If you
specify a nonzero value, that member server will always be contacted on
this port.
e. In the Health Port field, enter the member-specific health port or retain the
default value to use the load balancer group-defined port.
A nonzero value overrides the value for the Remote Port property of the
health check. This property is available during the configuration of the
health check on the Health tab.
f. Retain the default setting for Admin State. To place in an inactive
administrative state, click disabled.
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.
278
Procedure
Click Network > Other > Load Balancer Group
Click the name of load balancer group.
Click the Session Affinity tab.
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.
1.
2.
3.
4.
a. In the Monitored Cookies field, enter the name of the cookie to monitor.
b. Click Add
7. Optional: Repeat the previous step to add another cookie. The configuration
requires at least one cookie.
8. Click Apply to save the changes to the running configuration information.
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.
279
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.
Before you begin

Configure a load balancer group.
About this task

Configure the load balancer group to request workload management information
from the ODCInfo application. The load balancer groups uses the WebSphere Cell
configuration to gather information about the application servers in the WebSphere
cell. The WebSphere Cell configuration that is referenced by the load balancer
group forwards this information to the load balancer group.
Note: Until the load balancer group successfully receives the workload
management information from the ODCInfo application, it uses the
members defined as part of its running configuration.
Procedure
1. Click Objects > Network Settings > Load Balancer Group.
2. Click the name of the load balancer group to modify.
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. Optional: Set Enable Application Routing to on to use application intelligence.
When using application edition, either atomic or group rollout, set the Update
Method of the WebSphere Cell object to subscribe.
|
|
|
5. Optional: Review the session affinity information on the Session Affinity tab to
ensure that session affinity is correctly configured.
Results
The load balancer group begins to request information from the ODCInfo
application.
280
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
1.
2.
3.
4.
assign weight to members.

Click the name of the load balancer group to modify.
Click the Members tab.
Change the weight for a specific member.
a. Click the pencil icon to edit the member.

b. In the Weight field, change the value.
c. Click Save.
5. Repeat the previous step to modify another member.
Disabling members
If you need to disable a member, you can disable the member from the load
balancer group without deleting the member from the group.
To disable specific members to not participate in load balancing decisions:
3. Click the Members tab.
4. Disable members.
a. Click the pencil icon to edit the member.
b. Set Administrative State to disabled 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 com.ibm.datapower.odc.osgi.jar
v ODCInfo_ND61.war
v ODCInfoCheckInstall.jacl
v ODCInfoDeploy.jacl
v ODCInfoStart.jacl
281
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
Install the Open Services Gateway initiative (OSGi) bundle.
Install the ODCInfo application on the deployment manager.
Start the ODCInfo application.
Create or modify a load balancer group to use the ODCInfo application to
retrieve workload management information from the WebSphere cell.
1.
2.
3.
4.
|
|
|
Installing the OSGi bundle
Before you begin
Download the com.ibm.datapower.odc.osgi.jar file.
|
|
Note: Uninstall any previous version of the OSGi bundle before installing another
version.
About this task
|
|
The OSGi bundle is used to enable the ODCInfo application to interface with the
WebSphere Application server.
|
|
|
|
Procedure
Install the Open Services Gateway initiative (OSGi) bundle on the WebSphere
Application Server deployment manager.
1. Copy com.ibm.datapower.odc.osgi.jar to the <WAS_HOME>/plugins directory of

the WebSphere Application Server deployment manager.
2. Navigate to the /bin directory under <WAS_HOME>. For example:
cd /opt/IBM/WebSphere/AppServer/bin
|
|
3. Run the following command: ./osgiCfgInit.sh

4. Start the OSGi console: ./osgiConsole.sh.
5. From the console, run the following command:
|
|
diag com.ibm.datapower.odc.osgi
6. Verify that a message states: No unresolved constraints.
What to do next
Install the ODCInfo application.
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.
282
Before you begin
|
|
|
Ensure the WebSphere Application Server product is installed and is running

before installing the ODCInfo application. Verify that the OSGi bundle installation
is complete.
|
|
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_ND61.war file, ODCInfoCheckInstall.jacl, ODCInfoStart.jacl,

and ODCInfoDeploy.jacl to a local directory on the deployment manager. The
ODCInfo_ND61.war file applies to both WebSphere ND 6.1 and 7.0 releases.
2. Log in from the command line to the deployment manager.
3. Navigate to the /bin directory under the deployment manager profile. For
example:
cd /opt/IBM/WebSphere/AppServer/profiles/Dmgr01/bin
4. 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
5. 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.
6. 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. For additional information, see the topic on configuring virtual hosts in
the WebSphere Application Server documentation.
What to do next
Start the ODCInfo application.
Starting the ODCInfo application

|
|
Start the ODCInfo application to begin collecting the remote topology and
application information.
283
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 OSGi bundle
About this task
Before installing a new version of the OSGi bundle, uninstall any previous version.
|
|
Procedure
|
|
|
cd /opt/IBM/WebSphere/AppServer/bin
2. Start the OSGi console: ./osgiConsole.sh.
3. From the console, run the following command:
|
|
|
uninstall com.ibm.datapower.odc.osgi
4. From the <WAS_HOME>/plugins directory, delete the
com.ibm.datapower.odc.osgi.jar file.
To remove the OSGi bundle from the WebSphere Application Server deployment
manager, run the uninstall command.
1. Navigate to the /bin directory under <WAS_HOME>. For example:
284
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 ODCInfoUninstall.jacl file to a local directory on the WebSphere
deployment manager.
3. Navigate to the bin directory of the deployment manager profile. For example:
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.
|
|
Enabling the retrieval of workload management information

for non-WebSphere application servers
|
|
|
|
|
|
Non-WebSphere application server clusters can use a subset of the features of

workload management when a custom software application provides the load
balancing configuration data. This section describes the necessary configuration on
the DataPower appliance and explains the required format of the configuration
data in order for an application other than the ODCInfo application to dynamically
modify the load balancer group members.
Before you begin
|
|
|
|
The custom software application must be able to provide a properly formatted

response to a GET request. The response contains the configuration data for
current information about the host weights or if a new host has been added or
removed from the cluster.
285
About this task
|
|
|
On the DataPower appliance, define the required and optional configurations.

Correctly format the XML document and include it in a GET response from your
software application.
|
|
|
|
|
|
|
|
Procedure
Results
|
|
|
|
|
|
|
|
|
The following steps describe the message flow and processing actions that are
enabled with this configuration:
1. Create or modify a custom software application to provide a properly

formatted XML document in the GET response
2. Optional: Define an XML Firewall on the DataPower appliance if you want the
appliance to perform schema validation on the XML document
3. Create a WebSphere Cell for non-WebSphere application servers
4. Modify a load balancer group to use workload management information for
non-WebSphere application servers
1. The WebSphere Cell sends an HTTP, or an HTTPS, GET request to the custom
software application periodically.
2. The custom software application returns an HTTP, or an HTTPS, response
containing load balancer group member configuration information to the
WebSphere Cell or optionally to the XML Firewall.
3. Optional: The XML Firewall performs schema validation, as defined in the
ODCInfo.xsd schema, on the XML document in the response.
4. The load balancer group uses the configuration data in the response to
determine traffic routing when the appliance receives requests directed to the
load balancer group.
|
|
|
|
|
|
Defining the XML Document for non-WebSphere servers
|
|
|
|
When not using the ODCInfo application, a custom software application must be
able to respond to a GET request with a properly formatted XML document. The
response contains the configuration data for new and current cluster members.
This section describes how to properly format the response XML document.
Before you begin
|
|
|
When not using the ODCInfo application, you must create a custom software
application that responds to an HTTP, or an HTTPS, GET request with an XML
document that defines the cluster configuration information.
Define the XML elements
The following XML elements must be specified in the response document:
|
|
|
|
clusterData
Contains all of the clusters that were requested. The version attribute is
associated with the version of the custom software application and is
optional.
Define the XML document that the custom software application provides in
response to the GET request.
286
|
|
|
cluster
Contains all information associated with a single cluster or workload
management group.
|
|
|
|
|
|
|
|
v The cluster structure name attribute specifies the name given to the
cluster and corresponds with the workload management group name in
the DataPower load balancer group
v The version attribute specifies what revision of the data is sent to the
DataPower appliance. The version is used to determine if there are any
updates to the information since the previous poll. If the version
attribute is not present, a manual algorithm is used to determine if the
structure has changed.
|
|
|
|
|
affinityMode
The value attribute contains what type of session affinity to use for
this cluster. Valid values are active, active-conditional, passive,
or null. The affinityMode must be the same for all applications
within the load balancer group.
|
|
|
|
|
cookieNames
The value attribute contains a comma (,) separated list of session
cookie names used by any of the applications installed to this load
balancer group. This list is used for active-conditional or passive
session affinity.
|
|
|
Note: If you are unfamiliar with WebSphere Application Server

passive session affinity, you should use active-conditional
session affinity.
|
|
|
protocol
The type attribute specifies the protocol. Valid values are http or
https. No other transport protocols are supported for this function.
|
|
|
|
member
The member contains the host (hostname), port number, id (unique
identifier for this application server), and weight associated with
this application server instance over this transport protocol.
Example
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
A properly formatted GET response for a single cluster, that is single workload
group name:
<?xml version="1.0"?>
<clusterData version="3.8.1.0">
<cluster name="myCluster">
<affinityMode value="active-conditional"/>
<cookieNames value="WSJSESSIONID,JSESSIONID,SSLJSESSIONID"/>
<protocol type="http">
<member host="myhost34.example.com" port="9081" id="13jbh6o3q"
<member host="myhost33.example.com" port="9081" id="13jbh6qko"
<member host="myhost32.example.com" port="9081" id="140pntcf3"
</protocol>
<protocol type="https">
<member host="myhost34.example.com" port="9444" id="13jbh6o3q"
<member host="myhost33.example.com" port="9444" id="13jbh6qko"
<member host="myhost32.example.com" port="9444" id="140pntcf3"
</protocol>
</cluster>
</clusterData>
weight="20"/>
weight="20"/>
weight="20"/>
weight="20"/>
weight="20"/>
weight="20"/>
287
What to do next
|
|
Optionally, define an XML Firewall on the DataPower appliance if you want the
appliance to perform schema validation on the XML document.
|
|
|
Creating an XML Firewall to validate the XML document
About this task
|
|
|
|
|
If desired, an XML Firewall on the DataPower appliance can validate the XML
document that the custom software application sends. Most often, this would be
done during initial testing of the application. Once it is proven that the application
responds with a valid XML document, remove the XML Firewall from the flow to
optimize performance.
|
|
|
|
|
Procedure
Optionally, create an XML Firewall on the DataPower appliance to schema-validate

the XML document provided in the response from a custom software application.
1. Follow the procedures to create an XML Firewall.

2. Configure a processing policy with a validate action.
3. In the Schema Validation Method field, select Validate Document via Schema
URL.
4. In the Schema URL field, specify store:///ODCInfo.xsd for the schema file.
5. Complete configuration of the processing policy.
|
|
|
|
What to do next
|
|
Create a WebSphere Cell to act as an intermediary between the custom software

application and the load balancer group.
|
|
|
|
|
Creating a WebSphere Cell for non-WebSphere application

servers
Before you begin
|
|
|
If you created a DataPower XML Firewall for schema validation of the XML data
from a custom software application, you must know the address and port number
of the XML Firewall.
About this task
|
|
|
When not using the ODCInfo application, add and configure a WebSphere Cell to
query the custom software application. If there is an information update, the
WebSphere Cell sends the updated information to the load balancer group.
Note: Poll is the only supported update method in this configuration.
Procedure
1. Follow the procedures to create a WebSphere Cell.
Create a WebSphere Cell on the DataPower appliance to act as an intermediary

between a custom software application and the load balancer group on the
288
|
|
|
|
|
|
|
|
|
|
|
|
2. In the Deployment Manager Host field, if you are not using an XML Firewall
for schema validation, enter either the host name or the IP address of the
custom software application. If you are using an XML Firewall for schema
validation, enter the address used to access the XML Firewall.
3. In the Deployment Manager Port number field, if you are not using an XML
Firewall for schema validation, enter the port number associated with the
specified host name. If you are using an XML Firewall for schema validation,
enter the port number associated with the XML Firewall.
4. In the Update Method field, select poll. This is the only supported update
method in this configuration.
What to do next
Create or modify a load balancer group to reference the WebSphere Cell.
|
|
|
|
Modifying a load balancing group to use workload management

information for non-WebSphere application servers
Before you begin
Configure a WebSphere cell and a load balancer group.
About this task
|
|
|
|
Configure the load balancer group to request workload management information

from the independent software vendor application. The load balancer group uses
the WebSphere Cell configuration to gather information about the member
application servers.
Procedure
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
1. Click Objects > Network Settings > Load Balancer Group.

3. Modify the load balancer group to use the workload management information
from the WebSphere cell.
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 the WebSphere Cell
configuration that references the independent software vendor application.
d. In Workload Management Group Name field, enter the name of the
application server cluster as it is specified in the cluster attribute of the
response XML document.
|
|
Modify the configuration of a load balancer group to request workload

management information from the independent software vendor application.
4. Optional: Set Enable Application Routing to off. This is the only supported
option in this configuration.
5. Optional: Review the session affinity information on the Session Affinity tab to
ensure that session affinity is correctly configured.
289
Results
|
|
The load balancer group begins to request information (through the WebSphere
cell) from the custom software application.
Defining matching rules

To configure a matching rule:
1. Click Objects XML Processing Matching Rule.
2. Click Add.
configuration.
6. Set Match with PCRE to indicate whether match patterns use PCRE
expression or shell-style expressions.
7. Set Boolean Or Combinations to indicate whether to combine the match
criteria with OR semantics or with AND semantics.
8. Click the Matching Rule tab.
9. Define a matching rule.
a. Click Add.
b. From the Matching Type list, select the desired match type.
c. In match type specific fields, define the matching criteria.
d. Click Save.
10. Repeat this step to define another matching rule.
MTOM Policy
The message transmission optimization mechanism (MTOM) policy provides a way
to optimize the transmission and wire format of an XML/SOAP message.
Optimization is performed by selecting elements with Base64 encoded character
data. The selected elements are decoded and attached as MIME attachment parts
before transmission. Decoding before transmission reduces the overhead that is
associated with Base64 encoded data.
To use an MTOM policy with a DataPower service:
1. Define a processing policy that includes a transform action for the MTOM
operation.
2. In the transform action:
a. Click the Use XSLT specified in this action radio button.
b. Specify the location of the MTOM processing control file; for example,
store:///mtom.xsl.
c. On the Advanced tab, select the MTOM policy that becomes the stylesheet
parameter for the transform action.
To create an MTOM policy:
290
Click Objects XML Processing MTOM policy.

Click Add.
configuration.
1.
2.
3.
4.
6. From the MTOM Mode, select the optimization mode.

7. Optional: Set Include Content Type to off to disable the inclusion of the
xmlmine:contentType declaration in output messages when the input message
does not contain this declaration. If the input message contains this
declaration, the MTOM policy passes through the attribute regardless of this
setting.
8. Click the MTOM Rules tab to add MTOM rules.
9. Add an MTOM rule.
a. Click Add.
b. In the XPath Expression field, enter the XPath expression that defines a
schema element or elements to be subject to this rule. Alternatively, click
XPath Tool to launch the builder.
c. Optional: In the Content Type field, enter the Content Type for the
extracted data elements. This setting overrides the value from the
xmlmime:contentType attribute. If the provided XPath expression matches
more than one element, each corresponding MIME attachment part will
contain a Content-Type header with this value. If different Content-Type
values are required, selective expressions are required.
d. Optional: In the Content ID field, enter the explicit value for the
Content-ID header. If not explicitly configured, Content-ID headers are
automatically generated. This setting allows for the explicit configuration
of Content-ID headers and their associated href values. Rules that match
multiple data elements result in one attachment part for all matched
elements. The resulting attachment part contains data from the last match
only.
e. Click Apply.
10. Repeat the previous step to add another MTOM rule.
Multi-Protocol Gateway object

Click Objects Service Configuration Multi-Protocol Gateway.
Click Add.
Configuring basic operations

291

Comments
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 6, Handler configuration, on
Note: To use a Raw XML Front Side Handler, Type must be Dynamic
Backend.
XML Manager
Select an XML Manager. See XML Manager on page 366.
Backend URL
If Type is Static Backend, specify the URL of the target server.
The URL determines the protocol and endpoint of the backend server. To
use a load balancer, specify the name of an existing Load Balancer Group
instead of the address-port pair in the URL.
For example, the service uses the HTTP protocol for a URL that starts with
http:// but uses the MQ protocol for a URL that start with dpmq://. To
construct an MQ URL, use the builder.
Propagate URI
Control the behavior of URI propagation.
If the target URL is in a WebSphere MQ or TIBCO EMS or WebSphere JMS
format, disable URI propagation (set to off).
Enabling URI propagation is meaningful in the following situations only:
v When the service is configured to use a static backend.
v When the service is configured to use a dynamic backend and dynamic
routing is set with a route with style sheet (route-action) action in the
processing policy. In this case, use the dp:set-target() extension
element to define that target backend server.
For the other dynamic routing options that are available with the
route-action and route-set actions, the URI is absolute.
When enabled, the service rewrites the URI of the backend URL to the URI
in the client request. If URI propagation is enabled and the client submits
http://host/service and the backend URL is http://server/listener, the
URL is rewritten to http://server/service.
Notes:
v When enabled, any matching rule in a response processing rule
must match the rewritten URL.
v Any action in the processing policy can change the URI that is
sent to the backend server. The rewritten URI could override the
intended effect of this setting.
Load Balancer Hash Header
Specify the name of the HTTP header to use for calculating the hash for
load balancing traffic to the backend servers.
v When defined, the hash algorithm uses the value of the identified HTTP
header.
292
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.
Process Message Whose Body is Empty
Whether to force the processing of XML messages when their message
body is empty or missing in RESTful Web services.
|
|
|
Rewrite Error Messages

Enable or disable support for rewriting error messages to avoid providing
a padding oracle.
Processing Policy
Select a Processing Policy. Refer to Chapter 7, Processing policies, on
page 87.
Type
Select the proxy type.

Dynamic Backend
Specifies support for multiple backend servers. Server addresses
and port numbers are extracted from incoming client requests.
Static Backend
Specifies support for a single backend server. Requires the
specification of a backend URL.
Proxy Settings tab

URL Rewrite Policy
Optional: 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. See URL
Rewrite Policy on page 345.
SSL Proxy
Optional: Assign an SSL proxy profile. See SSL Proxy Profile objects on
page 29.
Crypto Credentials
Optionally assign a Firewall Credentials List. Refer to Defining Firewall
Credentials objects on page 23.
Default parameter namespace
Optionally identify the default XML namespace for parameters made
available to this Gateway from the command line or WebGUI.
The default namespace is http://www.datapower.com/param/config.
Query parameter namespace
Optionally identify the default XML namespace for parameters made
available to this Gateway from a URL query string.
The default namespace is http://www.datapower.com/param/query.
Request attachments processing mode
When the request type is SOAP or XML, select how to process client
requests with attachments.
293

Strip

Streaming
Unprocessed
attachments.
Response attachment processing mode
When the response type is SOAP or XML, select how to process server
responses with attachments.
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.
294
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.
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
Enable (on) or disable (off) MIME (Multi-Purpose Internet Mail Extensions)
header processing support.
The body of a message (that is, the payload, independent of any protocol
headers) can sometimes contain MIME headers before any preamble and
before the first MIME boundary in the body of the message. These MIME
headers can contain important information that is not available in the
protocol headers, such as a string that identifies the MIME boundary.
v If on, MIME headers are processed.
v If on and there are no MIME headers in the message, the appliance
continues to try and parse the message with the available protocol
header information.
v If off and MIME headers are in the body of the message, these MIME
headers are considered part of the preamble and not used to parse the
message. If the protocol headers (such as HTTP) indicate MIME
boundaries, the appliance can parse and process individual attachments.
If such information is not available, no attachments can be parsed from
the body of the message.
MIME support is enabled by default.
295
Back Side MIME Header Processing

Enable or disable MIME (Multi-Purpose Internet Mail Extensions) header
processing support.
The body of a message (that is, the payload, independent of any protocol
headers) can sometimes contain MIME headers before any preamble and
before the first MIME boundary in the body of the message. These MIME
headers can contain important information that is not available in the
protocol headers, such as a string that identifies the MIME boundary.
v If on, MIME headers are processed.
v If on and there are no MIME headers in the message, the appliance
continues to try and parse the message with the available protocol
header information.
v If off and MIME headers are in the body of the message, these MIME
headers are considered part of the preamble and not used to parse the
message. If the protocol headers (such as HTTP) indicate MIME
boundaries, the appliance can parse and process individual attachments.
If such information is not available, no attachments can be parsed from
the body of the message.
MIME support is enabled by default.
Stream Output to Back
Select the desired streaming behavior.
Buffer Messages
Buffers submitted messages until all processing is verified as
complete. After verification, forward the message to the
appropriate backend.
Stream Messages
Begins to send the message to the backend before all processing is
complete. This behavior potentially increases processing speed.
Select this option when the selected XML manager has streaming
enabled or when streaming of attachments is enabled.
Stream Output to Front
Select the desired streaming behavior.
Buffer Messages
Buffers submitted messages until all processing is verified as
complete. After verification, forward the message to the
appropriate requesting client.
Stream Messages
Begins to send the message to the requesting client all processing is
complete. This behavior potentially increases processing speed.
Select this option when the selected XML manager has streaming
enabled or when streaming of attachments is enabled.
Request Type
Characterize the client-generated request.
JSON Identifies the message as JavaScript Object Notation (JSON). The
service validates the message as well-formed JSON, performs
user-designated document processing, and forwards the resulting
material to the server. User-designated document processing can be
applied on the __JSONASJSONX context that represents the JSON
input as JSONx.
296
Non-XML
Does not directly characterize the message. The message body is
not filtered or transformed. The service can take other actions, such
as determining a route or authenticating the message, before
passing it to the target server.
SOAP Identifies the message as a SOAP message.
Pass-Thru
Does not directly characterize the message, but indicates that the
message is not filtered or transformed by the service. The message
is passed as is to its target.
XML
Identifies the message as unencapsulated XML.
Response Type
Characterize the server-generated response.
JSON Identifies the message as JavaScript Object Notation (JSON). The
service validates the message as well-formed JSON, performs
user-designated document processing, and forwards the resulting
material to the client. User-designated document processing can be
applied on the __JSONASJSONX context that represents the JSON
input as JSONx.
Non-XML
Does not directly characterize the message. The message body is
not filtered or transformed. The service can take other actions, such
as determining a route or authenticating the message, before
passing it to the target server.
SOAP Identifies the message as a SOAP message.
Pass-Thru
Does not directly characterize the message, but indicates that the
message is not filtered or transformed by the service. The message
is passed as is to its target.
XML
Identifies the message as unencapsulated XML.
Flow Control
Enable (on) or disable (off) flow control support. Use flow control to
manage the transmission of large files when the front side and back end
have different latencies and throughput while in streaming mode. This
option is available when the request type and the response type are
Non-XML or Pass-Thru. By default, flow control is disabled.
Note: The streaming behavior for output to back and output to front must
be set to Stream Messages. Also, if either the front side or the back
end will use the HTTP(S) protocol, Allow Chunked Uploads must
be set to on.
SOAP Schema URL
When the traffic type is SOAP, the SOAP Schema URL field appears. Use
this field to specify the full URL to the schema to validate the SOAP
schema for SOAP-formatted messages. When a service is in SOAP mode,
either on the request or response side, it validates incoming messages
against a W3C Schema for SOAP messages. You can customize the schema
to use by changing this property. Change the schema to accommodate
nonstandard configurations or special cases.
297
Front Side Timeout

Specify an integer between 10 and 86400 indicating the number of seconds
a connection with a client can remain idle during a transaction before it
times out and is closed. The default is 120 (2 minutes). When using an
Stateful Raw XML connection, set this value higher to ensure that the
connection is not closed due to a timeout.
Back Side Timeout
Specify an integer between 10 and 86400 indicating the number of seconds
a connection with a server can remain idle during a transaction before it
times out and is closed. The default is 120 (2 minutes). When using an
Stateful Raw XML connection, set this value higher to ensure that the
connection is not closed due to a timeout.
Front Persistent Connection Timeout
Specify an integer that sets the amount of time, in seconds, a persisted
connection can remain idle before the appliance closes the connection. This
is idle time between connections.
Back Persistent Connection Timeout
Specify an integer that sets the amount of time, in seconds, a persisted
connection can remain idle before the appliance closes the connection. This
is idle time between connections.
Include char-set in response type
Enable (on) or disable (off) including the character set encoding in any
content-type header or description produced. For example, when sending a
UTF-8 encoded XML document. If this property is disabled, text/xml will
be sent. If this property is enabled, text/xml; charset=UTF-8 will be sent.
Message Processing Modes
Enables in-order (serial) processing of queue-based messages during
different parts of transactions through the service. When enabled the
service respects the sequential order of the messages when writing them to
queues.
v If request rule in order, enforces serial processing of the actions defined
for request processing, excluding serial transmission of messages to the
backend request queue.
v If backend in order, enforces serial transmission of messages to the
backend request queue.
v If response rule in order, enforces serial processing of the actions defined
for response processing, including serial transmission of messages to the
front-side reply queue.
Monitors tab
Service Monitors
Optional: Use the list with the Add and Delete buttons to assign one or
more Web services monitors. See Configuring Web services monitors on
page 217.
Count Monitors
more count monitors. See Configuring count monitors on page 214.
Duration Monitors
more duration monitors. See Configuring duration monitors on page 216.
298
Monitors Evaluation Method

When a service uses more than one monitor, it is possible to determine
how the monitors interact with each other.
Terminate at First Throttle
(Default) Allows all monitors to take effect on a message until a
monitor takes a Shape or Reject action. No further monitors will
take effect after this point. The order of monitors thus matters. If
three monitors are included, and the first monitor in the list either
Shapes or Rejects a message, no other monitors will execute.
Terminate at First Match
Allows all monitors to take effect until a monitor matches a
message. At that point, all monitor processing of the message
stops. In this way, only one monitor increments its counters.
Parser Limits tab

Maximum Message Size
Optionally specify the maximum size (in Kilobytes) of SOAP or XML
messages accepted by this Gateway.
This property limits the SOAP or XML payload, not the size of the
incoming IP packet. This value overrides the corresponding value in the
XML Manager.
Messages in excess of the specified limit are rejected and an error is
reported.
Use an integer in the range of 0 through 2097151. The default is 0. A value
of 0 specifies unlimited size.
Gateway Parser Limits
Control whether to impose limits on the size and depth of XML documents
and elements. Enable or disable service-level limits. Service-level limits
override any similar limits set by the assigned XML manager.
XML Bytes Scanned
Specify the maximum number of bytes that canned be scanned in one
document. The default is 4194304. Only available when parser limits are
enabled.
XML Element Depth
Specify the maximum allowed element depth of a single document. The
default is 512. Only available when parser limits are enabled.
XML Attribute Count
Specify the maximum allowed number of attributes. The default is 128.
Only available when parser limits are enabled.
XML Maximum Node Size
Specify the maximum allowed number of bytes of a single element. The
default is 33554432. For optimal performance, set this value to a power of
2. Only available when parser limits are enabled.
XML Maximum Distinct Prefixes
Specifies the maximum number of distinct XML namespace prefixes in a
document. Only available when parser limits are enabled.
299
XML Maximum Distinct Namespaces

Specifies the maximum number of distinct XML namespace URIs in a
XML Maximum Distinct Local Names
Specifies the maximum number of distinct XML local names in a
XML External References
Specify how the XML parser continues processing when an input
document seeks to resolve an external reference such as an external entity
or external DTD definition. The default is Forbid. Only available when
parser limits are enabled.
Attachment Byte Count Limit
Specify the maximum allowed number of bytes in an attachment. The
default is 2000000000. Only available when parser limits are enabled.
Attachment Package Byte Count Limit
Specify the maximum number of bytes allowed for all parts of an
attachment package, including the root part. Attachment packages that
exceed this size will result in a failure of the whole transaction. If the value
is 0, no limit is enforced. The default is 0. Only available when parser
limits are enabled.
HTTP Options tab

Server Side HTTP Version
Select the HTTP protocol version (HTTP 1.0 or HTTP 1.1) used for
server-side connections. By default, HTTP/1.1 is used for server-side
connections.
Compression
Enable or disable GZIP compression negotiation with the backend server.
Persistent Connections
Enable or disable HTTP persistent connections with the target server.
Loop Detection
Enable or disable gateway loop detection. Some protocols allow for the
detection of loops between gateways. Enable loop detection to include the
HTTP Via header.
Follow Redirects
Enable or disable the following of server-side redirects (such as HTTP 302)
by the appliance. By default, the appliance will not follow redirects. The
number of redirects followed can be limited by a User Agent that applies
to the backend URL.
Rewrite Host Names When Gatewaying
Enable or disable host rewriting. Some protocols have distinct name-based
elements, separate from the URL, that are used to demultiplex. HTTP uses
the Host header for this purpose. If this feature is enabled, the backside
server will receive a request reflecting the final route, otherwise it will
receive a request reflecting the information as it arrived at the appliance.
Web servers that issue redirects might want to disable this feature, as they
often depend on the host header for the value of their redirect.
Allow Chunked Uploads
Enable or disable the ability to send Content-Type Chunked Encoded
documents to the backend server. When the appliance employs the HTTP
300
1.1 protocol, the body of the document can be delimited by either

Content-Length or chunked encoding. While all servers will understand
how to interpret Content-Length, many applications will fail to understand
chunked encoding. For this reason, Content-Length is the standard method
used. However doing so interferes with the ability of the appliance to fully
stream. To stream full documents towards the backend server, this property
should be turned on. However, the backend server must be RFC 2616
compatible, because this feature cannot be renegotiated at run time, unlike
all other HTTP 1.1 features which can be negotiated down at runtime if
necessary. This property can also be enabled by configuring a User Agent
to enable it on a per-URL basis.
Process Backend Errors
Indicates whether to process errors from the server.
v If enabled, ignores the error condition, and processes the response rule.
v If disabled, notices the error condition during request processing, and
processes the error rule.
Depending on the protocol, the service might return a response code that
indicates an error condition.
For HTTP messages, the response from the server might include a
response body that contains XML that provides more details about the
error.
v For MQ messages, the response from the MQ server does not provide a
response message.
HTTP Client Label

Specify the name of an HTTP Header to read to determine the IP address
of the requesting client (for example X-Forwarded-For). This value defaults
to X-Client-IP.
HTTP Header Injection tab

To add a proprietary header to the message stream, click HTTP Header Injection
and then click Add to display the HTTP Header Injection panel.
Click Add to display the Header Injection Property window.
Direction
Select the direction of the message.
Header Name
Specify the name of the proprietary header.
Header Value
Specify the contents of the proprietary header.
Click Save to return to the Header Injection Panel.
HTTP Header Suppression tab

To delete a header from the message stream, click HTTP Header Suppression to
display the Gateway Header Suppression panel.
Click Add to display the HTTP Header Suppression Property window.
301
Direction
Select the direction of the message.
Header Tag
Specify the name of the target header to delete.
Click Save to return to the Gateway Header Suppression Panel.
WS-Addressing tab
For information about configuring Web Services Addressing (WS-Addressing), refer
to the online help.
WS-ReliableMessaging tab
WS-ReliableMessaging
Enable or disables Web Services Reliable Messaging.
on
Enables Reliable Messaging.
off
(Default) Disables Reliable Messaging
When enabled, the WebGUI displays the following inputs:

Target Sequence Expiration Interval
Sets the target expiration lifetime in seconds for all Reliable Messaging
sequences.
If an incoming CreateSequence SOAP message has an Expires lifetime that
is longer than this value, the value in the SequenceResponse SOAP message
is reduced to this value. The same process applies to the Expires lifetime
in any accepted Offer in an incoming CreateSequence and for the
requested Expires value in any CreateSequence SOAP call that is made to
the client or server from a Reliable Messaging source. This implementation
never requests or accepts a non-expiring sequence (a value of PT0S that
represents zero seconds).
The default is 3600.
AAA Policy
Selects the AAA Policy to perform authentication of incoming Reliable
Messaging messages. This AAA Policy can be the same one that is used in
later processing by the request or response rule. The results are cached, so
it is not evaluated again.
While this is focused on protecting the Reliable Messaging control
messages, such as CreateSequence and TerminateSequence, it is also run on
incoming Reliable Messaging data messages, with a Sequence header. This
prevents unauthorized clients from using appliance resources by issuing
CreateSequence requests, or from disrupting existing Reliable Messaging
sequences with CloseSequence or TerminateSequence messages, or from
falsely acknowledging messages with SequenceAcknowledgement messages.
SSL session binding
Indicates whether to use an SSL session binding to protect sequence
lifecycle messages.
All Reliable Messaging control messages and sequence messages are bound
to the original SSL/TLS session that is created by the Reliable Messaging
source to transmit the CreateSequence control message. Sequence messages
that are received by the Reliable Messaging destination with the correct
identifier but on a different SSL/TLS session are rejected.
302
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.
Use an integer in the range of 1 through 256. The default is 10.
This property controls memory utilization.
Destination Accept Two-Way Offers
Indicates whether to accept offers for two-way Reliable Messaging in
CreateSequence SOAP requests. If the request includes an offer, the
creation of a Reliable Messaging destination creates a Reliable Messaging
source to send responses to the client.
on
Accepts two-way requests.
off
(Default) Does not accept two-way requests.

303
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.
on
Requires Reliable Messaging for all requests.
off
(Default) Does not require Reliable Messaging for all requests.
Required on Response
Indicates whether to require the use of Reliable Messaging for all SOAP
messages that response rules process. Any SOAP message without a
Sequence results in a SOAP fault.
304
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


The default is 4.
305

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 to Traditional or
WS-Addressing to WS-Addressing indicates whether to create a Reliable
Messaging source from the front side to the client when there is SOAP data
to send to the client and there is no Reliable Messaging source that was
created by a MakeOffer from the client by sending a CreateSequence SOAP
request to the WS-Addressing ReplyTo address.
on
Creates a Reliable Messaging source.
off
(Default) Does not create a Reliable Messaging source.

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


The default is 4.
306

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

To pass parameter-value pairs to the style sheets that support this Gateway, click
Stylesheet Parameter to display the Stylesheet Parameter panel.
Click Add to display the Stylesheet Parameter Property window.
Parameter Name
Specify the name of the parameter.
Parameter Value
Specify the value of the parameter.
Click Save to return to the Stylesheet Parameter Panel.
Policy Parameters
A Policy Parameters object defines policy parameters as key-value pairs for use in
a policy mapping style sheet. Specify the key with the {policy-domain-ns}key
format.
A policy parameters is the way that you must map the needed parameters that are
defined in or referenced by the WSDL policy or that are defined in an attached
source to the specific DataPower object. If you do not define all the needed
parameters, processing a message with the defined WS-Policy generates errors.
For example, you might need an X.509 token to use the defined WS-Policy. If you
need an X.509 token, you need to define which certificate that is stored on the
DataPower appliance to use. If the certificate is alice, you would need to set the
{http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702}ws-secpolCertificate parameter to alice.
Note: If you defined a policy parameters at the port or port-operation level, these
parameters are not applied to its parallel synthesize port or operation. The
policy parameters for synthesized ports and operations must be inherited
from the service level or redefined at the synthesized level.
To define policy parameters, use the following procedure:
308
1. Select Objects Policy Policy Parameters to display the Policy Parameters

catalog.
2. Define the properties on the Main tab.
3. Define the properties on the Policy Parameters tabs.
Main tab
To define policy parameters, use the following procedure:
1. Select Objects Policy Policy Parameters to display the Policy Parameters
catalog.
2. Click the Main tab.
Comments
4. Continue to the Policy Parameters tab to define the policy parameters.
Policy Parameters tab

To continue the definition of policy parameters, use the following procedure:
1. Click Policy Parameters tab to display the Policy Parameters (Policy Parameter)
configuration screen.
2. Define a policy parameter.
a. Click Add to display the Policy Parameters Property window.
b. Provide the following inputs:
Name Specify the name of the policy key with the {policy-domain-ns}key
format.
Value Specify the value of the key.
c. Click Submit.
3. Repeat the previous step for each required policy parameter.
Defining Processing Action objects

Use the following procedure to define global, reusable processing actions.
1. Select Objects XML Processing Processing Action.
2. Click Add.
309

Comments
Action Type
Select an action to be performed by the processing rule. After making
the selection, the screen redraws with properties that are relevant to the
selected action. The following actions are available:
AAA
Implements an AAA Policy specified by the AAA Policy

property.
An aaa action also requires that the Input context be identified,
and optionally allows for Output context identification. If the
output context is not identified, OUTPUT is used.
Call Processing Rule

Calls a named, reusable processing rule.
A call action requires that Input (document source) and
Output (document destination) contexts be identified, as well
as the target Processing Rule.
Checkpoint Event
Adds an administrative checkpoint. This action is available only
with Web Service Proxy services.
A checkpoint action requires that Input (document source)
context be identified as well as the Event that triggers the
action.
Conditional
Selects an action for processing based on an XPath match.
A conditional action requires that the Input (document source)
context be identified as well as the Match Condition that
triggers the action.
Convert Query Parameters to XML
Converts non-XML input (for example, an HTTP POST or an
HTTP form) into XML format.
A convert-http action requires that Input (document source)
and Output (document destination) contexts be identified, and
optionally allows selection of an HTTP Input Conversion Map
(specifying document encoding rules) with the Input
Conversion property.
Extract using XPath
Applies an XPath expression (defined by the XPath property) to
a source context (identified by the Input property) and stores
the result in a destination context (identified by the Output
property). The result can be stored in a named variable in the
destination context.
Fetch
Obtains a remote resource via HTTP

A fetch action requires that an External URL (the document
location) and Output context (the document destination) be
identified. You can use the Output Type property to
characterize the fetched data.
310
Filter
Applies a filtering style sheet, resulting in an accept/reject

decision.
A filter action requires that an Input context (the source of
the document to be filtered) and Transform style sheet be
identified.
Specification of an Output context and a Dynamic Stylesheet is
optional.
For Each
Implements a programmatic loop for each of the defined
actions. Each time an XPath expression returns true, a
designated action runs. The for-each action can be used to
apply a series of style sheets to input data, if desired. Instead of
using XPath expressions, the loop can be processed a specific
number of times. Each iteration of the loop stores its results in
a separate output context. These output contexts are available
to any other action in the processing policy.
Log
Generates a log message that contains the entire contents of a

context and send the message to a remote logging facility
The log action requires an Input context and an External URL,
to which the context contents are sent.
Specification of an Output context, an Output Type, a Log
Level, and a Log Type is optional.
On Error
Specifies a nondefault error handling procedure.
An on-error action requires only the selection of an Error
Mode. Optionally identify an error-rule and specify input and
output contexts for that rule.
Results
Sends the contents of a named context to another context or to
a remote location.
A results action requires that an Input context (the source of
the content to be sent) be identified, and optionally allows the
identification of an External URL (the content destination), the
identification of an Output context (which receives an expected
response from the content recipient), and characterization of the
Output Type.
You can use the Output Type property to characterize the type
of output data (in this case, the response from the destination
that received the results).
Results Asynchronous
Asynchronously sends the contents of a named context to
another context.
A results-async action requires that an Input context (the
source of the content to be sent) and an External URL (the
content destination) be identified.
Rewrite Header
Implements a URL Rewrite Policy.
311
A rewrite action requires that a URL Rewrite Policy be

identified.
Route using Stylesheet or XPath Expression
Performs dynamic, style sheet-based routing.
A route-action requires that an Input context (the source of
the document to be routed) and either a Transform style sheet
be identified or an XPath Map be identified.
Route using Variables
Routes message to an explicit destination.
A route-set action requires that an External URL (the routing
destination) be identified, and optionally allows the
identification of SSL Credentials to support a secure
connection to the destination.
Set Variable
Sets a variable.
A setvar action requires that a Variable Name, a Variable
Assignment, and an Output context (the context that contains
the variable) be identified. The variable name should take the
form var://context/somecontextname/somevarname.
Enforce SLM Policy
Implements an SLM Policy specified by the SLM Policy
property.
An slm action also requires that the Input context be identified,
and optionally allows for Output context identification. If the
output context is not identified, OUTPUT is used.
Strip Attachments
A strip-attachments action requires that an Input context (the
source of the document to be stripped) be identified, and
optionally allows the identification of an Attachment URI,
which specifies a single attachment to be deleted.
Deletes attachments (transmitted as part of a SOAP with
Attachments message package) from a named context.
Validate
Performs XML schema validation.
A validate action requires that an Input context (the source of
the document to be validated) and XML schema be identified.
The schema document can be specified either as a Schema URL
or Dynamic Schema. Schema validation optionally allows the
identification of an Output context, which stores the possibly
altered original document after validation, and of a URL
Rewrite Policy.
Transform
Applies a transformation style sheet to a named context
An xform action requires that an Input context (the source of
the document to be transformed), Output context (the
destination of the transformed document), and style sheet be
identified. The style sheet can be specified by either the
Transform or Dynamic Stylesheet property.
312
Specification of a URL Rewrite Policy and characterization of

the Output Type is optional.
Transform Binary
Applies a transformation style sheet that performs
binary-to-XML conversion to a named context
An xformbin action requires that an Input context (the source
of the document to be transformed), Output context (the
destination of the transformed document), and style sheet be
identified. The style sheet can specified as either Transform or
Dynamic Stylesheet. Only appears if licensed for DataGlue.
Transform using Processing Instruction
Performs transformation services based on instructions internal
to the candidate document
An xformpi action requires that an Input context (the source of
the document to be transformed), Output context (the
destination of the transformed document), and default style
sheet be identified. The default style sheet (which is used only
if the candidate document lacks internal processing
instructions) can specified by either the Transform or Dynamic
Stylesheet property.
Specification of a URL Rewrite Policy and characterization of
the Output Type is optional.
Input
Use when the Action Type is aaa, call, convert-http, extract, filter,
log, results, results-async, route-action, setvar, slm,
strip-attachments, validate, xform, xformbin, or xformpi. In all of
these cases, specify the name of the context that contains the document
or service request on which the action will operate. When the action is
not the first action in a rule, this value is very likely not going to be
INPUT but rather a context-sensitive name (such as tempvar1, for
example).
Use the reserved word INPUT to identify the original input to the
processing policy. That is, the original client request or server response.
Leave blank if the Action Type is call, fetch, rewrite, route-set, or
setvar. These actions do not operate on the Input context.
Transform
Use when the Action Type is filter, route-action, xform, xformbin, or
xformpi.
Specify the location of the style sheet that performs document filtering,
transformation, or routing.
You can specify the style sheet location as a URL or as a var:// URL
that expands to a URL.
If using a dynamic style sheet to perform filtering, routing, or
transformation, specify dynamic-stylesheet and use the Dynamic
Stylesheet property to specify the object from which to generate the
dynamic style sheet; for example, a Document Crypto Map object.
WTX Map File
Specify the WTX-generated map file that the Binary Transform
(xformbin) action uses to determine the input contexts and the output
313
contexts of the transform. For additional information, refer to IBM

WebSphere DataPower SOA Appliances: Integrating with WebSphere
Transformation Extender.
Top-Level Map Name
Specify which map in the WTX-generated map file that the Binary
Transform (xformbin) action uses this property to determine the input
contexts and the output contexts of the transform. For additional
information, refer to IBM WebSphere DataPower SOA Appliances:
Integrating with WebSphere Transformation Extender.
WTX Map Mode
Indicates whether to use mapping logic in XML-to-binary or
binary-to-XML WTX maps. Use when the Action Type is xformbin. For
additional information, refer to IBM WebSphere DataPower SOA
Appliances: Integrating with WebSphere Transformation Extender.
Output
Specify the name of the context that contains the results of the action
selected. Use when the Action Type is call, convert-http, extract,
fetch, setvar, xform, xformbin, or xformpi. Optional when the Action
Type is aaa, filter, log, results, results-async, route-action, slm, or
validate.
In each applicable case, the specified context contains the results of the
action. The results vary depending upon the action selected.
This context can be used, and usually is used, as the Input context to
the next action in a rule.
Use the reserved word OUTPUT to designate the context that contains the
content that is emitted by the service. This is the content that is sent
out on the wire. Typically, the last action in a rule sets Output to
OUTPUT.
If more than one action in a single rule sets Output to OUTPUT, the
results of all of those actions are emitted by the service. This is not a
recommended practice.
If both the Output and External URL properties are blank (the default
condition), the contents of the Input context are sent to the OUTPUT
context. OUTPUT identifies the final output from the Processing Policy.
That is, the processed client request or server response.
External URL
For fetch, log, results, results-async, and route-set actions to
identify the location (source or destination) of the resource. Specify the
location as a URL or as a variable that expands to a URL. If a variable,
use the var://context/name form.
v For a fetch action, identify the location of the document to fetch.
v For a log action, identify the destination of the generated log
message.
v For a results or results-async action, optionally identify the remote
destination that receives the transmitted context.
v For a route-set action, identify the routing destination.
If the action supports the Output property and both Output and
External URL are blank, the contents defined by the Input property are
sent to the OUTPUT context. The OUTPUT context identifies the final output
from the processing policy.
314
Schema URL
When the Action Type is validate, specify the location of the schema
that performs document validation.
You can specify the schema location as a URL or as a var:// URL that
expands to a URL.
If using a dynamic schema to perform validation, specify
dynamic-schema for the Schema URL property and use the Dynamic
Schema property to specify the object (for example, a Schema
Exception Map) from which the dynamic schema is generated.
Locate Named Inputs and Outputs
Use when the Action Type is xformbin to select how the transform
determines the input contexts and the output contexts. For additional
information, refer to IBM WebSphere DataPower SOA Appliances:
URL Rewrite Policy
When the Action Type is rewrite, validate, xform, or xformpi, select
the URL Rewrite Policy implemented by this Processing Action.
Note: This URL Rewrite Policy rewrites the URLs found in the
document being processed. This affects the location of additional
resources, such a schema identified in a namespace declaration
in the XML payload, used during processing. This does not
change the destination of the output.
AAA Policy
Use when the Action Type is aaa to select the AAA Policy
implemented by this Processing Action. Refer to Creating AAA Policy
SLM Policy
Use when the Action Type is slm to select the SSL Policy implemented
by this Processing Action. Refer to Service level monitors on page 324
Dynamic Schema
Optional when the Action Type is validate. Select the object (Schema
Exception Map) from which the dynamic schema is generated.
If using a dynamic schema to perform validation, first specify
dynamic-schema for the Schema URL property.
Refer to Schema Exception Map on page 323 for more information.
Dynamic Stylesheet
Optional when the Action Type is filter, route-action, xform,
xformbin, or xformpi. Select the object from which to generate the
dynamic style sheet; for example, a Document Crypto Map object.
If using a dynamic style sheet to perform filtering, routing, or
transformation, first specify dynamic-stylesheet for the Transform
property.
Refer to Document Crypto Map on page 263 for more information.
315
Output Type
Optional when the Action Type is fetch, log, results, xform, or
xformpi to specify the format of the output. The following output types
are available:
Default
Read the content-type from the resulting document. If the
content-type is XML or not declared, the content is treated as
XML, otherwise as binary.
XML
The content is treated and parsed as XML.
Binary
The content is treated as binary and not parsed.
Event Use when the Action Type is checkpoint to select the type of event that
triggers the checkpoint. The following events are available:
Authentication Complete
(Default) Signifies the completion on an authentication process.
Fault
Signifies a fault condition.
Request
Signifies the input as a server-originated document.
Response
Signifies the input as a client-originated document.
Input Conversion
Optional: When the Action Type is convert-http, select the Input
Conversion Map used by this processing rule to perform HTTP-to-XML
conversion. Refer to HTTP Input Conversion Map on page 263 for
more information.
XPath Use when the Action Type is extract. Specify the XPath expression
that is applied to the context identified by the Input property.
You can specify the expression in standard XPath format or as a var://
URL that expands to an XPath expression.
XPath Map
Use when Action Type is route-action, select an XPath Map.
Variable Name
Use with the Variable Assignment property when Action Type is
setvar or extract.
v For setvar, specify the variable to be created.
v Optional: For extract, specify the variable in which to store the
results of the XPath operation.
Variable Assignment
Use with the Variable Name property when Action Type is setvar or
extract. Specify the variable value.
SSL Cred
Optional: When the Action Type is route-set, specify the name of the
SSL Proxy Profile to establish a secure connection with the routing
destination.
Refer to SSL Proxy Profile objects on page 29 for more information.
316
Attachment URI
Optional: When the Action Type is strip-attachments, specify the URI
of the specific attachment to be discarded.
Error Mode
When the Action Type is on-error, select the action to take upon an
error condition .
Abort Stop executing the current rule
Continue
Continue executing the current rule
Error Input
Optional: When the Action Type is on-error, identify the input context
to the error-rule identified by Style Policy Rule. If no input context is
identified, the input context of the failed action is used as the default
input context for the invoked error-rule.
Error Output
Optional: When the Action Type is on-error, identify the output
context from the error-rule identified by Style Policy Rule. If no output
context is identified, the output context of the failed action is used as
the default output context for the invoked error-rule.
Use OUTPUT to transmit the error message to the requesting client.
Processing Rule
Use when the Action Type is call or on-error.
Specify the name of the Processing Rule or error-rule invoked by the
action.
Log Level
When the Action Type is log, select the priority of the generated log
message. Defaults to notice.
Log Type
Optional: When the Action Type is log, characterize log contents.
Defaults to none.
After completing the basic configuration, optionally identify
parameter-value pairs that are available to style sheets used by this
action.
Asynchronous
Determine whether the action is asynchronous:
on
Marks the action as asynchronous. This action does not need to

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

complete for the next action in the processing rule to begin.
Named Inputs tab

Click the Named Inputs tab to explicitly determine the Named Inputs for the
action. This screen is blank unless the Locate Named Inputs and Outputs property
is set to Explicit.
317
For additional information, refer to IBM WebSphere DataPower SOA Appliances:

Named Outputs tab

Click the Named Outputs tab to explicitly set the output contexts for the action.
This tab is blank unless the Locate Named Inputs and Outputs property is set to
Explicit.
For additional information, refer to IBM WebSphere DataPower SOA Appliances:
Stylesheet Parameters tab

To configure stylesheet parameters, use the following procedure:
1. Click Stylesheet Parameter to display the Processing Action Configuration
(Stylesheet Parameter) screen.
2. Click Add to display the Stylesheet Parameter Property window.
Parameter Name
Specify the name of the parameter.
Parameter Value
Specify the value of the parameter.
4. Click Save to return to the Processing Action Configuration (Stylesheet
Parameter) screen.
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.
318
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.
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.
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.
319
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 rule's
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.
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.
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
rules on page 290 for more information.
c. From the Rule list, select a processing rule. Refer to Defining Processing
Rule objects on page 321 for more information.
d. Click Save.
3. If necessary, repeat the procedure to add additional maps to the processing
policy.
320
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.
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.
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.

321
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.
RADIUS Settings
RADIUS settings define RADIUS servers. RADIUS settings can be defined in the
default domain only.
Within the DataPower appliance, RADIUS servers can be used for the following
purposes:
v On any appliance, to authenticate access using RBM.
v On all appliances except XML Accelerator XA35, to authenticate access in AAA
Policy objects.
Each RADIUS server has a positional value that the DataPower appliance uses to
determine the order in which to contact the servers. The appliances contacts the
servers from most preferred (lowest number) to least preferred (highest number).
The appliance sends the request to the next server based on the global timeout
value and the global retry value.
If the configuration defines three RADIUS servers with positional values of 10, 20,
and 30, the appliance contacts the servers in the following sequence:
1. Requests are always first sent to server 10.
2. If the request times out, it is sent to server 20.
3. If the request times out, it is sent to server 30.
NAS-identifier
The DataPower appliance is a client to RADIUS servers. The NAS-identifier is a
RADIUS attribute that the client uses to identify itself to a RADIUS server. The
NAS-Identifier, as defined in Section 5.32 of RFC 2865, can be used instead of an IP
address to identify the client. The NAS-identifier consists of one or more octets and
must be unique in the scope of the RADIUS server. The NAS-identifier is often the
fully qualified domain name (FQDN) of the RADIUS client.
Configuring RADIUS Settings

To configure RADIUS settings, use the following procedure:
1. Select Administration Access RADIUS Settings.
2. Configure global settings for all RADIUS servers.
a. Set Administrative State to identify the administrative state of the
configuration.
b. Optional: In the Comments field, enter a descriptive summary.
c. Specify the NAS-identifier in the Identifier field.
322
d. Specify the interval in milliseconds that the appliance waits for a reply from
a RADIUS server before retransmitting the outstanding request in the
Timeout field. Use an integer in the range of 1 through 5000. The default is
1000.
e. Specify the number of times that the appliance retransmits an unanswered
request to a RADIUS server before contacting another server in the list in
the Retries field.
3. Do not define RADIUS servers to authentication CLI access without the use of
RBM. In other words, do not define any RADIUS servers on the CLI Servers
tab. This functionality is deprecated. If using RADIUS for authentication, define
RADIUS as the RBM method and define the appropriate RADIUS servers on
the AAA/RBM Servers tab.
4. Define RADIUS servers for use by AAA Policy objects or by the RBM policy.
a. Click the AAA/RBM Servers tab.
b. Define a server.
1) Click Add.
2) Specify the relative position of this server in the list in the Number
field.
3) Specify the IP address or domain name of the server in the Server
Address field,
4) Specify the listening port on the remote server in the Server Port field.
5) Specify the password to log in to the server in the Secret field.
6) Reenter the password in the Confirm Secret field.
7) Click Save.
c. Repeat the previous step to add additional servers to the list.
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.
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.
323
Validation is performed by an internal dynamic schema that combines

the schema-based validation requirements with the exception rules in
this Schema Exception Map.
Rules tab
1. Click the Rules tab to display the Schema Exception Map Configuration (Rules)
screen.
2. Click Add to display the Rules Property window. Use this window to define
schema exception rules.
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
324
v A threshold that defines the limit (maximum transactions per second) before
triggering the action
Unlike message (count and duration) monitors and Web services monitors, SLMs
are not directly assigned to a DataPower service. SLMs are implemented as part of
a processing policy.
Creating an SLM policy

An SLM policy can be enforced across a group of appliances to handle
load-balanced traffic that is destined for the same resources. A peer group
establishes a data sharing protocol among these appliances. Each appliance in the
group includes traffic that has passed through the other peers to calculate whether
a threshold was reached. Refer to Defining peer groups on page 328 for more
information.
To create an SLM Policy:
1. Click OBJECT Monitoring SLM Policy.
2. Click Add.
configuration.
v
v


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 328 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 326 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 327 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
328 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 327 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.
325
2) From the Threshold Interval Type list, select how to measure intervals.
3) From the Threshold Algorithm list, select the methodology that
calculates the threshold.
4) From the Threshold Type list, select how to apply the threshold to the
monitored count or latency.
5) In the Threshold Level field, enter the threshold that triggers the
action.
6) In the High-Low Release Level field, if the algorithm is high-low, enter
the low threshold (stop point).
7) In the Burst Limit field, if the algorithm is token bucket, enter the size
of the committed burst.
i. Define reporting intervals.
1) In the Reporting Aggregation Interval field, enter the interval at which
to report statistics.
2) In the Maximum Records Across Intervals field, enter the maximum
aggregation of reporting records. A single aggregation interval can
contain multiple records; for example, one record per resource or
credential. Use this property to configure the maximum number of total
records to save across the maximum number of intervals.
j. Auto Generated by GUI is read-only.
k. In the Maximum Credentials-Resource Combinations field, enter the
maximum number of records for credential and resource combinations to
set a maximum memory-consumption threshold.
l. Click Save.
9. Repeat the previous step to define another statement.
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.
configuration.
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.
326
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.
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.
configuration.
5.
6.
7.
8.

From the Resource Type list, select the manner to identify resources.
From the Match Type list, select the matching algorithm that determines to
which resources to apply an SLM policy.
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.
327
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. Set Administrative State to identify the administrative state of the
configuration.
c. Optional: In the Comments 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.
Defining an SLM schedule

An SLM schedule defines the time period (hours and days) during which to
enforce the statements in an SLM policy. Schedules allow the application of
different statements during different time periods.
To create an SLM schedule:
1. Click OBJECT Monitoring SLM Schedule.
2. Click Add.
configuration.
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.
328
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 Integration Appliance XI50:
Administrators Guide.
To define a peer groups:
1. Click Objects Network Peer Groups.
2. Click Add.
configuration.
5.
6.
7.
8.
9.

In the Type field. retain the default value (SLM).
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.
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.
329
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.
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
330
configuration parameters in the configuration file are informational and define

characteristics about the environment. These configuration parameters cannot be
modified.
To
1.
2.
3.
create a SQL data source:

Click Objects Network Setting SQL Data Source.
Click Add.
On the Main tab, define the basic configuration.
4. Optional: On the Data Source Configuration Parameters tab, define optional

but valid ODBC (or CLI) configuration parameters.
Defining the base configuration

To define the base configuration for a SQL data source:
1. Click Objects Network Setting SQL Data Source.
2. Click Add.
configuration.
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.
9.
10.
11.
12.
b. In the Returned Data Size Limit field, enter the data size limit in
kilobytes.
Optional: Set Allow Read-Only Access to on to allow read-only access to the
data source.
Optional: in the Maximum Connections field, enter the maximum number of
concurrent connections to allow.
331
Adding configuration parameters

Configuration parameters modify the behavior of the services that run with a data
server.
To add configuration parameters to an existing SQL data source:
1. Click Objects Network Setting SQL Data Source.
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.
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 79.
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.
332
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.
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"/>
333
<xs:enumeration
<xs:enumeration
<xs:enumeration
<xs:enumeration
<xs:enumeration
<xs:enumeration
<xs:enumeration
<xs:enumeration
<xs:enumeration
<xs:enumeration
<xs:enumeration
<xs:enumeration
<xs:enumeration
<xs:enumeration
<xs:enumeration
</xs:restriction>
</xs:simpleType>
</xs:attribute>
</xs:restriction>
</xs:complexContent>
</xs:complexType>
</xs:element>
value="byte"/>
value="char"/>
value="short"/>
value="int"/>
value="long"/>
value="float"/>
value="double"/>
value="bytes"/>
value="string"/>
value="short_array"/>
value="int_array"/>
value="long_array"/>
value="float_array"/>
value="double_array"/>
value="map_message"/>


<xs:element name="Array">
<xs:complexType>
<xs:sequence>
<xs:element ref="Element" maxOccurs="unbounded"/>
</xs:sequence>
</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>
334
<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>
<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, the appropriate rules in the
processing policy runs, and the message is put on a backside queue or topic. With
transactional messaging, if the backside PUT or any PUT in the processing policy
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.
335
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.
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.
336
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.
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.
337
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.
Configuring as a unique host

To configure a TIBCO EMS object as a unique host, use the following high-level
procedure:
catalog.
configuration.
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. Set Transactional to enable or disable transactional processing. In a
transacted session, a group of related messages are sent and received in a
single transaction.
b. In the Memory Threshold field, specify the memory allocation in bytes for
pending messages.
338
c. In the Maximum Message Size field, specify the MTU in bytes for the
current TIBCO EMS server. The MTU defines the maximum size of
messages that this server can process . Messages that are larger than the
specified value are dropped.
d. From the Default Message Type list, select the default message type. The
selected value is used when the message type cannot be determined from
message headers.
v If Byte, indicates that the message payload is accessed as a Java byte
array.
v If Text, indicates that the message payload is accessed as a Java string
value.
8. Define the session and connection limits:
a. Specify the maximum number of concurrent, open connections to allow to
the server in the Total Connection Limit field. The minimum is 1. The
default is 5.
b. Specify the maximum number of concurrent multiplexed sessions that a
single connection can support in the Maximum Number of Sessions per
Connection field. The minimum is 5. The default is 20.
If the number of current connections is less than the connection limit, a new
session requests in excess of this value trigger the establishment of a new
connection to the server.
For example, with default values (20 for sessions per connection, and 5 for
connection limit) and 3 active fully-subscribed connections, a new session
request generates the establishment of a fourth connection.
9. Optional: Enable an automatic critical error-recovery procedure. This
procedure attempts to reestablish a connection that was closed in response to
an error condition.
a. Set Automatic Retry to control whether to enable the automatic recovery
procedure.
b. In the Retry Interval field, specify the interval between connection
attempts.
10. From the SSL Profile list, select the client crypto profile to support secured
connections to the TIBCO EMS server.
11. Set Enable JMS-Specific Logging to enable or disable the enhanced
JMS-specific 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.
339

configuration.
single transaction.
pending messages.
message headers.
array.
value.
default is 5.
an error condition.
procedure.
attempts.
340
12. Specify the domain name or IP address in the TIBCO EMS Server Host field.
Note: This property is a required property, but it is ignored in this
configuration.
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.
configuration.
341

single transaction.
pending messages.
message headers.
array.
value.
default is 5.
an error condition.
procedure.
attempts.
configuration.
14. Select the algorithm from the Load Balancing Algorithm list:
None
342
(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.
configuration.
single transaction.
pending messages.
343
message headers.
array.
value.
default is 5.
an error condition.
procedure.
attempts.
configuration.
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:
344

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.
See your TIBCO EMS documentation for more information on these settings.
URL Rewrite Policy

You can design a URL Rewrite Policy that defines rules for the following rewrite
and replacement operations:
v Rewrite the entire URL or a portion of the URL
v Replace a header value in the message
v Rewrite the HTTP POST body in the message
The rewrite rules in the URL Rewrite Policy are applied before document
processing. Therefore, the evaluation criteria in the Matching Rule is against the
rewritten value.
Use the following method to create a URL Rewrite Policy:
345
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.
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
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.
346
.* 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.
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.
347
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.
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:
348
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.
Note: The HTTP proxy is not intended to work with XSL Proxy or XML
Firewall services.
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 and SFTP 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
requests that match the URL expression. These client settings can be
overridden by query parameters in the URL that initiates the file transfer.
SFTP client
The user agent controls the client settings for outgoing SFTP connections
for requests that match the URL expression. These client settings can be
overridden by query parameters in the URL that initiates the file transfer.
349
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.
configuration.
6. Optional: In the HTTP Request-Header field, enter the value the user agent
transmits as the HTTP request-header field.
7. Optional: In the Maximum Redirects field, change the maximum number of
HTTP redirect messages to allow before declaring the target as unreachable.
8. Optional: In the Timeout field, change the idle timeout to allow in seconds
before timing out and closing the connection.
9. On the Proxy Policy tab, define HTTP proxy policies.
10. On the SSL Proxy Profile Policy tab, define secure connection policies for
HTTP proxy servers.
11. On the Basic-Auth Policy tab, define basic authentication policies.
12. On the Soap-Action Policy tab, define SOAP action policies.
13. On the Pubkey-Auth Policy tab, define public key authentication policies.
14. On the Allow-Compression Policy tab, define policies that disable
compression.
15. On the Header-Retention Policy tab, define header retention policies.
16. On the Restrict to HTTP 1.0 Policy tab, define HTTP 1.0 restriction policies.
17. On the Inject Header Policy tab, define header injection policies.
18. On the Chunked Uploads Policy tab, define policies that disable HTTP 1.1
chunked content encoding.
19. On the FTP Client Policies tab, define FTP client policies.
20. On the SFTP Client Policies tab, define SFTP 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.
350
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 off 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 29 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.
351

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 establish a connection to a remote resource over FTP or SFTP with password
authentication, configure a user agent with a basic authentication policy.
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 add a SOAP action policy to a user agent:
3. 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.
352
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.
353
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.
354
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.
355
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.

Adding an SFTP client policy

The user agent controls the client settings for outgoing SFTP connections for
requests that match the URL expression. These settings can be further overridden
by query parameters in the URL that initiates the file transfer. When no SFTP
356
Client Policies is specified for the user agent, then the client authentication
settings are controlled by the Basic-Auth and Pubkey-Auth policies.
To
1.
2.
3.
add an SFTP client policy to a user agent:

Click the SFTP Client Policies tab.
4. Add a policy.
a. Click Add.
c. From the SSH client profile field, select an existing SSH client profile from
the list of existing profiles. Refer to Creating an SSH Client Profile on
page 29 for information.
d. Optional: To disable the generation of a unique file name for puts to a
remote directory, select off in the Use unique file names field.
7. Click Save to add this policy to the list.
|
WebSphere Cell
|
|
|
The WebSphere Cell object is responsible for retrieving the configuration

information from the WebSphere Network Deployment or the WebSphere Virtual
Enterprise back end.
|
|
|
|
|
|
The WebSphere Cell object initiates requests to the ODCInfo application and
receives the results as an XML representation of membership, weights, and session
affinity information. When the WebSphere Cell object receives the response, it
notifies each Load Balancer Group of the new information. The Load Balancer
Group then updates its membership, weights, and session affinity information
accordingly.
Selecting the update method
|
|
|
The update method specifies how to retrieve the information from the ODCInfo
application on the WebSphere Application Server Network Deployment or
WebSphere Virtual Enterprise.
|
|
|
Use one of the following update methods:
|
|
|
The poll update method uses a static polling interval. The poll to retrieve the
WebSphere Cell information occurs every interval regardless of whether the
WebSphere Cell configuration has changed.
|
|
|
|
The subscribe update method specifies that the request to retrieve the WebSphere
Cell information waits for either the duration of the time interval to expire or for
the WebSphere Cell information to change, whichever occurs first. If the ODCInfo
application has any new information, the application immediately responds with
v Poll
v Subscribe
357
|
|
|
an XML document. If there is no new information, the ODCInfo application delays

for the specified time interval number of seconds before returning with the current,
unchanged XML document.
|
|
|
|
|
|
The subscribe method results in more responsive updates by the appliance to

changes in the cell. Using this method might result in several updates within a
short amount of time. As a result, the subscribe method consumes more resources
on the appliance and on the server that is running the ODCInfo application. The
subscribe method is more appropriate when application routing is enabled, and
must be used if application edition (group and atomic rollout) functions are used.
|
|
|
Note: To use the subscribe update method, the version of the ODCInfo application
must match the firmware version. A back-level ODCInfo application is not
supported.
Creating a WebSphere Cell
|
|
|
|
Create a WebSphere Cell on the DataPower appliance to act as an intermediary

between the ODCInfo application on the WebSphere deployment manager and the
load balancer group on the DataPower appliance.
Before you begin
|
|
|
|
|
|
|
|
The ODCInfo application must be installed, and you need to know the host and
port of the WebSphere deployment manager where this application is installed. To
find the port number
1. From the WebSphere Administrative Console, click System Administration >
Deployment Manager > ports.
2. Select the port name:
v Click the WC_adminhost port name for HTTP.
v Click the WC_adminhost_secure port name for HTTPS.
|
|
To create this configuration, the DataPower appliances require the Option for
Application Optimization feature.
About this task
|
|
|
|
Add and configure a WebSphere Cell to query the ODCInfo application for current
information about the host weights or if a new host has been added or removed
from the cluster. If there is an information update, the WebSphere Cell sends the
updated information to the load balancer group.
Procedure
1. Click Objects > Configuration Management > WebSphere Cell .
2. Click Add.
3. In the Name field, enter a name.
|
|
|
|
|
|
|
|
|
|
4. Retain the default setting for Admin State. To place in an inactive

administrative state, click disabled.
5. Optional: In the Comments field, enter a brief descriptive summary.
6. In the Deployment Manager Host field, enter the host name or IP address of
the deployment manager with the installation of the ODCInfo application.
7. In the Deployment Manager Port number field, enter the port of the
deployment manager.
358
|
|
|
|
|
|
|
|
|
|
8. Optional: From the SSL Proxy Profile list, select the SSL proxy profile for a
secured connection.
9. In the Update Method field, indicate whether to use a static polling interval
or to subscribe to the WebSphere cell information.
10. In the Time Interval field, if the update method is poll, specify the amount of
time in seconds between poll requests. If the update method is subscribe,
specify the maximum duration of the request in seconds. The recommended
value is 10 seconds.
What to do next
Create or modify a load balancer group to reference the WebSphere Cell.
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, the appropriate rules in the
processing policy runs, and the message is put on a backside queue or topic. With
transactional messaging, if the backside PUT or any PUT in document 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.
359
v Configure the service with a WebSphere JMS Front Side handler and a
WebSphere JMS backend URL.
v For the handler and the backend URL, use the same WebSphere JMS server
object with the Transactional property enabled.
v Define the WebSphere JMS URL using the Transactional=true parameter. For
example:
dptibems://TIBCOEMSServer?RequestQueue=OUTQUEUE&Transactional=true
With this configuration, the WebSphere JMS Front Side handler and the WebSphere
JMS backend URL share the same WebSphere JMS transacted session. A single
COMMIT or ROLLBACK operation is issued depending on the processing result.
This guarantees once-and-only-once message delivery to WebSphere JMS
messages.
Single WebSphere JMS session with commit

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.
360
v Configure a processing policy with at least one action that uses a WebSphere
JMS URL open call such as a results action, a dp:url-open or a dp:soap-call
extension function.
Note: Asynchronous actions do not support the WebSphere JMS transacted
session.
v Configure all URL open calls with the Transactional=true parameter.
v Configure the WebSphere JMS Front Side handler and all WebSphere JMS URL
open calls using the same WebSphere JMS server object with the Transactional
property enabled.
v Optional: Use a WebSphere JMS backend URL defined with the
Transactional=true parameter.
In this configuration, the same transacted WebSphere JMS session receives the
message on the front side and sends the message using either a results action or a
dp:url-open extension function and optionally sends on the backend URL. The
WebSphere JMS transacted session is shared not only between the WebSphere JMS
Front Side handler and the WebSphere JMS Backend URL, but also between any
WebSphere JMS URL open calls used in the processing policy.
A single COMMIT or ROLLBACK operation is issued depending on processing
result. This guarantees once-and-only-once message delivery to the WebSphere
JMS messages. All calls to the WebSphere JMS server use the same shared
transacted session.
Shared WebSphere JMS session in message fanout with commit

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
361
session is shared between the front and back side, this COMMIT or ROLLBACK
serves as an the end of transactions for both receive and send operation.
If the WebSphere JMS URL is defined with a reply queue parameter or if the
processing policy contains any other actions that will be using the same shared
transacted WebSphere JMS session, a new transaction is created. This new
transaction will be committed or rolled back either when the processing policy
finishes or when some other action is configured with WebSphere JMS URL open
call with the Sync=true parameter.
Configuring a WebSphere JMS server

To define the connection to a WebSphere JMS server:
1. Click Objects Network WebSphere JMS.
2. Click Add.
Name Specify the name of this WebSphere JMS Server object.
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
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 the maximum local memory, in bytes, that are allocated for
pending messages.
Maximum Message Size
Specify 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.
362
Text JMS message

Indicates that the message payload is accessed as a Java string
value.
Total Connection Limit
Optionally specify the maximum number of concurrent, open,
transport protocol connections between the DataPower appliance and
the remote WebSphere JMS Server.
The default value, 5 connections, specifies the maximum open
concurrent number of HTTP, HTTPS, SSL, and TCP connections. To
change the default value, specify an integer between 1 and 9.
The desirable number of sessions per connection
Optionally specify the maximum number of concurrent, open,
multiplexed sessions supported by a single transport-layer connection.
Session requests in excess of this value trigger the establishment of a
new transport-layer connection to the WebSphere JMS Server,
assuming that the number of open transport-layer connections is less
than the value specified by Total Connection Limit property.
Automatic Retry
Enable (on, the default) or disable (off) an automatic critical
error-recovery procedure that attempts to reestablish a connection that
has been broken in response to an error condition.
Retry Interval
Optionally specify the interval, in milliseconds, between connection
attempts.
Enable JMS-specific logging
Enable (on) or disable (off, the default) an enhanced
messaging-specific logging facility.
WebSphere JMS Target Transport Chain
Select the predefined transport chain provided by the WebSphere
Application Server, and used for message exchange between the
application server and the WebSphere JMS object.
Inbound Basic Messaging
(Default) Specifies the predefined InboundBasicMessaging
transport chain (JFAP-TCP/IP)
Inbound HTTP Messaging
Specifies the predefined InboundHTTPMessaging transport chain
(tunnels JFAP using HTTP wrappers)
Inbound HTTPS Messaging
Specifies the predefined InboundHTTPSMessaging transport
chain (tunnels JFAP using HTTPS wrappers)
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.
363
WebSphere JMS Messaging Bus

Specify the Service Integration Bus (SIB) used to access the remote
WebSphere Application Server.
An SIB supports applications using message-based and
service-oriented architectures. A bus is a group of interconnected
servers and clusters that have been added as members of the bus.
Applications connect to a bus at one of the messaging engines
associated with its bus members.
If you have access to the WebSphere Administrative Console, you can
view bus information, to include bus members and messaging
engines, queues and topics, and the bus-specific default topic space
through the Service integration Buses menu.
4. Click the WebSphere JMS Endpoint tab display the WebSphere JMS Endpoint
catalog (list of configured bootstrap servers).
5. Click Add to display the JMS Endpoint Property window, which you use to
specify the location of a bootstrap server.
A service integration bus (SIB) supports applications using message-based and
service-oriented architectures. A bus is a group of interconnected servers and
clusters that have been added as members of the bus. Applications connect to
a bus at one of the messaging engines associated with its bus members.
A messaging engine is a component, running inside a server, that manages
messaging resources for a bus member. Applications are connected to a
messaging engine when accessing a SIB.
Applications (such as the WebSphere JMS object) running outside the WAS
environment cannot locate directly a suitable messaging engine to connect to
the target bus. In such cases the remote clients or servers must access the bus
through a bootstrap server that is a member of the target bus.
A bootstrap server is an application server running the SIB process, but need
not be running any message engines. Rather the bootstrap server selects a
messaging engine that is running in an application server that supports the
bootstrap protocol requested by the remote appliance.
To connect to a messaging engine the remote application first connects to a
bootstrap server; the bootstrap server selects a messaging engine and then
tells the client application to connect to that message engine to gain bus
access.
A bootstrap server uses a host name or IP address, with a port number and a
bootstrap transport chain (identifying the protocol stack offered by the
bootstrap server) to define an endpoint address.
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)
364
HTTPS
Specifies the predefined BootstrapTunneledSecureMessaging
transport chain (tunnels JFAP using HTTPS wrappers)
7.
8.
9.
10.
SSL
Specifies the predefined BootstrapSecureMessaging transport

chain (JFAP-SSL-TCP/IP)
TCP
(Default) Specifies the predefined BootstrapBasicMessaging

transport chain (JFAP-TCP/IP)
The protocol stack used to access the bootstrap server does not need
to be the same protocol stack that is used for actual message transfer
via the bus.
Click Save to bootstrap server identification and to return to the WebSphere
JMS Endpoint catalog.
If necessary, repeat steps 5 on page 364 to 7 to identify additional bootstrap
servers.
Is you want to establish a secure (SSL-enabled) connection between the
WebSphere JMS object and the remote WAS JMS default message provider,
click the SSL tab to display the WebSphere JMS SSL panel.
SSL Profile
Select the client crypto profile to support secured connections to the
WebSphere JMS 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
365
DES
Data Encryption Standard
EDE
Encrypt/Decrypt/Encrypt for the triple DES algorithm
EXPORT
Exportable
FIPS
Federal Information Processing Standard
MD5
Secure hashing that converts an arbitrarily long data string to

a fixed size (128 bytes) digest
NULL No encryption
RC2
a stream cipher designed for RSA
RC4
a stream cipher designed for RSA (variable key size from 40 to

128 bits)
RSA
Public key algorithm (requires RSA or DSS key exchange)
SHA
Secure Hash Algorithm (produces 160-bit hash)
SSL
Secure Sockets Layer
TLS
Transport Layer Security
FIPS Compliant Ciphers Suite

Indicate whether to force the use of IBM FIPS-compliant cipher
specifications.
XML Manager
The firmware creates a default XML Manager object in the default domain and in
each application. The default instance in each domain can be edited like any other
instance of an XML Manager object. The default instance in each domain operates
independently of each other.
An XML Manager object obtains and manages XML documents, style sheets, and
other document resources on behalf of one or more services. An XML Manager
also provides the following capabilities:
v Basic network configuration, such as load balancing and accessing remote
servers.
v Set manager-associated limits on the parsing of XML documents. By default, the
appliance imposes limits on various characteristics of XML documents. These
limitations provide for increased security and stability to protect against DoS
attacks or runaway data. Parser limits defined by the XML Manager object that
is associated with a service can be overridden by service-specific settings.
v Enable the caching of documents that this XML Manager object obtains. XML
Manager objects obtain documents via HTTP. The number of documents in the
cache depends on the availability of allocated memory.
v Define extension function mapping. An XML Manager object can automatically
map custom style sheet extension functions to DataPower extension functions.
This ability removes the need to alter or rewrite a style sheet for use by the
appliance. The most common example is the node-set() extension function. If a
service uses style sheets that reference the Microsoft node-set, Oracle node-set,
366
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. For more information, see Document cache policy URL
matching expression.
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.
Document cache policy URL matching expression

This topic explains the order of evaluation of the URL match expression when
there are multiple URL matching strings with various priorities.
The match patterns of a document cache policy are evaluated in alphabetical order.
However, the priority assigned to the policy determines which policy is applied.
The policy with the highest priority is the one that is selected.
For example, consider a policy containing the following URL match expressions:
Table 11. Example Document Cache Policy
URL Match expression
Policy type
Priority
*.xml
Protocol-based
20
*192.0.2.24*
Protocol-based
*usrconfig*
no-cache
10
The request, http://192.0.2.24/site/usrconfig, matches *192.0.2.24* and

*usrconfig*. If the priorities assigned to the policies are the same, the first pattern
that matches is selected. In the example policy, if both *192.0.2.24* and *usrconfig*
had the same priority, *192.0.2.24* would be selected because it would be the first
pattern matched based on the referenced asset (URL). However, *usrconfig* is
selected because it has the higher priority.
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.
367
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:
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)
NSS Client
The NSS client enables integration with RACF on the z/OS Communications
Server. The NSS Client object specifies the authentication information required to
allow the DataPower appliance to function as an NSS client. The NSS Client object
specifies the following properties:
v Remote Address
v Remote Port
v SSL Proxy Profile
v Client ID
v System Name
v User Name
v Password
Based on these properties and the request type, the following actions occur:
v DataPower requests a secure connection to the z/OS Communications Server
368
v RACF performs authentication of users

v RACF performs authorization to resources
v RACF logs authorized and unauthorized attempts to access RACF-protected
resources
v z/OS Communications Server NSS protocol provides return codes and reason
codes for connectivity requests
To support this functionality, the NSS server must be configured to support the
NSS client. See the following z/OS Communications Server documentation for
these configuration steps:
v Enable the XMLAppliance discipline support. For further information, refer to the
section on network security services server in the z/OS Communications Server: IP
Configuration Reference.
v Authorize the client userid to SAF profiles representing security services and
resources. For further information, refer to the section on preparing to provide
network security services in the z/OS Communications Server: IP Configuration
Guide.
v Configure SSL for the TCP connection between the client and server. For further
information, refer to the section on configuring the NSS server in the z/OS
Communications Server: IP Configuration Guide.
Only one physical connection per Remote Address, Remote Port, and Client ID is
allowed. Additional 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 NSS Client

To configure an NSS client:
1. Click OBJECTS z/OS Configurations NSS Client.
2. Click Add.
configuration.
369
6. In the Remote Address field, specify the IP address or hostname of the NSS
server.
7. In the Remote Port field, specify the port on which the NSS server listens.
8. From the SSL Proxy list, select an SSL Proxy Profile to provide a secured
connection to the remote authentication server.
9. In the Client ID field, specify the client ID to use for registration with the
NSS server.
10. In the System Name field, specify the system name to identify the NSS client
to the NSS server.
11. In the User Name field, specify the user name to use to authenticate with the
SAF.
12. In the Password field, specify the password to use to authenticate with the
SAF.
13. Reenter the password in the Confirm Password field.
370
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.
371
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
372
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
373
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.
374

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 transaction. A
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 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, see
Extension variables on page 385.
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 transaction. A
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 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 document processing scope.
A named context variables can be user-defined or based on an extension
variable. For a complete list of the available extension variables, see
Extension variables on page 385.
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 document processing session. The
majority of service variables are read-only and cannot be set.
375
For a complete list of the available service variables, see Service

variables.
var://system/variable
Addresses a global variable that is available in all contexts. System
variables persist beyond the scope of request-response processing 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 request-response processing, use a
system variable.
For a complete list of the available global system variables, see System
variables on page 386.
Note: See List of available variables on page 387 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 services
v Legacy MQ-specific services
General service variables

This section contains information about general variables in an alphabetic order by
permission category. General variables are available to all services. Table 12 lists the
names and permission for these variables.
Table 12. 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 an alphabetic order by permission
category. Table 13 on page 377 lists the names and permission for these variables.
376
Table 13. Names and permissions for general service variables that are available to only
Multi-Protocol Gateway and Web Service Proxy services
Variable name
Permission
var://service/mpgw/backend-timeout
Read-write
var://service/mpgw/skip-backside
Write-only
var://service/reply-to-q
Read-write
var://service/reply-to-qm
Read-write
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 service variables

This section contains information about variables for configuration services in an
alphabetic order by permission category. Table 14 lists the names and permission
for these variables.
Table 14. Names and permissions for variables that are available for 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.
377
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.
Load balancer service variables

This section contains information about load balancer variables in an 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 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 an alphabetic
order by permission category. MQ-specific variables are available to only the legacy
MQ Host and MQ Proxy services. Table 16 lists the names and permission for these
variables.
Table 16. 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
Read-write
var://service/mqmd-reply-to-qm
Read-write
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.
378
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.
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 an alphabetic order by
permission category. Multistep variables usually impact the behavior of specific
actions in the context of a processing rule. Table 17 lists the names and permission
Table 17. Names and permissions for variables that are available to all services
Variable name
Permission
var://service/log/soapversion
Read-write
379
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.
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 an
Table 18. 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
380
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
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 an alphabetic
order by permission category. Table 19 lists the names and permission for these
variables.
Table 19. Names and permissions for variables that are available for 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 can 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
381
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 document 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.
Gets or sets the error subcode. This variable can help to disambiguate the
reason for which the error rule was invoked. Often, the subcode is the
same as the value of the var://service/error-code variable. Sometimes,
the subcode is a more specific result code.
Gets or sets the strict error mode. This variable controls the error mode for
document processing.
v If the value is set, an invocation of the dp:reject extension element
stops document processing.
v If the value is not set, an invocation of the dp:reject extension element
logs a message but does not stop document processing.
Headers transaction variables

This section contains information about header variables in an alphabetic order by
permission category. Table 20 lists the names and permission for these variables.
Table 20. Names and permissions for variables that are available for 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.
382
Persistent connection transaction variables

This section contains information about persistent connection variables in an
Table 21. Names and permissions for variables that are available for persistent connections
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 an alphabetic order by
Table 22. Names and permissions for variables that are available for routing
Variable name
Permission
var://service/routing-url
Read-write
var://service/routing-url-delay-content-type-determination
Read-write
var://service/routing-url-sslprofile
Read-write
For XML Firewall, Multi-Protocol Gateway, and Web Service Proxy
services, gets or 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
property (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
383
elements do not allow the specification of a protocol. These extension

element, if provided, overrides the value of the target server that is
specified in this variable.
|
|
var://service/routing-url-delay-content-type-determination
Gets or sets the routing URL with delayed content-type determination.
|
|
|
|
|
|
This variable is a variant of the var://service/routing-url variable. It

functions the same as the var://service/routing-url variable, except that
it delays the content-type determination for MIME documents, which in
certain scenarios helps the DataPower appliance send the content-type of
the MIME documents (not the content-type of the root document in the
MIME document) to the back-end server.
|
|
Use the var://service/routing-url variable first. If the appliance sends

the wrong content-type to the back-end server, use this variable instead.
Gets or 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 an
Table 23. 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 an alphabetic order by permission category. Table 24 lists the names
and permission for these variables.
Table 24. Names and permissions for variables that are available to WSM
384
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 25 lists the
names and permission for these variables.
Table 25. Names and permissions for extension variables
Variable name
Permission
var://local/_extension/allow-compression
Write-only
var://local/_extension/donot-follow-redirect
Write-only
var://local/_extension/header/
Write-only
var://local/_extension/http-10-only
Write-only
var://local/_extension/prevent-persistent-connection
Write-only
var://local/_extension/sslprofile
Write only
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"
385
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:
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 26. 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.
386
List of available variables

Table 27 lists the variables that you can define for document processing.
Table 27. 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
387
Table 27. 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
388
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 user's responsibility to evaluate and verify the
operation of any non-IBM product, program, or service.
IBM may have patents or pending patent applications covering subject matter
described in this document. The furnishing of this document does not grant you
any license to these patents. You can send license inquiries, in writing, to:
IBM Director of Licensing
IBM Corporation
North Castle Drive
Armonk, NY 10504-1785
U.S.A.
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, DataPower, and WebSphere are registered trademarks of the
International Business Machines Corporation in the United States or other
countries. If these and other IBM trademarked terms are marked on their first
occurrence in this information with a trademark symbol ( or ), these symbols
indicate U.S. registered or common law trademarks owned by IBM at the time this
information was published. Such trademarks may also be registered or common
law trademarks in other countries. A current list of IBM trademarks is available on
the Web at Copyright and trademark information at www.ibm.com/legal/
copytrade.shtml.
Adobe is either a registered trademark or trademark of Adobe Systems
Incorporated in the United States, and/or other countries.
389
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.
Other product and service names might be trademarks of IBM or other companies.
390
Index
Special characters
__JSONASJSONX keyword 93
... button
list of referenced object 9
referenced object 8
.java.policy file 191
[configuration-database] stanza, file
entry 252
[ldap] stanza, ssl-keyfile-pwd entry 252
[manager] stanza, replica entry 252
<results> element 148
<url> element 148
+ button
referenced object 8
A
AAA
authentication
search parameters 266
TFIM 253
aaa action
purpose 88
AAA action
defining 95
dictionary attack, protection 45
AAA Info file
Authenticate element 247
Authorize element 247
editor
authenticated identities 248
authorized access to
resources 250
confirmation 250
credentials 248
default credential 248
file information 250
map credentials 249
map resources 249
overview 247
unauthenticated identity 248
MapCredentials element 247
MapResource element 247
overview 246
AAA Info File
authentication 165
authorization, AAA 179
credentials mapping, AAA 167
resources mapping, AAA 171
AAA Policy
AAA Info file
Authenticate element 247
Authorize element 247
MapCredentials element 247
MapResource element 247
overview 246
authentication
AAA info file 165
AAA Policy (continued)

authentication (continued)
BinarySecurityToken 165
ClearTrust 163
custom 164
Kerberos AP-REQ 165
LDAP 160
LTPA token 159
Netegrity 163
none 164
RADIUS 165
SAML assertion, artifact 164
SAML assertion, valid
signature 159
SAML assertions, remote 373
SAML server 161
signer certificate 166
SSL certificate, connection
peer 166
TAM 164
context 165
WS-Trust server 162
X.509 certificates, remote 372
z/OS NSS authentication 164
authorization
AAA Info File 179
always 172
any authenticated 172
ClearTrust 173
custom 173
LDAP 174
Netegrity 173
SAML attribute from
authentication 177
SAML attribute query 176
SAML authorization query 175
TAM 172
XACML PDP 178
z/OS NSS authorization 173
changing authentication caching
policy 168
changing authorization caching
policy 180
configuring 151
creating 152
credentials mapping
AAA Info file 167
custom 167
from identity extraction 167
none 167
TFIM 167
WS-SecureConversation 167
defining authentication method 159
defining authorization method 172
defining identity extraction
method 153
defining resource extraction
methods 168
file editor
authenticated identities 248

file editor (continued)
authorized access to
resources 250
confirmation 250
credentials 248
default credential 248
file information 250
map credentials 249
map resources 249
overview 247
unauthenticated identity 248
identity extraction
BinarySecurityToken, WS-Security
Header 154
client IP address 157
custom 159
derived-key UsernameToken,
WS-Security Header 154
extracted token, cookie value 158
extracted token, message 158
HTTP Authentication Header 153
Kerberos AP-REQ, SPNEGO 156
Kerberos AP-REQ, WS-Security
Header 155
LTPA token 158
name, SAML
AttributeStatement 156
name, SAML authentication
assertion 156
password-carrying
UsernameToken, WS-Security
Header 153
Processing Metadata 159
SAML artifact 157
subject DN, certificate in message
signature 157
Token Subject DN (SSL),
connection peer 156
Identifier 154
WS-Trust Base 155
WS-Trust Supporting 155
LTPA, adding user attributes 246
Main 221
mapping authentication
credentials 167
mapping resources 170
namespace mappings
XPath bindings 245
NSS Client 368
object pages
Authenticate 226
Authorize 235
creating 221
Identity 224
LTPA Attributes 244
Map Credentials 233
Map Resource 235
391

object pages (continued)
Namespace Mapping 243
Post Processing 242
Resource 234
SAML Attributes 243
Transaction Priority 245
post processing
Authorized Counter 180
available activities 181
CICS Transaction Server 184
Count Monitors 180
custom style sheet 182
ICRX token 184
Kerberos AP-REQ 182
logging access attempts 181
LTPA 183
Rejected Counter 180
SAML assertion 182
SAML Assertion/Response 184
SPNEGO 183
TFIM 184
WS-Security UsernameToken 183
WS-Trust 182
z/OS identity propagation 184
resource extraction
HTTP operations 169
local name of request element 169
URI of top-level element 169
URL from client 169
URL to backend 168
XPath from request 169
resources mapping
AAA Info File 171
custom 170
none 170
TAM 170
TFIM 170
XPath from resource
extraction 171
SAML attributes
defining 245, 258
SFTP Server Front Side Handler 74
AAAInfo.xsd file 246
Accept-Encoding header, retaining 354
accepted configuration
deployment policy 207
actions
aaa
purpose 88
AAA
defining 95
antivirus
defining 95
purpose 88
call
defining 97
defining reusable rules 145
purpose 88, 148
checkpoint
defining 97
purpose 88
conditional
defining 98
purpose 88
392
actions (continued)
contexts
__JSONASJSONX 92
input 92
output 92
convert-http
defining 99
purpose 89
cryptobin
defining 99
purpose 89
decrypt
defining 107
Encrypted tokens 371
purpose 89
defining 95
encrypt
defining 109
ID references 371
purpose 89
SOAP message with
WS-Security 109
SOAP message with XML
encryption 113
XML message with XML
encryption 114
event-sink 115
purpose 89
extract
defining 116
purpose 89
fetch
attachment protocol 147
defining 116
locating remote resources 145
purpose 89
query parameters 147
specifying remote locations 146
filter
conformance filter 119
defining 117
purpose 89
replay filter 117
required elements filter 118
standard filter 117
WS-Security message layout
filter 119
for-each 119
purpose 89
for-each action
specifying multiple URLs 146
log
defining 122
purpose 90
method rewrite
defining 130
MQ Header
modifying reply queue 125
modifying reply queue
manager 126
modifying request message
headers 124
modifying response message
headers 125
actions (continued)
MQ Header (continued)
overview 123
retrieving responses with
correlation ID 124
retrieving responses with message
ID 124
on-error
defining 126
purpose 90
variable builder 148
purpose 88
results
defining 128
purpose 90
results-async
defining 129
purpose 90
rewrite header
purpose 90
rewrite header (rewrite)
defining 130
rewrite method
purpose 90
route-action
defining with style sheet 131
defining with XPath
expression 131
purpose 90
route-set
defining 132
purpose 91
specifying remote location 146
setvar
defining 132
purpose 91
sign
defining 133
generating signature
confirmation 374
ID references 371
purpose 91
verifying signature
confirmation 374
slm
defining 135
purpose 91
sql
defining 135
purpose 91
strip-attachments
defining 136
purpose 91
supported protocols 146
actions (continued)
validate 142
purpose 92
verify
adding 144
confirmation 374
Kerberos AP-REQ tokens,
remote 373
purpose 92, 144
verifying signature
confirmation 374
xform
defining 137
defining buffer attachment
transform 141
defining conformance
transform 142
defining SOAP refinement
transform 139
purpose 91
xformbin
defining 138
purpose 91
xformpi
defining 138
purpose 91
Add button
admin account
exporting configuration data 197
Administration menu 7
administrative states, objects 12
allow compression policy, user
agent 353
antivirus (antivirus) action
defining 95
antivirus action
purpose 88
AP-REQ message, Kerberos 255
appliance configuration
backing up 197, 198
comparing 206
configuration checkpoints 202
copying
files 200
objects 200
exporting 197
select objects and files 199
importing configuration 204
managing configuration changes 205
moving
files 200
objects 200
reading change report 206
reverting changes 207
undoing changes 207
appliance-wide log
location 188
application domains
backing up configuration 198
Apply button 11
asymmetric signatures
verifying 144
asynchronous transaction variables

service/transaction-timeout 380
asynchronous transactions variables
listing 380
service/transaction-key 380
service/transaction-name 380
asynchronous variables
service/soap-oneway-mep 380
attachment protocol
actions 147
attachments
buffering transform 141
Attachments Profile 1.0
Conformance Policy 261
audit log
location 187
viewing 187
audit: directory 187
Authenticate element, AAA Info file 247
authentication
configuring RADIUS settings 322
LDAP 266
authentication caching policy,
changing 168
authentication policy
user agent
basic 352
public key 353
SCP protocol 353
SFTP protocol 353
authentication, AAA
AAA info file 165
available methods 159
ClearTrust 163
connection peer
SSL certificate 166
custom 164
Kerberos AP-REQ 165
LDAP 160
LTPA token 159
Netegrity 163
none 164
RADIUS 165
SAML assertion
artifact 164
valid signature 159
SAML server 161
signer certificate 166
TAM 164
WS-SecureConversation context 165
WS-Trust server 162
z/OS NSS authentication 164
authorization caching policy,
changing 180
Authorization header, HTTP 352
authorization, AAA
AAA Info File 179
always 172
any authenticated 172
ClearTrust 173
custom 173
authorization, AAA (continued)

LDAP 174
Netegrity 173
SAML attribute from
authentication 177
SAML attribute query 176
SAML authorization query 175
TAM 172
XACML PDP 178
z/OS NSS authorization 173
Authorize element, AAA Info file 247
auto-config.cfg file 11
B
backend-timeout variable 377
basic configuration
MQ Front Side Handler 83
Basic Profile 1.0
Basic Profile 1.1
Basic Security Profile 1.0
BinarySecurityToken
authentication, AAA 165
identity extraction, AAA 154
bold typeface 2
buffer-attachments.xsl style sheet 141
builder
burst limit
count monitors 215
buttons
... 8
+ 8
Apply 11
Cancel 11
Delete 12
Edit 9
Logout 7
Save Config 7, 11
Undo 11
View 9
C
CA Unicenter Manager 366
caches
flushing
document cache 368
stylesheet cache 368
caching policy
AAA Policy
authentication 168
authorization 180
call action
defining 97
purpose 88
call processing rule (call) action
call processing rule action
See call action
Cancel button 11
cert: directory 187
Index
393
certificate files
location 187
Certificate objects
export packages 197
certificates
converting 21
DER 17
exporting 19
generating 18
importing 20
PEM 17
PKCS #12 17
PKCS #8 17
security
location, shared 188
location, Web browsers 188
supported formats 17
uploading 191
checkpoint action
purpose 88
checkpoint configuration files
location 187
checkpoint event (checkpoint) action
defining 97
chkpoints: directory 187
clear pdp cache CLI 260
clear xsl cache CLI 260
ClearTrust
client-to-server rule 88
Clone link 13
commands
clear pdp cache 260
clear xsl cache 260
web-mgmt 7
compression policy, user agent 353
conditional action
defining 98
purpose 88
config: directory 187
configuration
managing appliance
configuration 195
configuration checkpoints
defining number to allow 202
deleting 203
listing 203
loading 203
overwriting 202
rolling back 203
saving 202
configuration data
applying 11
backing up
WebGUI 197, 198
backing up application domains 198
comparing
WebGUI 206
configuration checkpoints 202
copying
files 200
objects 200
different release level 197
exchanging 197
394
configuration data (continued)

exporting
location of files 187
select objects and files 199
WebGUI 197
files not included 197
importing
WebGUI 197, 204
managing changes 205
moving
files 200
objects 200
objects not included 197
reading change report 206
reading changes 207
saving 11
undoing changes 207
configuration files
exported, location 187
location 187
TAM
ASCII 251
creating 252
modifying 252
obfuscated 251
configuration service variables
listing 377
service/config-param/ 377
service/max-call-depth 378
configuration states, objects 12
Conformance Policy
filter actions 261
object pages 261
WS-I Attachments Profile 261
WS-I Basic Profile 261
WS-I Basic Security Profile 261
conformance transform 142
conformance-filter.xsl style sheet 119
conformance-xform.xsl style sheet 142
Content-Length header 355
contexts
actions
__JSONASJSONX 92
input 92
output 92
keywords
__JSONASJSONX 93
INPUT 92
NULL 93
OUTPUT 92
PIPE 93
processing policies 92
processing rules 92
Control Panel
File Management 189
convert query parameters to XML
(convert-http) action
defining 99
convert query parameters to XML action
See convert-http action
convert-http action
defining 99
purpose 89
Count Monitor
Count Monitor (continued)

post processing, AAA 180
count monitors
burst limit 215
configuring 214
Count monitors 298
credentials
identification
configuring 24
creating 24
credentials mapping
LDAP 266
credentials mapping, AAA
AAA Info file 167
custom 167
from identity extraction 167
none 167
TFIM 167
WS-SecureConversation 167
crypto binary (cryptobin) action
defining 99
crypto binary action
See cryptobin action
Crypto Certificate
configuring 21
creating 21
object pages 21
Crypto Firewall Credentials
object pages 23
Crypto Identification Credentials
object pages 24
Crypto Key
configuring 25
creating 25
object pages 25
Crypto Profile
configuring 27
creating 27
Crypto Tools
converting certificates 21
converting keys 20
exporting certificates 19
exporting keys 19
generating certificates 18
generating keys 18
importing certificates 20
importing keys 20
cryptobin action
defining 99
purpose 89
cryptography
shared secrets 28
D
dashboard 7
debugging
decrypt action
defining 107
purpose 89
decrypt.xsl file 107
default log
location 188
Delete button 12
denial-of-service, protection
multiple message (MMXDoS) 42
single message (XDoS) 41
deployment policy
accepted configuration 207
creating 208
filtered configuration 207
modified configuration 207
using the builder 209
Deployment Policy
object pages 208
deployment policy builder
creating matching statements 209
DER
certificate format 17
key format 17
directories
audit: 187
available 187
cert: 187
chkpoints: 187
config: 187
displaying contents 189
dpcert: 187
export: 187
hiding contents 189
image: 187
local: 187
logstore: 187
logtemp: 188
managing 187
pubcert: 188
refreshing contents 190
sharedcert: 188
store: 188
tasktemplates: 189
temporary: 189
disabled administrative state 12
Document Crypto Map
creating 263
documentation conventions, typefaces
Domain list 7
down operation state 12
dpcert: directory 187
dpmq protocol 146
dptibems protocol 146
dpwasjms protocol 146
dpwasjmss protocol 146
DSA signatures
verifying 144
duration monitors
filters 217
Duration monitors 298
E
Edit button 9
elements
EncryptedData element 371
SecurityTokenReference 372
SignatureConfirmation 373
enabled administrative state 12
encoding, chunked content 355

encrypt action
defining 109
ID references 371
purpose 89
SOAP message with WS-Security 109
SOAP message with XML
encryption 113
XML message with XML
encryption 114
encrypt-soap.xsl file 113
encrypt-wssec.xsl file 109
encrypt.xsl file 114
encrypted tokens
error code rule 87
error handling variables
listing 381
service/error-code 381
service/error-ignore 381
service/error-message 382
service/error-protocol-reasonphrase 381
service/error-protocol-response 381
service/error-subcode 382
service/strict-error-mode 382
error rule 88
event-sink action
defining event-sink 115
purpose 89
Export link 12
export packages
admin account 197
files not included 197
objects not included 197
permission 197
export: directory 187
Extensible Access Control Markup
Language
See XACML PDP
extension functions
node-set() 366
set-target() 131
extension variables
listing 385
local/_extension/allowcompression 385
local/_extension/donot-followredirect 385
local/_extension/header/ 385
local/_extension/http-10-only 386
local/_extension/prevent-persistentconnection 386
local/_extension/sslprofile 386
local/_extension/timeout 386
extract action
defining 116
purpose 89
extract using XPath (extract) action
defining 116
extract using XPath action
See extract action
F
fault-tolerance
TIBCO EMS 339, 343
fetch action
defining 116
purpose 89
file entry, [configuration-database]
stanza 252
File Management utility, launching 189
file system
See directories
files
.java.policy 191
AAAInfo.xsd 246
auto-config.cfg 11
certificates
location 187
checkpoint configurations
location 187
configurations
location 187
copying 192
remote URL 192
decrypt.xsl 107
deleting 194
editing
during configuration 10
File Management utility 194
encrypt-soap.xsl 113
encrypt-wssec.xsl 109
encrypt.xsl 114
exported, location 187
fetching 192
managing 187
moving 193
not in export packages
firmware files 197
log files 197
pkcs7-decrypt.xsl 106
pkcs7-encrypt.xsl 104
pkcs7-sign.xsl 99
pkcs7-verify.xsl 102
private keys
location 187
renaming 193
SQL-Injection-Filter.xsl 44
SQL-Injection-Patterns.xml 44
TAM
ASCII configuration 251
creating configuration 252
modifying configuration 252
obfuscated configuration 251
SSL key 251
SSL stash 251
tibco.conf 345
uploading
JKS 191
remote 192
workstation 190
viewing
during configuration 10
File Management utility 194
Index
395
filter action
defining 117
purpose 89
replay filter 117
required elements filter 118
SQL injections, protection 44
standard filter 117
WS-Security message layout
filter 119
filter-accept-all.xsl style sheet 117
filter-reject-all.xsl style sheet 117
filtered configuration
filters
duration monitors 217
Firewall Credentials
configuring 23
creating 23
firmware files
between release levels 197
export packages 197
firmware images
location 187
flash drive
See directories
for-each
purpose 89
for-each action
defining for-each 119
use cases 119
Front Side Handler
FTP Poller 51
FTP Server 54
HTTP 65
HTTPS 66
IMS Connect 67
NFS Poller 68
object pages
MQ 83
TIBCO EMS 79
WebSphere JMS 81
SFTP Poller 71
SFTP Server 74
Stateful Raw XML 77
Stateless Raw XML 78
FTP client
command channel
encrypting 356
stopping encryption after
authentication 356
data (ASCII, binary) 356
encrypting file transfers 356
NAT compatibility 356
passive mode 356
sending command to server 356
unique file names (STOU, STOR) 356
user agent 356
FTP Poller
Front Side Handler 51
ftp protocol 146
FTP Server
396
G
general variables
listing 376
service/soap-fault-response
376
H
header injection policy, user agent 355
header retention policy, user agent 354
heartbeat detection, TIBCO 345
HMAC signatures
verifying 144
HTTP 1.0 restriction policy, user
agent 354
HTTP 1.1
chunked contents 355
Content-Length header 355
HTTP Front Side Handler 65
HTTP header
HTTP Header Injection
Multi-Protocol Gateway 301
HTTP header matching rule 87
HTTP Header Suppression
HTTP headers
Accept-Encoding, retaining 354
Authorization 352
Content-Length 355
MQMD, retaining 354
Range, retaining 354
request-header 350
SoapAction 352
TE, retaining 354
object pages
Input Encoding 264
Main 263
HTTP method matching rule 87
HTTP operations
resource extraction, AAA 169
HTTP Options
http protocol 146
HTTP proxy policy
securing with SSL proxy policy 351
user agent 351
HTTPS Front Side Handler 66
https protocol 146
I
IBM Tivoli Access Manager
See TAM
IBM Tivoli Federated Identity Manager
See TFIM
ICRX token 184
ID references
encrypt action 371
sign action 371
Identification Credentials
configuring 24
creating 24
identity extraction
AAA
BinarySecurityToken, WS-Security
Header 154
identity extraction, AAA
client IP address 157
connection peer
Token Subject DN, SSL 156
custom 159
extracted token
as cookie value 158
from message 158
HTTP Authentication Header 153
LTPA token 158
SAML artifact 157
SAML assertion
AuthenticationStatement 156
SPNEGO
Kerberos AP-REQ 156
subject DN
certificate in message
signature 157
SSL certificate 156
Identifier 154
WS-Security Header
Kerberos AP-REQ 155
UsernameToken, derived-key 154
UsernameToken,
password-carrying 153
WS-Trust
Base 155
Supporting 155
image: directory 187
Import Package
creating 196
IMS Connect 264
URL builder 46
IMS Connect Handler 67
ims protocol 146
imsssl protocol 146
Include Configuration File
creating 195
input context, actions 92
INPUT keyword 92
installation images
See firmware images
intellectual property 389
intermediary service provider,
SOAP 139
italics typeface 2
J
J2RE (j2re1.4.2) 191
j2re1.4.2 (J2RE) 191
j2sdk1.4.2 (SDK) 191
Java Crypto Extension
See SunJCE
Java Crypto Extension Key Store
See JCEKS
keywords (continued)
contexts (continued)
PIPE 93
Java Key Store

See JKS
Java Message Service
See JMS
java.security package 191
JCE
See SunJCE
JCEKS 191
JetStream Formats and Protocols
See JFAP
JKS
crypto extension 191
granting permissions 191
java.security package 191
keytool utility 191
managing 191
required software 191
uploading certificates 191
working with 191
K
KDC, Kerberos 255
Kerberos
AP-REQ message 255
configuring KDC server 257
KDC 255
keytab 255
principal 255
signature verification 144
Kerberos AP-REQ
SPNEGO 156
WS-Security Header 155
verify action 373
Kerberos AP-REQ tokens, remote
Kerberos KDC server
configuring 257
creating 257
object pages 257
Kerberos keytab
configuring 257
definition 255
Key Distribution Center
See KDC
Key objects
export packages 197
key-certificate pairs
creating 17
keys
converting 20
DER 17
exporting 19
generating 18
importing 20
PEM 17
PKCS #12 17
PKCS #7 17
supported formats 17
keywords
contexts
__JSONASJSONX 93
INPUT 92
NULL 93
OUTPUT 92
373
LDAP
authentication
credentials mapping
licensing
sending inquiries 389
links
Clone 13
Export 12
Show Probe 13
View Logs 12
View Status 12
load balancer group
adding members 278
basic configuration 277
creating 267, 276
health
convalescent (down) 274
healthy (up) 274
quarantined (softdown) 274
health checks
enabling 279
overriding port 277
health of members 274
members
assigning weight 281
disabling members 281
server state 267
Load Balancer Group
example
DataPower service 48
replacing back-end server 48
load balancer service variables
listing 378
service/lbhealth/ 378
load-balancing
TIBCO EMS 341, 343
local: directory 187
local/_extension/allow-compression
variable 385
local/_extension/donot-follow-redirect
variable 385
local/_extension/header/ variable 385
local/_extension/http-10-only
variable 386
local/_extension/prevent-persistentconnection variable 386
local/_extension/sslprofile variable 386
local/_extension/timeout variable 386
log action
defining 122
purpose 90
log files
export packages 197
log/soapversion variable 380

logging
post processing, AAA
access attempts 181
Logout button 7
logs
appliance-wide
location 188
audit
location 187
viewing 187
default
location 188
viewing configuration-specific
logs 12
viewing from catalog 12
viewing from configuration pane
logstore: directory 187
logtemp: directory 188
LTPA
adding user attributes, AAA
Policy 246
12
M
map message
TIBCO EMS 79
MapCredentials element, AAA Info
file 247
MapResource element, AAA Info
file 247
matching rules
defining 290
error code 87
HTTP header 87
HTTP method 87
URL 87
XPath 87
matching statements
deployment policy builder 209
deployment policy, manual 209
message catalogs 188
message layout filter, WS-Security 119
message monitors
configuring 211, 216
count monitors 214
duration monitors 216
filter action 213
message matching 212
message type 213
traffic definition 212
message tampering, protection 43
message transmission optimization
mechanism
See MTOM
messages
validating conformance 261
method rewrite action
defining 130
MMXDoS, protection 42
modified configuration
Modified configuration state 12
Index
397
monitors
See also message monitors
See also Web services monitors
managing 211
types 211
configuring 217
overview 217
monospaced typeface 2
MQ
URL builder 47
advanced configuration 85
basic configuration 83
configuration 83
properties and headers
configuration 85
publish and subscribe
configuration 84
MQ Get Message Options (GMO)
MQGET options 83
MQGMO_* 83
MQ header action
modifying
reply queue 125
reply queue manager 126
request message headers 124
response message headers 125
overview 123
retrieving responses
with correlation ID 124
with message ID 124
MQ Host variables
listing 378
service/correlation-identifier 379
service/expiry 379
service/format 379
service/message-identifier 379
service/message-type 379
service/mq-ccsi 378
service/mqmd-reply-to-q 379
service/mqmd-reply-to-qm 379
service/persistence 379
service/priority 379
service/reply-to-q 379
service/reply-to-qm 379
service/report 379
mq protocol 146
MQ Proxy variables
listing 378
service/expiry 379
service/format 379
service/mq-ccsi 378
service/report 379
MQ request messages
modifying message headers 124
specifying correlation ID 124
398
MQ request messages (continued)

specifying message ID 124
MQ response messages
modifying headers 125
modifying reply queue 125
modifying reply queue manager 126
MQMD header, retaining 354
MTOM policy
defining 290
configuring 35
configuring Multi-Protocol Gateway
objects 291
creating 36
creating Multi-Protocol Gateway
objects 291
HTTP Header Injection 301
HTTP Header Suppression 301
monitors 298
object pages
HTTP Options 300
Main 291
Proxy Settings 293
WS-Addressing 302
Parser Limits 299
service description 291
service variables
backend-timeout 377
skip-backside 377
Stylesheet Parameter 308
threat protection 41
WS-ReliableMpessaging 302
multistep variables
log/soapversion 380
multistep/loop-count service
variable 122
multistep/loop-iterator service
variable 122
N
namespace mappings, AAA Policy 245
NAS-identifier 322
NAT
FTP clients 356
navigation
Network menu 7
Objects menu 7
Services menu 7
Status menu 7
Netegrity
Network Address Translation
See NAT
Network menu 7
New configuration state 12
NFS
Poller Front Side Handler 68
NFS Poller Front Side Handler 68
node-set() extension function 366
notices 389
NSS Client
creating 369
NSS Client (continued)

overview 368
NULL keyword 93
O
object pages
AAA Policy
Authenticate 226
Authorize 235
Identity 224
LTPA Attributes 244
Map Credentials 233
Map Resource 235
Namespace Mapping 243
Post Processing 242
Resource 234
SAML Attributes 243
Transaction Priority 245
Crypto Certificate 21
Crypto Firewall Credentials 23
Crypto Identification Credentials
Crypto Key 25
Deployment Policy 208
Front Side Handler
MQ 83
TIBCO EMS 79
WebSphere JMS 81
Input Encoding 264
Main 263
Kerberos KDC server 257
HTTP Options 300
Main 291
Proxy Settings 293
WS-Addressing 302
Policy Parameters
Main 309
Policy Parameters 309
Processing Action
Main 309
Named Inputs 317
Named Outputs 318
Stylesheet Parameters 318
Processing Metadata
Main 318
Metadata Items 319
Processing Policy
Main 320
Policy Maps 320
Processing Rule 321
Main 323
Rules 324
SLM Action 327
SLM Credentials Class 326
SLM Resource Class 327
SLM Schedule 328
Main 329
SOAP Header Refine
Instruction 329
SSH Client Profile 29
SSL Proxy Profile 29
TAM 252
24
object pages (continued)

TFIM 253
TIBCO EMS 332
URL Rewrite Policy
Main 345
URL Rewrite Rule 346
WebSphere JMS server 359
XML Manager 366
objects
administrative state 12
configuration state 12
not in export packages
Certificate 197
Key 197
User 197
operational state 12
referenced
... button 8
+ button 8
creating 8
modifying 8
selecting 8
status 12
Objects menu 7
on-error
on-error action
defining 126
purpose 90
operational states, objects 12
output context, actions 92
OUTPUT keyword 92
P
padding oracle protection 43
Parser Limits
patents 389
peer group
defining 328
PEM
key format 17
persistent connections variables
listing 383
service/connection/note 383
PIPE keyword 93
PKCS #12
key format 17
PKCS #7
decrypting documents 106
encrypting documents 104
signing documents 99
verifying signed documents 102
PKCS #8
key format 17
pkcs7-decrypt.xsl file 106
pkcs7-encrypt.xsl file 104
pkcs7-sign.xsl file 99
pkcs7-verify.xsl file 102
Policy Decision Point
See XACML PDP
Policy Parameters
defining 308
object pages
Main 309
Policy Parameters 309
post processing, AAA
available activities 181
Count Monitors 180
custom style sheet 182
ICRX token 184
Kerberos AP-REQ 182
logging access attempts 181
LTPA 183
SAML assertion 182
SAML Assertion/Response 184
SPNEGO 183
TFIM 184
WS-Security UsernameToken 183
WS-Trust 182
z/OS identity propagation 184
principal, Kerberos 255
private key files
location 187
private keys
uploading 191
Processing Action
object pages
Main 309
Named Inputs 317
Named Outputs 318
Stylesheet Parameters 318
Processing Metadata
object pages
Main 318
Metadata Items 319
resource extraction, AAA 170
ssh-password-metadata 74
ssh/password variable 74
ssh/publickey variable 74
ssh/username variable 74
processing policies
contexts 92
creating 93
debugging 149
defining 87
matching rules 87
processing rules 88
Processing Policy
object pages
Main 320
Policy Maps 320
Processing Rule
object pages 321
processing rules
client-to-server 88
contexts 92
direction 88
error 88
matching rules 290
server-to-client 88
two way 88
protocol handler
quiesce 14
unquiesce 14
protocols
supported 146
Proxy Settings
pubcert validation credentials 32
pubcert: directory 188
publish
Q
query parameters
actions 147
queues
TIBCO EMS 78
WebSphere JMS 81
quiesce
protocol handler 14
service 14
R
RADIUS
NAS-identifier 322
purpose 322
Range header, retaining 354
referenced objects
... button 8
+ button 8
creating 8
modifying 8
selecting 8
referenced objects, lists
... button 9
+ button 9
Add button 9
adding 9
creating 9
Delete button 9
deleting 9
modifying 9
selecting 9
Rejected Counter Tool 180
replay filter 117
replay-filter.xsl style sheet 117
replica entry, [manager] stanza 252
request-header, HTTP 350
required-elements-filter.xsl style
sheet 118
resource extraction, AAA
HTTP operations 169
local name of request element 169
URI of top-level element 169
URL from client 169
URL to backend 168
XPath from request 169
resources mapping, AAA
AAA Info File 171
Index
399
resources mapping, AAA (continued)

custom 170
none 170
TAM 170
TFIM 170
XPath from resource extraction 171
restriction policy for HTTP 1.0, user
agent 354
results action
<url> element 148
defining 128
purpose 90
results asynchronous action
See results-async action
results-async
defining 129
results-async action
<url> element 148
purpose 90
rewrite header (rewrite) action
defining 130
rewrite header action
See also rewrite header action
purpose 90
rewrite method action
See also rewrite method action
purpose 90
RFC 2616 355
route action
overview 130
with style sheet 131
with variables 132
with XPath expression 131
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 131
with XPath expression 131
purpose 90
route-set action 146
defining 132
purpose 91
RSA signatures
verifying 144
400
S
S11:actor SOAP attribute 139
S11:mustUnderstand SOAP attribute 139
S12:mustUnderstand SOAP attribute 139
S12:notUnderstood SOAP attribute 139
S12:relay SOAP attribute 139
S12:role SOAP attribute 139
SAML assertion 184
authentication, AAA
artifact 164
valid signature 159
AuthenticationStatement 156
SAML assertions 373
AAA Policy
authentication 373
identity extraction 373
verify action 373
SAML attributes
defining, AAA Policy 245, 258
SAML server
authorization, AAA
attribute query 176
authorization query 175
Save Config button 7, 11
Saved configuration state 12
object pages
Main 323
Rules 324
schemas
location 188
SCP protocol
authentication policy, user agent 353
public keys 353
SDK (j2sdk1.4.2) 191
search parameters, LDAP 266
security certificates
shared
location 188
Web browsers
location 188
Security Token Reference
See STR
SecurityContextToken, WS-Trust
SecurityTokenReference element 372
server pool
See load balancer group
server state
load balancer group 267
server-to-client rule 88
service
quiesce 14
unquiesce 14
service level monitors
See SLM
service variables
listing 376
multistep/loop-count 122
multistep/loop-iterator 122
types 376
service/append-request-header/
variable 382
service/append-response-header/
variable 382
service/config-param/ variable 377
service/connection/note variable 383
service/correlation-identifier
variable 379
service/error-code variable 381
service/error-ignore variable 381
service/error-message variable 382
service/error-protocol-reason-phrase
variable 381
service/error-protocol-response
variable 381
service/error-subcode variable 382
service/expiry variable 379
service/format variable 379
service/lbhealth/ variable 378
service/max-call-depth variable 378
service/message-identifier variable 379
service/message-type variable 379
service/mq-ccsi variable 378
service/mqmd-reply-to-q variable 379
service/mqmd-reply-to-qm variable 379
service/persistence variable 379
service/priority variable 379
service/protocol-method variable 384
service/reply-to-q variable 377, 379
service/reply-to-qm variable 377, 379
service/report variable 379
service/routing-url variable 75, 383
service/routing-url-delay-content-typedetermination variable 384
service/routing-url-sslprofile
variable 384
service/set-request-header/ variable 382
service/set-response-header/
variable 382
service/soap-fault-response variable 376
service/soap-oneway-mep variable 380
service/strict-error-mode variable 382
service/transaction-key variable 380
service/transaction-name variable 380
service/transaction-timeout variable 380
service/URI variable 75, 384
service/wsa/genpattern variable 385
service/wsa/timeout variable 385
service/wsm/wsdl-error variable 385
service/wsm/wsdl-warning
variable 385
Services
Multi-Protocol Gateway Service 291
Services menu 7
set variable (setvar) action
defining 132
set variable action
See setvar action
set-target() extension function 131
setvar action
<url> element 148
defining 132
purpose 91
SFTP Poller
SFTP protocol
authentication policy, user agent 353
public keys 353
SFTP Server
SFTP Server Front Side Handler
AAA Policy 74
authentication 74
authorization 74
configuration considerations 74
metadata variables 74
routing 75
URI propagation 75
URL specifications 75
Shared Secret Key
configuring 28
creating 28
shared secrets 28
sharedcert: directory 188
Show Probe link 13
sign action
defining 133
confirmation 374
ID references 371
purpose 91
verifying signature confirmation 374
signature confirmation 373
SignatureConfirmation element 373
signatures
verifying 144
signed documents, PKCS #7
decrypting 106
encrypting 104
signing 99
verifying 102
skip-backside variable 377
SLM
overview 324
slm action
defining 135
purpose 91
SLM action
See slm action
SLM Action
creating 327
object pages 327
SLM Credentials Class
creating 326
object pages 326
SLM policy
adding statements 325
creating 325
creating SLM actions 327
SLM Policy
creating SLM Credentials Class
objects 326
creating SLM Resource Class
objects 327
creating SLM schedules 328
SLM Resource Class
creating 327
object pages 327
SLM Schedule
creating 328
object pages 328
SLM statements
adding to policy 325
overview 324
smtp protocol 146
SOAP attributes
S11:actor 139
S11:mustUnderstand 139
S12:mustUnderstand 139
S12:notUnderstood 139
S12:relay 139
S12:role 139
object pages
Main 329
SOAP Header Refine
Instruction 329
SOAP refinement transform 139
SOAP service provider type 139
soap-refine.xsll style sheet 139
SoapAction header 352
SPNEGO
Kerberos AP-REQ 156
sql action
defining 135
purpose 91
SQL action
See sql action
SQL Data Source
adding configuration parameters 332
base configuration 331
defining 330
high-level configuration 331
SQL injections, protection 44
sql protocol 146
SQL-Injection-Filter.xsl style sheet 44
SQL-Injection-Patterns.xml file 44
SSH
AAA Policy 74
authentication 74
authorization 74
client profile, creating 29
metadata variables 74
routing 75
streaming 74
timeout 74
URI propagation 75
URL specifications 75
SSH Client Profile
creating 29
object pages 29
ssh-password-metadata Processing
Metadata 74
ssh/password variable 74
ssh/publickey variable 74
ssh/username variable 74
SSL
client proxy, creating 30
forward proxy, creating 30
reverse, proxy, creating 30
server proxy, creating 30
two-way proxy, creating 31
SSL authentication 27
SSL proxy policy, user agent 351
SSL Proxy Profile

creating
client proxy 30
forward proxy 30
reverse proxy 30
server proxy 30
two-way proxy 31
object pages 29
ssl-keyfile-pwd entry, [ldap] stanza 252
Stateful Raw XML Handler 77
Stateless Raw XML Handler 78
statistics, enabling 219
Status menu 7
store: directory 188
STR dereference transform 372, 373
strip-attachments action
defining 136
purpose 91
style sheets
buffer-attachments.xsl 141
conformance-filter.xsl 119
conformance-xform.xsl 142
filter-accept-all.xsl 117
filter-reject-all.xsl 117
flushing the cache 368
location 188
replay-filter.xsl 117
required-elements-filter.xsl 118
soap-refine.xsl 139
wssecurity-message-layoutfilter.xsl 119
Stylesheet Parameter
subdirectories
creating 189
deleting 190
subscribe
SunJCE
JCEKS 191
symmetric signatures
verifying 144
system variables
listing 386
system/map/debug 386
system/tasktemplates/debug 386
system/map/debug variable 386
system/tasktemplates/debug
variable 386
T
TAM
ASCII configuration file 251
authorization server replicas 252
configuration, general 251
configuring TAM objects 252
creating configuration files 252
creating TAM objects 252
licensing 251
modifying configuration files 252
obfuscated configuration file 251
object pages 252
refreshing certificates 253
Index
401
TAM (continued)
security 251
SSL key file 251
SSL stash file 251
tasktemplates: directory 189
tcp protocol 146
tcps protocol 146
TE header, retaining 354
temporary: directory 189
TFIM
AAA 253
object pages 253
TFIM endpoint
WS-Trust messages 253
threat protection
denial-of-service
multiple message 42
single message 41
dictionary attack 45
message tampering 43
padding oracle protection 43
SQL injections 44
XML virus (X-Virus) 44
TIBCO EMS
fault-tolerant hosts 339, 343
heartbeat detection 345
load-balanced hosts 341, 343
map message 332
object pages 332
tibco.conf 345
transactional messaging 335
unique host 338
URL builder 46
TIBCO EMS Front Side Handler
map message 79
purpose 78
queues 78
support 78
topic spaces 78
TIBCO Rendezvous 78
TIBCO SmartSockets 78
tibco.conf file 345
Tivoli Access Manager
See TAM
topic spaces
TIBCO EMS 78
WebSphere JMS 81
trademarks 389
transaction headers variables
listing 382
service/append-request-header/ 382
service/append-responseheader/ 382
service/set-request-header/ 382
service/set-response-header/ 382
transaction logging 122
transaction routing variables
listing 383
service/routing-url 383
service/routing-url-delay-contenttype-determination 384
service/routing-url-sslprofile 384
transaction URL variables
listing 384
402
transaction URL variables (continued)

service/protocol-method 384
service/URI 384
transaction variables
listing 380
types 380
transform action
See also xform action
attachments
buffering 141
transform 141
defining conformance transform 142
transform 139
defining standard transform
non-XML messages 138
XML messages 137
overview 137
processing instruction-based
transform 138
SOAP messages
refinement transform 139
XML messages
conformance 142
defining 137
processing instruction-based 138
transform actions
MTOM policy 290
Transform binary action
See xformbin action
Transform using processing instruction
action
See xformpi action
two way rule 88
typeface conventions 2
U
ultimate service provider, SOAP 139
Undo button 11
unquiesce
protocol handler 14
service 14
up operational state 12
URL builder
IMS Connect 46
MQ 47
TIBCO EMS 46
WebSphere JMS 47
URL matching rule 87
URL Rewrite Policy
object pages
Main 345
URL Rewrite Rule 346
use cases
for-each action 119
User Agent
creating 350
default configuration 348
modifying basic configuation 350
overview 348
policies
allow-compression policy 353
basic authentication 348, 352
chunked upload 355
chunked uploads, HTTP 1.1 348
User Agent (continued)

policies (continued)
compression 348
compression policy 353
FTP client 348, 356
header injection 348, 355
header retention 348, 354
HTTP 1.0 restriction policy 354
HTTP proxy 348
HTTP proxy policy 351
public key authentication 348, 353
restriction, HTTP 1.0 348
SOAP action 352
SOAPAction 348
SSL proxy 348
SSL proxy policy 351
user authentication
RADIUS 322
User objects
export packages 197
UsernameToken
derived-key 154
utilities
keytool 191
V
validate action 142
message tampering, protection 43
purpose 92
validation credentials
non expiring, non-password-protected
certificates 32
pubcert 32
specific certificates 33
supported extensions 33
types 32
validation methods 32
variables
asynchronous
service/soap-oneway-mep 380
asynchronous transactions
listing 380
service/transaction-key 380
service/transaction-name 380
service/transaction-timeout 380
configuration service
listing 377
service/config-param/ 377
service/max-call-depth 378
error handling
listing 381
service/error-code 381
service/error-ignore 381
service/error-message 382
service/error-protocol-reasonphrase 381
service/error-protocolresponse 381
service/error-subcode 382
service/strict-error-mode 382
extension
listing 385
variables (continued)
extension (continued)
local/_extension/allowcompression 385
local/_extension/donot-followredirect 385
local/_extension/header/ 385
local/_extension/http-10-only 386
local/_extension/preventpersistent-connection 386
local/_extension/sslprofile 386
local/_extension/timeout 386
general
listing 376
service/soap-fault-response 376
list, all available 387
load balancer service
listing 378
service/lbhealth/ 378
MQ Host
listing 378
service/expiry 379
service/format 379
service/mq-ccsi 378
service/report 379
MQ Proxy
listing 378
service/expiry 379
service/format 379
service/mq-ccsi 378
service/report 379
backend-timeout 377
skip-backside 377
multistep
log/soapversion 380
persistent connections
listing 383
service/connection/note 383
service
listing 376
type 376
service/URI 75
ssh/password 74
ssh/publickey 74
ssh/username 74
variables (continued)
system
listing 386
system/map/debug 386
system/tasktemplates/debug 386
transaction
listing 380
type 380
transaction headers
listing 382
service/append-requestheader/ 382
service/append-responseheader/ 382
service/set-request-header/ 382
service/set-response-header/ 382
transaction routing
listing 383
service/routing-url-delay-contenttype-determination 384
service/routing-url-sslprofile 384
transaction URL
listing 384
service/protocol-method 384
service/URI 384
types 375
using 375
Web Service Proxy
backend-timeout 377
skip-backside 377
WSM
listing 384
service/wsa/genpattern 385
service/wsa/timeout 385
service/wsm/wsdl-error 385
service/wsm/wsdl-warning 385
verify action
adding 144
confirmation 374
Kerberos AP-REQ tokens, remote 373
purpose 92, 144
verifying signature confirmation 374
View button 9
View Logs link 12
View Status link 12
W
Web Management Interface 7
Web Service Proxy
defining policy parameters 308
service variables
backend-timeout 377
skip-backside 377
Web services monitors 298
configuring 217
overview 217
specifying dual thresholds 218
web-mgmt command 7
WebGUI
accessing 7
applying configuration changes 11
canceling changes 11
cloning services 13
common tasks 11
dashboard 7
deleting objects 12
Domain list 7
exporting objects 12
logging in 7
Logout button 7
Network menu 7
Objects menu 7
resetting configuration 11
reverting changes 11
Save Config button 7
saving configuration changes 11
Services menu 7
Status menu 7
viewing configuration-specific
logs 12
viewing object status 12
viewing probe data 13
Welcome screen 7
WebSphere Cell
purpose 357
WebSphere JMS
transactional messaging 359
URL builder 47
WebSphere JMS Front Side Handler
purpose 81
queues 81
support 81
topic spaces 81
WebSphere JMS server
object pages 359
WebSphere Transformation Extender
See WTX
Welcome screen 7
workstation
uploading files 190
WS-Addressing
WS-ReliableMessaging
WS-Security
message layout filter 119
WS-Security Header
UsernameToken, derived-key 154
UsernameToken,
WS-Security Management
See WSSM
WS-Trust
WS-Trust messages
TFIM endpoint 253
Index
403
WSM variables
listing 384
service/wsa/genpattern 385
service/wsa/timeout 385
service/wsm/wsdl-error 385
service/wsm/wsdl-warning 385
wssecurity-message-layout-filter.xsl style
sheet 119
WTX
DPA 314
Exported Files 314
input contexts 315
Mapping Logic Disabled 314
Named Inputs 317
Named Outputs 318
output contexts 315
xformbin action 138, 315
z/OS NSS authentication

z/OS NSS authorization
X
X-Virus, protection 44
X.509 certificates 372
AAA Policy
authentication 372
identity extraction 372
verify action 372
XACML PDP
configuring 259
XDoS, protection 41
xform
defining standard transform 137
XML messages 137
xform action
defining 137
transform 141
defining conformance transform 142
transform 139
purpose 91
xformbin action
defining 138
purpose 91
xformpi action
defining 138
purpose 91
XML Manager
caches
flushing the document cache 368
flushing the stylesheet cache 368
configuring 366
document cache, flushing 368
Load Balancer Group
DataPower service 48
modifying 366
object pages 366
XML virus, protection 44
XPath bindings
AAA Policy 245
XPath matching rule 87
Z
z/OS identity propagation
404
184

Printed in USA

MultiProtocolGatewayDevelopersGuide Xi50

Enviado por

Dados do documento

Título original

Direitos autorais

Formatos disponíveis

Compartilhar este documento

Compartilhar ou incorporar documento

Opções de compartilhamento

Você considera este documento útil?

Este conteúdo é inapropriado?

Direitos autorais:

Formatos disponíveis

MultiProtocolGatewayDevelopersGuide Xi50

Enviado por

Direitos autorais:

Formatos disponíveis

WebSphere DataPower Integration Appliance XI50

Multi-Protocol Gateway Developers

WebSphere DataPower Integration Appliance XI50

Multi-Protocol Gateway Developers

Third Edition (August 2011)

Defining Key objects . . . . . . .

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

Chapter 4. Securing communication . . 17

Chapter 5. Multi-Protocol Gateway

Chapter 3. Common WebGUI tasks. . . 11

Creating a Multi-Protocol Gateway service . .

Chapter 6. Handler configuration . . . 51

Configuring a stateful raw XML handler. . . . .

Chapter 7. Processing policies . . . . 87

Chapter 8. AAA Policy configuration

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

Chapter 9. Managing files . . . . . . 187

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

Chapter 10. Managing the

Chapter 11. Managing monitors. . . . 211

Appendix A. Referenced objects . . . 221

Using SAML attributes for post processing . .

Defining peer groups . . . . . . . .

Flushing the document cache

Appendix B. Cryptographic support in

Appendix C. Working with variables

Notices and trademarks . . . . . . . 389

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

File naming guidelines

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

Object naming guidelines

Identifies commands, programming keywords, and GUI controls.

Identifies words and phrases used for emphasis and user-supplied

Purpose of Multi-Protocol Gateway services

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

Support for Web 2.0 configurations

REST principals in Web 2.0

POST Creates a resource

Modifies or creates a resource

Allows you to specify an HTTP method and

Allows you to rewrite an HTTP method to

REST proxy deployment scenario

little message transformation.

Figure 1. DataPower appliance as a proxy

REST bridge deployment scenario

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

Figure 2. A DataPower appliance as a bridge

Web 2.0 and JSON

JSON can be specified in any of the following configuration options:

v The response type of Multi-Protocol Gateway or of XML Firewall services

In all of these cases, when a DataPower service or processing action processes a

In Multi-Protocol Gateway or in XML Firewall services, you can specify JSON as

JSON deployment scenario

Figure 3. A DataPower appliance using JSON and JSONx

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

Chapter 2. WebGUI basics

Objects on the appliance

Working with objects

Accessing the WebGUI

Copyright IBM Corp. 2002, 2011

This screen is separated into the following areas:

Common WebGUI conventions

Working with referenced objects