You are on page 1of 186

WebSphere DataPower SOA Appliances

Version 3.7.3

Web Application Firewall Developers Guide



WebSphere DataPower SOA Appliances

Version 3.7.3

Web Application Firewall Developers Guide



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

First Edition (May 2009)


This edition applies to version 3, release 7, modification 3 of IBM WebSphere DataPower SOA Appliances and to all
subsequent releases and modifications until otherwise indicated in new editions.
Copyright International Business Machines Corporation 2002, 2009.
US Government Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract
with IBM Corp.

Contents
Preface . . . . . . . . . . . . . . . v
Who should read this document . . . . . . . . v
How this document is organized . . . . . . . v
Publications . . . . . . . . . . . . . . vi
Installation and upgrade documentation . . . . vi
Administration documentation . . . . . . . vi
Development documentation . . . . . . . vii
Reference documentation. . . . . . . . . vii
Integration documentation . . . . . . . . vii
Problem determination documentation . . . . viii
Supplemental documentation . . . . . . . viii
File naming guidelines . . . . . . . . . . viii
Object naming guidelines . . . . . . . . . . ix
Typeface conventions . . . . . . . . . . . ix

Chapter 1. WebGUI basics . . . . . . . 1


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

Chapter 2. Securing communication


Supported cryptographic formats . . . .
Working with keys and certificates . . . .
Creating key-certificate pairs . . . . .
Generating keys and certificates . . .
Exporting keys and certificates . . . .
Importing keys and certificates . . . .
Defining Certificate objects . . . . . .
Defining Firewall Credentials objects . . .
Defining Identification Credentials objects .
Defining Key objects . . . . . . . .
Defining Profile objects . . . . . . .
Defining Shared Secret Key objects . . .
Defining SSL Proxy Profile objects . . . .
Creating a forward (or client) proxy . .
Creating a reverse (or server) proxy . .
Creating a two-way proxy . . . . .
Working with Validation Credentials objects
Copyright IBM Corp. 2002, 2009

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

1
1
1
1
2
2
3
3
4
4
4
4
4
5
5
5
5
6
6
7

. . 9
.
.
.

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

.
.
.
.
.
.
.

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

. 9
. 9
. 9
. 10
. 11
. 12
. 13
. 14
. 15
. 16
. 17
. 18
. 19
. 19
. 19
. 20
. 21

Creating for non-expiring, non-passwordprotected certificates . . . . . . . .


Creating for select certificates . . . . .

.
.

. 21
. 21

Chapter 3. Configuring Web Application


Firewall services . . . . . . . . . . 25
Scenarios . . . . . . . . . . . .
Scenario one: College enrollment form .
Scenario two: Benefits management site .
Scenario three: Trading site . . . . .
Configuring a Web Application Firewall . .
General configuration . . . . . . .
Timeout/Protocol . . . . . . . .
Configuring an Application Security Policy .
General configuration . . . . . . .
Request Maps . . . . . . . . .
Response Maps . . . . . . . . .
Error Maps . . . . . . . . . .

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

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

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

25
25
26
26
27
27
29
30
30
30
31
31

Chapter 4. Managing files. . . . . . . 33


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

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

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

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

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

33
35
35
35
36
36
36
37
37
37
37
37
38
38
39
39
40
40
40

Chapter 5. Managing the configuration


of the appliance . . . . . . . . . . . 41
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 to
allow . . . . . . . . . . . . . .
Saving configuration checkpoints . . . . .
Listing configuration checkpoints . . . . .
Rolling back to a configuration checkpoint . .

.
.
.
.
.
.
.
.

41
42
43
44
44
45
47
48

.
.
.
.

48
49
49
50

iii

Deleting configuration checkpoints .


Importing configuration data . . . .
Managing changes in configuration data.
Comparing configurations . . . .
Reading the change report . . . .
Reverting changes . . . . . . .
Configuring deployment policies . . .
Creating a Deployment Policy object .
Using the deployment policy builder .
Specifying the matching statement. .

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

50
50
52
52
53
53
54
54
55
56

Appendix A. Referenced objects. . . . 57


AAA Policy . . . . . . . . . . . . .
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 mappings (XPath bindings)
Defining SAML attributes . . . . . . .
Adding LTPA user attributes . . . . . .
Using an AAA Info file . . . . . . . .
IBM Tivoli Access Manager . . . . . . .
IBM Tivoli Federated Identity Manager . . .
Working with Kerberos objects . . . . . .
XACML Policy Decision Point . . . . . .
Application Security Policy . . . . . . . .
Request Maps tab . . . . . . . . . .
Response Maps tab . . . . . . . . . .
Error Maps tab . . . . . . . . . . .
Count Monitor . . . . . . . . . . . .
Error Policy . . . . . . . . . . . . .
Defining an LDAP Search Parameters object . .
Load Balancer Group . . . . . . . . . .
Health of member servers . . . . . . .
Setting the health state with a variable . . .
Configuring Load Balancer Group objects . .
Matching Rule . . . . . . . . . . . .
Name-Value Profile . . . . . . . . . .
Validation List tab . . . . . . . . . .
Processing Rule. . . . . . . . . . . .
Rate Limiter . . . . . . . . . . . . .
Session Management Policy . . . . . . .
URL Rewrite Policy . . . . . . . . . .
URL Rewrite Rule tab . . . . . . . .
User Agent . . . . . . . . . . . . .
Proxy Policy . . . . . . . . . . . .
SSL Proxy Profile . . . . . . . . . .
Basic HTTP Authentication . . . . . . .
SOAP Action Policy . . . . . . . . .
Public Key Authentication Policy . . . . .
Allow Compression Policy . . . . . . .
Restrict to HTTP 1.0 Policy . . . . . . .

iv

. 57
. 57
. 60
. 62
. 68
. 69
. 70
. 71
. 77
. 80
. 81
. 81
. 82
. 82
. 82
. 83
. 83
. 88
. 90
. 92
. 95
. 97
. 98
. 98
. 99
. 99
. 99
. 100
. 101
. 101
. 102
. 102
. 106
. 108
. 110
. 111
. 112
. 113
. 114
. 114
. 117
. 118
. 118
. 119
. 120
. 120
. 121
. 122

Inject Header Policy . . . .


Chunked Uploads Policy . .
FTP Client Policies . . . .
Web Application Firewall . . .
Proxy Settings tab . . . . .
HTTP Options tab . . . . .
Source Addresses tab . . . .
Web Request Profile . . . . .
Profile tab . . . . . . .
Methods & Versions tab . . .
Processing tab . . . . . .
Name Value tab . . . . .
Cookie tab . . . . . . .
Multipart Form tab . . . .
Threat Protection tab . . . .
Web Response Profile. . . . .
Profile tab . . . . . . .
Codes & Versions tab. . . .
Processing tab . . . . . .
Name Value tab . . . . .
Threat Protection tab . . . .
XML Manager . . . . . . .
Configure XML Manager objects
Flushing the document cache .
Flushing the stylesheet cache .
z/OS NSS Client . . . . . .
Creating the z/OS NSS Client .

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

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

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

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

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

Appendix B. Working with variables

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

122
123
124
127
129
130
131
132
133
134
134
135
136
137
138
139
140
140
140
141
142
142
143
143
143
144
145

147

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

148
148
148
149
150
150
151
152
152
153
154
154
155
155
156
156
158
159

Appendix C. Getting help and


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

.
.
.

.
.
.

.
.
.

.
.
.

.
.
.

.
.
.

.
.
.

. 161
. 161
. 162

Notices and trademarks . . . . . . . 163


Trademarks .

. 163

Index . . . . . . . . . . . . . . . 165

IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

Preface
IBM WebSphere DataPower SOA Appliances are purpose-built, easy-to-deploy
network appliances that simplify, help secure, and accelerate your XML and Web
Services deployments while extending your SOA infrastructure. These appliances
offer an innovative, pragmatic approach to harness the power of SOA while
simultaneously enabling you to leverage the value of your existing application,
security, and networking infrastructure investments.

Who should read this document


This document is intended for developers who manage the configuration of Web
Application Firewall services, objects, and associated referenced objects on the
DataPower appliance. Developers should have the following knowledge:
v Network architecture and concepts
v Internet protocols, including HTTP, TCP/IP
v Lightweight Directory Access Protocol (LDAP) and directory services
v Authentication and authorization
v XML and XSLT
Developers should also be familiar with SSL protocol, key exchange (public and
private), digital signatures, cryptographic algorithms, and certificate authorities.
This document assumes that an Administrator has installed and initially
configured the appliance as described in the IBM WebSphere DataPower SOA
Appliances: 9003: Installation Guide or in the IBM WebSphere DataPower SOA
Appliances: Type 9235: Installation Guide, depending on the model type.

How this document is organized


This document is organized across the following broad concepts:
v Chapter 1, WebGUI basics, on page 1
Provides basic informations about using the DataPower graphical interface,
which is referred to as the WebGUI, as well as information about performing
common tasks in the WebGUI.
v Chapter 2, Securing communication, on page 9
Provide information about securing communication to and from the DataPower
appliance. The appliance provide these capabilities with a combination of
utilities and objects.
v Chapter 3, Configuring Web Application Firewall services, on page 25
Provide detailed information about developing Web Application Firewall
services on a DataPower appliance.
v Chapter 4, Managing files, on page 33
Provides information about managing files on the appliance.
v Chapter 5, Managing the configuration of the appliance, on page 41
Provide information about managing the configuration of application domains
and importing and exporting configurations.
v Appendix A, Referenced objects, on page 57
Copyright IBM Corp. 2002, 2009

Provides detailed information about configuring objects that are referenced while
developing services on a DataPower appliance.
v Appendix B, Working with variables, on page 147
Provides information about using variables in document processing.
v Appendix C, Getting help and technical assistance
Provides details about contacting IBM Support.

Publications
The IBM WebSphere DataPower library is organized into the following categories:
v Installation and upgrade documentation
v Administration documentation
v Development documentation on page vii
v
v
v
v

Reference documentation on page vii


Integration documentation on page vii
Problem determination documentation on page viii
Supplemental documentation on page viii

Installation and upgrade documentation


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

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

vi

IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

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

Reference documentation
v Product-specific documentation for using commands from the command line.
The documentation is specific to each of the following products. Each document
provides an alphabetical listing of all commands with syntactical and functional
descriptions.
IBM WebSphere DataPower XML Accelerator XA35: Command Reference
IBM WebSphere DataPower XML Security Gateway XS40: Command Reference
IBM WebSphere DataPower XML Integration Appliance XI50: Command Reference
IBM WebSphere DataPower B2B Appliance XB60: Command Reference
IBM WebSphere DataPower Low Latency Messaging Appliance XM70: Command
Reference
v IBM WebSphere DataPower SOA Appliances: Extension Elements and Functions
Catalog
Provides programming information about the usage of DataPower XSLT
extension elements and extension functions.

Integration documentation
The following documents are available for managing the integration of related
products that can be associated with the DataPower appliance:
v Integrating with ITCAM
Provides concepts for integrating the DataPower appliance with IBM Tivoli
Composite Application Management for SOA.
v IBM WebSphere DataPower SOA Appliances: Integrating with WebSphere
Transformation Extender
Preface

vii

Provides concepts for integrating the DataPower appliance with WebSphere


Transformer Extender.
v IBM WebSphere DataPower SOA Appliances: Integrating with WebSphere MQ
Explains the concepts and common use patterns for connecting DataPower
services to WebSphere MQ systems.

Problem determination documentation


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

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

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)

viii

IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

v - (dash)
v . (period)
Note: Names cannot contain two consecutive periods (..).

Object naming guidelines


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

Typeface conventions
The following typeface conventions are used in the documentation:
bold

Identifies commands, programming keywords, and GUI controls.

italics

Identifies words and phrases used for emphasis and user-supplied


variables.

monospaced
Identifies user-supplied input or computer output.

Preface

ix

IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

Chapter 1. WebGUI basics


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

Objects on the appliance


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

Working with objects


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

Accessing the WebGUI


To use the WebGUI, the Web Management Interface must be configured. This
interface was defined during the initial firmware setup (during appliance
installation) or afterward with the web-mgmt command.
To access the WebGUI, use the following procedure:
1. Direct your browser to the WebGUI login screen. Use the IP address and port
number assigned during the configuration of the Web Management interface.
The address uses the HTTPS protocol and has the https://address:port
format.
2. In the login fields, specify an account name and password.
3. From the Domain list, select the domain to which to log in.
4. Click Login.
After verifying credentials, the WebGUI displays the Control Panel.

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

Copyright IBM Corp. 2002, 2009

This screen is separated into the following areas:


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

Common WebGUI conventions


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

Working with referenced objects


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

Figure 1. Input field for referenced objects

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

IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

v Use the + button to create a new referenced object. When created, the input field
contains the name of the newly created referenced object.
v Use the ... button to modify the referenced object whose name is in the input
field. When modified, the input field retains the name of the referenced object.
When you click the + button or ... button, the WebGUI launches a new window
that displays the configuration screen for that type of object.

Working with lists of referenced objects


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

Figure 2. Input list for referenced objects

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

Viewing and editing local files during configuration


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

Chapter 1. WebGUI basics

Viewing local files


To
1.
2.
3.

view a local file, use the following procedure:


Select the file from the lists.
Click View to open the file editor in view mode.
Review the file.

4. Click Cancel.

Editing local files


The edited file overwrites the original file.
To edit a local file, use the following procedure:
1.
2.
3.
4.
5.

Select the file from the lists.


Click Edit to open the file editor in edit mode.
Edit the file as required.
Click Submit to save changes.
Click Close.

Common WebGUI tasks


The majority of objects provide the following common tasks. Not all of these tasks
are available to all objects.
v Applying and saving configuration changes
v Canceling changes before saving to the running configuration
v Resetting changes to an object
v
v
v
v
v
v

Deleting an object
Exporting the configuration of an object
Viewing object-specific logs
Viewing object status
Cloning a service
Accessing probe captures

Applying and saving changes


As you use the WebGUI to manage object and service configurations, click Apply
to save these changes to the running configuration. Changes that are made to the
running configuration take effect immediately, but are not persisted to the startup
configuration. During an appliance restart these changes are lost.
To retain applied changes across an appliance restart, click Save Config. The
changes are saved to the startup configuration. The startup or persistent
configuration is persisted across an appliance restart. By default, the appliance
reads the startup configuration from the auto-config.cfg file.

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

IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

Resetting objects
Independent of whether the settings are saved to the configuration, you can reset
an object to its default configuration.
Use the following procedure to revert changes to a specific object:
1. Display the catalog for the object. The catalog lists the available instances of
this object.
2. Click the name of the object for which to reset to display the configuration
screen.
3. Click Undo.
4. Follow the prompts.

Deleting objects
You might want to delete objects that are no longer needed. If no other object
depends on the object to be deleted, you can delete it at any time. Because a
DataPower service is a top-level object, you can delete it at any time. Conversely,
you cannot delete an object that is active and that is in use by a higher-level object.
Use the following procedure to delete an object:
1. Display the catalog for the object. The catalog lists the available instances of
this object.
2. Click the name of the object to delete to display the configuration screen.
3. Click Delete.
4. Follow the prompts.
Deleting an object deletes that object only. Deleting an object does not delete any
referenced object.

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

Viewing object-specific logs


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

Viewing log files from the catalog


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

Viewing log files from the configuration screen


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

Chapter 1. WebGUI basics

Viewing object status


You can view the status of an object and all its referenced objects to help determine
why a configuration object is in a down state. When you view the object status, the
WebGUI opens a new window. This window provides the ability to show or hide
unused properties.
v To show the unused properties, click Show.
v If the display lists unused properties, click Hide to hide these properties. Hiding
unused properties is the default behavior.
When viewing the object status, the window provides the following information:
v The name of the instance and its type with a control to collapse (hide) or expand
(show) referenced objects
v Its configuration state: New, Modified, or Saved
v It operational state: up or down
v Its administrative state: enabled or disabled
v Details about the detected error, if applicable
v A link (magnifying glass icon) to view the logs for this object
Use the following procedure to view the status for an object:
1. Display the catalog for the object. The catalog lists the available instances of
this object.
2. Click the name of the object to view to display the configuration screen.
3. Click View Status.

Cloning services
You might want to create a service that is similar to an existing service. For
example, you need two equivalent services, but each service communicates with a
different remote server. In these cases, you can create a clone of an existing service
and edit the clone. The cloning process can expedite the creation of a similar
service.
Use the following procedure to clone a server:
1. Display the catalog for the service. The catalog lists the available instances of
this service.
2. Click the name of the service to clone to display the configuration screen.
3. Click Clone.
4. When the screen refreshes, specify the name of the clone.
5. Specify the Ethernet interface that the service monitors for incoming client
requests in the Device Address field. Use the default address (0.0.0.0) to specify
all interfaces.
6. Specify the Ethernet port that the service monitors for incoming client requests
in the Device Port field.
7. As necessary, edit the other properties.
8. Click Apply to save the object to the running configuration.
9. Optionally, click Save Config to save the object to the startup configuration.

IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

Accessing probe captures


After enabling the probe, defining the triggers, and sending transactions that
match the conditions defined by the triggers, you can view the captured
transactions.
Use the following procedure to access probe captures:
1. Display the catalog for the service object. The catalog lists the available
instances of this object.
2. Click the name of the service for which to view the probe captures to display
the configuration screen.
3. Click Show Probe.
4. Click the magnifying glass icon to view details about that captured
transactions.
For complete details about using the probe, refer to the IBM WebSphere DataPower
SOA Appliances: Problem Determination Guide.

Chapter 1. WebGUI basics

IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

Chapter 2. Securing communication


This chapter provide information about securing communication to and from the
DataPower appliance. The appliance provide these capabilities with a combination
of utilities and objects.

Supported cryptographic formats


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

Working with keys and certificates


The DataPower appliance provides actions that allow you to work with keys and
certificates. With the provided cryptographic tools, you can perform the following
actions:
v Create key-certificate pairs
v Generate keys and certificates
v Export keys and certificates
v Import keys and certificates
Unless you are using an appliance with HSM hardware, you cannot export or
import keys. For details about using an HSM-enabled appliance, refer to the IBM
WebSphere DataPower SOA Appliances: Hardware Security Module Guide.

Creating key-certificate pairs


When you generate a key, you get a key file and a Certificate Signing Request
(CSR) file. The CSR file from the initial key generation is not a signed certificate.
Send the CSR to a Certificate Authority (CA), such as VeriSign. The CA signs the
CSR and returns it to you, which effectively creates the certificate. Load this
certificate on the box.
In other words, use the following procedure to create the key-certificate pair:
1. Use the Crypto Tool to create the key and CSR
2. Store the private key on the box and create a Key object that references it.
3. Send the CSR to VeriSign. Do not store it on the box (except in the temporary:
directory).
Copyright IBM Corp. 2002, 2009

4. VeriSign returns the signed certificate.


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

Generating keys and certificates


You can generate a private cryptographic key and optionally a self-signed
certificate from the Crypto Tools page. The Certificate Signing Request (CSR)
needed by a certificate authority (CA) is created by default.
If the file is stored in the cert: directory, it cannot be deleted or edited. If a file is
stored in the local: directory or in the temporary: directory, it can be deleted and
edited.
To generate a key, use the following procedure:
1. Select Administration Miscellaneous Crypto Tools to display the
Generate Key page.
2. Define the LDAP entry.
a. Use the LDAP (reverse) Order of RDNs toggle to indicate whether to
create the LDAP entry in reverse RDN order.
on
b.
c.
d.
e.

Creates the entry in reverse RDN order.

off
(Default) Create the entry in forward RDN order.
Optionally specify a country name in the Country Name (C) field.
Optionally specify a state or province name in the State or Province (ST)
field.
Optionally specify a locality name in the Locality (L) field.
Optionally specify the name of an organization in the Organization (O)
field.

f. Optionally specify the name of an organizational unit in the Organizational


Unit (OU) field.
g. Optionally specify the names of additional organizational units in the
Organizational Unit 2 (OU), Organizational Unit 3 (OU), and
Organizational Unit 4 (OU) fields.
3.
4.

5.
6.

h. Specify a common name in the Common Name (CN) field.


Select a key length from the RSA Key Length list. This defaults to 1024.
Specify the name of the key file to generate in the File Name field. The value
takes the directory:///name form. Leave blank to allow the action to create
the name.
Specify the number of days that the key is valid in the Validity Period field.
Specify a password to access the key file in the Password field. The password
must be at least 6 characters in length.

7. Specify a password alias to access the key file in the Password Alias field.
8. Use the Export Private Key toggle to indicate whether the action writes the
key file to the temporary: directory.

10

on

Writes the key file to the temporary: directory.

off

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

IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

9. Use the Generate Self-Signed Certificate toggle to indicate whether the action
creates a self-signed certificate that matches the key.
on

(Default) Creates a self-signed certificate.

off
Does not create a self-signed certificate.
10. Use the Export Self-Signed Certificate toggle to indicate whether the action
writes the self-signed certificate to the temporary: directory.
on

(Default) Writes the self-signed certificate to the temporary: directory.

off
Does not write the self-signed certificate to the temporary: directory.
11. Use the Generate Key and Certificate Objects toggle to indicate whether the
action automatically creates the objects from the generated files.
on

(Default) Creates the objects from the generated files.

off
Does not create the objects from the generated files.
12. Specify the name for the Key and Certificate objects in the Object Name field.
Leave blank to allow the action to generate the names from from the input
information (based on the Common Name (CN) or File Name property).
13. Specify the name of an existing Key object in the Using Existing Key Object
field. If supplied and valid, the action generates a new certificate and a new
Certificate Signing Request (CSR) that is based on the key in the identified
Key object. In this case, the appliance does not generate a new key.
14. Click Generate Key to generate a private key and, if requested, a self-signed
certificate. A CSR is created automatically.
15. Follow the prompts.
The CSR can be submitted to a certificate authority (CA) to receive a certificate that
is based on this private key. This action creates the following files and objects:
v Creates the private key file in the cert: directory; for example,
cert:///sample-privkey.pem
v Creates the CSR in the temporary: directory; for example, temporary:///
sample.csr
v If Generate Self-Signed Certificate is enabled, creates a self-signed certificate in
the cert: directory; for example, cert:///sample-sscert.pem
v If Export Self-Signed Certificate is enabled, creates a copy of the self-signed
certificate in the temporary: directory; for example, temporary:///samplesscert.pem
v If Generate Key and Certificate Objects is enabled, creates a Key object and a
Certificate object
If the action creates a self-signed certificate, you can use this certificate-key pair for
the following purposes:
v Establish Identification Credentials
v Encrypt or decrypt XML documents

Exporting keys and certificates


Use the Export Crypto Objects tab of the Crypto Tools screen to export key and
certificate objects.
Note: If the appliance has HSM hardware, you can export Key objects. For details,
refer to IBM WebSphere DataPower SOA Appliances: Hardware Security Module
Guide.
Chapter 2. Securing communication

11

1. Select Administration Miscellaneous Crypto Tools to display the Crypto


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

Importing keys and certificates


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

12

IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

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

Defining Certificate objects


A Certificate object that provides an added layer of security by supplying a
indirect reference (or alias) to a certificate file. The alias provided by the Certificate
object is later used in the creation of a Firewall Credentials, an Identification
Credentials, or a Validation Credentials.
To create and configure a Certificate, use the following procedure:
1. Select Objects Crypto Crypto Certificate.
2. Click Add.
3. Provide the following inputs:
Name
Specify the name of the object.
Admin State
Retain the default setting. To place the object in an inactive administrative
state, click disabled.
File Name
Access a list of files, contained in the cert: or pubcert: file repository, and
select the file that contains the certificate referenced by this Certificate
object.
You can click Upload or Fetch to transfer the file.
You can also click Details to display information about the selected
certificate file.
Password
Depending of business security policies, provide one of the following:
v If local security policies provide for password-protected keys, specify
the password (or a password alias).
v If local polices do not support password protection, leave blank.
v If key files are protected by a plaintext password, specify the password.
Note: Plaintext passwords appear as such in the configuration script.
v If key files are protected by an aliased password, specify the alias.
The CLI provides a password-map command that uses a
locally-generated key to 3DES encrypt a password used to access a
private key file. The command maps the encrypted password to a
password alias in a password map file. The password map and the
locally-generated key are saved to separate files on the appliance.
Plaintext passwords are not stored in memory or saved on the appliance.

Chapter 2. Securing communication

13

Password Alias
Use the toggle to specify if the text entered in the Password field is a
plaintext password or a password alias.
on

Identifies the text as a password alias for an encrypted password.

off

(Default) Identifies the text as a plaintext password.

Ignore Expiration Dates


Use these toggle to allow the creation of a certificate prior to its activation
date (the NotBefore value in the certificate) or after its expiration date (the
NotAfter value in the certificate).
off

(Default) Prevents the creation of certificates outside of their


internal expiration values.

on

Creates the certificate and places it in the up state. Although the


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

In other words, the certificate itself is in the up state, but


Validation Credentials, Firewall Credentials, or Identification
Credentials that references the certificate adhere to the internal
expiration values. If the certificate is used for a certificate chain
validation from a Validation Credentials and the certificate is not
valid, validation fails. Similarly, if the certificate is used from an
Identification Credentials, the DataPower appliance sends the
certificate to the SSL peer for an SSL connection, but the peer can
reject the certificate as not valid.
4. Click Apply to save the object to the running configuration and return to the
object catalog.
5. Optionally, click Save Config to save the object to the startup configuration.

Defining Firewall Credentials objects


A Firewall Credentials consists of a list of Key objects and Certificate objects. A
Firewall Credentials provides a list of Key objects and Certificate objects.
Certificates and keys not referenced in the Firewall Credentials are unavailable. If
no Firewall Credentials exist, all keys and certificates stored locally are available.
To create a Firewall Credentials, use the following procedure:
1. Select Objects Crypto Crypto Firewall Credentials to display the Crypto
Firewall Credentials catalog.
2. Click Add to display the Crypto Firewall Credentials Configuration screen.
3. Provide the following inputs:
Name
Specify the name of the object.
Admin State
Retain the default setting. To place the object in an inactive administrative
state, click disabled.
Private Key
Use the list to add Key objects to the Firewall Credentials. Refer to
Defining Key objects on page 16 for more information.

14

IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

Shared Secret Key


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

Defining Identification Credentials objects


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

15

Defining Key objects


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

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


Select Objects Crypto Crypto Key to display the Crypto Key catalog.
Click Add to display the Crypto Key Configuration screen.
Provide the following inputs:
Name
Specify the name of the object.
Admin State
Retain the default setting. To place the object in an inactive administrative
state, click disabled.
File Name
Access a list of files (contained in the cert: file repository) and select the
file that contains the private key aliased by this Key object.
You can click Upload or Fetch to transfer the file.
Note: Keys can be retrieved from a Java Key Store residing on the local
workstation. Click Java Key Store on the Upload field. Refer to
IBM WebSphere DataPower SOA Appliances: Appliance Overview for
more information.
Password
Depending on business security policies, provide one of the following:
v If local security policies provide for password-protected keys, specify
the password (or a password alias).
v If local polices do not support password protection, leave blank.
v If key files are protected by a plaintext password, specify the password.
Note: Plaintext passwords appear as such in the configuration script.
v If key files are protected by an aliased password, specify the alias.
The CLI provides a password-map command that uses a locally-generated
key to 3DES encrypt a password used to access a private key file. The
command maps the encrypted password to a password alias in a
password map file. The password map and the locally-generated key are
saved to separate files on the appliance. Plaintext passwords are not
stored in memory or saved on the appliance.
Password Alias
Use the toggle to specify if the text entered in the Password field is a
plaintext password or a password alias.
on

Identifies the text as a password alias for an encrypted password.

off

(Default) Identifies the text as a plaintext password.

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


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

16

IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

Defining Profile objects


A Profile object identifies a collection of SSL resources that support SSL
connections with remote peer appliances.
To create and configure a Profile object, use the following procedure:
1. Select Objects Crypto Crypto Profile to display the catalog.
2. Click Add to display the configuration screen.
3. Provide the following inputs:
Name
Specify the name of the object.
Admin State
Retain the default setting. To place the object in an inactive administrative
state, click disabled.
Identification Credentials
Select the Identification Credentials to assign to this Profile object, or
retain the default value, none, when no Identification Credentials is
needed.
The Identification Credentials provides the PKI certificate-key pair that
will be used to authenticate the appliance during the SSL handshake.
Refer to Defining Identification Credentials objects on page 15 for more
information.
Validation Credentials
Select the Validation Credentials for this Profile object, or retain the
default value, none, when no Validation Credentials is needed. Refer to
Working with Validation Credentials objects on page 21 for more
information.
Ciphers
Use the field to identify the symmetric key-encryption algorithms for this
Profile object. Common cipher values are as follows:
ALL

Includes all cipher suites, except the eNULL ciphers.

DEFAULT
Includes all cipher suites, except for the following ciphers and
cipher suites:
v eNULL ciphers
v Cipher suites that use DH authentication
v Cipher suites that contain the RC4, RSA, and SSL version 2
ciphers
HIGH Includes all high encryption cipher suites. These ciphers
support a key length in excess of 128 bits.
MEDIUM
Includes all medium encryption cipher suites. These ciphers
support a key length of 128 bits.
LOW

Includes all low encryption cipher suites. These ciphers support


a key length of 56 or 64 bits, but exclude EXPORT cipher suites.

EXPORT
Includes all cipher suites that support a key length of 40 or 56 bits
and are eligible for export outside of the United States.
Chapter 2. Securing communication

17

For a detailed list of ciphers, refer to the profile command in the


product-specific version of the Command Reference.
Options
Use the check boxes to disable support for SSL versions and variants. By
default, SSL Version 2, SSL Version 3, and Transaction Level Security
(TLS) Version 1 are enabled.
v To disable SSL Versions 2, click Disable-SSLv2.
v To disable SSL Version 3, click Disable-SSLv3.
v To disable TLS Version 1, click Disable-TLSv1.
Send Client CA List
Use the toggle to enable the transmission of a Client CA List during the
SSL handshake.
Note: Transmission of a Client CA List is meaningful only when this
Profile object supports a reverse (or server) proxy and when this
Profile object has an assigned Validation Credentials.
on

Enables transmission of a Client CA List.

off

(Default) Disables transmission of a Client CA List.

A Client CA List consists of a listing of the CA certificates in the


Validation Credentials for this Profile object. A Client CA List can be sent
by an SSL server as part of the request for a client certificate. The Client
CA list provides the client with a list of approved CAs whose signatures
are acceptable for authentication purposes.
Note: SSL servers are not required by the protocol to send a Client CA
List. Generally, SSL servers do not send a Client CA list.
Some implementations or local policies, however, might mandate
the use of Client CA lists.
4. Click Apply to save the object to the running configuration.
5. Optionally, click Save Config to save the object to the startup configuration.

Defining Shared Secret Key objects


A Shared Secret Key objects provides an added layer of security by supplying an
indirect reference (or alias) to a shared secret key. A shared secret key is used by
mutual agreement between a sender and receiver for encryption, decryption, and
digital signature purposes.
To create and configure a Shared Secret Key, use the following procedure:
1. Select Objects Crypto Crypto Shared Secret Key to display the Crypto
Shared Secret Key catalog.
2. Click Add to display the Crypto Shared Secret Key Configuration screen.
3. Provide the following inputs:
Name Specify the name of the object.
Admin State
Retain the default setting. To place the object in an inactive
administrative state, click disabled.

18

IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

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

Defining SSL Proxy Profile objects


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

Creating a forward (or client) proxy


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

Creating a reverse (or server) proxy


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

Chapter 2. Securing communication

19

6. Select the profile that defines SSL service to frontend clients from the Reverse
(Server) Crypto Profile list.
7. Use the Server-side Session Caching toggle to enable or disable server side
caching.
8. Specify the time that session-specific state data is maintained in the server
cache in the Server-side Session Cache Timeout field.
9. Specify the maximum size of the server-side cache in the Server-side Session
Cache Size field.
10. Use the Client Authentication is optional toggle to control when SSL client
authentication is optional.
on

Client authentication is not required. When there is no client


certificate, the request does not fail.

(Default) Requires client authentication only when the server


cryptographic profile has an assigned Validation Credentials.
11. Use the Always Request Client Authentication toggle to control when to
request SSL client authentication.
off

on

Always requests client authentication.

off

(Default) Requests client authentication only when the server


cryptographic profile has an assigned Validation Credentials.

12. Click Apply to save the object to the running configuration.


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

Creating a two-way proxy


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

20

Client authentication is not required. When there is no client


certificate, the request does not fail.

IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

(Default) Requires client authentication only when the server


cryptographic profile has an assigned Validation Credentials.
13. Use the Always Request Client Authentication toggle to control when to
request SSL client authentication.
off

on

Always requests client authentication.

(Default) Requests client authentication only when the server


cryptographic profile has an assigned Validation Credentials.
14. Click Apply to save the object to the running configuration.
15. Optionally, click Save Config to save the object to the startup configuration.
off

Working with Validation Credentials objects


A Validation Credentials consists of a list of certificate objects. Validation
Credentials are used to validate the authenticity of received certificates and digital
signatures. You can create Validation Credentials with the following types of
credentials:
v All non-expiring, non-password-protected credentials
v Select credentials
Independent of which type of Validation Credentials, the creation starts at the
same location. To create any Validation Credential, select Objects Crypto
Crypto Validation Credentials.

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


You can create a Validation Credential includes all valid, non-expired,
non-password-protected certificates in the pubcert: file repository. The following
procedure silently creates a Certificate object for each valid certificate file in the
pubcert: file repository
To create this type of Validation Credentials, use the following procedure:
1. Select Objects Crypto Crypto Validation Credentials.
2. Click Create Validation Credential from pubcert: to display a confirmation
screen.
3. Click Confirm to create the Validation Credentials, with the appliance-supplied
name of pubcert.
4. After the WebGUI reports successful completion, click Close.
To refresh the Crypto Validation Credentials catalog, select Objects Crypto
Crypto Validation Credentials. Click Refresh List.
To save the Validation Credentials to the startup configuration, click Save Config.

Creating for select certificates


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

21

Admin State
Retain the default setting. To place the object in an inactive administrative
state, click disabled.
Certificates
Use the list to add select Certificate objects to the Validation Credentials.
Certificate Validation Mode
Select one of the following modes:
Match exact certificate or immediate issuer
(Default) The behavior is that the Validation Credentials contains
either the exact peer certificate to match or the certificate of the
immediate issuer, which could be an intermediate CA or a root
CA. This mode is useful when you want to match the peer
certificate exactly, but that certificate is not a self-signed (root)
certificate.
Full certificate chain checking (PKIX)
The complete certificate chain is checked from subject to root
when using this Validation Credentials for certificate validation.
Validation succeeds only if the chain ends with a root certificate
in the Validation Credentials. Non-root certificates in the
Validation Credentials will be used as untrusted intermediate
certificates. Additional untrusted intermediate certificates will be
obtained dynamically from the context at hand (SSL handshake
messages, PKCS#7 tokens, PKIPath tokens, and so forth).
Use CRLs
Determines whether each Certificate Revocation List (CRL) is checked
during the processing of the certificate chain.
on

(Default) Checks the CRLs.

off

Does not check CRLs.

Require CRLs
When CRLs are checked during processing of the certificate chain,
determines whether the processing should fail when no CRL is available.
on

Processing fails.

off

(Default) Processing succeeds.

CRL Distribution Points Handling


Determines how to handle Certificate Revocation List (CRL) checking of
X.509 CRL Distribution Points extensions during processing of the
certificate chain and controls how to handle certificates in the Validation
Credentials.
Ignore Ignores extensions.
Require
Checks, but does not retrieve, extensions.
Initial Certificate Policy Set
When the mode is PKIX, defines the certificate chain validation input that
RFC 3280 calls the user-initial-policy-set. This set of OIDs specifies the
only allowable values of Certificate Policies at the end of chain
processing.

22

IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

If you define an initial certificate policy set, you will want to enable the
Require Explicit Certificate Policy field. Otherwise, these certificate
policy sets will be used only when there are Policy Constraints extensions
in the certificate chain.
The default contains the OID for anyPolicy.
Require Explicit Certificate Policy
When the mode is PKIX, controls whether the validation chain
(algorithm) can end with an empty policy tree (that RFC 3280 calls the
initial-explicit-policy).
on

The algorithm must end with a non-empty policy tree.

The algorithm can end with an empty policy tree unless Policy
Constraints extensions in the chain require an explicit policy.
4. Click Apply to save the object to the running configuration and return to the
object catalog.
5. Optionally, click Save Config to save the object to the startup configuration.
off

Chapter 2. Securing communication

23

24

IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

Chapter 3. Configuring Web Application Firewall services


This chapter documents the creation or editing of a Web Application Firewall
service using the Advanced Web Application Firewall Configuration screen.
A Web Applications Firewall provides security, proxy, threat mediation, and
content processing services for a Web-based application (such as enrollment,
benefits management, ticket sales, or a trading system). The Web Applications
Firewall is designed to handle traffic that is primarily URL-encoded HTTP POST
operations (or HTTP GET with or without Query Strings) and not primarily Web
services SOAP-based XML payloads (although XML traffic can be handled).
The Web Application Firewall offers:
v Destination Service Proxy
v SSL Termination
v Authentication and Authorization Service
v Rate Limiting
v
v
v
v
v

Session Start and Timeout Enforcement


URL-Encoded Name-Value Input Processing
HTTP Protocol Filtering
Threat Protection, such as SQL Injection
Cookie Handling, including Sign and Encrypt

v Error Handling
v XML and Non-XML Content Processing

Scenarios
This section provides scenarios using the Web Application Firewall service. For
each scenario, there is a requirement statement followed by the recommended
configuration to meet those requirements.

Scenario one: College enrollment form


Requirements
A community college offers the opportunity to sign up for evening classes.
The server that hosts this application is connected to sensitive College
administrative systems and thus the college does not want HTTP traffic to
flow directly to the host. The college IT administrators would also like to
restrict the size and depth of inbound posts, to protect against malicious
intent. The entire transaction must be SSL-encrypted but the host does not
have the necessary cycles to manage the encryption.
Solution
Web Application Firewall Configuration:
v
v
v
v
v
Copyright IBM Corp. 2002, 2009

Proxies Destination Address (real host address not exposed)


Applies SSL Server Proxy Profile
Default Threat Protections
Default Multi-Part Form Protections
Error Handling Policy redirects to friendly page

25

Scenario two: Benefits management site


Requirements
A large corporation offers complete online management of employee
benefits. The information is sensitive so the transaction must be SSL
encrypted and any login must time out after a certain amount of idle time.
Users must supply a user name and password to access the site. As some
forms are multi-page, a session cookie is required and this cookie must be
encrypted for security reasons. Certain partner sites are allowed to POST
entire forms as XML data. Users are redirected to an error handling page
when errors occur.
Solution
Web Application Firewall Configuration:
v Proxies Destination Address (real host address not exposed)
v Applies SSL Server Proxy Profile
v AAA Basic Authentication verifies user name and password with LDAP
v Default Threat Protections
v Default Multi-Part Form Protections
v Well Formed XML enforced
v Error Handling Policy redirects to friendly page; XML submits get XML
response
v Cookie Required
v Cookie Encrypted
v Start Page Filtering
v Session Management Timeout

Scenario three: Trading site


Requirements
An online business offers a trading site, in which customers are trading
nearly anything for anything. Customers need to be able to search for
desired objects, upload descriptions of items for trade, and securely close
the deal. In some cases, an offered item might draw more than one bidder
(or trade offer). Users must supply a user name and password to access the
site. Because of the speed of transactions, a single signon system is needed
and cookies are used. Due to the competitive nature of the business,
connections must be rate limited, preventing a single entity from flooding
the site. The site offers third party participation, so every post must be
vetted for size and correctness. In addition, responses from the central
trading systems must also be limited in size and vetted for correctness.
SQL Injection Attack protection is required.
Solution
Web Application Firewall Configuration:
v Proxies Destination Address (real host address not exposed)
v Applies SSL Server Proxy Profile
v AAA basic authentication verifies user name and password with LDAP
v Custom threat protections and protection from SQL injection
v Custom Multi-Part Form Protections
v Requests Rate Limited
v Requests Vetted for Correct Name-Value Pairs

26

IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

v
v
v
v
v

Error Handling Policy redirects to friendly page


Cookie Required
Start Page Filtering
Session Management Timeout
Responses Vetted for Correct Name-Value Pairs

Configuring a Web Application Firewall


General configuration
Select Services Web Application Firewall New Web Application Firewall to
display the Web Application Firewall Configuration screen.
Provide the following inputs.
Name Specify a unique name for this object. The name must be unique
throughout the appliance.
Summary
Brief summary for user annotation. This is optional.
Remote Host Address
The host name or IP address of the backend server. To use a load balancer,
specify the name of the Load Balancer Group.
If the appliance should employ an SSL connection to the backend server,
configure an SSL Proxy Profile that in turn uses a Crypto Profile
configured for client (or forward) connections.
Remote IP Port
The TCP port number of the backend server.
XML Manager
An XML Manager manages the compilation and caching of XSL style
sheets, the caching of XML documents, and provides configuration
constraints on the size and parsing depth of XML documents. You can
enable streaming XML operation by configuring an XML Manager to use a
Streaming Compile Option Policy.
An XML Manager can optionally employ a User Agent. The User Agent
settings, in turn, can affect the behavior of the gateway when
communicating with backend servers or with clients when sending back
responses.
More than one firewall can use the same XML Manager. Select an existing
XML Manager to assign the Manager to this firewall. Click the + button to
create a new XML Manager that is assigned to this firewall. A default
Manager is used if you do not create one.
SSL Proxy Profile
Select an existing SSL Proxy Profile to assign the SSL Proxy Profile to this
handler. When selected, communication with clients, the backend server, or
both will use SSL in accordance with the configured Crypto Profile.
v To implement SSL communication with requesting clients, use an SSL
Proxy Profile that uses a Crypto Profile configured as a Server (reverse)
profile. Under Source Addresses, set the Use SSL check box for at least
one source address.

Chapter 3. Configuring Web Application Firewall services

27

v To implement SSL communication with the backend server, use an SSL


Proxy Profile that uses a Crypto Profile configured as a Client (forward)
profile.
v To implement SSL communication with both requesting clients and the
backend server, use an SSL Proxy Profile that uses a Crypto Profile
configured for two-way SSL.
Refer to Defining SSL Proxy Profile objects on page 19 for more
information.
Default Error Handling Policy
If any part of the Application Security Policy selected below is violated, the
service will handle the violation, or error, in accordance with the rules set
forth in the selected Error Policy. This is the default policy that will handle
the response sent to the client. If no Policy is selected (the list remains at
(none)), all failures of Policy will generate an error by default. An
Application Security Policy can also establish an Error Policy; the Error
Policy established by the Application Security Policy overrides this default
selection.
Refer to Error Policy on page 99 for more information.
Security Policy
A Security Policy is required to create the service. To establish the security
policy enforced by this firewall, select an Application Security Policy. Refer
to Configuring an Application Security Policy on page 30 for more
information.
Either the Request security policy or the Response security policy that is
established by the select Application Security Policy can be turned off
using the Request Security or Response Security toggle on the
Timeout/Protocol tab.
Source Addresses
Source addresses determine the IP addresses and TCP ports to assign to
the service. Remote clients connect to these addresses. At least one source
address must be configured.
To add a source address, provide the following information.
IP

Specify the IP address, host name, or host alias on which the


service listens. The default is 0.0.0.0. This value indicates that the
service is active on all addresses.

Port

Specify the TCP port on which the service listens. Use an integer in
the range of 1 through 65535. There is no default value.

SSL

Indicates whether the service acts as an SSL server for requesting


clients.
v Select the check box to enable.
v Ensure that the check box is not selected to disable.
When enabled, the Crypto Profile of the selected SSL Proxy Profile
handles these requests.

Click Add. The new Source Address appears in the listing of all configured
source addresses.

28

IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

To create the new Web Application Firewall service using the standard defaults for
the configuration options available on the Timeout/Protocol tab, click Commit. You
can optionally set additional configuration parameters on the Timeout/Protocol
tab.

Timeout/Protocol
These configuration options control time outs and HTTP protocol-specific options.
The defaults are set to handle the majority of scenarios.
Provide the following inputs:
Front Side Timeout
Controls the amount of time a front side client connection can be idle
before being abandoned in a transaction.
Back Side Timeout
Controls the amount of time a back side client connection can be idle
before being abandoned in a transaction.
Front Persistent Timeout
Specifies the maximum number of seconds (in the range 0 through 86400,
with a default of 180) that a gateway maintains an idle persistent TCP
connection on the front side.
Back Persistent Timeout
Specifies the maximum number of seconds (in the range 0 through 86400,
with a default of 180) that a gateway maintains an idle persistent TCP
connection on the back side.
HTTP Response Version
Select the HTTP version (1.0 or 1.1) to be used on client responses.
Incoming version 1.0 requests will always be replied to with 1.0 compatible
responses regardless of this setting. Use 1.1 to support chunked responses.
HTTP Version to Server
Select the HTTP version (1.0 or 1.1) to use on the server-side connection.
Certain HTTP 1.1 features, such as chunked uploads, require the selection
of 1.1. The backend server must also support HTTP 1.1 for the connection
to be established and maintained using the 1.1 version of the protocol.
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.
Chapter 3. Configuring Web Application Firewall services

29

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.
Normalize URI
When enabled (on), the URI is rewritten to make the URI RFC-compliant.
Certain characters will be escaped; additionally, characters that are escaped
that do not need to be are unescaped. This makes checking for attack
sequences more reliable.
Request Security
If disabled (off), no request side security policies is enforced and all
requests are allowed through. This setting overrides the previously selected
Application Security Policy.
Response Security
If disabled (off), no response side security policies is enforced and all
responses are allowed through. This setting overrides the previously
selected Application Security Policy.

Configuring an Application Security Policy


An Application Security Policy establishes the rules that are used to enforce
security for a Web Application Firewall service. This policy employs Request Map,
Response Map, and Error Map objects. Each of these map objects, in turn, matches
a Web Request Profile, Web Response Profile, or Error Policy object, respectively, to
client-requests that are based on a set of matching criteria. The selected profile
object then provides the detailed security configuration.

General configuration
Provide the following input:
Name
Specify a name for this Policy. This is the name that appears in all Policy
listings.

Request Maps
Request Maps select Web Request Profiles to execute on client requests based on a
set of matching criteria. If the client request meets the matching criteria, the
corresponding Web Request Profile executes.
Note: You must create at least one Request Map to complete the Policy creation.
Click the Request Maps tab to establish Web Request matching maps.
Provide the following inputs:
Match Select an existing Matching Rule. Refer to Matching Rule on page 106 for
more information.
Rule

Select an existing Web Request Profile. Refer to Web Request Profile on


page 132 for more information.

Click Add Request Map to save the map. The new map is displayed in the
catalog.

30

IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

Click Commit to complete configuration of the Policy.


Note: The order of Request Maps is important. The maps are checked from the top
to the bottom of the list; the first matching expression that returns true will
execute. Use the Reorder button to establish the desired ordering of maps.

Response Maps
Response Maps select Web Request Profiles to execute on server responses based
on a set of matching criteria. If the server response meets the matching criteria, the
corresponding Web Request Profile executes.
Note: You must create at least one Response Map to complete the Policy creation.
Click the Response Maps tab to establish Web Response matching maps.
Provide the following inputs:
Match Select an existing Matching Rule. Refer to Matching Rule on page 106 for
more information.
Rule

Select an existing Web Response Profile. Refer to Web Response Profile


on page 139 for more information.

Click Add Response Map to save the map. The new map is displayed in the
catalog.
Click Commit to complete configuration of the Policy.
Note: The order of Response Maps is important. The maps are checked from the
top to the bottom of the list; the first matching expression that returns true
will execute. Use the Reorder button to establish the desired ordering of
maps.

Error Maps
Error Maps select a Processing Rule to execute on errors based on a set of
matching criteria. If the error meets the matching criteria, the corresponding
Processing Rule executes.
Click the Error Maps tab to establish Error Policy matching maps.
Provide the following inputs:
Match Select an existing Matching Rule. Refer to Matching Rule on page 106 for
more information.
Rule

Select an existing Processing Rule. Refer to Processing Rule on page 111


for more information.

Click Add Error Map to save the map. The new map is displayed in the catalog.
Click Commit to complete configuration of the Policy.

Chapter 3. Configuring Web Application Firewall services

31

32

IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

Chapter 4. Managing files


The appliance contains no hard drive for file storage. As a result, the storage space
for files and other artifacts is limited.

Directories on the appliance


The file system contains many examples and critical configuration files. These
directories and their contents are as follows:
audit: This directory contains the audit logs. Each appliance contains only one
audit: directory. This directory cannot be the destination of a copy. This
directory is available from the command line in the default domain only.
To view the audit log from the WebGUI, select Status View Logs Audit
Log.
cert:

This encrypted directory contains private key and certificate files that
services use in the domain. You can add, delete, and view files, but you
cannot modify these files while in the domain. Each application domain
contains one cert: directory. This directory is not shared across domains.

chkpoints:
This directory contains the configuration checkpoint files for the appliance.
Each application domain contains one chkpoints: directory. This directory
is not shared across domains.
config:
This directory contains the configuration files for the appliance. Each
application domain contains one config: directory. This directory is not
shared across domains.
dpcert:
This encrypted directory contains files that the appliance itself uses. This
directory is available from the command line in the default domain only.
export:
This directory contains the exported configurations that are created with
the Export Configuration utility. Each application domain contains one
export: directory. This directory is not shared across domains.
image: This directory contains the firmware images (primary and secondary) for
the appliance. This directory is where firmware images are stored typically
during an upload or fetch operation. Each appliance contains only one
image: directory. This directory is available in the default domain only.
local:

This directory contains miscellaneous files that are used by the services
within the domain, such as XSL, XSD, and WSDL files. Each application
domain contains one local: directory. This directory can be made visible to
other domains. When viewed from other domains, the directory name
changes from local: to the name of the application domain.

logstore:
This directory contains log files that are stored for future reference.
Typically, the logging targets use the logtemp: directory for active logs. You
can move log files to the logstore: directory. Each application domain
contains one logstore: directory. This directory is not shared across
domains.
Copyright IBM Corp. 2002, 2009

33

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

34

This encrypted subdirectory contains files that are used by the


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

IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

pubcerts
This encrypted subdirectory contains files that are used by the
appliance itself. This subdirectory is available from the command
line only.
tasktemplates:
This directory contains the XSL files that define the display of specialized
WebGUI screens. Each appliance contains only one tasktemplates: directory.
This directory is visible to the default domain only.
temporary:
This directory is used as temporary disk space by processing rules. Each
application domain contains one temporary: directory. This directory is not
shared across domains.

Launching the File Management utility


To manage files, launch the File Management utility with one of the following
methods:
v Select the File Management icon from the Files and Administration section of
the Control Panel.
v Select Administration Main File Management.
Either method displays the File Management screen. The initial screen shows the
top level directories.

Displaying directory contents


To display (expand) the contents of a directory, perform the following procedure:
1. Launch the File Management utility. Refer to Launching the File Management
utility for details.
2. Select the directory to display its contents.
To hide (collapse) the content-view of a directory, select that directory again.

Creating a subdirectory
Subdirectories can only be creates under the local: directory or one of its
subdirectories.
Follow these steps to create a subdirectory under the local: directory or one of its
subdirectories:
1. Launch the File Management utility. Refer to Launching the File Management
utility for details.
2. From the Action column, click Actions aligned with the directory for the
subdirectory to be created.
3.
4.
5.
6.

Click Create Subdirectory. The File Management screen displays.


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

Chapter 4. Managing files

35

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

Refreshing directory contents


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

Uploading files from the workstation


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

36

IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

Working with Java Key Stores


A Java Key Store (JKS) is a Sun-proprietary format file that contains private keys
and certificates. The java.security package and sub-packages access the data in
the JKS to carry out their cryptographic operations.

Required software
JKS support requires the following software on the WebGUI workstation:
v Version 1.4.2 of the Java runtime environment (j2re1.4.2)
v SDK (j2sdk1.4.2)
v Internet Explorer
Note: You must have the JRE or Java SDK /bin path name in the Windows PATH
environment variable on the WebGUI workstation. The Java Key Store file
cannot reside on any of the local directories. It must be uploaded from a
workstation.

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

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

Types of key stores


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

Uploading a file from a Java Key Store


Use the following procedure to upload a file from a Java Key Store (JKS) to the
appliance:
1. Launch the File Management utility. Refer to Launching the File Management
utility on page 35 for details.
2.
3.
4.
5.

Navigate to the directory into which you want to upload the file.
Click Actions in that row to open the Directory Actions menu.
Click Upload Files to display the File Upload screen.
Click the Java Key Store radio button to display the JKS Upload screen.
Note: When you click the Java Key Store radio button, the Java Console of
the browser opens and shows whether the Java Key Store Access

Chapter 4. Managing files

37

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
35.
If the upload fails, look at the Java Console of the browser to determine whether
an exception was thrown.

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

3.
4.
5.
6.
7.

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

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

38

IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

1. Launch the File Management utility. Refer to Launching the File Management
utility on page 35 for details.
2. Navigate to the directory that contains the files to be copied.
3. Select files by clicking the box adjacent to the file name.
4. Scroll to the top or bottom of the screen and click Copy to display the File
Copy screen.
5. From the New Directory Name list, select the target directory.
6. Specify the name for the file, if different, in the New File Name field.
7. If one of the selected files already exists in its associated target directory and
you want to overwrite this file, check the Overwrite Existing Files check box. If
you do not select this check box and the file already exists, the file is not
copied.
8. Click Confirm Copy to copy the files to the target directories.
9. When the appliance reports success, click Continue to return to the File
Management screen.
The target directories now contain the copied files. To verify that the files exist, use
the procedure described in Displaying directory contents on page 35.

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

Moving files
Use the following procedure to move a file from one directory to another:
1. Launch the File Management utility. Refer to Launching the File Management
utility on page 35 for details.
2.
3.
4.
5.
6.

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


Select files by clicking the box adjacent to the file name.
Click Move to display the Move File screen.
From the New Directory list, select the target directory.
If one of the selected files already exists in its directory and you want to
overwrite this file, select the Overwrite Existing Files check box. If you do not
select this check box and the file already exists, the file is not moved.
Chapter 4. Managing files

39

7. Click Confirm Move.


8. When the appliance reports success, click Continue to return to the File
Management screen.
The target directories now contain the moved files. To verify that the files exist, use
the procedure described in Displaying directory contents on page 35.

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

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

Deleting files
Use the following procedure to delete a file:
1. Launch the File Management utility. Refer to Launching the File Management
utility on page 35 for details.
2. Navigate to the directory that contains the files to be deleted.
3. Select files by clicking the box adjacent to the file name.
4. Scroll to the top or bottom of the screen and click Delete to display the Delete
File screen.
5. Click Confirm Delete to delete the files.
6. When the appliance reports success, click Continue to return to the File
Management screen.
The selected files were deleted. To verify that the files no longer exist, use the
procedure described in Displaying directory contents on page 35.

40

IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

Chapter 5. Managing the configuration of the appliance


This chapter provide information about managing the configuration of application
domains and importing and exporting configurations.

Creating Include Configuration File objects


Include Configuration File objects allow you to include configuration information
from an external configuration file in the local configuration information. This
external file can be stored on a centralized configuration server or another
DataPower appliance. The information in the Include Configuration File object is
appended to the local configuration information when the configuration of the
DataPower appliance is reloaded (such as during appliance reboot, firmware
reload, or domain restart).
An Include Configuration File object can include configuration information only.
On the other hand, an Import Configuration File object is a configuration package
that can include both configuration information and supporting files.
To append configuration information from an external file to the local
configuration information, perform the following procedure:
1. Select Objects Configuration Management Include Configuration File to
display the catalog.
2. Click the name of an existing Include Configuration File object to edit it, or
click Add to create a new one. The Include Configuration File configuration
screen is displayed.
3. Specify the name of the object in the Name field.
4. Retain the default setting for the Admin State toggle. To place the object in an
inactive administrative state, click disabled.
5. Specify a descriptive object-specific summary in the Comment field.
6. Specify the URL of the configuration file in the URL of Configuration File
field. For example, specify https://config.server.com/datapower/
firewalls.cfg.
7. Use the Execute on Startup toggle to indicate whether to import the
configuration package at startup.
on

(Default) Imports the configuration package at startup. The


configuration is marked external and cannot be saved to the startup
configuration. This behavior is equivalent to always importing the
configuration.

Imports the configuration package when manually triggered. The


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

on

Retrieves the configuration file after the local interface is up.

off

(Default) Retrieves the configuration file at appliance reload without


waiting for the local interface to be up.

Copyright IBM Corp. 2002, 2009

41

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


10. Optionally, click Save Config to save the object to the startup configuration.
Note: Unless you click Save Config, the included configuration file will not take
affect when the appliance is started.

Creating Import Configuration File objects


Import Configuration File objects allow you to import a configuration package
from an external configuration file into the local configuration information. The
external file can be stored on a centralized configuration server or another
DataPower appliance. The configuration data and files in the configuration file is
added to the local configuration information when the configuration of the
DataPower appliance is reloaded (such as during appliance reboot, firmware
reload, or domain restart). The default configuration of an Import Configuration
File object does not provide warnings about conflicts with existing files and
objects.
An Import Configuration File object is a configuration package that can include
both configuration information and supporting files. On the other hand, an Include
Configuration File object can include configuration information only.
To import a configuration package from an external file to the local configuration
information, perform the following procedure:
1. Select Objects Configuration Management Import Configuration File to
display the catalog.
2. Click the name of an existing configuration package to edit it, or click Add to
create a new one. The Import Configuration File configuration screen is
displayed.
3. Specify the name of the object in the Name field.
4. Retain the default setting for the Admin State toggle. To place the object in an
inactive administrative state, click disabled.
5. Specify a descriptive object-specific summary in the Comment field.
6. Specify the URL of the configuration package in the URL of Configuration
Package field. For example, specify https://config.server.com/datapower/
firewalls.zip.
Note: You cannot use the SCP or SFTP protocol to retrieve a configuration
package. All other URL protocols are available; for example, HTTP,
HTTPS, or FTP.
7. Select the package format from the Format of Configuration Package list.
ZIP

(Default) Indicates that the configuration package is in ZIP format. If


the format is ZIP, the bundle is unzipped automatically.

XML

Indicates that the configuration package in XML format.

8. Use the Overwrite Files toggle to control the overwrite behavior.


on

(Default) Overwrites files of the same name.

off
Does not import the file if a file of the same name exists.
9. Use the Overwrite Objects toggle to control the overwrite behavior.

42

on

(Default) Overwrites objects of the same name.

off

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

IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

10. (Optional) Select a deployment policy that preprocesses the configuration


package from the Deployment Policy list. For more information, refer to
Configuring deployment policies on page 54.
11. Use the Local IP Rewrite toggle to indicate whether to rewrite local IP
addresses on import.
on

(Default) Rewrites IP addresses to match the local configuration when


imported. For example, a service in the configuration package that
binds to eth1 is rewritten to bind to eth1 when imported.

off
Retains the original IP address in the configuration package.
12. Use the Import on Startup toggle to indicate whether to import the
configuration package at startup.
on

(Default) Imports the configuration package at startup. The


configuration is marked external and cannot be saved to the startup
configuration. This behavior is equivalent to always importing the
configuration.

Imports the configuration package when manually triggered. The


configuration is not marked external and can be saved to the startup
configuration. This behavior is equivalent to importing the
configuration one time.
13. Click Apply to save the object to the running configuration.
14. Optionally, click Save Config to save the object to the startup configuration.
off

Backing up and exporting configuration data


The backup and export utility copies specified configuration data from the
appliance to a file in the export: directory. You can optionally download the file to
your workstation.
Note: Exported configuration data should not be imported to an appliance with an
earlier release level. Between releases, configuration data for properties can
change. If you attempt to import configuration data from an appliance of a
later release level into an appliance of an earlier release level, the operation
might report success, but the configuration data might not be the same.
Therefore, use this utility to exchange configuration data among appliances
of the same release level.
You can use this utility to perform the following operations:
v Create a backup of the entire appliance
v Create a backup of one or more application domains
v Export select objects from the current domain
v Copy or move select objects between domains
Note: The following objects are never exported:
v User account objects
v Certificate objects
v Key objects (HSM appliances only)
The following files are never exported:
v Log files
v Firmware files
Chapter 5. Managing the configuration of the appliance

43

To ensure that all other objects and files are exported, use the admin account.
For any other user, only objects and files that are accessible to that user are
included in the export package.
To start a back up or export operation, select Administration Configuration
Export Configuration to display the initial Export Configuration screen. This
screen provides the following export options:
v Create a backup of the entire system
v Create a backup of one or more application domains
v Export configuration and files from the current domain
v Copy or move configuration and files between domains

Backing up the entire appliance


Use the following procedure to back up (export) all configuration data for the
appliance.
1. Select Administration Configuration Export Configuration to display the
Initial Export Configuration screen.
2. Select Create a backup of the entire system and click Next to display the File
Name screen.
a. Specify a descriptive object-specific summary in the Comment field.
b. Optionally create or select the name of a Deployment Policy to accept, filter,
or modify a configuration during import.
c. The Export File Name defaults to export (.zip). If a file of this name exists
in the export: directory, it is overwritten.
d. Click Next. The configuration of the entire appliance is backed up.
When the backup completes, the file is in the export: directory. You can optionally
download the export file to your workstation.
Note: The Import Configuration utility requires that the export file resides on your
workstation.
3. Optionally click Download to download the file to your workstation.
4. Click Done to close this window and return to the Control Panel.
The export file can be accessed from the export: directory. If downloaded, the
export file is on your workstation.

Backing up domains
Best practice is to periodically back up all domains individually.
To back up configuration information for one or more application domains, follow
this procedure:
1. Select Administration Configuration Export Configuration to display the
Initial Export Configuration screen.
2. Select Create a backup of one or more application domains and click Next to
display the selection screen.
3. Provide the following inputs:
a. Specify a descriptive object-specific summary in the Comment field.
b. Optionally create or select the name of a Deployment Policy to accept, filter,
or modify a configuration during import.

44

IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

c. The Export File Name defaults to export (.zip). If a file of this name exists
in the export: directory, it is overwritten.
d. Select the check boxes adjacent to each domain to export.
e. Click Next
When the backup completes, the file is in the export: directory. You can optionally
download the export file to your workstation.
Note: The Import Configuration utility requires that the export file resides on your
workstation.
4. Optionally click Download to download the file to your workstation.
5. Click Done to close this window and return to the Control Panel.
The export file can be accessed from the export: directory. If downloaded, the
export file is on your workstation.

Exporting select objects


The Export Configuration utility remains available from the initial Export
Configuration screen. To export select objects and files, use the following
procedure:
1. Select Administration Configuration Export Configuration to display the
Initial Export Configuration screen.
2. Select Export configuration and files from the current domain and click Next
to display the Export Configuration screen.
3. Provide the following inputs:
a. Specify a descriptive object-specific summary in the Comment field.
b. Optionally create or select the name of a Deployment Policy to accept, filter,
or modify a configuration during import.
c. The Export File Name defaults to export (.xml or .zip depending on the
selected export format). If a file of this name exists in the export: directory,
it is overwritten.
d. Use the To radio buttons to specify the export format.
XML Config
Exports configuration data as XML files. Include Configuration files
are referenced in the XML document only, they are not included.
ZIP Bundle
Exports configuration data in compressed ZIP format. Include
Configuration files are in the bundle.
e. Use the Configuration radio button to specify the data to export.
Currently running configuration
Exports the configuration data from the running configuration, not
the startup configuration.
Last persisted configuration
Exports the configuration data from the startup configuration, not
the current running configuration.
f. Use the Referenced Objects radio buttons to specify the scope of the data to
export.
Include only the selected base objects
Exports only the configuration data for the selected objects.

Chapter 5. Managing the configuration of the appliance

45

Include all objects required by selected base objects


Exports configuration data for the selected objects and all objects
that are required by the selected objects. For example, if exporting an
XSL Proxy, the export includes configuration data for the XSL Proxy,
the assigned XML manager, and all associated matching rules,
processing policies, processing rules, cryptographic certificates,
credentials, and keys.
g. Use the Export Files radio buttons to specify the scope of the data to
export.
Export no files
No files are included in the export. If, for example, the selected
objects use files, such as a style sheet, those files are not included.
This option is useful when the configuration data itself is all that is
needed.
Export files referenced by exported objects
In addition to the selected objects (and possibly referenced objects),
exports public files that are associated with the selected objects.
Note: The export does not include private files. These files are in the
cert: and sharedcert: directories.
Export all local files
Exports public files that are associated with the selected objects and
all files that are in the following directories:
v config:
v local:
v pubcert:
v store:
v tasktemplates:
h. From the Objects list, select the type or class of configuration data to
export.
After selecting an entry, all instances of that type or class are listed in the
left-hand box.
1) Select the objects from the left-hand list. To select multiple objects, select
objects in combination with the Shift and Control keys.
2) Click > to move the selected object to the Selected Base Objects list.
i. Adjust the Selected Base Objects list, if necessary.
1) Select objects in the right-hand list. To select multiple objects, select
objects in combination with the Shift and Control keys.
2) Click < to remove the selected objects or click <<to remove all objects
from the Selected Base Objects list.
j. Click Show Contents at any time to display all contents marked for
inclusion in the export.
k. Click Next.
When the backup completes, the file is in the export: directory. You can optionally
download the export file to your workstation.
Note: The Import Configuration utility requires that the export file resides on your
workstation.
4. Optionally click Download to download the file to your workstation.
5. Click Done to close this window and return to the Control Panel.

46

IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

The export file can be accessed from the export: directory. If downloaded, the
export file is on your workstation.

Copying or moving select objects


The copy or move utility is available from the initial Export Configuration screen.
To copy or move selected objects and files, use the following procedure:
1. Select Administration Configuration Export Configuration to display the
Initial Export Configuration screen.
2. Select Copy or move configuration and files between domains and click Next
to display the Export Configuration screen.
a. Optionally create or select the name of a Deployment Policy to accept, filter,
or modify a configuration during import.
b. Use the Delete After Export toggle to indicate whether the operation is a
copy operation or a move operation.
on

Indicates a move operation.

off

Indicates a copy operation.

c. Use the Configuration radio button to specify the data to export.


Currently running configuration
Exports the configuration data from the running configuration, not
the startup configuration.
Last persisted configuration
Exports the configuration data from the startup configuration, not
the current running configuration.
d. Use the Referenced Objects radio buttons to specify the scope of the data
to export.
Include only the selected base objects
Exports only the configuration data for the selected objects.
Include all objects required by selected base objects
Exports configuration data for the selected objects and all objects
that are required by the selected objects. For example, if exporting
an XSL Proxy, the export includes configuration data for the XSL
Proxy, the assigned XML manager, and all associated matching
rules, processing policies, processing rules, cryptographic
certificates, credentials, and keys.
e. Use the Export Files radio buttons to specify the scope of the data to
export.
Export no files
No files are included in the export. If, for example, the selected
objects use files, such as a style sheet, those files are not included.
This option is useful when the configuration data itself is all that is
needed.
Export files referenced by exported objects
In addition to the selected objects (and possibly referenced objects),
exports public files that are associated with the selected objects.
Note: The export does not include private files. These files are in the
cert: and sharedcert: directories.

Chapter 5. Managing the configuration of the appliance

47

Export all local files


Exports public files associated with the selected objects and all files
contained in the following directories:
v config:
v image:
v pubcert:
v store:
v tasktemplates:
f. From the Objects list, select the type or class of configuration data to export.
After selecting an entry, all instances of that type or class are listed in the
left-hand box.
1) Select the objects from the left-hand list. To select multiple objects, select
objects in combination with the Shift and Control keys.
2) Click the > button to move the selected objects to the Selected Base
Objects list.
g. Adjust the Selected Base Objects list, if necessary.
1) Select objects in the right-hand list. To select multiple objects, select
objects in combination with the Shift and Control keys.
2) Click < to remove the selected objects or click <<to remove all objects
from the Selected Base Objects list.
3. Click Show Contents at any time to display all contents marked for inclusion
in the export.
4. Click Next to display the Import File window.
a. From the Domain list, select the domain where the configuration data is to
imported.
b. Click Import to initiate file transfer.
5. Respond to WebGUI prompts.
6. Click Done to close the Import File screen.

Managing configuration checkpoints


A configuration checkpoint contains configuration data from a specific point in
time. The configuration checkpoint might be equivalent to the persistent
configuration, might be equivalent to the running configuration, or might be
different from the persisted configuration or running configuration.
Within each application domain, the administrator who is associated with the
admin account defines the number of configuration checkpoints to allow. You can
save up to the allowed number of configuration checkpoints.
When saved, a ZIP formatted file for the configuration checkpoint is written the
chkpoints: directory for that application domain.

Defining number configuration checkpoints to allow


The administrator who is associated with the admin account can define the number
of checkpoint configurations to allow for each application domain. To define the
number of checkpoint to allow for an existing domain, use the following
procedure:
1. Select Administration Configuration Application Domain to display the
Application Domain catalog.

48

IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

2. Select the specific application domain to open the domain-specific configuration


screen.
3. Select the Configuration tab.
4. Specify the number of checkpoint configuration to allow in the Configuration
Checkpoint Limit field. Use an integer in the range of 1 through 5. The default
is 3.
5. Click Apply to save the object to the running configuration.
6. Optionally, click Save Config to save the object to the startup configuration.

Saving configuration checkpoints


Do not click Save Config to save a configuration checkpoint. This button does not
allow you the option of saving a configuration checkpoint.
To save a configuration checkpoint, use the following procedure:
1. Select Administration Configuration Configuration Checkpoints.
2. Specify the name of the configuration checkpoint in the Checkpoint Name
field.
3. Click Save Checkpoint.
4. Respond to WebGUI prompts.
A ZIP-formatted configuration file of the specified name is written to the
chkpoints: directory.
You cannot overwrite a configuration checkpoint. You must first delete the original
configuration checkpoint before saving a new configuration checkpoint of the same
name. For details, refer to Deleting configuration checkpoints on page 50.

Listing configuration checkpoints


You can view the list of saved configuration checkpoint in one of the following
ways:
v From the Configuration Checkpoints screen
v From the File Management screen

Listing from the Configuration Checkpoints screen


To view from the Configuration Checkpoints screen, select Administration
Configuration Configuration Checkpoints. This screen displays the list of saved
configuration checkpoints at the time by name and timestamp.
This section of the screen provides the following actions:
Rollback
Loads the configuration that is defined in the configuration checkpoint.
Remove
Deletes the checkpoint configuration from the chkpoints: directory.
Compare
Launches the Compare Configuration utility. For details, refer to
Comparing configurations on page 52.

Listing from the File Management utility


To view from the File Management utility, use the following procedure:
1. Select the File Management icon from the Control Panel.
2. Expand the chkpoints: directory.
Chapter 5. Managing the configuration of the appliance

49

Rolling back to a configuration checkpoint


To load the configuration that is defined in the configuration checkpoint, use the
following procedure:
1. Select Administration Configuration Configuration Checkpoints. This
screen displays the list of saved configuration checkpoints at the time by name
and timestamp.
2. Click Rollback.
3. Respond to WebGUI prompts.

Deleting configuration checkpoints


You can delete configuration checkpoint in one of the following ways:
v From the Configuration Checkpoints screen
v From the File Management screen

Deleting from the Configuration Checkpoints screen


To delete from the Configuration Checkpoints screen, use the following procedure:
1. Select Administration Configuration Configuration Checkpoints. This
screen displays the list of saved configuration checkpoints at the time by name
and timestamp.
2. Click Remove.
3. Respond to WebGUI prompts.

Deleting from the File Management screen


To delete from the File Management screen, use the following procedure:
1. Select the File Management icon from the Control Panel.
2. Expand the chkpoints: directory.
3. Select the check box beside the configuration checkpoint file.
4. Click Delete.
5. Respond to WebGUI prompts.

Importing configuration data


The import utility copies specified configuration data from your workstation to the
DataPower appliance.
Note: Exported configuration data should not be imported to an appliance with an
earlier release level. Between releases, configuration data for properties can
change. If you attempt to import configuration data from an appliance of a
later release level into an appliance of an earlier release level, the operation
might report success, but the configuration data might not be the same.
Therefore, use this utility to exchange configuration data among appliances
of the same release level.
While importing a configuration, you can:
v Set the local address bindings of services contained in the export package to
match the equivalent interfaces of the local device with the Rewrite Local
Service Addresses toggle (optional).
v Add, modify or delete values in the configuration package being imported
whose values match the defined match statement in a Deployment policy with
the Use Deployment Policy list (optional).

50

IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

Best practice when the goal is to add, modify or delete values in a configuration
package is to use a Deployment policy while importing the configuration package.
Use the following procedure to import configuration data.
1. Select Administration Configuration Import Configuration to display the
Import Configuration window.
a. Use the From radio buttons to specify the import format.
XML Config
Imports configuration data as XML files.
ZIP Bundle
Imports configuration data in compressed ZIP format.
b. Retain the selection of the File radio button.
c. Click Browse to select the file to import.
d. Retain the selection of (none) for the Use Deployment Policy list. For more
information, refer to the Configuring deployment policies on page 54.
e. Use the Rewrite Local Service Addresses toggle to control whether to
substitute IP addresses:
on

(Default) Allows local IP addresses to be rewritten.

off
Does not allow local IP addresses to be rewritten.
2. Click Next to display the Select Application Domains for Import window. If
there are no objects in the configuration you are importing, skip to step 6c on
page 52.
When importing from any domain other than default, the imported
configuration applies only to the current domain. The WebGUI might display
an error message when importing data that was exported from the default
domain.
3. Select the desired domains. To select all domains, click All. To deselect selected
domains, click None. If a selected domain does not exist on the appliance, as
indicated, it will be created.
4. Click Next to display the Import Object Selection List window.
5. Select the objects to import.
Note: Click Save Config to save the configuration for each domain that
contains imported objects or files.
To effectively complete an appliance import (restore), use the admin
account. The appliance to be restored must also first be re-initialized
through the command line.
6. Click Next to display the Import Summary window, which details the contents
of the target file. In some cases, the summary might indicate differences in file
versions.
Note: Warnings can appear on this screen that alert you to a range of possible
conflicts that the imported configuration might cause. Depending on the
warning, you might want to create a new application domain, or you
might want to choose not to overwrite objects or files.
a. Select each item to overwrite. To select all item, click All. To deselect
selected items, click None. Only selected items are imported.
b. Click Import to initiate file transfer.

Chapter 5. Managing the configuration of the appliance

51

At the completion of the import process, the WebGUI displays the Object
Import Results window, which details the results.
c. Click Done to close this window.
If more than one domain is being imported, the Import Summary window is
displayed for the next domain to import.

Managing changes in configuration data


You to create a report that lists the differences between two configurations.
Generally, the two configurations that are being compared are the persisted
configuration and the running configuration. However, you can compare either
configuration to a saved version of the configuration. These saved versions of the
configuration can be an exported configuration (XML format or ZIP format), a
backup configuration (ZIP format only), or a configuration checkpoint.
When you compare configurations, the report provides a list of objects that
changed between the two configurations and the changes that were made to these
objects. The report list how the configuration changed:
v An object was added
v An object was deleted
v An object was modified

Comparing configurations
To compare configurations, use the following procedure:
1. Select Administration Configuration Compare Configuration to display
the Configuration Comparison screen.
2. From the From list, select which configuration to be the first configuration
source; and from the To list, select which configuration to be the second
configuration source. The source for each of the configurations can be one of
the following:
Persisted Configuration
The last saved configuration on the appliance. This is the default in the
From list.
Running Configuration
The configuration that is currently running on the appliance. This is the
default in the To list.
Domain Configuration
The last saved or currently running domain configuration on the
appliance.
XML Configuration
The XML file that was created during an export operation. This file has
an .xcfg extension.
Export ZIP Bundle
A ZIP file that was created during an export operation. This file has a .zip
extension.
Backup ZIP Bundle
A ZIP file that was created during backup operation. This file has a .zip
extension.

52

IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

Checkpoint
A ZIP file that was created through a save checkpoint operation. This file
has a .zip extension and is in the chkpoint: directory.
3. When the source (From or To) is XML Configuration, Export ZIP Bundle, or
Backup ZIP Bundle, specify or browse for and select the configuration file.
Also, create or select a deployment Policy that can be used to accept, filter, or
modify a configuration.
4. When the source (From or To) is Checkpoint, select the checkpoint from the
Checkpoint list.
5. From the View list, select whether the report lists only changed objects between
the configurations or all objects in the configurations. The default is changed
objects only.
6. Click Run Comparison to generate the report.
The results are displayed below the horizontal rule.

Reading the change report


After running a comparison, the results are displayed below the horizontal rule.
Review the report to determine whether these changes should be saved to the
startup configuration, reverted to their original settings, saved to a configuration
checkpoint, or a combination of these operations.
Each item in the report contains the following data:
Type

The object type

Name The name of the object


Property
The name of the property
From

The value of the property as defined in the From source

To

The value of the property as defined in the To source

Change
The type of change between the From source and the To source. The
change is one of the following values:
v modified
v added
v deleted
Beside each item is a check box.

Reverting changes
After running a comparison and reviewing the results, you can revert select
changes or all changes between the two configurations. You can revert changes at
the property level only. To revert changes to select properties for an object, use the
object-specific configuration screens.
To revert changes, use the following procedures:
1. Determine which objects to revert:
v To revert select objects, select the check box beside those objects.
v To revert all objects, click Select All.
2. Click Undo Selected.
Chapter 5. Managing the configuration of the appliance

53

The results are displayed on a new screen.


If a selected object is a referenced object, it cannot be deleted until after the
deletion of its parent object. You might need to run the comparison multiple times
to delete referenced objects. For example, you cannot delete certificates that are
referenced by a validation credentials list until after the deletion of the validation
credentials list itself.

Configuring deployment policies


Deployment policies use fine-grained matching statements and clause types to
control the inclusion of configuration data from imported configuration packages.
Depending on the clause type, the deployment policy can perform the follow types
configuration management against the imported configuration package:
v Use an accepted configuration to include resources in the package that match
specified criteria.
v Use a filtered configuration to delete resources in the package that match specified
criteria.
v Use a modified configuration to modify resources in the package that match the
specified criteria. Modified configurations support the following actions:
Add

Adds the property with the identified value during the import.

Changed
Substitutes the value for the identified property during the import.
Deleted
Deletes the property during the import.
The processing sequence is as follows:
1. Process the accepted configuration, the whitelist, to always include resources
that match.
2. Process the filtered configuration, the blacklist, to always delete resources that
match.
3. Process the modified configuration to change the resources based on the
defined action type.

Creating a Deployment Policy object


A deployment policy is a sequence of accepted, filtered, and modified
configurations that respectively include, delete, or change configuration data in the
configuration package during the import. When specifying the matching statement,
you can use the builder or manually specify the statement.
v For details about using the builder to define the statement, refer to Using the
deployment policy builder on page 55.
v For details about manually specifying the statement, refer to Specifying the
matching statement on page 56.
Note: You cannot modify the administrative state of Deployment Policy objects.
To create a Deployment Policy object, use the following procedure:
1. Select Objects Configuration Management Deployment Policy to display
the catalog.
2. Click Add to display the configuration screen.

54

IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

3. Specify the name of the object in the Name field.


4. Specify a descriptive object-specific summary in the Comment field.
5. Define accept clauses.
a. Specify the matching statement in the Accepted Configuration field, or click
Build.
b. Click Add.
Repeat this step to define another accept clause.
6. Define filter clauses.
a. Specify the matching statement in the Filtered Configuration field, or click
Build.
b. Click Add.
Repeat this step to define another filter clause.
7. Define modify clauses on the Modified Configuration tab.
a. Click Add to display the Modified Configuration property window.
b. Specify the matching statement for the modify clause in the Configuration
Match field, or click Build.
c. Select the type of configuration modification from the Modification Type
list.
Add Configuration
Adds a configuration setting.
Delete Configuration
Deletes a configuration setting.
Change Configuration
Changes a configuration setting.
d. If adding a configuration, specify the name of the property to add in the
Configuration Property field.
e. If adding or changing a configuration, specify the value of the property to
add or modify in the Configuration Value field.
f. Click Save to return to the configuration screen.
Repeat this step to define another modify clause.
8. Click Apply to save the object to the running configuration.
9. Optionally, click Save Config to save the object to the startup configuration.

Using the deployment policy builder


Deployment policies include a builder to help create matching statements in the
following format:
address/domain/resource[?Name=resource-name
&Property=property-name&Value=property-value]

To access the builder, click Build. This button is associated with the following
properties:
v Accepted Configuration on the Main tab
v Filtered Configuration on the Main tab
v Configuration Match in the properties Window that the WebGUI displays after
clicking Add on the Modified Configuration tab
To create a matching statement with the builder, use the following procedure:
1. Click Build to open the builder.
Chapter 5. Managing the configuration of the appliance

55

2. Specify the IP address or host alias in the Device Address field. The value *
matches all IP addresses.
3. Select the name of the application domain from the Application Domain list.
The selection (none) matches all domains.
4. Select the resource type from the Resource Type list. The select (all resources)
matches all resource types.
5. Optionally specify a name match for a resource in the Name Match (PCRE)
field. This property limits the matching statement to resources of the specified
name. Use a PCRE to select groups of resource instances. For example, foo*
would match all resources with names that start with foo.
6. Optionally specify the name of the configuration property in the Configuration
Property field. This property limits the matching statement to resources of the
specified property.
7. Optionally specify the value for the configuration property in the
Configuration Value Match (PCRE) field. This property limits the matching
statement to resources of the specified value. Use a PCRE Match Expression to
select groups of configuration property values.
8. Click Save.
The statement is added to the list of matching statements.

Specifying the matching statement


Instead of using the builder, you can manually specify the matching statement.
Matching statements have the following format:
address/domain/resource[?Name=resource-name
&Property=property-name&Value=property-value]

address
Specifies the IP address or host alias. The value * matches all IP addresses.
domain Specifies the name of the application domain. The value * matches all
domains.
resource
Specifies the resource type. The value * matches all resource types.
Name=resource-name
Optionally specifies a name match for a resource. This property limits the
matching statement to resources of the specified name. Use a PCRE to
select groups of resource instances. For example, foo* would match all
resources with names that start with foo.
Property=property-name
Optionally specifies the name of the configuration property. This property
limits the matching statement to resources of the specified property.
Value=property-value
Optionally specifies the value for the configuration property. This property
limits the matching statement to resources of the specified property.
PCRE documentation is available at the following Web site:
http://www.pcre.org

56

IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

Appendix A. Referenced objects


AAA Policy
1. Select Objects XML Processing AAA policy to display the AAA Policy
catalog.
2. Click Add to display the AAA Policy Configuration (Main) screen. Use this
screen to provide policy-wide, global configuration data.
3. Click the Identify tab to define how to extract the identity.
4. Click the Authenticate tab to define how to authenticate the identity.
5. Click the Map Credentials tab to how to map the credential.
6. Click the Resource tab to define how to extract the resource.
7. Click the Map Resource tab to define how to map the resource.
8. Click the Authorize tab to define how to authorize the credential.
9. Optionally click the Post Processing tab to define post processing activities.
10. Optionally click the Namespace Mapping tab to define how to map
namespaces.
11. Optionally click the SAML Attributes tab to define SAML attributes.
12. Optionally click the LTPA User Attributes tab to define LTPA user attributes.
13. Optionally click the Transaction Priority tab to define the priority of
transactions.
14. Click Apply to save the object to the running configuration.
15. Optionally, click Save Config to save the object to the startup configuration.

Main tab
Name Specify the name of the object.
Admin State
Retain the default setting. To place the object in an inactive administrative
state, click disabled.
Comments
Specify a descriptive object-specific summary.
Authorized counter
Optionally select a message-count monitor. This object monitors and
controls incoming messages authorized by this AAA Policy. This counter
should Measure type XPath to allow the AAA Policy to increment the
counter on successful authorization. Refer to Count Monitor on page 99
for more information.
Rejected counter
Optionally select a message-count monitor This object monitors and
controls incoming messages rejected by this AAA Policy. This counter
should Measure type XPath to allow the AAA Policy to increment the
counter on rejected authorization. Click Rejected Counter Tool to configure
a counter for this purpose. Refer to Count Monitor on page 99 for more
information.
SAML Signature Validation Credentials
Optionally (and only if SAML-based identity extraction, authentication,
Copyright IBM Corp. 2002, 2009

57

and authorization is used by this AAA policy), select the Crypto Validation
Credentials used to validate digitally-signed SAML assertions from the
Credentials list. Refer to Working with Validation Credentials objects on
page 21 for more information.
SAML Message Signing Key
Optionally if SAML-based identity extraction, authentication, or
authorization is used by this AAA Policy, select a crypto key used to sign
SAML assertions. Refer to Defining Key objects on page 16 for more
information.
SAML Message Signing Certificate
Optionally if SAML-based identity extraction, authentication, or
authorization is used by this AAA Policy, select the matching crypto
certificate that is the public certificate associated with the private key
designated by the SAML message signing key. Refer to Defining
Certificate objects on page 13 for more information.
SAML Signing Message Digest Algorithm
Select the hash algorithm for SAML signing message. The default is sha1.
SAML Message Signing Algorithm
Select the algorithm to sign SAML messages. RSA and DSA are supported
by older releases. rsa is same as rsa-sha1, and dsa is same as dsa-sha1. The
default is rsa.
LDAP Suffix
Optional if LDAP authentication or authorization is used by this AAA
policy. Specify an LDAP base DN.
LDAP-based authentication implementations require an X.500 DN (for
example, cn=Alice,dc=datapower,dc=com) and a password. When
configuring LDAP for authentication, it is typical to create a base DN (such
as dc=datapower,dc=com) and then create one entry under this base for each
user.
To make LDAP authentication more usable, the AAA policy provides the
LDAP suffix. Set the LDAP suffix to the base name under which user
entries are found. If the LDAP suffix is not an empty string, the AAA
Policy builds an X.509-compliant DN by prepending cn= to the surname
and appending a comma followed by the value of the LDAP suffix. Hence,
an LDAP suffix of dc=datapower,dc=com, the user name Alice is mapped to
the DN cn=Alice,dc=datapower,dc=com.
Log Allowed
By default, the AAA policy generates log messages at the indicated level
for every access allowed. Set to off to change this behavior.
Log Allowed Level
When Log Allowed set to on, change the default level. Log messages
generated for each access allowed by this AAA policy will be set at the
level selected.
Log Rejected
By default, the AAA policy generates log messages at the indicated level
for every access rejected. Set to off to change this behavior.
Log Rejected Level
When Log Rejected set to on, change the level. Log messages generated
for each access rejected by this AAA policy will be set at the level selected.

58

IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

Note: Log targets capture messages at or above the level configured for
the target. The higher the level, the more likely one or more log
targets will catch the message. To be sure log targets capture these
AAA messages, coordinate these levels.
WS-Trust Encryption Recipient Certificate
When generating a WS-Trust token for a secret key (such as a
WS-SecureConversation token), select the key to encrypt the initial secret.
SAML Artifact Mapping File
This file contains a map of SAML artifact source identifiers to artifact
retrieval endpoints. This property is required only when artifacts will be
retrieved from multiple endpoints and the source identifiers for these
endpoints are encoded in the artifact itself (per the SAML specification). If
there is only one artifact retrieval URL, it can be specified by the SAML
artifact responder URL in the authentication phase.
Ping Identity Compatibility
Select whether to enable (on) or disable (off) Ping Identity compatibility.
Enable Ping Identity compatibility when using SAML for authentication or
authorization.
SAML 2.0 Metadata File
This file contains information about the various SAML Authorities that
might be used for SAML 2.0 authentication and authorization. From the
list, select a file, and click Upload to upload a file.
The file must conform to the SAML 2.0 metadata schema
(xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata").
DoS Flooding-Attack Valve
Specifies the number of times to perform the same XML processing per
user request. Use a value in the range of 1 through 1000. The default is 3.
This property limits the number of times to perform the same XML
processing per user request. XML processing includes encryption,
decryption, message signing, and signature validation. At this time, the
AAA Policy supports this property in the following cases:
v Identity extraction when the method is Subject DN from Certificate in
the Messages signature
v Authentication when the method is Validate the Signer Certificate for a
Digitally Signed Message
When used with the value of 1, the AAA Policy extracts the first signature
and its first reference from the security header and ignores all other
signatures or signing references. If the security header contains more
signatures or a single signature contains more signing references, these
signatures and signing references are ignored. During signature
verification, the processing fails if the needed signature is not part of
extracted identity.
For example if dos-valve is 2 and the needed information to verify the
signature was the third signing reference, the verification would fail.
However if the information was the second signing reference, the
verification would succeed.
LDAP Version
Select the LDAP protocol version (2, the default version, or 3) used when
accessing the authorization server.

Appendix A. Referenced objects

59

Enforce Actor/Role for WS-Sec Message


Most of the times a WS-Security message has a S11:actor or S12:role
attribute for its wsse:Security header, we can enforce those attributes
when AAA tries to use wsse:Security header, for example, there should be
only one wsse:Security element having same actor/role, and AAA should
only process the wsse:Security header for the designated Actor/Role
Identifier. This setting takes effect for all AAA processing except post
processing. The default is on.
WS-Sec Actor/Role Identifier
When enforcing WS-Security Actor/Role, specify the identifier.
Continue with defining the identity extraction method.

Identity tab
The initial processing performed by an AAA Policy consists of extracting
information from an incoming message and its protocol envelope(s) about the
claimed identity of the service requester.
Use the Identity panel to specify the method or methods used by the AAA Policy
to extract the identity claimed by the service requester. Click the Identity tab to
display the AAA Policy Configuration (Identity) screen.
Use the check boxes to enable (on) or disable (off) one or more identification
methods.
HTTPs Authentication header
The claimed identity of the requester is extracted from the HTTP
Authorization header (name and password).
If selected, the WebGUI prompts for the following property:
HTTPs Basic Authentication Realm
The name of the HTTP Basic Authentication Realm as described by
RFC 2617, HTTP Authentication: Basic and Digest Access Authentication.
A browser might display this name to help determine which
credentials to supply.
UserName element from WS-Security header
The claimed identity of the requester is extracted from the WS-Security
UserName element (name and password) contained in a SOAP header.
BinarySecurityToken element from WS-Security header
The claimed identity of the requester is extracted from the WS-Security
BinarySecurityToken element (using the tokens string value as the claimed
identity) contained in a SOAP header.
WS-SecureConversation Identifier
The claimed identity of the requester is extracted from a
WS-SecureConversation Identifier.
WS-Trust Base or Supporting Token
The claimed identity of the requester is extracted from a WS-Trust Base or
Supporting token.
Kerberos AP-REQ from WS-Security header
The claimed identity of the requester is extracted from a Kerberos AP-REQ
contained in the WS-Security header.

60

IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

Kerberos AP-REQ from SPNEGO token


The claimed identity of the requester is extracted from a Kerberos AP-REQ
contained in the SPNEGO token.
Subject DN of the SSL Client Certificate from the Connection Peer
The claimed identity of the requester is extracted from the SSL client
certificate presented during the SSL handshake. If this is checked, the
Validation Credentials for Signing Certificate appears.
Name from SAML attribute assertion
The claimed identity of the requester is extracted from a SAML assertion that
contains a SAML attribute statement. The name contained in the Subject
element of the attribute statement is used as the claimed identity.
Name from SAML authentication assertion
The claimed identity of the requester is extracted from a SAML assertion that
contains a SAML authentication statement. The name contained in the Subject
element of the authentication statement is used as the claimed identity.
SAML artifact
The claimed identity of the requester is extracted from a SAML artifact.
Client IP address
The clients IP address is used for identity extraction.
Subject DN from the certificate in the messages signature
The claimed identity of the requester is extracted from a certificate used to
validate a digitally-signed message verify the signature validity, if the
signature is valid, use the Subject DN extracted from the certificate associated
with the signature as the claimed identity. If this is checked, the Validation
Credentials for Signing Certificate field is displayed.
If selected, the WebGUI prompts for the following property:
Validation Credentials for Signing Certificate
Select the Validation Credentials List used to validate the presented
certificate. Refer to Defining Identification Credentials objects on
page 15 for more information.
Token extracted from the message
The claimed identity of the requester is extracted using an XPath expression.
If this is checked, the XPath Expression field is displayed. If selected, the
WebGUI prompts for the following property:
XPath expression
Provide the operative XPath expression. The XPath expression is
applied to the entire message.
If you require name spaces in the XPath expression, refer to
Namespace Mapping tab on page 80 for procedural and
configuration details.
Token extracted as Cookie value
The claimed identity of the requester is extracted from a Cookie value. If
selected, the WebGUI prompts for the following property:
Cookie name
Specify the cookie name.
LTPA Token
The claimed identity of the requester is extracted from an LTPA (Lightweight
Third Party Authentication) token value. LTPA tokens, which are opaque
Appendix A. Referenced objects

61

signed and encrypted strings, are carried via HTTP, specifically in the
Set-Cookie response and Cookie request headers.
Refer to Understanding LTPA for more information.
Custom template
The claimed identity of the requester is extracted by a custom or proprietary
identification resource (for example, a style sheet). If selected, the WebGUI
prompts for the following property:
Custom URL
Specify the local or remote URL of the identification resource.
Click Apply to commit AAA Policy properties.
Optionally, click Save Config to save the object to the startup configuration.

Authenticate tab
After extracting the claimed identity of the service requester, an AAA Policy
authenticates the claimed identity. The authentication process can use internal or
external resources. Use the Authenticate panel to designate the authentication
method.
1. Click the Authenticate tab to display the AAA Policy Configuration
(Authenticate) screen.
2. From the Method list, select an authentication method.
Accept a SAML Assertion with a Valid Signature
The requester is authenticated by a SAML assertion with a valid
signature.
Accept an LTPA token
The requester is authenticated by an encrypted LTPA token. If selected,
the WebGUI prompts for the following property values:
LTPA Token Versions
Specifies the LTPA formats supported for authentication purposes.
Use the check boxes to specify the LTPA versions that are
supported for authentication. Select at least one version, or all
LTPA-based authentication will fail.
Because the LTPA token must be decrypted before authentication,
the following properties identify the needed cryptographic
resources.
LTPA Key File
Provide the name of the file that contains the cipher keys to be
used for encryption and decryption.
LTPA Key File Password and Confirm LTPA Key File Password
Provides the cleartext password to the LTPA key file.
Refer to Understanding LTPA for more information.
Bind to Specified LDAP Server
(Default) The requester is authenticated by an LDAP server. If selected,
the WebGUI prompts for the following properties:
Host

62

Specify the IP address or domain name of the LDAP


authentication server.

IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

Port

Specify the LDAP authentication server port number. If not


supplied, defaults to the canonical port number.

LDAP Prefix
Optionally specify an LDAP Prefix name. This string is prepended
to the identity extracted before submission to the LDAP server.
The default is cn=.
This property is relevant when the Search for DN is off.
LDAP Suffix
Optionally specify an LDAP Suffix name. This suffix string is
appended to the identity extracted before submission to the LDAP
server. For example, o=datapower.com.
This property is relevant when the Search for DN is off.
LDAP Load Balancer Group
Optionally select a Load Balancer Group. If you select a group,
LDAP queries will be load balanced in accordance with the
settings in the group. Load balancing allows for failover. Refer to
Load Balancer Group on page 101 for more information.
When specified, this property overrides the settings for the Host
and Port properties.
SSL Proxy Profile
Select an SSL Proxy Profile to provide a secure connection to
remote authentication server. Retain the default value to use a
non-SSL connection.
LDAP Bind DN
Specify the Distinguished Name for the LDAP bind operation.
LDAP Bind Password and Confirm LDAP Bind Password
Specify and confirm the password for the LDAP bind operation.
LDAP Search Attribute
Specify the name of the LDAP attribute that contains the cleartext
password. The default is userPassword.
This property is meaningful only when the identity extraction
method is Password-carrying UsernameToken Element from
WS-Security Header and the <Username> element in the header
has the Type attribute set to PasswordDigest. In this case, the
LDAP server returns the text in the specified LDAP attribute for
the user in the UsernameToken. If the hashed value of the
returned text does not match the value in the <Password> element,
authentication fails.
Search for DN
Indicate whether to perform an LDAP search retrieve the DN of
the user.
on

Enables an LDAP search for the users group. The login


name of the user along with the LDAP Search Parameters
will be used as part of an LDAP search to retrieve the
users DN.

off

(Default) Disables an LDAP search for the users group.


The login name of the user along with the LDAP prefix
and the LDAP suffix will be used to construct the users
DN.
Appendix A. Referenced objects

63

v If on, the WebGUI displays the following field.


LDAP Search Parameters
Select the LDAP Search Parameters from the list. Refer to
Defining an LDAP Search Parameters object on page 100
for detail.
v If off, the WebGUI removes the following fields:
LDAP Prefix
LDAP Suffix
Contact a SAML Server for a SAML Authentication Statement
The requester is authenticated by issuing a SAML Authentication Query
to the appropriate server. If selected, the WebGUI prompts for the
following properties:
SAML Authentication Query Server
Specify the URL of the SAML Authentication Query Server that
can authenticate the requesting entity and supply a SAML
Authentication Assertion.
SAML Version
Select the SAML version used for authentication. Versions 1.0, 1.1
and 2.0 are supported. The version selected affects the format of
the messages sent to SAML authorities.
SSL Proxy Profile
Select an SSL Proxy Profile to provide a secure connection to
remote authentication server. Retain the default value to use a
non-SSL connection.
Contact a WS-Trust Server for a WS-Trust Token
The requester is authenticated by a WS-Trust token obtained from a
WS-Trust server. If selected, the WebGUI prompts for the following
properties:
WS-Trust Token Server
Specify the URL of the WS-Trust server that can authenticate the
requesting entity and supply a WS-Trust token.
SSL Proxy Profile
Select an SSL Proxy Profile to provide a secure connection to
remote authentication server. Retain the default value to use a
non-SSL connection.
The following properties are relevant for attaching WS-Policy, not for
AAA authentication.
Require Client Entropy
Indicates whether to require client entropy as key material in the
WS-Trust request.
on

Requires client entropy. The DataPower appliance sends


an entropy element to the WS-Trust server as part of the
security token request exchange. Use the WS-Trust
Encryption Certificate property to determine how to
include the key material in the request.

off

(Default) Does not require client entropy.

When required, specify the size of the client entropy in bytes in


the Client Entropy Size field. The size refers to the length of the

64

IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

client entropy before Base64 encoding. Use an integer in the range


of 8 through 128. The default is 32.
Require Server Entropy
Indicates whether to require server entropy in the WS-Trust
response.
on

Requires server entropy. The WS-Trust server must return


an entropy element to the DataPower appliance as part of
the security token request exchange.

off

(Default) Does not require server entropy.

When required, specify the minimum allowable size of the


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

Generates a WS-Trust RequestSecurityTokenCollection.

off

(Default) Generates a WS-Trust RequestSecurityToken.

Require AppliesTo SOAP Header


Indicates whether to generate a WS-Addressing AppliesTo header
as part of the security token request exchange.
on

Generates a WS-Addressing AppliesTo header.

off

(Default) Does not generate a WS-Addressing AppliesTo


header.

When required, specify the value for the AppliesTo header in the
AppliesTo Header field.
WS-Trust Encryption Certificate
Optionally select a Crypto Certificate to encrypt WS-Trust
elements in the request. If selected, he public key of the certificate
encrypts the client entropy key material for the recipient. If blank,
the WS-Trust BinarySecret element contains the entropy material.
In this case, use an SSL Proxy Profile to secure the message
exchange with the WS-Trust server.
Contact ClearTrust Server
The requester is authenticated via a ClearTrust server. If selected, the
WebGUI prompts for the following properties:
ClearTrust Server URL
Provide a local or remote URL that locates the authentication
resource.
SSL Proxy Profile
Select an SSL Proxy Profile to provide a secure connection to
remote authentication server. Retain the default value to use a
non-SSL connection.
Contact Netegrity SiteMinder
The requester is authenticated by a Netegrity server. If selected, the
WebGUI prompts for the following properties:
Appendix A. Referenced objects

65

Host

Specify the IP address or domain name of the Netegrity


authentication server.

Port

Specify the Netegrity authentication server port number.

Netegrity Base URI


Specify the appropriate URI string.
SSL Proxy Profile
Select an SSL Proxy Profile to provide a secure connection to
remote authentication server. Retain the default value to use a
non-SSL connection.
Contact NSS for SAF Authentication
The requester is authenticated by the SAF. If selected, the WebGUI
prompts for the following property:
z/OS NSS Client Configuration
Select the z/OS NSS Client object that specifies the details for
connecting to the NSS server. Refer to z/OS NSS Client on page
144 for more information.
Contact Tivoli Access Manager
The requester is authenticated by a Tivoli Access Manager. A Tivoli Access
Manager object must exist and be in an enabled state for this method to
succeed. Refer to IBM Tivoli Access Manager on page 88 for more
information.
Custom Template
The requester is authenticated by a custom/proprietary resource (for
example, a style sheet). If selected, the WebGUI prompts for the following
property:
Custom URL
Provide a local or remote URL that locates the authentication
resource.
Pass Identity Token to the Authorize Step
The requester is not authenticated by this AAA policy, the request is
passed to the authorization server for disposition.
Retrieve SAML Assertions Corresponding to a SAML Browser Artifact
The requester is authenticated by a SAML artifact. If selected, the WebGUI
prompts for the following properties:
SAML Artifact Responder
Specify the URL of the SAML Artifact Responder that can
authenticate the requesting entity using the artifact supplied.
SAML Version
Select the SAML version used for authentication. Versions 1.0, 1.1
and 2.0 are supported. The version selected affects the format of
the messages sent to SAML authorities.
SAML 2 Issuer
Specify a value that appears in the SAML <samlp:Issuer> element
after the SAML Artifact has been authenticated. This element is
included in the information delivered to the Authorize phase.
SSL Proxy Profile
Select an SSL Proxy Profile to provide a secure connection to
remote authentication server. Retain the default value to use a
non-SSL connection.

66

IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

Use an Established WS-SecureConversation Security Context


The requester is authenticated by a WS-SecureConversation token
contained in the request.
User certificate from BinarySecurityToken
The requester is authenticated by a certificate that is included with a
BinarySecurityToken. If selected, the WebGUI prompts for the following
property:
X.509 BinarySecurityToken Validation Credentials
Select the Validation Credentials to validate the X.509 certificate in
the BinarySecurityToken. Refer to Working with Validation
Credentials objects on page 21 for more information.
Use DataPower AAA Info File
The requester is authenticated by an XML file. If selected, the WebGUI
prompts for the following properties:
AAA Info File URL
Specify the location of the XML file used for authentication
purposes.
To identify a local resource, use the form store:///authfile.xml. To
examine a sample AAA Info file, open store:///authfile.xml.
Use specified RADIUS Server
The requester is authenticated by a RADIUS server.
Validate a Kerberos AP-REQ for the Correct Server Principal
The requester is authenticated via a Kerberos AP-REQ contained in the
WS-Security header. If selected, the WebGUI prompts for the following
properties:
Kerberos principal name
Provide the name part of the server identity. This value is the
server name that is contained in the sname field of the
unencrypted portion of the Kerberos ticket.
Kerberos keytab
Select the Kerberos Keytab File object. This field is required.
Validate the Signer Certificate for a Digitally Signed Message
The signature requires validation. If selected, the WebGUI prompts for the
following properties:
Signature Validation Credentials
Use a Validation Credentials List.
XPath Expression
Use the specified XPath expression.
Validate the SSL Certificate from the Connection Peer
The requester is authenticated via its client SSL credentials. If selected, the
WebGUI prompts for the following property:
SSL Client Validation Credentials
Select the Validation Credentials List used to validate offered
client certificates. Refer to Working with Validation Credentials
objects on page 21 for more information.
The following inputs are displayed for all methods.

Appendix A. Referenced objects

67

Cache authentication results


Select the caching strategy. By default, authentication information from
remote resources is cached for a period of three seconds. On
authentication failure, authentication information is removed from the
cache.
Absolute
(Default) Caches all authentication data with an explicit TTL
(time-to-live), specified by the Cache Lifetime property.
Disabled
Disables caching of authentication data
Maximum
Compares the explicit TTL with the received TTL (if any). Use the
data-specific TTL if it is less than the explicit TTL. Otherwise, use
the explicit value.
Minimum
Compares the explicit TTL specified by the Cache Lifetime
property with the received TTL (if any). Use the data-specific TTL
if it is greater than the explicit TTL. Otherwise, use the explicit
value.
Cache Lifetime
Specify the explicit TTL in seconds. This defaults to 3.
3. Click Apply to commit AAA Policy properties.
4. Optionally, click Save Config to save the object to the startup configuration.

Map Credentials tab


After receiving authentication credentials, an AAA Policy can optionally map these
credentials. It might be necessary to map credentials presented by an
authentication method to a format congruent with a different authorization
method; for example, mapping an authenticated account name/password to an
LDAP group. To perform such credentials mapping, an AAA Policy uses custom
XML or XPath resources, which you identify during policy definition.
If credentials mapping is necessary, use the Map Credentials panel to designate the
mapping method and resource.
1. Click the MapCredentials tab to display the AAA Policy Configuration (Map
Credentials) screen.
2. From the Method list, select a credentials mapping method.
Custom
The authentication credentials are mapped by a custom/proprietary
resource (for example, a style sheet). If selected, the WebGUI prompts
for the following property:
Custom URL
Provide a local or remote URL that locates the mapping
resource.
None

Authentication credentials are not mapped.

Credentials from Tivoli Federated Identity Manager


The authentication credentials are mapped by Tivoli Federated Identity
Manager (TFIM). If selected, the WebGUI prompts for the following
property:

68

IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

TFIM Configuration
Select an existing TFIM object. Refer to IBM Tivoli Federated
Identity Manager on page 90 for more information.
Credentials from WS-SecureConversation Token
The authentication credentials are mapped via a
WS-SecureConversation exchange.
AAA Info File
The authentication credentials are mapped using an XML file as the
mapping resource. If selected, the WebGUI prompts for the following
property:
AAA Info File URL
Specify the location of the XML file used for authentication
purposes.
To identify a local resource, use the form store:///authfile.xml.
Open store://authfile.xml to examine a sample AAA Info file.
Apply XPath Expression
The authentication credentials are mapped using an XPath expression
as the mapping resource. If selected, the WebGUI prompts for the
following property:
XPath Expression
Specify the operative XPath expression.
3. Click Apply to commit AAA Policy properties.
4. Optionally, click Save Config to save the object to the startup configuration.

Resource tab
After authenticating a client, an AAA policy identifies the specific resource being
requested by that client.
Use the Resource panel to designate the methods used to identify the resource
requested by an authenticated client.
1. Click the Resource tab to display the AAA Policy Configuration (Resource)
screen.
2. Use the check boxes to enable (on) or disable (off) one or more resource
identification methods.
URL sent to back end
The identity of the requested resource is extracted from the (possibly
rewritten) URL sent to the server. The URL can be rewritten by a URL
Rewrite Policy attached to the service or by another processing action
before the AAA Policy.
URL sent by client
The identity of the requested resource is extracted from the original URL
sent by the client. This URL has not been rewritten.
URI of toplevel element in the message
The identity of the requested resource is extracted from the namespace of
the top level application element
Local name of request element
The identity of the requested resource is extracted from the simple name
of the top level application element

Appendix A. Referenced objects

69

HTTP operation (GET/POST)


The identity of the requested resource is extracted from the HTTP method
of the client request
XPath expression
The identity of the requested resource is extracted from the client request
by an XPath expression. If selected, the WebGUI prompts for the
following property:
XPath Expression
Specify the operative XPath expression.
3. Click Apply to commit AAA Policy properties.
4. Optionally, click Save Config to save the object to the startup configuration.

Map Resource tab


After identifying the requested resource, it might be necessary to map extracted
resource identities to a form compatible with the authorization method.
If resource identity mapping is necessary, use the Map Resource panel to designate
the mapping method.
1. Click the Map Resource tab to display the AAA Policy Configuration (Map
Resource) screen.
2. From the Method list, select a resource mapping method.
Custom
The identified resource is mapped by a custom/proprietary resource (for
example, a style sheet). If selected, the WebGUI prompts for the following
property:
Custom URL
Provide a local or remote URL that locates the mapping resource.
None
Identified resources are not mapped.
AAA Info File
The identified resource is mapped using an XML file as the mapping
resource. If selected, the WebGUI prompts for the following property:
AAA Info File URL
Specify the location of the XML file used for authentication
purposes.
To identify a local resource, use the form store:///authfile.xml. To
examine a sample AAA info file, open store:///authfile.xml.
Apply XPath Expression
The identified resource is mapped using an XPath expression as the
mapping resource. If selected, the WebGUI prompts for the following
property:
XPath Expression
Specify the operative XPath expression.
3. Click Apply to commit AAA Policy properties.
4. Optionally, click Save Config to save the object to the startup configuration.

70

IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

Authorize tab
After authenticating a service requester and extracting the identity of the requested
resource, an AAA Policy next authorizes the client, that is, determines if the
authenticated service requester is allowed access to the requested resource. The
authorization process can use internal or external resources. Use the Authorize
panel to designate the authorization method.
1. Click Authorize to display the AAA Policy Configuration (Authorize) screen.
2. From the Method list, select an authentication method.
Allow Any Authenticated Client
Any authenticated used is authorized.
Contact ClearTrust Server
The requester is authorized via a ClearTrust server. If selected, the
WebGUI prompts for the following properties:
ClearTrust Server URL
Specify a local or remote URL that locates the authorization
resource.
SSL Proxy Profile
Select an SSL Proxy Profile to provide a secure connection to remote
authorization server. Retain the default value to use a non-SSL
connection.
Custom Template
The requester is authorized by a custom/proprietary resource (for
example, a style sheet). If selected, the WebGUI prompts for the following
property:
Custom URL
Specify a local or remote URL that locates the authorization
resource.
Check for Membership in an LDAP Group
The requester is authorized by an LDAP server. If selected, the WebGUI
prompts for the following properties:
Host
Specify the IP address or domain name of the LDAP authentication
server.
Port Specify the LDAP authentication server port number. If not
specified, defaults to the canonical port number.
Group DN
Specify the Distinguished Name of the LDAP group.
LDAP Load Balancer Group
Optionally select a Load Balancer Group. If a group is selected,
LDAP queries will be load balanced in accordance with the settings
in the group. Load balancing allows for failover when using LDAP
for authorization.
LDAP Bind DN
Specify the Distinguished Name for the LDAP Bind.
LDAP Bind Password and Confirm Bind Password
Specify and confirm the password for the LDAP Bind.

Appendix A. Referenced objects

71

LDAP Group Attribute


Specify a GroupAttribute string. The authorizing identity must be
presented as the value that corresponds to the attribute.
SSL Proxy Profile
Select an SSL Proxy Profile to provide a secure connection to remote
authorization server. Retain the default value to use a non-SSL
connection.
LDAP Search Scope
Select the depth of the LDAP search.
Base
Specifies that the search matches only the input itself
One Level
Specifies that the search matches the search input and any
object that is one-level below
Subtree
(Default) Specifies that the search matches the input and any
descendents
LDAP Search Filter
Optionally enable the specification of an LDAP search filter which
allows tailored LDAP searches. LDAP filter syntax is defined in RFC
2254, The String Representation of LDAP Search Filters.
Contact Netegrity SiteMinder
The requester is authorized by a Netegrity server. If selected, the WebGUI
prompts for the following properties:
Host
Specify the IP address or domain name of the Netegrity
authorization server.
Port Specify the Netegrity authorization server port number.
Netegrity Base URI
Specify the appropriate URI string.
Netegrity Operation Name Extension
The Netegrity Base URI is combined with the Host, Port, and
Netegrity Operation Name Extension configuration items to form
the URL for attempting Netegrity authentication. The URL is of the
following form:
http://Host:Port/NetegrityBaseURI/operationNetegrityOpNameExtension

where NetegrityOpNameExtension is directly appended to the


operation name.
SSL Proxy Profile
Select an SSL Proxy Profile to provide a secure connection to remote
authorization server. Retain the default value to use a non-SSL
connection.
Contact NSS for SAF Authorization
The requester is authorized by the SAF. If selected, the WebGUI prompts
for the following properties:

72

IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

z/OS NSS Client Configuration


Select the z/OS NSS Client object that specifies the details for
connecting to the NSS server. Refer to z/OS NSS Client on page
144 for more information.
Default Action
Select the default action to specify the access level to the resource.
The default is r (Read). The value specified by this property can
be programmatically overridden by setting the
var://context/AAA/az-zosnss-operation variable to one of the
valid values.
a (Alter)
c (Control)

r (Read)
u (Update)

Always Allow
All messages are forwarded to the backend server.
Generate a SAML Attribute Query
The requester is authorized by a SAML attribute query/response
exchange between the DataPower appliance and a SAML server. If
selected, the WebGUI prompts for the following properties:
URL
Specify the location of the SAML server.
SAML Match
Select the minimum authorization criteria.
All

Authorization requires the presence of all configured SAML


attributes

All-Values
Authorization requires that all configured attribute names
and values be present in the SAML attribute statement
Any

Authorization requires the presence of a single SAML


attribute

Any-Value
Authorization requires that a single configured attribute
name and value be present in the SAML attribute statement
XPath Authorization requires that SAML server responses are
evaluated with an XPath expression
SAML XPath
If SAML Match is XPath, specify the operative XPath expression.
SAML Name Qualifier
Optionally specify the value of the NameQualifier attribute of the
NameIdentifier in the generated SAML query. Some SAML
implementations require this value to be present.
SAML Version
Select the SAML protocol version to use when employing SAML for
authorization. Versions 1.0, 1.1 and 2.0 are supported. The version
selected affects the format of the messages sent to SAML authorities.

Appendix A. Referenced objects

73

SSL Proxy Profile


Select an SSL Proxy Profile to provide a secure connection to remote
authorization server. Retain the default value to use a non-SSL
connection.
Generate a SAML Authorization Query
The requester is authorized by a SAML authorization query/response
exchange between the DataPower appliance and a SAML server. If
selected, the WebGUI prompts for the following properties:
URL
Specify the location of the SAML server.
SAML Match
Select the minimum authorization criteria.
All

Authorization requires the presence of all configured SAML


attributes

All-Values
Authorization requires that all configured attribute names and
values be present in the SAML attribute statement
Any Authorization requires the presence of a single SAML attribute
Any-Value
Authorization requires that a single configured attribute name
and value be present in the SAML attribute statement
XPath
Authorization requires that SAML server responses are
evaluated with an XPath expression
SAML XPath
If SAML Match is XPath, specifies the operative XPath expression
SAML Name Qualifier
Optionally specify the value of the NameQualifier attribute of the
NameIdentifier in the generated SAML query. Some SAML
implementations require this value to be present.
SAML Version
Select the SAML protocol version to use when employing SAML for
authorization. Versions 1.0, 1.1 and 2.0 are supported. The version
selected affects the format of the messages sent to SAML authorities.
SSL Proxy Profile
Select an SSL Proxy Profile to provide a secure connection to remote
authorization server. Retain the default value to use a non-SSL
connection.
Contact Tivoli Access Manager
The requester is authorized by a Tivoli Access Manager (TAM). A TAM
object must exist for this method to succeed. Refer to IBM Tivoli Access
Manager on page 88 for more information.
Use SAML Attributes from Authentication
The requester is authorized by the same SAML authentication or attribute
statements used to authenticate the requester. If selected, the WebGUI
prompts for the following property:
SAML Match
Select the minimum authorization criteria.

74

IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

All

Authorization requires the presence of all configured SAML


attributes

All-Values
Authorization requires that all configured attribute names
and values be present in the SAML attribute statement
Any

Authorization requires the presence of a single SAML


attribute

Any-Value
Authorization requires that a single configured attribute
name and value be present in the SAML attribute statement
XPath Authorization requires that SAML server responses are
evaluated with an XPath expression
SAML XPath
If SAML Match is XPath, specifies the operative XPath expression
Use XACML Authorization Decision
The requester is authorized by an XACML Policy Decision Point (PDP),
which might be configured and located on the DataPower appliance, or
which might reside on a remote network appliance. If selected, the
WebGUI prompts for the following properties:
XACML Version
Select the XACML version (1.0 or 2.0, the default) used for
communications between the PDP and this AAA Policy, acting as an
XACML Policy Enforcement Point (PEP).
PEP Type
Select how the AAA Policy, acting as an XACML PEP, processes the
PDP authorization response.
Base PEP
If the XACML response to the authorization request is
permit, the client is authorized; if the permit response is
accompanied by obligations, the client is authorized only if
the AAA Policy, acting as a PEP, can understand and
discharge the conditions.
If the XACML response to the authorization request is deny,
the client is rejected; if the deny response is accompanied by
obligations, the client is rejected only if the AAA Policy,
acting as a PEP, can understand and discharge the
conditions.
Deny-biased PEP
If the XACML response to the authorization request is
permit, the client is authorized; if the permit response is
accompanied by obligations, the client is authorized only if
the AAA Policy, acting as a PEP, can understand and
discharge the conditions.
Any other XACML response results in the clients rejection.
Permit-biased PEP
If the XACML response to the authorization request is deny,
the client is rejected; if the deny response is accompanied by

Appendix A. Referenced objects

75

obligations, the client is rejected only if the AAA Policy,


acting as a PEP, can understand and discharge the
conditions.
Any other XACML response results in the clients
authorization.
Use On Box PDP
Use this toggle to specify the location of the PDP.
on

(Default) Specifies use of a local PDP. If selected, the WebGUI


displays the following property:
Policy Decision Point
Select the PDP to provide authorization services for the
AAA Policy. Refer to XACML Policy Decision Point on
page 95 for more information.

off

Specifies the use of a remote XACML PDP. If selected, the


WebGUI displays the following property value:
URL of External Policy Decision Point
Specify the URL to which to send XACML-based
authorization requests.
PDP Requires SAML 2.0
Use this toggle to force the use of the SAML2.0 Profile.
Meaningful only when the XACML version is 2.0.
on

Forces the use of the SAML2.0 profile.

off

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


profile.

SOAP Enveloping
Use the toggle to determine whether the external PDP
requires SOAP enveloping. If the custom binding style
sheet generated SOAP enveloping, retain the default
setting.
on

Before the PEP posts the context request to the


external PDP with the HTTP POST method, the
SOAP Body of the content request is wrapped by
the <xacml-samlp:XACMLAuthzDecisionQuery> SAML
Profile element.

off

(Default) The PEP posts the context request to the


external PDP with the HTTP POST method.

This property can be combined with the PDP Requires


SAML 2.0 property when the XACML request is
wrapped by the <xacml-samlp:XACMLAuthzDecisionQuery>
SAML Profile element.
AAA XACML Binding Method
Retain the default value, which is the only supported option.
Custom Stylesheet to Bind AAA and XACML
Select the custom style sheet that maps the AAA result or input
message to the XACML context request. This context request
contacts the PDP for an XACML decision.

76

IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

Obligation Fulfillment Custom Stylesheet


Specify the custom style sheet to parse any obligation that
accompany an authorization decision that is received from the PEP.
AAA Info File
The requester is authorized by an XML file. If selected, the WebGUI
prompts for the following property:
AAA Info File URL
Specify the location of the XML file used for authorization purposes.
To identify a local resource, use the form store:///authfile.xml. To
example a sample AAA Info file, open store:///authfile.xml.
The following inputs appear for all methods.
Cache authorization results
Select the caching strategy. By default, authorization information from
remote resources is cached for a period of three seconds. On authorization
failure, authorization information is removed from the cache.
Absolute
(Default) Caches all authorization data with an explicit TTL
(time-to-live), specified by the Cache Lifetime property
Disabled
Disables caching of authorization data
Maximum
Compares the explicit TTL with the received TTL (if any). Use the
data-specific TTL if it is less than the explicit TTL. Otherwise, use
the explicit value.
Minimum
Compares the explicit TTL (specified by the Cache Lifetime
property) with the received TTL (if any). Use the data-specific TTL if
it is greater than the explicit TTL. Otherwise, use the explicit value.
Cache Lifetime
Specify the explicit TTL in seconds. Defaults to 3.
3. Click Apply to commit AAA Policy properties.
4. Optionally, click Save Config to save the object to the startup configuration.

Post Processing tab


After authorizing the client, an AAA Policy can perform postprocessing activities.
For example, it could generate a SAML authentication assertion and place that
assertion in the header of the message.
Use the Post Processing panel to specify postprocessing behavior.
1. Click the Post Processing tab to display the AAA Policy Configuration (Post
Processing) screen.
2. Provide the following inputs:
Run custom post processing stylesheet
Select whether to enable (on) or disable (off) custom (style sheet-based)
postprocessing. If selected, the WebGUI prompts for the following
property:

Appendix A. Referenced objects

77

Custom URL
If custom post processing is enabled, specify a local or remote
URL that locates the style sheet.
Generate SAML Authentication Assertion
Select whether to enable (on) or disable (off) the generation of SAML
authentication assertions. If selected, the WebGUI prompts for the
following properties:
Issuer for generated SAML assertions
If generation of SAML authentication assertions is enabled,
Optionally specify the assertion originator or retain the default
value, XS.
SAML Name Qualifier
If generation of SAML authentication assertions is enabled,
Optionally specify a NameQualifier as defined by the SAML
protocol version selected.
SAML Version
If generation of SAML authentication assertions is enabled,
select the SAML protocol version to use when employing
SAML for authentication. Versions 1.0, 1.1 and 2.0 are
supported. The version selected affects the format of the
messages sent to SAML authorities.
Include a WS-Security Kerberos AP-REQ token
Select whether to enable (on) or disable (off) the inclusion of a
WS-Security Kerberos AP-REQ token, attesting to the authenticity of the
requesting client, in the appliance transmission to the target server. If
selected, the WebGUI prompts for the following properties:
Kerberos client principal
Provide the name part of the clients identity (the client name
contained in the cname field of the unencrypted portion of the
Kerberos ticket).
Kerberos client password
If obtaining a Kerberos ticket for the requesting client, specify
the client Kerberos password (the shared secret known only to
the requesting client and the Kerberos Key Distribution Center).
Specify the shared secret in the upper field and confirm the
entry in the lower field.
Kerberos server principal
Provide the name part of the servers identity (the server name
contained in the cname field of the unencrypted portion of the
Kerberos ticket).
Kerberos Client Keytab
Provide the location of the Kerberos keytab.
Generate requested WS-Trust token
Set to on to generate a WS-Trust token after authentication and
authorization has taken place. This token can serve as
WS-SecureConversation token. If selected, the WebGUI prompts for the
following properties:
Generate token timestamp
If generation of WS-Trust tokens is enabled, set to on to
generate a WS-Trust token timestamp.

78

IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

Allow WS-Trust token renewal


If generation of WS-Trust tokens is enabled, set to on to allow
for the renewal of the WS-Trust token.
Send SAML Logout Message (SAML 2.0 only)
Click on to enable SAML Version 2.0 Single Logout. If selected, the
WebGUI prompts for the following properties:
SAML Logout Message Session Authority
Specify the URL of the SAML authority to which to send the
logout message.
SSL Proxy Profile
Optionally select the SSL Profile to support a secure connection
to the SAML authority.
Add WS-Security UsernameToken
Select whether to enable (on) or disable (off, the default) the inclusion
of a WS-Security UsernameToken in the server-bound message. If
selected, the WebGUI prompts for the following properties:
WS-Security UsernameToken Password Type
Select the password type.
Text

The actual password for the user name, the password


hash, or derived password

Digest The digest of the password as specified in Web Services


Security UsernameToken Profile 1.0
Include Password
Select whether to enable (on) or disable (off) the inclusion of
the password in the WS-Security Username Token.
Generate an LTPA Token
Add an LTPA Token to the HTTP headers transmitted to the server. If
selected, the WebGUI prompts for the following properties:
LTPA Token Version
Select the token version/type.
Domino LTPA
Used in Lotus environments
WebSphere Version 1 LTPA
Used in WebSphere environments
WebSphere Version 2 LTPA
(Default), Used in WebSphere environments (introduced
in WebSphere Application Server version 5.1.0.2, for
z/OS, and version 5.1.1, for other platforms)
LTPA Token Expiry
Specify the LTPA token lifetime (the number of seconds from
the cookie creation to its expiration).
LTPA Key File
Specify the name of the file that contains the cipher keys used
for encryption and decryption.
LTPA Key File Password and Confirm LTPA Key File Password
Provide and confirm the cleartext password to the LTPA key
file. Refer to Understanding LTPA for more information.

Appendix A. Referenced objects

79

Generate a Kerberos SPNEGO Token


Add an Kerberos SPNEGO token to be inserted into the
WWW-Authenticate HTTP header sent to the target server. If selected,
the WebGUI prompts for the following properties:
Kerberos Client Principal
Specify the name part of the clients identity (the client name
contained in the cname field of the unencrypted portion of the
Kerberos ticket).
Kerberos Server Principal
Specify the name part of the server identity (the server name
contained in the cname field of the unencrypted portion of the
Kerberos ticket).
Kerberos Client Keytab
Specify the location of the Kerberos keytab. Refer to
Understanding SPNEGO for more information.
Request TFIM Token Mapping
Select whether to enable or disable token mapping by IBM Tivoli
Federated Identity Manager (TFIM). If enabled, the WebGUI prompts
for the following property:
TFIM Configuration
Select an existing TFIM object. Refer to IBM Tivoli Federated
Identity Manager on page 90 for more information.
3. Click Apply to commit AAA Policy properties.
4. Optionally, click Save Config to save the object to the startup configuration.

Namespace Mapping tab


An AAA Policy can use XPath expressions as it processes client requests
specifically XPath expressions can be used while:
v Identifying service requestors
v Mapping authentication credentials
v Identifying requested resources
v Mapping requested resources
v Authorizing an authenticated service requestor
Use the Namespace Mapping panel to provide namespace mappings that might be
required by XPath expressions.
1. Click the Namespace Mapping tab to display the AAA Policy Configuration
(Namespace Mapping).
2. Click Add to display the Namespace Mapping Property window.
3. Provide the following inputs:
Prefix Specify the namespace prefix.
URI
Specify the namespace URI.
4. Click Save to return to the AAA Policy Configuration (Namespace Mapping).
5. Click Apply to commit AAA Policy properties.
6. Optionally, click Save Config to save the object to the startup configuration.

80

IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

SAML Attributes tab


Use the SAML Attributes panel to provide SAML attribute namespace data. These
attribute name mappings and attribute values can be used for authentication and
authorization.
1. Click the SAML Attributes tab to display the AAA Policy Configuration
(SAML Attributes).
2. Click Add to display the SAML Attributes Property window.
3. Provide the following inputs:
Namespace URI
Specify the attribute namespace URI.
Local Name
Specify the attribute name.
Attribute Value
Specify the appropriate value.
4. Click Save to return to the AAA Policy Configuration (SAML Attributes).
5. Click Apply to commit AAA Policy properties.
6. Optionally, click Save Config to save the object to the startup configuration.

LTPA Attributes tab


The WebSphere Version 1 and Version 2 LTPA tokens, but not the Domino LTPA
token, can optionally contain an extended attribute field, consisting of an arbitrary
list of name-value pairs. Such pairs provide a means to transmit additional
information about the cookie subject to applications which can decrypt the cookie.
Such information, for example, can identify the server which authenticated the
user, or specify various user-associated LDAP attributes. If desired, you can use the
following procedure to add name-value pairs to the LTPA token.
1. Click the LTPA User Attributes tab to display the LTPA User Attributes catalog.
2. Click Add to display the LTPA User Attributes Property window.
a. Specify the attribute name in the LTPA User Attribute Name field.
b. Select the method to assign a value to this attribute from the LTPA User
Attribute Type field.
Static

(Default) Use the value explicitly assigned by the value for the
LTPA User Attribute Static Value property

XPath Use an XPath expression to set the value dynamically


c. If XPath is selected, the expression specified in the LTPA User Attribute
XPath Value is evaluated against the input context of the AAA action with
the result of the evaluation assigned as the value portion of the name-value
pair at runtime.
d. Use the LTPA User Attribute Static Value property (meaningful only when
the attribute type is set to Static) to explicitly set the value assigned to
LTPA User Attribute Name
e. Use the LTPA User Attribute XPath Value property (meaningful only when
the attribute type is set to XPath) to provide the XPath expression used to
extract a value dynamically assigned to LTPA User Attribute Name.
To assist in creating the XPath expression, click XPath Tool. This tool allows
you to upload an XML document and build the expression by pointing at
the desired node.
If the defined expression contains namespace elements, you can click XPath
Binding to provide namespace/prefix data.
Appendix A. Referenced objects

81

Refer to Setting namespace mappings (XPath bindings) for more


information.

Transaction Priority tab


Click the Transaction Priority tab to display the Transaction Priority catalog.
Click Add to display the Transaction Priority Property window.
1. Specify the name of the mapped credential in the Credential Name field.
Note: You might need to use the multistep probe to determine the string for
the mapped credential.
2. Select the priority of the transaction from the Transaction Priority list. The
default is Normal.
3. Select whether to require authorization with the Require Authorization toggle.
The default is off.
4. Click Save to return to the catalog.

Setting namespace mappings (XPath bindings)


If you need to provide namespace data for XPath expressions, use the following
procedure:
1. Click XPath Bindings to display the XPath Bindings catalog.
2. Click Add to display the Namespace Property window.
a. Specify the namespace prefix in the Prefix field.
b. Specify the namespace URI in the URI field.
c. Click Save to return to the XPath Bindings catalog.
3. If necessary, repeat the step 2 to add additional namespace mappings.
4. Click Done to complete the namespace mapping.
5. Click Commit. This commits all changes to the AAA Policy under construction
or modification.
6. Click Done to close the confirmation window.

Defining SAML attributes


To
1.
2.
3.

define SAML attributes, use the following procedure:


Click SAML Attributes to display the SAML Attributes catalog.
To create new SAML attribute, click Add.
Define the following properties:
Namespace URI
The URI for the namespace of the Local Name.
Local Name
The local attribute name. This name can be used for matching.

Attribute Value
The attribute value. This value can be used for matching.
All of these fields are optional, depending on the specific context or the SAML
Match Type selected.
4. Click Save to save the configuration.
5. Repeat step 2 through step 4 to create as many SAML attributes as needed.
6. After defining all SAML attribute, click Done.

82

IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

Adding LTPA user attributes


To
1.
2.
3.

add name-value pairs to the LTPA token, use the following procedure:
Click LTPA User Attributes to display the catalog.
Click Add to display the LTPA User Attributes window.
Provide the following inputs:
LTPA User Attribute Name
Specify the name of the attribute.
LTPA User Attribute Type
Select the type of attribute.
Static

(Default) Use the explicitly assigned value.

XPath Use an XPath expression to set the value dynamically. If


selected, the expression is evaluated against the input context of
the AAA action with the result of the evaluation assigned as
the value portion of the name-value pair at runtime.
LTPA User Attribute Static Value
Meaningful only when the type is Static. The explicit value of the
attribute.
LTPA User Attribute XPath Value
Meaningful only when the type is XPath. The XPath expression used to
extract a value dynamically.
For assistance in creating the XPath expression, click XPath Tool. This
tool allows you to load an XML document and build the expression by
selecting the desired node.
If the defined expression contains namespace elements, click XPath
Binding to provide namespace/prefix data. Refer to Setting
namespace mappings (XPath bindings) on page 82 for more
information.

Using an AAA Info file


AAA Info File
An AAA Info file can be selected as the method for the following steps of an AAA
policy:
v Authenticate
v Map Credentials
v Map Resource
v Authorize
The AAA Info XML file has the following basic structure, which mirrors the steps
of an AAA Policy. The following is a reproduction of the AAAInfo.xsd file in the
store: directory.
<xsd:element name="Authenticate" type="tns:AuthenticateType"
maxOccurs="unbounded">
</xsd:element>
<xsd:element name="MapCredentials" type="tns:MapCredentialsType"
maxOccurs="unbounded">
</xsd:element>
<xsd:element name="MapResource" type="tns:MapResourceType"
maxOccurs="unbounded">

Appendix A. Referenced objects

83

</xsd:element>
<xsd:element name="Authorize" type="tns:AuthorizeType"
maxOccurs="unbounded">
</xsd:element>

Note: Any given XML File could be used for one or more of these operations.
Only the part of the file that supports the desired operation needs to be
completed. For example, if the file is only used for Map Credentials, it does
not need to include an Authenticate, Map Resource, or Authorize section.
The schema for an AAA Info file uses the AAAInfo.xsd file in the store: directory.
One or more XML files could be used for these operations. In each case, the field
that offers the ability to select an XML file has the + and ... buttons. These buttons
allow for the creation of a new XML file or the editing of an existing XML file,
respectively. Clicking either of these buttons launches the AAA Info File Editor.
Refer to AAA Info File editor on page 85 for more information.
Note: The AAA Info file can be edited outside of the AAA Info File Editor and
uploaded to the appliance.
Authenticate element: The Authenticate element or elements contain the
database of identities that can be authenticated by this file. Identities can be
identified by one or more of the following attributes:
v User name
v Password
v IP address or host name
v IP network
v Distinguished name (DN)
v Custom token
Each identity is given a credential by this element.
MapCredentials element: The MapCredentials element takes in a credential string
and maps it to another. The input can be matched by a PCRE regular expression.
This element can be fed directly from an Authenticate element contained in this
file. Usually, however, this element is used to map an identity extracted from a
message to another identity more meaningful to the authorization method.
MapResource element: The MapResource element takes in a resource string
extracted from the message and maps it to another, perhaps more meaningful to
the authorization method. Input resources can be one or more of the following
types:
v Original (client) URL
v
v
v
v
v

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.

84

IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

Authorize element: The Authorize element takes in a Credential and a Resource


and returns an access status (allow or deny). Both the Credential and the Resource
can be matched by a PCRE regular expression.

AAA Info File editor


The AAA Info File Editor, launched by the WebGUI, steps through each of these
sections in an AAA Info file and helps to configure them. Click Next or Back to
move between pages.
The AAA Info File Editor has the following pages:
v Default credential (unauthenticated identity)
v Credentials (authenticated identities)
v Map credentials
v Map resources
v Authorized access to resources
v File information
At any point, click Cancel to abandon all changes and close the file editor.
Default credential (unauthenticated identity): The initial screen presents the
opportunity to set the default credentials for unauthenticated identities. This is the
credential assigned to identities for which no other credential can be found in the
Authenticate section. If left blank, all unauthenticated identities are denied access.
Credentials (authenticated identities): The authenticated identities page provides
a list of identities that are authenticated by this file. When creating a new file, none
are initially listed.
Click Next if this file will not be used for authentication. Click Add to create new
identities that this file can authenticate. A new window opens with a form for
adding identities.
Host Name or IP Address
The host name or IP address of the client that submitted the message. The
IP address takes dotted decimal form w.x.y.z. The entry 0.0.0.0 (or 0) is
not allowed.
v Use this field only when the identity extraction method is set to Client
IP address.
v If this field is used, you cannot use the IP Network field.
IP Network
The IP network of the client that submitted the message. This entry takes
the form x.y.z.a/b (for example 192.168.2.25/24).
v Use this field only when the identity extraction method is set to Client
IP address.
v If this field is used, you cannot use the Host Name or IP Address field.
User name
The user name extracted from the message. User names can be extracted
from messages in a number of ways, including HTTP Basic Authentication,
WS-Security UserName, and Name from SAML headers. If those AAA
Policy identity extraction methods are not used, do not use this field.
Password
The password extracted from the message. Passwords can be extracted
from messages by HTTP Basic Authentication and WS-Security UserName.

Appendix A. Referenced objects

85

If the Identity Extraction method used by the AAA Policy does not use
either of these methods, do not use this field.
Distinguished Name
The DN extracted from the message. The AAA Policy identity extraction
methods Subject DN from SSL certificate or Subject DN from SAML
signature return this value. If those methods are not used, do not use this
field.
Custom token
A custom token is extracted from the message. The AAA Policy identity
extraction methods Token extracted from the message and Token extracted
as cookie value return this value. If those methods are not used for
extraction, do not use this field.
Credential Name
The credential returned by the authentication. This can be the same as the
extracted identity or different. The value should be meaningful either to
the AAA Policy Map Credentials method or to the AAA Policy Authorize
method.
All of the fields that contain information must be matched for the authentication to
succeed. If the identity extraction method returns only a user name (such as with
SAML) and the Authenticate Identity entry contains both user name and password,
authentication will fail. The AAA policy, however, tests an extracted identity
against all entries in the order in which they are listed, stopping after it finds a
complete match. It is possible to create one entry for user name Bob that also has a
password of foo and another with no password entry. Should the extraction
method only retrieve the user name and not the password, Bob will still
authenticate.
Map credentials: The Map Credentials page presents a list of all credential maps
contained in the file. When creating a new file, this list is empty.
Click Next to move to the next page if this file will not be used for mapping
credentials. Click Add to create a new credential map.
Input Credential
The credential input to the mapping. This field accepts PCRE expressions,
allowing a single expression to match more than one input credential.
Entering foo causes the AAA policy to match all input credentials that
contain the string foo.
Credential Name
The credential to output in place of the input credential. This is the value
to which the input credential is mapped. This is not a regular expression.
Click Submit to add the new map to the list of maps. Create as many mapping
entries as needed by clicking Add for each new entry.
Note: If this file is used for mapping credentials, any input credential that does
not match a map is converted to a blank credential for the purposes of
authorization.
Map resources: The Map Resource page presents a list of all resource mappings
contained in the file. Resource mapping is used to map the resource identifier
extracted from the message to something else. If the AAA Policy uses more than
one resource extraction method, all methods will be executed.

86

IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

Click Next if this file will not be used for resource identity mapping. Click Add to
create a new map.
Original URL
The URL sent by the client submitting the message. This is a PCRE
expression.
Target URL
The URL used to send the message to the back end server, after the
firewall URL Rewrite Policy has executed. This is a PCRE expression.
Request URI
The Namespace URI of the action or method requested in the body of the
SOAP message. This is identified as the topmost element in the SOAP:Body
element.
Request Operation
The name of the operation requested in the body of the SOAP message.
HTTP Method
Select the desired method. Select any to allow any method.
Result of XPath Expression
Any value that is extracted from the message by an XPath expression. This
is a PCRE expression.
Resource
The resource string to which the input resource is mapped. This field is
required.
Note: If this file is used for mapping resources, any resource that does not mapped
by the file will be converted to a blank resource for the purposes of
authorization.
Authorized access to resources: The Authorize page presents a list of all
authorization pairs contained in this file. Authorization is based on an input
credential (after mapping, if any) and an input resource (after mapping, if any).
If this file is not used for authorization, click Next. To create an authorization entry,
click Add.
Credential
The credential to match for authorization. This field accepts PCRE
expressions.
Resource
The resource to match for authorization. This field accepts PCRE
expressions.
Access
Select allow or deny as the authorization result.
Note: When this file is used for authorization, access is denied by default. Any
unmatched entries result in denied access. Access is allowed only if a match
is found and the Access for that match is allow.
File Information: The file information page provides a means to name the file
and add a comment if desired.
This file is typically placed in the local: directory.

Appendix A. Referenced objects

87

Confirmation: The last page of the reflects the name of the file and offers the
opportunity to make changes or save the changes to the file.
v Click Cancel to abandon all changes and close the window.
v Click Back to move backward through the file to make any additional changes
needed.
v Click Commit to save the file and close the window.

IBM Tivoli Access Manager


Integrating with IBM Tivoli Access Manager (TAM) allows a user to be
authenticated using a simple user name and password. Authorization decisions are
made for an authenticated user on a resource and an operation. Only authenticated
users can receive an authorization decision. In this case, a resource is passed as a
string.
Note: Integration with TAM requires the presence of a license on the DataPower
appliance.
An AAA Policy object can use TAM for both authentication and authorization. The
AAA policy will not succeed with TAM without first configuring an instance of the
TAM object with at least one authorization server replica.

Tivoli Access Manager configuration


Configuration consists of creating a TAM client configuration file and configuring a
TAM object. The configuration files specify the network and security configuration
for the policy server, replica authorization servers, and the LDAP (directory) server.
During object configuration, the TAM configuration files must reside on the
appliance.
Although native TAM supports both local and remote clients, the appliance
supports only remote client operations. The TAM configuration supports only one
policy server and supports only LDAP directories. Although the configuration files
allow specifications for Microsoft Active Directory and Lotus Domino, the
appliance does not support these directory servers.

Tivoli Access Manager security


The TAM client supports LDAP along with the proprietary IBM protocol. SSL keys
and certificates must be in the proprietary IBM CMS database format and must be
uploaded to the appliance. The configuration files identify the location of these
files. You do not need to create Key objects or Certificate objects. The files can be
placed in the encrypted cert: or sharedcert: flash directories.

Creating TAM configuration files


Before configuring a TAM object, you need to have the TAM configuration files on
the appliance. Both the ASCII and obfuscated versions of the configuration files are
needed. You can create TAM configuration files either on the appliance or using
the native TAM configuration utilities.
The following files are needed to create the TAM object or are created using the
appliance:
v The ASCII version of the configuration file (.conf extension)
v The obfuscated version of the configuration file (.conf.obf extension) using the
same file name as the ASCII version
v The TAM SSL key file (.kdb extension)
v The TAM SSL stash file (.sth extension)

88

IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

Notes:
v If you use the native TAM configuration utilities to create the
configuration files, you might need to modify them before creating the
TAM object.
v During the creation of TAM object, you might need to upload the SSL
key file for the LDAP server (.kdb extension). When using secure
communication, ensure that this file is on the workstation.
Modifying native TAM configuration files: When the configuration files are
generated by the native TAM utilities, you might need to make the following
modifications:
v Unless the LDAP key stash file is uploaded to the appliance, modify the TAM
configuration file by defining the ssl-keyfile-pwd entry in the [ldap] stanza.
v The TAM object needs at least one authorization server replica. You can create
authorization server replicas during the creation of the TAM object, or you can
define replica entries in the [manager] stanza. When defined in the
configuration file, the replicas are not shown in the Authorization Server Replica
catalog.
v Ensure that the obfuscated version of the configuration file is on the workstation
and is the same name as the ASCII version. If not the same name, ensure that
the file entry in the [configuration-database] stanza defines the location of
the obfuscated version of the configuration file on the appliance.
Creating configuration files on the appliance: To create a TAM configuration file:
1. Select Administration Miscellaneous IBM Tivoli Access Manager Tools to
display the action screen.
2. Define the operational properties. Refer to the online help for details.
3. Click Create Tivoli Access Manager Configuration.
4. Follow the prompts.
The ASCII version and the obfuscated version of the TAM configuration files are
stored in the local: directory. The key file and the stash file that TAM uses are
stored in the cert: directory. If you set the Create File Copies to Download
property to on, copies of the key file and the stash file are stored in the temporary:
directory.

Creating and configuring TAM objects


After creating the TAM configuration, key, and stash files, you can now create and
configure a TAM object. Each TAM object requires at least one authorization server
replica. A replica indicates the network location of a remote TAM authorization
server. If necessary, configure additional replicas for failover purposes.
To create and configure a TAM object:
1. Select Objects Access IBM Tivoli Access Manager to display the catalog.
2. Click Add to display the configuration screen.
3. Define the operational parameters. Refer to the online help for details.
4. Define at least one authorization server replica.
a. Click the Authorization Server Replica tab.
b. Define a replica.
1) Click Add to display the properties window. Use this window to specify
the operational parameters.
2) Define the operational parameters. Refer to the online help for details.
Appendix A. Referenced objects

89

3) Click Save.
c. If necessary, repeat the previous step to create another replica.
5. Click Apply to save the object to the running configuration.
6. Optionally, click Save Config to save the object to the startup configuration.

Refreshing certificates
Refreshing Tivoli Access Manager (TAM) certificates first refreshes the password of
the keystore associated with the TAM object and then refreshes the client certificate
in the keystore with the configured TAM server. The clients associated with this
configuration and any other configuration which use the same keystore will be
stopped if running and restarted when the refresh is complete.
To refresh certificates:
1. Select Administration Miscellaneous IBM Tivoli Access Manager Tools to
display the action screen.
2. Click the Refresh Tivoli Access Manager Client Certificate tab.
3. Define the operational properties. Refer to the online help for details.
4. Click Refresh Tivoli Access Manager Client Certificate.
5. Follow the prompts.

IBM Tivoli Federated Identity Manager


DataPower appliances integrate with IBM Tivoli Federated Identity Manager
(TFIM) through the exchange of WS-Trust SOAP messages. The TFIM management
object centralizes the configuration of the TFIM endpoint and prevents parameter
duplication between the Map Credential and the Post Processing phases in an
AAA Policy. During the Map Credential phase, an authenticated identity can be
mapped to the identity for authorization. During the Post Processing phase, an
authorized identity can be mapped to the output AAA identity.
When integrating with TFIM, the provided input credentials must be able to be
expressed in the request token format for the TFIM endpoint. For example, a
WS-Security Username token as the request token cannot be created when the
available user credential is an X.509 certificate.

Creating the TFIM object


To create and configure a TFIM object, use the following procedure:
1. Use the Objects Access Settings IBM Tivoli Federated Identity Manager
menu path to display the IBM Tivoli Federated Identity Manager catalog.
2. Click Add to display the IBM Tivoli Federated Identity Manager configuration
screen. Use this screen to specify operational parameters.
a. Specify the name for the object in the Name field.
b. Retain the default setting for the Admin State toggle. To place the object in
an inactive administrative state, click disabled.
c. Specify a descriptive object-specific summary in the Comment field.
d. Specify the host name or IP address of the TFIM server in the Server field.
e. Specify the port number of the TFIM server in the Port field. The default is
9080.
f. Select the currently configured version of TFIM from the Compatibility
Mode list. The value determines the details for the namespace and WS-Trust
messages.

90

IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

Note: Selecting Version 6.2 as the compatibility mode will cause the TFIM
client/endpoint to generate WS-Trust messages using version 1.3 of
the WS-Trust specification. In this case, trust chains in the TFIM 6.2
server must use the Validate OASIS URI as the Request Type. To use
WS-Trust version 1.2 messages with a TFIM 6.2 server, select TFIM 6.1
as the compatibility mode. If the 6.1 compatibility mode is selected,
TFIM 6.2 will behave the same as TFIM 6.1.
Version 6.0
Indicates Tivoli Federated Identity Manager, version 6.0.
Version 6.1
(Default) Indicates Tivoli Federated Identity Manager, version 6.1.
Version 6.2
Indicates Tivoli Federated Identity Manager, version 6.2.
g. Select the format of the request token from the Request Token Format list.
The available formats depend on the selected value for Compatibility
Mode.
v If Version 6.0, the following formats are available:
Custom
Indicates a custom style sheet for generating the TFIM request.
When selected, requires the specification of a Custom Request.
SAML 1.0
Indicates a SAML Assertion 1.0.
SAML 1.1
Indicates a SAML Assertion 1.1.
Username Token
(Default) Indicates a WS-Security Username Token Type.
v If Version 6.1 or Version 6.2, the following formats are available:
Binary Security Token
Indicates a WS-Security BinarySecurityToken.
Custom
Indicates a custom token. When selected, requires the
specification of a Custom Request.
Custom Token
Indicates a custom token.
SAML 1.0
Indicates a SAML Assertion 1.0.
SAML 1.1
Indicates a SAML Assertion 1.1.
SAML 2.0
Indicates a SAML Assertion 2.0.
Kerberos Token
Indicates a WS-Security Kerberos Token.
Username Token
(Default) Indicates a WS-Security Username Token Type.
X.509 Token
Indicates a WS-Security X.509 Token.

Appendix A. Referenced objects

91

h. When using TFIM 6.0, TFIM 6.1, or TFIM 6.2 and when Request Token
Format is Custom, select the location of the custom style sheet in the
Custom Request field. The custom style sheet file must be in the local: or
store: directory. Click Upload or Fetch to upload the custom style sheet file.
i. When Request Token Format is not Custom, define the following properties:
1) When using TFIM 6.0, TFIM 6.1, or TFIM 6.2, specify the scope for this
security token in the Applies-To Address field. For example, specify the
services to which this token applies:
http://tfim.ibm.com:9080/EchoApplication/Services/EchoServiceUser
http://9.33.97.251:9080/EchoApplication/Services/EchoServiceUser

In the TFIM service, this information specifies the destination of the


request. The TFIM trust service uses this information to determine which
trust chain to invoke. To determine the correct value, consult your TFIM
administrator.
2) When using TFIM 6.0, TFIM 6.1, or TFIM 6.2, specify the identity that
issued the request in the Issuer field. For example, in the TFIM
WS-Security Management (WSSM) component, the Issuer is either the
WSSM token generator or the WSSM token consumer:
urn:itfim:wssm:tokenconsumer

The TFIM trust service uses this information to determine which trust
chain to invoke. To determine the correct value, consult your TFIM
administrator.
3) When using TFIM 6.1 or TFIM 6.2, optionally specify the name of the
Web services port type to use in the Port Type field. A port type is a
group of Web services operations. For example:
EchoService

The TFIM trust service uses this information to determine which trust
chain to invoke with finer granularity. If a value is not specified, a
default value of NotSpecified is used. To determine the correct value,
consult your TFIM administrator.
4) When using TFIM 6.1 or TFIM 6.2, optionally specify the name of the
Web services operation to use in the Operation field. For example:
echo

The TFIM trust service uses this information to determine which trust
chain to invoke with finer granularity. If a value is not specified, a
default value of NotSpecified is used. To determine the correct value,
consult your TFIM administrator.
j. From the SSL Proxy Profile list, select an SSL Proxy Profile to manage
secure communications with the peer.
k. Use the Schema Validate Response toggle to specify whether to
schema-validate responses from the TFIM server. When enabled, TFIM
responses are schema-validated with the WS-Trust version that is defined by
the compatibility mode.
on

Responses are schema-validated.

off
(Default) Responses are not schema-validated.
3. Click Apply to save the object to the running configuration.
4. Optionally, click Save Config to save the object to the startup configuration.

Working with Kerberos objects


A basic description of the Kerberos authentication protocol is helpful for
understanding the support provided by the DataPower appliance.

92

IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

The Kerberos authentication protocol uses a star topology. The Key Distribution
Center (KDC) is at the center of the star. Each Kerberos principal (a human, a
computer client, or an instance of a service running a specific computer) is
registered with the KDC and has a shared secret known only to the principal and
to the KDC. This shared secret takes the form of a password for human principals
and a randomly generated keytab file for nonhuman principals.
When a Kerberos client (for example, Alice) wants to communicate securely with a
Kerberos server (for example, the FTP service), Alice must access KDC of her
Kerberos realm and request a ticket for the FTP service. At this point, the KDC has
the option of requiring pre-authentication before responding, or the KDC can
immediately issue the ticket to Alice.
The KDC response contains two items:
v A randomly generated session key encrypted with Alices shared secret
v A ticket for the FTP service
The ticket contains:
v
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.
Appendix A. Referenced objects

93

There is no restriction in Kerberos that specifies which clients can request tickets
for a particular service.
Note: Microsoft Windows, when configured to use an Active Directory domain, is
based on a security infrastructure that is, at its core, Kerberos. As of
Windows 2000, authentication in a Windows domain is handled by
Kerberos. Such authentication is entirely transparent to the user. Refer to
Understanding SPNEGO for implementation details.

Kerberos KDC Server objects


Use the following procedure to configure a Kerberos KDC Server:
1. Select Objects Crypto Kerberos KDC server to display the Kerberos KDC
Server catalog.
2. Click Add to display the Kerberos KDC Server configuration screen.
3. Provide the following inputs:
Name
Specify the name of the object.
Admin State
Retain the default setting. To place the object in an inactive administrative
state, click disabled.
Comments
Specify a descriptive object-specific summary.
Kerberos realm name
Specify the name of the Kerberos realm that is serviced by this KDC.
There is exactly one KDC per Kerberos realm.
Kerberos KDC Server
Specify the host name or IP address of the KDC server. Click Ping to
verify connectivity.
Use TCP
Select whether to use UDP or TCP as the Transport Layer protocol to
access the KDC server.
on

Use Transmission Control Protocol (TCP)

off

(Default) Use User Datagram Protocol (UDP)

Server Port Number


Specify the UDP or TCP port that is monitored by the KDC for incoming
Kerberos requests. The default is 88.
UDP Timeout
When the Transport Layer protocol is UDP, specify the UDP timeout.
4. Click Apply to save the object to the running configuration.
5. Optionally, click Save Config to save the object to the startup configuration.

Kerberos Keytab File objects


A Kerberos Keytab file contains the keys needed to decrypt the ticket presented by
a client attempting to obtain services. Previously, only a password was required.
This has been changed to an encrypted key for added security. The Kerberos
Keytab File object identifies the file that contains the keys needed to decrypt the
ticket.
Use the following procedure to configure a Kerberos Keytab File:

94

IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

1. Select Objects Crypto Kerberos Keytab to display the Kerberos Keytab


catalog.
2. Click Add to display the Kerberos Keytab Configuration screen.
3. Provide the following inputs:
Name
Specify the name of the object.
Admin State
Retain the default setting. To place the object in an inactive administrative
state, click disabled.
Comments
Specify a descriptive object-specific summary.
File Name
Select the keytab file. This list includes files that are stored in the
encrypted and protected cert: directory of the appliance. If the file does
not reside on the appliance, click Upload or Fetch to transfer the file.
Note: This file is not generated on the DataPower appliance. It is
generated through the Kerberos system itself.
4. Click Apply to save the object to the running configuration.
5. Optionally, click Save Config to save the object to the startup configuration.

XACML Policy Decision Point


During the authorization phase of an AAA Policy, you can select Use XACML
Authorization Decision. The AAA Policy acts as an XACML Policy Enforcement
Point (PEP). The PEP allows the XACML Policy Decision Point (PDP) to decide
whether or not to authorize access.
The DataPower appliance supports the mandatory to implement and optional
specifications that are listed in Section 10.2.8 of the OASIS Standard, eXtensible
Access Control Markup Language (XACML) Version 2.0, dated February 1, 2005.
Use the following procedure to configure an XACML Policy Decision Point (PDP).
1. Select Objects Access XACML Policy Decision Point to display the
XACML Policy Decision Point catalog.
2. Click Add to display the XACML Policy Decision Point Configuration screen.
a. Use the Name field to specify the name of this XACML PDP.
b. Retain the default setting for the Admin State toggle. To place the object in
an inactive administrative state, click disabled.
c. Specify a descriptive object-specific summary in the Comment field.
d. Use the Evaluate Individual Policies Equally toggle to signal the presence
of a comprehensive top-level XACML policy-set.
on

Indicates the presence of multiple XACML policy-sets, each of


which will be used in the authorization decision

off

(Default) Indicates the presence of a top-level XACML policy-set


that is specified by the General Policy File property

In the event of multiple authorization matches, a policy combining


algorithm, which defines a procedure for arriving at an authorization
decision given the individual results of evaluation by a set of policies, is
employed to render the final decision.
Appendix A. Referenced objects

95

e. Specify the location of the top-level XACML policy-set in the General


Policy File field.
This property is meaningful only if the Evaluate Individual Policies
Equally radio button is set to off.
f. Specify the policy combining algorithm used by this XACML PDP in the
Dependent Policies Combining field.
This property is meaningful only if the Evaluate Individual Policies Equally
radio button is set to on.
The XACML Version 2.0 standard defines the following policy combining
algorithms:
Deny Overrides
The deny-overrides policy-combining algorithm evaluates each
policy in the order that it appears in the XACML policy set. If any
policy in the set evaluates to deny, the policy combination evaluates
immediately to deny. In other words a single deny takes precedence
over other policy evaluations. If all policies are determined to be
NotApplicable, the policy combination evaluates to NotApplicable.
First Applicable
(Default) The first-applicable policy combining algorithm evaluates
each policy in the order that it appears in the XACML policy set. For
an individual policy, if the target (resource) evaluates to TRUE and
the policy conditions evaluate unambiguously to permit or deny,
evaluation is immediately halted, and the policy combination
evaluates to the effect of that individual policy. If the individual
policy evaluates the target as FALSE or the policy conditions as
NotApplicable, then the next policy in the order is evaluated; if no
further policy exists in the order, the policy combination evaluates to
NotApplicable.
Only One Applicable
The only-one-applicable policy combining algorithm evaluates each
policy in the order that it appears in the XACML policy set; unlike
the other policy combining algorithms, only-one-applicable must
evaluate all policies to render a final evaluation. If after evaluating
all policies, no policy is considered applicable by virtue of its target
(the requested resource), the policy combination evaluates to
NotApplicable. If after evaluating all policies, more than one policy
is considered applicable by virtue of its target, the policy
combination evaluates to Indeterminate. If after evaluating all
policies, only one single policy is considered applicable by virtue of
its target, the policy combination evaluates to the result of
evaluating that single policy.
Permit Overrides
The permit-overrides policy combining algorithm evaluates each
policy in the order that it appears in the XACML policy set. If any
policy in the set evaluates to permit, the policy combination
evaluates immediately to permit. In other words a single permit
takes precedence over other policy evaluations. If all policies are
determined to be NotApplicable, the policy combination evaluates to
NotApplicable.
g. Use the Dependent Policy Files field with the Add and Delete buttons to
construct a list of dependent policy files.

96

IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

Policy sets can be local or remote to the appliance; use local or standard
URLs to locate files.
h. Optionally, use the Other Policy Files from Directory field with the Add
and Delete buttons to construct a list of local directories that contain
dependent files.
All files in noted directories with a .xml or .xacml extension are considered
as potentially available to the current XACML PDP.
i. Use the XACML Policies Cache Lifetime field to specify the policy
combining algorithm used by this XACML PDP. Specify an integer (in the
range from 0 to 2,678,400) that specifies the time, in seconds, that compiled
XACML policies are maintained in the PDP cache. The default value of 0
specifies that the cache is never expired.
There are several ways for users to control the XACML PDP policy caches.
Explicitly clear the cache
Use the clear pdp cache CLI command to clear the cache.
Specify the TTL for the PDP
During PDP configuration, use the WebGUI or CLI to specify a cache
lifetime.
Use the XML Manager
When the PDP is used by an AAA policy for authorization, users can
access the XML manager that is associated with the AAA policy with
the clear xsl cache CLI command. This command also clears the
compiled XACML policies that are referenced by AAA polices that
are supported by the XML manager.
Use a URL Refresh Policy
Use a URL Refresh Policy whose conditions match the internal URL
xacmlpolicy:///pdpName to perform periodic cache refreshes.
v When TTL for the PDP is 0 (cache never expires), the URL Refresh
Policy controls cache refresh
v When the URL Refresh Policy is no-cache, XACML policies are
never cached, regardless of any assigned TTL value
v When the URL Refresh Policy is protocol-specified, the TTL
setting for the PDP will govern cache refresh unless its value is 0
v When the URL Refresh Policy is default with a refresh interval,
the TTL for the PDP is ignored and the URL Refresh Policy refresh
interval controls cache refresh
v When the URL Refresh Policy is no-flush with a refresh interval,
the greater of the URL Refresh Policy refresh interval or the TTL
for the PDP controls cache refresh
3. Click Apply to save the object to the running configuration.
4. Optionally, click Save Config to save the object to the startup configuration.

Application Security Policy


An Application Security Policy establishes the rules used to enforce security for a
Web Application Firewall service. This policy employs Request Maps, Response
Maps, and Error Maps. Each of these maps, in turn, matches a Web Request
Profile, Web Response Profile, or Error Policy, respectively, to client requests that
are based on a set of matching criteria. The Profiles selected then provide the
detailed security configuration.

Appendix A. Referenced objects

97

Select Objects Web Applications Application Security Policy to display the


Application Security Policy catalog. This catalog lists all Application Security
Policy objects that are configured in the current domain.
Click on the name of a Policy to edit it. Click Add to create a new Policy.
Provide the following inputs:
Name
Specify a name for this Policy. This is the name that appears in all Policy
listings.
Admin State
Retain the default setting. To place the object in an inactive administrative
state, click disabled.
Comments
Specify a descriptive object-specific summary.

Request Maps tab


Request Maps select Web Request Profiles to execute on client requests based on a
set of matching criteria. If the client request meets the matching criteria, the
corresponding Web Request Profile executes. At least one Request Map entry is
required.
Click the Request Maps tab to establish Web Request matching maps. A catalog of
all configured maps is displayed.
Click the name of a Map to edit it. Click Add to create a new Map.
Provide the following inputs:
Matching Rule
Select an existing Matching Rule. Refer to Matching Rule on page 106 for
more information.
Request Profile
Select a Web Request Profile. Refer to Web Request Profile on page 132 for
more information.
Click Save to save the map and close the window. The new map then appears in
the catalog list of maps.

Response Maps tab


Response Maps select Web Request Profiles to execute on server responses based
on a set of matching criteria. If the server response meets the matching criteria, the
corresponding Web Request Profile executes. At least one Response Map entry is
required.
Click the Response Maps tab to establish Web Response matching maps. A catalog
of all configured maps is displayed.
Click the name of a Map to edit it. Click Add to create a new Map.
Provide the following inputs:

98

IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

Matching Rule
Select an existing Matching Rule. Refer to Matching Rule on page 106 for
more information.
Response Profile
Select a Web Response Profile. Refer to Web Response Profile on page 139
for more information.
Click Save to save the map and close the window. The new map then appears in
the catalog list of maps.

Error Maps tab


Error Maps select a Processing Rule to execute on errors based on a set of
matching criteria. If the error meets the matching criteria, the corresponding
Processing Rule executes.
To establish Error Policy matching maps, use the following procedure:
1. Click the Error Maps tab to display the Error Maps catalog. This catalog lists
all configured maps.
2. Click the name of a Map to edit it. Click Add to create a new Map.
3. Provide the following inputs:
Matching Rule
Select an existing Matching Rule. Refer to Matching Rule on page 106
for more information.
Processing Rule
Select an existing Processing Rule. Refer to Processing Rule on page
111 for more information.
4. Click Save to save the map and close the window. The new map is in the Error
Maps catalog. Click Cancel to abandon any changes.

Count Monitor
Although the configuration of the following objects all the configuration of count
monitors, Web Application Firewall services do not support this type of monitor
configuration.
v AAA Policy
v Error Policy

Error Policy
A Web Application Firewall service can employ an Error Policy to handle errors
returned by the backend service. An Error Policy can take action on the error,
changing the error response received by the requesting client.
Select Objects Web Applications Error Policy to display the Error Policy
catalog. This catalog lists all the Error Policy objects.
Click on the name of an existing Policy to edit it. Click Add to create a new Policy.
The Error Policy object configuration screen is displayed.
Provide the following inputs:

Appendix A. Referenced objects

99

Name
Specify a name for this Error Policy object. This name will appear in the
catalog listing of objects as well as in any list of Error Policy objects.
Admin State
Retain the default setting. To place the object in an inactive administrative
state, click disabled.
Comments
Specify a descriptive object-specific summary.
Mode
Select a mode of operation.
Redirect
Redirects the client to the specified URL. The URL field appears
when this mode is selected.
Proxy The appliance fetches the specified URL and then return its contents
to the client. The URL field appears when this mode is selected.
Error-rule
The appliance executes a selected Processing Rule and return the
result to the client. The Error Rule field appears when this mode is
selected.
Standard
The appliance passes the error to the Application Security Policy
selected for the Web Application Firewall. If the Application Security
Policy includes an Error Map that will match the error, then that
action is taken. This mode is useful when you want to execute error
handling rules for specific requests and want to enforce monitoring
of all errors, even if no Error Map matches the request.
URL
Specify a fully qualified URL (http://host/...). This URL is used only for
the Redirect or Proxy modes of operation.
Error Rule
Select a Processing Rule when the mode is set to Error-rule. This rule is
executed against the error returned by the application server.
Monitor
Do not select a Count Monitor object. The Web Application Firewall service
does not support this configuration.

Defining an LDAP Search Parameters object


The LDAP Search Parameters object serves as a container for the parameters that
are used to perform an LDAP search operation.
Authentication
The parameters for an LDAP search to retrieve the DN of the user.
Credentials mapping
The parameters for an LDAP search to retrieve the group name (DN or
attribute) based on the DN of the authenticated user.
You need to add a prefix and optionally add a suffix to create the LDAP filter. The
prefix and suffix are constructs of the LDAP filter expression, as defined in LDAP:
String Representations of Search Filters. This filter is used to perform the LDAP
search and return matching entries.

100

IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

To create an LDAP Search Parameters object, use the following procedure:


1. Select Objects Access Settings LDAP Search Parameters to display the
catalog.
2. Click Add to display the configuration screen.
3. Specify the name of the object in the Name field.
4. Retain the default setting for the Admin State toggle. To place the object in an
inactive administrative state, click disabled.
5. Specify a descriptive object-specific summary in the Comment field.
6. Specify the base DN to begin the search in the LDAP Base DN field. This
value identifies the entry level of the tree used by the LDAP Scope property.
7. Specify the name of the attribute to return for each entry that matches the
search criteria in the LDAP Returned Attribute field. The default is the dn
attribute.
8. Specify the prefix of the LDAP filter expression in the LDAP Filter Prefix
field.
If the prefix is mail= and the user name is bob@example.com, the LDAP search
filter would be mail=bob@example.com.
9. Optionally specify the suffix of the LDAP filter expression in the LDAP Filter
Suffix field.
If the prefix is mail=, the suffix is )(c=US)), and the user name is
bob@example.com, the LDAP search filter would be
(&(mail=bob@example.com)(c=US)).
10. Select the depth of the search from the LDAP Scope list:
Base

Searches the entry level of the tree only.

One level
Searches the entry level of the tree and any object that is one-level
below the input.
Subtree
(Default) Search the entry level of the tree and all of its descendents.
11. Click Apply to save the object to the running configuration.
12. Optionally, click Save Config to save the object to the startup configuration.

Load Balancer Group


A Load Balancer Group is a server pool that can provide redundancy among a
collection of servers. A Load Balancer Group can be used as the backend server for
a DataPower service or can be used to provide LDAP or IMS Connect server
failover protection. A request to connect to a Load Balancer Group results in the
selection of a healthy server to receive an incoming client request.
Each instance of a Load Balancer Group can support 512 members.

Health of member servers


The health of each member of the group is considered one of the following :
v Healthy or up
v Quarantined or softdown
v Convalescent or down

Appendix A. Referenced objects

101

Healthy
By default, all servers are considered healthy and are eligible to receive forwarded
client requests. When healthy, the health state is up.

Quarantined
During a normal HTTP transaction or the TCP ping, a failure to connect to a server
causes the server to be quarantined until a dampening period elapses. When the
dampening period elapses, the server returns to the healthy state and becomes
eligible to receive forwarded client requests. When quarantined, the health state is
softdown.
While quarantined, the server is:
v Removed from the server pool
v Ineligible to receive forwarded client requests
v Excluded from the optional health check

Convalescent
Optionally, you can associate a periodic health check with a Load Balancer Group.
If the health check fails, the server is deemed convalescent. The server is not
considered to be healthy until it passes a health check. When deemed convalescent,
the health state is down.
While deemed convalescent, the server is:
v Removed from the server pool
v Ineligible to receive forwarded client requests

Setting the health state with a variable


The health state for each server can be set with the service/lbhealth/ service
variable. This variable takes one of the following syntax statements:
var://service/lbhealth/group/server/state
var://service/lbhealth/group/server:port/state

Where:
group

The name of the Load Balancer Group

server

The IP address or host name of the member

port

The port of the member

state

The state of the server, which is one of the following values:


v up
v down
v softdown
Refer to Health of member servers on page 101 for details.

Configuring Load Balancer Group objects


The configuration of a Load Balancer Group consists of the following activities:
1. Providing basic configuration properties on the Main tab
2. Defining server members on the Members tab
3. Optionally defining health check criteria on the Health tab

102

IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

Providing basic configuration


To
1.
2.
3.

start the configuration, perform the following procedure:


Select Objects Network Load Balancer Group to display the catalog.
Click Add to display the configuration screen.
Provide the following inputs:
Name Specify the name for the Load Balancer Group.
Admin State
Retain the default setting. To place the object in an inactive
administrative state, click disabled.
Comments
Specify a descriptive object-specific summary.
Algorithm
Select the algorithm to select the actual server. The following values are
available:
First Alive
Uses the concept of a primary server and backup servers. When
the primary server is healthy, all connections are forwarded to
this server. When the primary server is quarantined or
convalescent, connections are forwarded to backup servers. The
primary server is the first server in the members list.
Hash

Uses the IP address of the client or the value of an HTTP


header as the basis for server selection.
When using an HTTP header, use the Load Balancer Hash
Header property to identify the header to read. This property is
available for Multi-Protocol Gateway and Web Service Proxy
services only. Additionally, this property is available only in the
object view, and this property is on the Main tab.
The same client is served by the same server. This algorithm is
used in applications that require the storage of server-side state
information, such as cookies.

Least Connections
Maintains a record of active server connections and forward a
new connection to the server with the least number of active
connections.
Round Robin
(Default) Maintains a list of servers and forwards a new
connection to the next server on the list.
Weighted Round Robin
Maintains a weighted list of servers and forwards new
connections in proportion to the weight (or preference) of each
server.
Damp Time
Specify the number of seconds that a server remains in an softdown
state. Use a value in the range of 1 through 86400. The default is 120.
This property does not impact servers that are in the down state.
Do not Bypass Down State
Select the connection-behavior when no member is up.

Appendix A. Referenced objects

103

on

Does not forward the connection to any member. Makes the


next attempt when at least one members is in the up state.

off

(Default) Selects the first member in the down state and


forwards the connection to this server.

Try Every Server Before Failing


Select the retry-behavior for a failed attempt.
on

Sends the requests to each server until one responds or all fail.
Each server that fails is set to the softdown state.

off

(Default) Does not attempt to contact other members.

Masquerade as Group Name


Select which name to present in the message header.
on

Uses the name of the Load Balancer Group. If


appserver1.domain.com is a member of the Appsters Load
Balancer Group, the message header contains Appsters.

(Default) Use the host name of the member. If


appserver1.domain.com is a member of the Appsters Load
Balancer Group, the message header contains
appserver1.domain.com.
4. Continue with procedure that is provided in Defining server members.
off

Defining server members


Use the following procedure to add members or assign weight to members. For all
algorithms except First Alive, the order of members is not important.
1. Select the Members tab to display the catalog.
2. Click Add to display the property window.
3. Provide the following inputs:
Actual Host
Specify the IP address or the domain-qualified host name of the
member.
Weight
If the algorithm is Weighted Round Robin only, specify the relative
weight (preference). Use a value in the range of 1 through 65000. The
default is 1.
The greater the value, the more likely this server is to receive a
connection request. For example there are three members (A, B, and C)
that have the assigned weights of 100, 60, and 40, respectively. Because
of the weighting, A receives 50% of requests, B receives 30% of requests,
and C receives 20% of requests.
Mapped Server Port
Specify the member-specific target port or retain the default value (0) to
use the DataPower service-defined port. Use a value in the range of 0
through 65535. The default is 0.
By default, member servers are contacted on the DataPower
service-defined port. However, if you have services running on
different ports for different member servers, explicitly identify the
member-specific target port. If you specify a nonzero value, that
member server will always be contacted on this port.

104

IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

Health Port
Specify the member-specific health port or retain the default value (0)
to use the Load Balancer Group-defined port. Use a value in the range
of 0 through 65535. The default is 0.
A nonzero value overrides the value for the Remote Port property of
the health check. This property is available during the configuration of
the health check on the Health screen.
4. Click Save to return to the catalog.
Assignment of all members to a Load Balancing Group completes the required
configuration.
v To associate a periodic health check with the new Load Balancer Group, refer to
Defining health checks.
v If you are completed with the configuration, click Apply to save the object to the
running configuration and return to the object catalog.
v Optionally, click Save Config to save the object to the startup configuration.

Defining health checks


A health check is essentially a scheduled rule that sends the same request to each
server member. The successful completion of the health check requires that the
server passes normal TCP and HTTP connection criteria. Optionally, the health
check contains a filter to test the response from the server. If the filter accepts the
response, the server is considered to be healthy; otherwise, it is considered to be
convalescent.
Use the following procedure to define the health check:
1. Click the Health tab to display the configuration screen.
2. Provide the following inputs:
Enabled
Controls whether to perform the periodic health check.

URI

on

Enables the health check.

off

(Default) Disables the health check.

When the check type is Standard, specify the non-server (file path)
portion of the target URI. That is, specify the URI to receive the client
request that is generated by the rule. The default is /.
This URI is used with the specified remote port.

Remote Port
Specify the port on the target server to receive the query. The default is
80.
You can override this value for one or more members of the Load
Balancer Group with the Health Port property. This property is
available during the configuration of member servers in the group.
The response from the server is evaluated to determine the health
status of each member server in the group. The request is sent to the
target URI and remote port.
Health Check Type
Select the type of check to perform.
Standard
(Default) Select if the group does not consist of LDAP servers.
Appendix A. Referenced objects

105

LDAP Select if the group consists of LDAP servers.


IMS Connect
Select if the group consists of IMS Connect servers.
Send SOAP Request?
When the check type is Standard, specify the HTTP method to access
the target URI.
on

(Default) Click to access the target URI with an HTTP POST


operation (by posting a SOAP message).

off

Click to access the target URI with an HTTP GET operation.

SOAP Request Document


When Send SOAP Request? is on, specify the SOAP message to send
as a client request. The default is the healthcheck.xml file in the store:
directory (store:///healthcheck.xml).
Timeout
Specify the number of seconds for the completion of the health check.
Use a value in the range of 2 through 86400. The default is 10.
If successful, the server is deemed healthy and is marked as up;
otherwise, the server is deemed convalescent and is marked as down.
Frequency
Specify the number of seconds between health checks. Use a value in
the range of 5 through 86400. The default is 180.
XPath Expression
When the check type is Standard, use with the XSL Health Check
Filter property to specify the XPath expression that must be found in a
valid server response. If necessary, click XPath Tool to define an XPath
expression.
XSL Health Check Filter
When the check type is Standard, specify the style sheet to filter the
server response. The default is the healthcheck.xsl file in the store:
directory (store:///healthcheck.xsl).
This style sheet uses the specified XPath Expression value as input and
scans the server response for its presence. If found, the server is
deemed healthy and is marked as up; otherwise, the server is deemed
convalescent and is marked as down.
SSL proxy profile
Optionally, when the check type is Standard, select an SSL Proxy
Profile to provide the resources for a secure connection.
3. Click Apply to save the object to the running configuration.
4. Optionally, click Save Config to save the object to the startup configuration.

Matching Rule
Matching Rule objects support the implementation of processing policies and XML
manager-based schema validation rules. Both use a Matching Rule to determine if
a candidate XML document is subject to a particular processing or validation
action in a processing policy.
A Matching Rule contains one or more match expressions. Match expressions are
of the following types:

106

IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

v Error code expressions define an error set that is subject to a specific error-rule.
As error codes are written as hexadecimal integers, the error code expression
matches one or more hexadecimal integers.
v HTTP expressions work with a specified HTTP header to define a group of
HTTP headers. An HTTP expression can define, for example, an HTTP header
that contains a specific header field or an HTTP header that contains a defined
value in a specific header field.
v URL expressions define a group of URLs. For example, a URL expression could
define all URLs or only URLs that contain a specific domain name.
v XPath expressions define content in the XML document. For example, an XPath
expression could define all attributes of a specific name.
Note: Candidate documents are evaluated against all match expressions in the
Matching Rule. A document matches the rule only if it conforms to all
expressions in the rule. Documents that fail to match all expressions do not
match the rule.
To configure a Matching Rule, use the following procedure:
1. Select Objects XML Processing Matching Rule to display the catalog.
2. Click Add to display the configuration screen.
3. Specify the name of the object in the Name field.
4. Retain the default setting for the Admin State toggle. To place the object in an
inactive administrative state, click disabled.
5. Specify a descriptive object-specific summary in the Comment field.
6. Use the Match with PCRE toggle to indicate whether match patterns use
PCRE expression or shell-style expressions.
on

Uses PCRE expressions.

off

(Default) Uses shell style expressions.

7. Use the Boolean Or Combinations toggle to indicate whether to combine the


match criteria with OR semantics or with AND semantics.
on

Uses OR semantics to evaluate the criteria. Only a single match


condition needs to be true for the match to succeed.

(Default) Uses AND semantics to evaluate the criteria. All match


conditions must be true for the match to succeed.
8. Define matching rules on the Matching Rule tab
off

a. Click Add to display the Property window.


b. Select the desired match type from the Matching Type list.
Error Code
Bases the match on an error code. This type is for use in the
processing of error rules.
Full URL
Deprecated. Use URL.
This legacy type creates a match that uses a shell-style match
pattern against the full inbound URL.
Host

Deprecated. Use HTTP.


This legacy type creates a match that uses a shell-style match
pattern against the Host: header in HTTP 1.1 requests.

HTTP Bases the match on HTTP header fields.


Appendix A. Referenced objects

107

URL

Bases the match on the inbound URL after any URL rewrite.

XPath Bases the match on an XPath expression. The expression is applied


to the inbound document. When the XPath expression evaluates to
true, a match is made.
c. Define the matching criteria:
v When HTTP:
1) Specify the target HTTP header field in the HTTP Header Tag field.
2) Specify the HTTP expression in the HTTP Value Match field.
Wildcards are allowed.
v When URL, specify the URL match expression in the URL Match field.
You can use wildcards to define a match pattern as follows:
*

The string wildcard matches 0 or more occurrences of any


character.
For a PCRE expression, use .* rather than * to match any number
of any characters.

The single character wildcard matches one occurrence of any single


character.

[]

The delimiter pair to bracket a character or numeric range.


[1-5]

Matches 1, 2, 3, 4, or 5

[xy]
Matches x or y
You can use any PCRE-compliant expression. For more information,
refer to http://www.pcre.org.
v When Error Code, identify the target error code in the Error Code field.
Click Select to view a list of selectable error codes.
v When XPath, specify the XPath expression in the XPath Expression
field. Click XPath Tool for help creating this expression.
d. Click Save.
Repeat this step to define another matching rule.
9. Click Apply to save the object to the running configuration.
10. Optionally, click Save Config to save the object to the startup configuration.

Name-Value Profile
Web applications communicate with clients using the various mechanisms of the
HTTP protocol. The protocol provides for HTTP headers, cookie values,
URL-encoded query strings, and URL-encoded request messages. Each of these
kinds of communication mechanisms operate using a string of name-value pairs
(such as token=valueA&token1;=valueB&broken;=reject). To provide integrity and
security for such an application, it is necessary to inspect and take action on these
names and values. A Name-Value Profile provides a means to implement this
inspection and action configuration.
A Name-Value Profile filters names, and for names that match a given expression,
sets constraints on the corresponding values, again expressed as a match
expression. The Name-Value Profile works by comparing each name in a
name-value pair to all entries in a configured Validation List. If a match is found,
the corresponding value is compared to a corresponding match expression. If a
match is found, the pair passes. If no match is found, one of several actions is
taken.

108

IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

For example, given the URL-encoded string token=valueA&token1;=valueB


&broken;=reject, only names that contain the substring token will be accepted,
and those that are accepted must have a value that contains the string value. The
name-value pair with a name of broken can optionally be passed through, stripped
from the string or replaced with a known value, or the entire string can be rejected
(in which case, the profile will fail to pass).
1. Select Objects Web Applications Name-Value Profile to display the
Name-Value Profile catalog. The catalog lists all available Name Value Pair
objects.
2. To edit an existing object, click the object name. To create a new object, click
Add. The Name-Value Profile configuration page appears.
3. Provide the following inputs:
Name
Specify an alphanumeric name for this profile object. This name appears
in all lists of available Name-Value Profiles.
Admin State
Retain the default setting. To place the object in an inactive administrative
state, click disabled.
Comments
Specify a descriptive object-specific summary.
Maximum Count
Specify an integer to determine the maximum number of name value
pairs allowed in a single entity (header, cookie set, Post body, or Query
String).
Total Size
Specify an integer to determine the maximum size, in bytes, of the
aggregated names and values in a single entity.
Max Name Length
Specify an integer to determine the maximum size, in bytes, of a name
attribute used in this profile. The default is 512 bytes.
Max Value Length
Specify an integer to determine the maximum size, in bytes, of a value
attribute used in this profile The default is 1024 bytes.
No Match Policy
Select an option to determine the action taken when a given name does
not match a Name Matching expression in the configured Validation List
(refer to Validation List tab on page 110).
Error

The Profile validation fails and an error is generated. This is the


default.

Pass-thru
The given Name Value pair is passed through to the next step in
processing.
Set

The given Name token is replaced with a default value. The No


Match Map Value input appears when this option is selected.

Strip

The Name-Value pair is removed from the entity (headers, Post


body, Query String or cookie) and processing continues.

No Match Map Value


Specify an alphanumeric string. The Value of any Name Value pair that
Appendix A. Referenced objects

109

does not match at least one entry in the Validation List will be replaced
with this constant value when the No Match Policy is Set.
No Match XSS Policy
When set to on, name values that do not match an entry in the Validation
List are checked for Cross Site Scripting (sometimes called CSS or XSS)
signatures. These signatures are generally attempts to obfuscate the real
meaning of the value if the value were displayed directly in a browser.
Use to validate any data that might get stored and displayed again later such as the contents of a comment form. When set to on, investigates
escaped characters, those characters with the high-bit set, and various
forms of the term script which is often used to engage JavaScript on a
browser without the user's knowledge. The default is off.

Validation List tab


The Name-Value Profile works by comparing each name of a name-value pair to
the expression on the Validation List. If no match is found, the No Match Policy is
executed. When a match is found, the corresponding value is compared to the
corresponding Value Constraint in the Validation List. If a match is found, the
Name Value Pair passes. If no match is found, the Failure Policy is executed. In
addition, unmatched values can also be checked for cross site scripting (XSS).
1. Click the Validation List tab to edit and create a Validation List.
2. Click Add to create new entries.
3. Provide the following inputs:
Name Expression
The regular expression that the submitted names are matched against.
If they match, the value must also match against the corresponding
value constraint to be passed through.
Value Constraint
The regular expression (PCRE style) that is applied to a value input to
determine whether it is an expected input.
Failure Policy
Select an option to determine the action taken when a given value does
not match the Value Constraint expression.
Error

The Profile validation fails and an error is generated. This is the


default.

Pass-thru
The given Name Value pair is passed through to the next step
in processing.
Set

The given Value is replaced with a default value. The Map


Value input appears when this option is selected.

Strip

The Name Value pair is removed from the entity (headers, Post
body, Query String, or cookie) and processing continues.

Map Value
Specify an alphanumeric string. The value will be replaced with this
constant value when the Failure Policy is Set.
Check XSS
When set to on, the values that do not match the Value Constraint
expression are checked for cross site scripting (sometimes called CSS or
XSS) signatures. These signatures are generally attempts to obfuscate
the real meaning of the value if the value were displayed directly in a

110

IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

browser. Use to validate any data that might get stored and displayed
again later - such as the contents of a comment form. When set to on,
investigates escaped characters, characters with the high-bit set, and
various forms of the term script, which is often used to engage
JavaScript on a browser without the user's knowledge. The default is
off.

Processing Rule
You can create global, reusable processing rules which can later be assigned to one
or more processing policies.
1. Select Objects XML Processing Processing Rule to display the catalog.
2. Click Add to display the configuration screen.
3. Provide the following inputs:
Name Specify the name of this Processing Rule.
Admin State
Retain the default setting. To place the object in an inactive
administrative state, click disabled.
Comments
Specify a descriptive object-specific summary.
Rule Direction
Select the rule type or direction.
Error

A specialized bidirectional rule used for error handling

Client to Server
A rule applied only to client-originated documents
Server to Client
A rule applied only to server-originated documents
Both Directions
A bidirectional rule applied to both client- and
server-originated documents
Input Filter
Select a decompression algorithm to apply to the entire message
payload prior to the first action of the rule executing.
gzip

The message will be decompressed using the gzip algorithm.

PKZIP
The message will be decompressed using the pkzip algorithm.
If the message is not compressed using the selected algorithm, an error
will result. This is, in effect, a filter.
Output Filter
Select a compression algorithm to apply to the entire message payload
after the last action of the rule executes.
gzip

The message will be decompressed using the gzip algorithm.

PKZIP
The message will be decompressed using the pkzip algorithm.
The created archive contains only one file. If the message contains
attachments, the attachments are contained in the one file.

Appendix A. Referenced objects

111

Non-XML Processing
Select whether to enable or disable the processing of non-XML
documents.
on

Enables the processing of non-XML documents.

off

(Default) Disables the processing of non-XML documents.

Unprocessed
Select whether to determine whether the actions of the rule will take
effect on the message. This duplicates the Request Type and Response
Type properties of the services.
Actions
Use the Add and Delete buttons, with the list of available processing
actions, to manage actions for this processing rule.
4. Click Apply to save the object to the running configuration.
5. Optionally, click Save Config to save the object to the startup configuration.

Rate Limiter
A Rate Limiter object establishes policies used to control the rate at which requests
are received by a Web Application Firewall. When the rate exceeds the limits set,
the Limiter can reject requests, post notification or shape, or delay traffic to remain
in the limits set. A Rate Limiter object is used by a Web Request Profile.
Select Objects Web Applications Rate Limiter to display the Rate Limiter
catalog. This catalog lists all Rate Limiter objects.
To edit an existing object, click the name. To create a new object, click Add. The
Rate Limiter object configuration page appears.
Provide the following inputs:
Name Specify an alphanumeric name for this object.
Admin State
Retain the default setting. To place the object in an inactive administrative
state, click disabled.
Comments
Specify a descriptive object-specific summary.
Rate

Specify an integer to set the rate of acceptable traffic, per user, expressed in
transactions per second. The default is 500.

Enforcement Style
Select the action taken when the rate limit is exceeded.
Notify Generate log message in the appropriate application domain. Log
targets must subscribe to this event to capture message.
Reject Requests are rejected until transaction rate drops below the
configured limit.
Shape Delay requests as much as possible to lower the transaction rate to
the configured limit. Once too many messages are buffered,
creating a low memory state, transactions are rejected until rate
drops. The ability to shape transactions is limited when concurrent
connections are high.

112

IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

Distinct Users
The count is organized by the identity most recently used. When too many
distinct counts are observed, the users not seen in the longest time are
discarded. This parameter specifies how many distinct users to track before
discarding.
Concurrent Connections
The number of simultaneous connections allowed per user. Set to 0 to
disable this enforcement.

Session Management Policy


A Session Management Policy controls and manages the following Web request
attributes:
v The URL of the pages that start, or begin, a session (such as a login page)
v The lifetime of the session
v Session renewal
Select Objects Web Applications Session Management Policy to display the
Session Management Policy catalog. This catalog lists all Session Management
Policy objects.
Click on the name of an existing Policy to edit it. Click Add to create a new object.
The Session Management Policy configuration page appears.
Provide the following inputs:
Name Specify an alphanumeric name for this Policy. This name appears in all
listings of available Policies.
Admin State
Retain the default setting. To place the object in an inactive administrative
state, click disabled.
Comments
Specify a descriptive object-specific summary.
Auto Renew
If this property is enabled (on), the session lifetime is renewed on each use
of the session. The click of a mouse or submission of a form constitutes a
use. When this is set to on, the Session Lifetime then measures idle time
between uses. When this is set to off, the session lifetime is the total
amount of time allowed before returning to the login sections.
Session Lifetime
Specify an integer that determines the lifetime of a session, in seconds. The
login cookie is only good for the amount of time specified by this property.
The login cookie can be renewed during activity depending on the value of
the Auto Renew property. Use an integer in the range of 1 through 864000.
The default is 3600.
Address Independent Sessions
Normally the session cookie contains the client IP address to prevent using
the session on any other host. Some environments might make this
behavior undesirable. Enabling this property makes the session cookie
address independent.
Start Pages
Select the matching rule that is used to identify start pages. Start pages are
pages that can be accessed without a session cookie. If a security policy is
Appendix A. Referenced objects

113

enforced on the page, these pages will then issue a session cookie. Refer to
Matching Rule on page 106 for more information.

URL Rewrite Policy


You can design a URL Rewrite Policy that defines rules for the following rewrite
and replacement operations:
v Rewrite the entire URL or a portion of the URL
v Replace a header value in the message
v Rewrite the HTTP POST body in the message
The rewrite rules in the URL Rewrite Policy are applied before document
processing. Therefore, the evaluation criteria in the Matching Rule is against the
rewritten value.
Use the following method to create a URL Rewrite Policy:
1. Select Objects XML Processing URL Rewrite Policy to display the URL
Rewrite Policy catalog.
2. Click Add to display the URL Rewrite Policy Configuration (Main) screen.
3. Provide the following inputs:
Name Specify the name of this URL Rewrite Policy.
Admin State
Retain the default setting. To place the object in an inactive
administrative state, click disabled.
URL Rewrite Direction
Select the direction of the URL Rewrite Policy. Direction is applied at
the service level and has no effect on other policies.
Both

Applies to both client requests and server responses.

Request
Applies to client requests only.
Response
Applies to server responses only.
4. Continue with URL Rewrite Rule tab.

URL Rewrite Rule tab


1. Click the URL Rewrite Rule tab to display the URL Rewrite Policy Rule
Configuration (URL Rewrite Rule) screen.
2. Click Add to display the URL Rewrite Policy Property window.
3. Provide the following inputs:
URL Rewrite Type
Select the rule type.
absolute-rewrite
Rewrites the entire URL or a portion of the URL based on a
URL match.
content-type
Replaces the value of the Content-Type header based on a URL
match.

114

IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

header-rewrite
Replaces the value of an arbitrary header based on its value.
post-body
Rewrites the body of an HTTP POST request. The POST body
contains the input values for a basic HTTP POST request.
rewrite
This rule type is deprecated.
Match Expression
Specify a PCRE (Perl-compatible regular expression) that defines the
match condition that triggers the rewrite rule. Depending on the rule
type, a candidate URL or specific HTTP header field is matched against
the expression.
v For absolute-rewrite, content-type, and post-body, defines the
expression to be matched against the URL.
.* or *
Matches any string.
(.*)xsl=(.*)\?(.*)
Matches a string of the following format:
a. A text subpattern.
b. Followed by xsl=.
c. Followed by a text subpattern.
d. Followed by ?. The backward slash (\) in the PCRE is a
URL escape.
e. Followed by a text subpattern.
(.*)&[Xx][Ss][Ll]=([^&]+)(.*)
Matches a string of the following format:
a. A text subpattern.
b. Followed by &.
c. Followed by X or x.
d. Followed by S or s.
e. Followed by L or l.
f. Followed by =.
g. Followed by a text subpattern that does not contain an
ampersand (&) character.
h. Followed by a text subpattern.
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.

Appendix A. Referenced objects

115

If a rewritten URL begins with a host name or port that is different


from the configured remote address, the host name or port portion of
the rewritten URL is ignored.
v For content-type, defines the replacement value for the Content-Type
header.
v For header-rewrite, defines the replacement value for the specified
header.
v For post-body, defines the rewritten body of the HTTP POST. For
example:
If the match pattern is .* or *, specify the complete replacement.
If the match pattern is (.*)xsl=(.*)\?(.*), specify the evaluation
replacement for any text subpattern or retain the original text
subpattern. To retain the first text subpattern, specify $1; to retain
the second text subpattern, specify $2, and so forth. To omit the
second text subpattern only, specify $1$3.
Stylesheet Replace Expression
Specify a PCRE-style replacement that identifies the replacement style
sheet. This option is available for absolute-rewrite or post-body only.
v If the match pattern is .* or *, specify the complete replacement.
v If the match pattern is (.*)xsl=(.*)\?(.*), specify the evaluation
replacement for any text subpattern or retain the original text
subpattern. To retain the first text subpattern, specify $1; to retain the
second text subpattern, specify $2, and so forth. To retain the second
text subpattern only and not use the third text subpattern, specify
http://mantis:8000/$2.
Input URL Unescape
Select whether URL-encoded characters (for example, %2F) that occur in
the rewritten URL are replaced with literal character equivalents. This
option is available for absolute-rewrite or post-body only.
on

Enables the substitution of literal characters for URL-encoded


characters.

off

(Default) Disables the substitution of literal characters for


URL-encoded characters.

Stylesheet URL Unescape


Select whether URL-encoded characters (for example, %2F) that occur in
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 (/).

116

IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

on

(Default) Enables normalization.

off
Disables normalization.
4. Click Save to return to the URL Rewrite Policy Configuration (Main) screen.
5. Click Apply to save the object to the running configuration.
6. Optionally, click Save Config to save the object to the startup configuration.

User Agent
A User Agent is a client that initiates a request for a local service. An XML
Manager uses a User Agent, for example, to retrieve resources from elsewhere on
the network. The settings of a User Agent can affect messages that sent out by a
specific DataPower service when its XML Manager employs a User Agent.
Select Network User Agent to display the User Agent catalog.
Click Add to display the User Agent configuration (Main) screen.
Provide the following inputs:
Name Specify the User Agent name.
Admin State
Retain the default setting. To place the object in an inactive administrative
state, click disabled.
Comments
Specify a descriptive object-specific summary.
HTTP Request-Header
Optionally, include the User Agent HTTP request-header field in client
requests issued by this User Agent, and to specify the contents of the field.
The field contains information about the user agent that sends the request.
The HTTP specification does not require this field.
By default, the appliance does not include the request-header field. Leave
blank to suppress the inclusion of this field in client requests that the User
Agent issues.
Maximum Redirects
Specify the maximum number of HTTP redirect messages that this User
Agent can receive before the it declares the target URL as unreachable.
Timeout
Specify the amount of time, in seconds, that the connection can be idle
before the User Agent times out and closes the connection. Use an integer
in the range of 1 through 86400. The default is 300.
Note: The default timeout for a connection failure is 10 seconds, which
cannot be changed. The timeout applies when a specified server
cannot be contacted.
Click Apply to save the object to the running configuration and return to the object
catalog.
Optionally, click Save Config to save the object to the startup configuration.

Appendix A. Referenced objects

117

Proxy Policy
The User Agent will forward all requests that meet the URL Matching Expression
to an HTTP server instead of to the host that is identified in the target URL. When
there are multiple proxy policies, candidate URLs are evaluated against each proxy
policy in the order in which it was created. Consequently, the sequence of proxy
policies is important.
1. Click the Proxy Policy tab to display the User Agent configuration (Proxy
Policy) screen.
2. Click Add to display the Proxy Policy Property window.
3. Provide the following inputs:
URL Matching Expression
Define the target URL sets associated with this Proxy Policy.
Match patterns can contain the following wildcard syntax:
*

Indicates a string that matches 0 or more occurrences of any


character.

Indicates a single character that matches one occurrence of any


single character.

[]

Indicates a delimited range of alphabetic or numeric characters.


For example, [1-5] would match 1, 2, 3, 4, or 5, and [x-y]
would match x or y.

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


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

Use the toggle to specify whether requests for an identified URL (that
is, a member of the target URL set) are forwarded to the specified
HTTP server.
on

Does not forward requests.

off

(Default) Forwards requests to the specified HTTP server. When


selected, provide the following inputs.
Remote Host
Specify the host name or IP address of the HTTP server
to which to forward requests.
Remote Port
Specify the port on the HTTP server to which to
forward requests.

4. Click Save.
5. Click Apply to save the object to the running configuration.
6. Optionally, click Save Config to save the object to the startup configuration.

SSL Proxy Profile


Certain User Agent requests require a secure (SSL-enabled) connection. The
resources required for SSL support are provided by an SSL Proxy Profile. Refer to
Defining SSL Proxy Profile objects on page 19 for more information.
To assign an instance of an SSL Proxy Profile object to the User Agent, use the
following procedure:
1. Click the SSL Proxy Profile Policy tab.
2. Click Add.

118

IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

3. In the URL Matching Expression field, define the target URL sets associated
with this policy. If the target URL matches this expression, the communication
will use SSL employing the SSL Proxy Profile specified.
Match patterns can contain the following wildcard syntax:
*

Indicates a string that matches 0 or more occurrences of any character.

Indicates a single character that matches one occurrence of any single


character.

[]

Indicates a delimited range of alphabetic or numeric characters. For


example, [1-5] would match 1, 2, 3, 4, or 5, and [x-y] would match x
or y.

You can use any PCRE-compliant expression. For more information, refer to
http://www.pcre.org.
4. From the SSL Proxy Profile list, select an instance of the SSL Proxy Profile
object to support secure access to the HTTP Proxy Server. The SSL Proxy Profile
must be either a client or two-way profile.
5. Click Save.

Basic HTTP Authentication


Certain User Agent requests require basic HTTP authentication (user name and
password). Click the Basic-Auth Policy tab to display the User Agent configuration
(Basic-Auth Policy) screen, which lists all user name/password pairs.
Click Add to display the Basic-Auth Policy Property window.
Provide the following inputs:
URL Matching Expression
Define the target URL(s) set associated with this policy. If the target URL
matches this expression, an HTTP Authorization header will be added,
using the User Name and Password supplied.
Match patterns can contain the following wildcard syntax:
*

Indicates a string that matches 0 or more occurrences of any


character.

Indicates a single character that matches one occurrence of any


single character.

[]

Indicates a delimited range of alphabetic or numeric characters. For


example, [1-5] would match 1, 2, 3, 4, or 5, and [x-y] would
match x or y.

You can use any PCRE-compliant expression. For more information, refer
to http://www.pcre.org.
The URL set defined by this matching expression could be identical to the
set defined by the HTTP Proxy Policy, or it could be a subset.
User name
Specify the user name.
Password
Specify the associated password.
Confirm Password
Specify the associated password again.
Appendix A. Referenced objects

119

Click Save to complete basic authentication and return to the User Agent
configuration (Basic-Auth Policy) screen, which now lists the newly created user
name-password pair.
Optionally, click Save Config to save the object to the startup configuration.

SOAP Action Policy


Certain User Agent requests require that the contents of the SOAPAction HTTP
request header field be supplied. Click the Soap-Action Policy tab to display the
User Agent configuration (SOAP-Action Policy) screen, which lists all SOAP
actions.
Click Add to display the SOAP Action Property window.
Provide the following inputs:
URL Matching Expression
Define the target URL set that is associated with this policy. If the target
URL matches this expression, the corresponding header will be inserted in
the request to the resource.
Match patterns can contain the following wildcard syntax:
*

Indicates a string that matches 0 or more occurrences of any


character.

Indicates a single character that matches one occurrence of any


single character.

[]

Indicates a delimited range of alphabetic or numeric characters. For


example, [1-5] would match 1, 2, 3, 4, or 5, and [x-y] would
match x or y.

You can use any PCRE-compliant expression. For more information, refer
to http://www.pcre.org.
Soap Action
Specify the SOAP action (a URI that identifies the intent of the SOAP
HTTP request). In the following example, the Soap Action is:
GetCatalogList
POST /webServices/soap/endpoint HTTP/1.1
Host: www.somedomain.info
Content-Type: text/xml; charset="utf-8"
Content-Length: <length of HTTP request>
SOAPAction: GetCatalogList

Click Save to complete specification of the header field contents and return to the
User Agent configuration (Soap-Action Policy) screen, which now lists the newly
created SOAP action.
Optionally, click Save Config to save the object to the startup configuration.

Public Key Authentication Policy


A User Agent can use public key authentication in its communications with remote
resources. This feature is useful when the agent uses the SCP or SFTP protocol for
communication. Click the PubKey-Auth Policy tab to set the configuration values
for this feature.

120

IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

Click any existing policy to edit the policy, or click Add to create a new policy. The
Public Key Property window is displayed.
Provide the following inputs:
URL Matching Expression
Specify a URL Match expression in the URL Matching Expression field.
Match patterns can contain the following wildcard syntax:
*

Indicates a string that matches 0 or more occurrences of any


character.

Indicates a single character that matches one occurrence of any


single character.

[]

Indicates a delimited range of alphabetic or numeric characters. For


example, [1-5] would match 1, 2, 3, 4, or 5, and [x-y] would
match x or y.

You can use any PCRE-compliant expression. For more information, refer
to http://www.pcre.org.
Examples include the following:
v https://server.domain.com/transactions/*
v sftp://user@server.com/images/*
v scp://user[a-c]@10.10.[0-4].23/inbound/*
Private Key
Select the desired private key. If the Crypto Key object needed is not
presented in the list, click the + button to create the object. The Private Key
file must be uploaded to the local appliance to create the Crypto Key
object.
The remote server must also possess the appropriate certificate. This
certificate must reside in $HOME/.ssh/authorized_keys on the remote
server.
Click Save to add this policy to the list.

Allow Compression Policy


A User Agent can compress the payload of its communications with remote
resources. This feature is useful when the payload is large.
Click the Allow-Compression Policy tab to set the configuration values needed for
this feature.
Click any existing policy to edit the policy, or click Add to create a new policy. The
Allow Compression Property window is displayed.
Provide the following inputs:
URL Matching Expression
Specify a URL Match expression in the URL Matching Expression field.
Match patterns can contain the following wildcard syntax:
*

Indicates a string that matches 0 or more occurrences of any


character.

Appendix A. Referenced objects

121

Indicates a single character that matches one occurrence of any


single character.

[]

Indicates a delimited range of alphabetic or numeric characters. For


example, [1-5] would match 1, 2, 3, 4, or 5, and [x-y] would
match x or y.

You can use any PCRE-compliant expression. For more information, refer
to http://www.pcre.org.
Allow Compression
Use the toggle to enable (on) or disable (off) compression.
Click Save to add this policy to the list.

Restrict to HTTP 1.0 Policy


The User Agent can restrict HTTP communications to the HTTP 1.0 specification, if
so desired. Use this Policy to control this behavior. Click the Restrict to HTTP 1.0
Policy tab.
Click any existing policy to edit the policy, or click Add to create a new policy. The
Restrict to HTTP 1.0 Policy Property window is displayed.
Provide the following inputs:
URL Matching Expression
Specify a URL Match expression in the URL Matching Expression field.
Match patterns can contain the following wildcard syntax:
*

Indicates a string that matches 0 or more occurrences of any


character.

Indicates a single character that matches one occurrence of any


single character.

[]

Indicates a delimited range of alphabetic or numeric characters. For


example, [1-5] would match 1, 2, 3, 4, or 5, and [x-y] would
match x or y.

You can use any PCRE-compliant expression. For more information, refer
to http://www.pcre.org.
Restrict to HTTP/1.0
Use the toggle to enable (on) or disable (off) HTTP protocol restriction.
Click Save to add this policy to the list.

Inject Header Policy


The User Agent can inject an HTTP Header and corresponding value into the
communication with the remote server. Click the Inject Header Policy tab.
Note: A Multi-Protocol Gateway can also inject HTTP headers. The User Agent
operates on the communication after the gateway.
Click any existing policy to edit the policy, or click Add to create a new policy. The
Inject Header Property window is displayed.
Provide the following inputs:

122

IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

URL Matching Expression


Specify a URL Match expression in the URL Matching Expression field.
Match patterns can contain the following wildcard syntax:
*

Indicates a string that matches 0 or more occurrences of any


character.

Indicates a single character that matches one occurrence of any


single character.

[]

Indicates a delimited range of alphabetic or numeric characters. For


example, [1-5] would match 1, 2, 3, 4, or 5, and [x-y] would
match x or y.

You can use any PCRE-compliant expression. For more information, refer
to http://www.pcre.org.
Header Name
Specify the name of the HTTP Header to inject.
Header Value
Specify the corresponding value string for the injected header.
Click Save to add this policy to the list.

Chunked Uploads Policy


The User Agent can use HTTP 1.1 Chunked content encoding. This is useful for
streaming large documents. When the appliance employs the HTTP 1.1 protocol,
the body of the document can be delimited by either Content-Length or chunked
encoding. While all servers will understand how to interpret Content-Length,
many applications will fail to understand Chunked encoding. For this reason,
Content-Length is the standard method. However doing so interferes with the
ability of the appliance to fully stream. To stream full documents towards the
backend server, this property should be enabled. However, the backend server
must be RFC 2616 compatible, because this feature cannot be renegotiated at run
time, unlike all other HTTP 1.1 features that can be negotiated down at runtime if
necessary.
Click the Chunked Uploads Policy tab.
Note: A Multi-Protocol Gateway can also control Chunked Uploads. The User
Agent operates on the communication after the Multi-Protocol Gateway.
Click any existing policy to edit the policy, or click Add to create a new policy. The
Chunked Uploads Property window is displayed.
Provide the following inputs:
URL Matching Expression
Specify a URL Match expression in the URL Matching Expression field.
Match patterns can contain the following wildcard syntax:
*

Indicates a string that matches 0 or more occurrences of any


character.

Indicates a single character that matches one occurrence of any


single character.

Appendix A. Referenced objects

123

[]

Indicates a delimited range of alphabetic or numeric characters. For


example, [1-5] would match 1, 2, 3, 4, or 5, and [x-y] would
match x or y.

You can use any PCRE-compliant expression. For more information, refer
to http://www.pcre.org.
Enable/Disable HTTP 1.1 Chunked Request Bodies
Use the toggle to enable (on) or disable (off) chunked encoding.
Click Save to add this policy to the list.

FTP Client Policies


The User Agent can associate a set of FTP URLs with a specified policy that
controls the default values of many FTP client options for outgoing FTP
connections. These controls can be further overridden by query parameters in the
URL that is used to initiate the file transfer.
Click the FTP Client Policies tab to display the User Agent configuration (FTP
Client Policies) screen.
Click any existing policy to edit or click Add to create a new policy to display the
FTP Client Policies Property window.
Provide the following inputs:
URL Matching Expression
Specify a shell-style expression that defines a URL set.
Match patterns can contain the following wildcard syntax:
*

Indicates a string that matches 0 or more occurrences of any


character.

Indicates a single character that matches one occurrence of any


single character.

[]

Indicates a delimited range of alphabetic or numeric characters. For


example, [1-5] would match 1, 2, 3, 4, or 5, and [x-y] would
match x or y.

You can use any PCRE-compliant expression. For more information, refer
to http://www.pcre.org.
Passive Mode
Select how the use of FTP passive mode to control the direction in which
FTP data connections are made.
Passive Mode Not Requested
Do not use the FTP PASV command to allow the client to open
FTP data connections. The FTP server will open all data
connections to the FTP client. Often, this mode is incompatible
with firewalls.
Request Passive Mode
Use the FTP PASV command to request that the FTP client be
allowed to open all data connections to the FTP server, but do not
fail if the server does not support PASV.

124

IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

Require Passive Mode


(Default) Use the FTP PASV command to request that the FTP
client be allowed to open all data connections to the FTP server,
and fail if the server does not support PASV.
Encrypt Command Connection
Select how to control the use of TLS to secure the FTP command
connection.
No Authentication Requested
(Default) Do not use the FTP AUTH command to allow encrypt
the command connection. The user name and password will be
passed in the clear.
Request TLS Authentication
Use the FTP AUTH TLS command to encrypt the command
connection, if available.
Require TLS Authentication
Use the FTP AUTH TLS command to encrypt the command
connection. If not available, fail.
Stop Command Encryption After Authentication
Select how to control the cessation of FTP command channel encryption
after user authentication. Encryption must be stopped for compatibility
with NAT (Network Address Translation) and other firewall applications.
Although this behavior might be a security risk, this behavior is the only
option when a NAT is in use.
Leave Encrypted
(Default) Leave the FTP command connection encrypted after
(optional) authentication of the USER and PASS commands. The
command connection remains secure. This setting is not compatible
with NAT and many firewalls.
Request Stop Encryption
Use the FTP CCC command to request the end of encryption of the
command channel using TLS, if supported by the server.
Require Stop Encryption
Use the FTP CCC command to request the end of encryption of the
command channel using TLS. If not supported, fail. Some servers
do not support CCC. This setting is required for compatibility with
NAT and many firewall.
Encrypt File Transfers
Select how to control the encryption of file transfers. All setting are
compatible with NAT.
Unencrypted Data
(Default) Do not encrypt FTP data connections, even if the
command channel is encrypted. Use the FTP PROT C command if
command channel is encrypted or has been encrypted.
Request Data Encryption
Request encryption of FTP data connections using the FTP PROT P
command. This setting requires that the command change is
encrypted or has been encrypted. Do not fail if the server does not
support data encryption.
Require Data Encryption
Request encryption of FTP data connections using the FTP PROT P
Appendix A. Referenced objects

125

command. This setting requires that the command change is


encrypted or has been encrypted. Fail if the server does not
support data encryption.
Data Type
Select the default data type of file transfers. In most cases, the default
value of binary is appropriate.
ASCII Data
Transfer files in ASCII mode. This setting allows for the
standardizations of end-of-line conventions between different
operating systems. This setting increases the overhead at both ends
of the transfer. This setting uses the FTP TYPE A command.
Image (Binary) Data
(Default) Transfer files in image mode, which transfers data as
binary 8-bit bytes. This setting is more efficient and has less
overhead at both ends of the transfer. Some XML files, such as
ones that are signed, must be transferred in image mode. This
setting uses the FTP TYPE I command.
Write Unique Filename if Trailing Slash
Select whether the FTP server creates unique file names. Some FTP servers
provide the STOU command. The STOU command causes the FTP server
to choose a unique file name to write to in the current directory, instead of
having the FTP client choose a unique name. When enabled and the URL
end in a slash, the STOU command is used instead of the STOR
command. Before enabling, ensure that the FTP server support the STOU
command.
Request Unique File Name When Trailing Slash
(Default) If the supplied file name ends in a slash (before the
question mark (?) character that initiates the query parameter, or
the semicolon (;) character that begins the suffix), use the STOU
command to request that the server generates a unique file name
in the target directory. This behavior allows multiple systems to
write files to the same directory without any risk of duplicate file
names that overwrite each other. The transfer fails if the FTP server
does not support the STOU command.
Use Supplied File name
Always uses the supplied file name to generate the target file name
that is requested on the server. This setting uses the STOR
command to initial the transfer. If the URL ends in a slash, the
transfer generally fails, because there is only a directory
specification (no file name).
Quoted Commands
Select an FTP Quoted Command to send to the FTP server before each
STOU, STOR, or RETR command.
Size Check
Select whether to perform a size check after a transfer.
Disabled
Do not perform this check.
Optional
(Default) If the FTP SIZE command is available, use it to check the
size of the file after transfer. The SIZE command compares the

126

IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

returned value to the number of bytes that were transferred. If not


equal, the transfer is marked as failing.
Click Save to add this policy to the list.

Web Application Firewall


A Web Applications Firewall provides security, proxy, threat mediation and content
processing services for a Web-based application (such as enrollment, benefits
management, ticket sales, or a trading system). The Web Applications Firewall is
designed to handle traffic that is primarily URL-encoded HTTP form POST
operations (or HTTP GET with or without Query Strings) and not primarily Web
services SOAP-based XML payloads (although XML traffic can be handled as well).
The Web Application Firewall offers:
v Destination service proxy
v SSL termination
v Authentication and authorization service
v Rate limiting
v Session start and timeout enforcement
v URL-encoded name-value input processing
v HTTP protocol filtering
v Threat protection, such as SQL Injection
v Cookie handling, including sign and encrypt
v Error handling
v XML and non-XML content processing
1. Select Objects Services Web Application Firewall to display the Web
Application Firewall catalog. The catalog lists all Web Application Firewall
objects that are configured in the current domain.
2. To edit an existing Web Application Firewall, click the name of the firewall in
the catalog. To create a new Web Application Firewall service, click Add. The
Web Application Firewall Configuration (Main) screen is displayed.
3. Provide the following inputs:
Name Specify a unique name for this object. The name must be unique
throughout the appliance.
Admin State
Retain the default setting. To place the object in an inactive
administrative state, click disabled.
Comments
Specify a descriptive object-specific summary.
Remote Host
Specify the host name or IP address of the backend server. To use a
load balancer, specify the name of the Load Balancer Group.
If the appliance should employ an SSL connection to the backend
server, configure an SSL Proxy Profile that in turn uses a Crypto Profile
configured for client (or forward) connections.
Remote Port
Specify the TCP port number of the backend server.
SSL Proxy Profile
Select an existing SSL Proxy Profile to assign the SSL Proxy Profile to

Appendix A. Referenced objects

127

this handler. When selected, communication with clients, the backend


server, or both will use SSL in accordance with the configured Crypto
Profile.
v To implement SSL communication with requesting clients, use an SSL
Proxy Profile that uses a Crypto Profile configured as a Server
(reverse) profile. Under Source Addresses, set the SSL check box for
at least one source address.
v To implement SSL communication with the backend server, use an
SSL Proxy Profile that uses a Crypto Profile configured as a Client
(forward) profile.
v To implement SSL communication with both requesting clients and
the backend server, use an SSL Proxy Profile that uses a Crypto
Profile configured for two-way SSL.
Refer to Defining SSL Proxy Profile objects on page 19 for more
information.
Security Policy
To establish the security policy to be enforced by this firewall, select an
Application Security Policy.
To override (disable) the defined request or response security policy
that is defined by the selected Application Security Policy, click off for
these fields on this configuration screen.
Refer to Application Security Policy on page 97 for more information.
XML Manager
Select an existing XML Manager to assign that manager to this firewall.
The default XML Manager is used if you do not create one.
An XML Manager manages the compilation and caching of XSL style
sheets and XML documents and provides configuration constraints on
the size and parsing depth of XML documents. You can enable the
streaming of XML operations by configuring the XML Manager to use a
Streaming Compile Option Policy.
Optionally, an XML Manager can employ a User Agent. The User
Agent settings, in turn, can affect the behavior of the gateway when
communicating with backend servers or with clients when returning
responses. User Agent settings override settings on the XML Manager.
More than one firewall can use the same XML Manager.
Refer to XML Manager on page 142 for more information.
Error Policy
Select an existing Error Policy to assign that policy to this firewall.
If any part of the Application Security Policy is violated, the rules in
this policy handle the violation.
This policy is the default policy that handles responses sent to the
client. Because an Application Security Policy can also establish an
Error Policy, the Error Policy established by the Application Security
Policy overrides this selection.
Refer to Error Policy on page 99 for more information.
Request Security
If disabled (off), no request-side security policies are enforced. All

128

IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

requests are allowed through. This property overrides the request


security policy that is defined in the selected Application Security
Policy.
Response Security
If disabled (off), no response-side security policies are enforced. All
responses are allowed through. This property overrides the response
security policy that is defined in the selected Application Security
Policy.
4. Click Apply to save the object to the running configuration.
5. Optionally, click Save Config to save the object to the startup configuration.

Proxy Settings tab


To modify the default proxy settings:
1. Click the Proxy Settings tab.
2. Provide the following inputs:
Normalize URI
When this property is enabled (on, the default), the URI is rewritten to
make the URI RFC-compliant. Certain characters will be escaped;
additionally, characters that are escaped that do not need to be are
unescaped. This makes checking for attack sequences more reliable.
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.
Back Side Timeout
Specify the amount of time, in seconds, that a backside client-connection
can be idle before being abandoned in a transaction.
Front Side Timeout
Specify the amount of time, in seconds, that a front-side client-connection
can be idle before being abandoned in a transaction.

Appendix A. Referenced objects

129

Back Persistent Timeout


Specify the maximum amount of time, in seconds (in the range 0 through
86400, with a default of 180), that a gateway maintains an idle persistent
TCP connection on the backside.
Front Persistent Timeout
Specify the maximum amount of time, in seconds (in the range 0 through
86400, with a default of 180), that a gateway maintains an idle persistent
TCP connection on the front side.
Header and URL Rewrite Policy
Optionally assign a URL Rewrite Policy.
This policy defines rules to rewrite the entire URL or a portion of the
URL, to replace a header value in the message, or to rewrite the HTTP
POST body in the message. The rewrite rules are applied before
document processing. Therefore, the evaluation criteria in the Matching
Rule is against the rewritten value.
Refer to URL Rewrite Policy on page 114 for more information.
3. Click Apply to save the object to the running configuration.
4. Optionally, click Save Config to save the object to the startup configuration.

HTTP Options tab


To modify the default HTTP options:
1. Click the HTTP Options tab.
2. Provide the following inputs:
HTTP Version to Server
Select the HTTP version (HTTP 1.0 or HTTP 1.1, the default) to use on
the server-side connection. Certain HTTP 1.1 features, such as chunked
uploads, require the selection of 1.1. The backend server must also
support HTTP 1.1 for the connection to be established and maintained
using the HTTP 1.1 protocol.
HTTP Response Version
Select the HTTP version (HTTP 1.0 or HTTP 1.1, the default) to use on
client responses. Incoming HTTP 1.0 requests will always be replied to
with 1.0 compatible responses regardless of this setting. Use HTTP 1.1 to
support chunked responses.
Follow Redirects
Some protocols generate redirects as part of the protocol; for example,
HTTP response code 302. If this property is enabled (on, the default) the
firewall tries to resolve the redirects.
Rewrite Host Names When Gatewaying
Some protocols have distinct name-based elements, separate from the
URL, to demultiplex. HTTP uses the Host header for this purposes. When
enabled (on, the default) the backside server receives a request that
reflects the final route. When disabled (off) the backside server receives a
request that reflects the information as it arrived at the DataPower
appliance. Web servers that issue redirects might want to disable this
feature. Web servers often depend on the Host header for the value of
their redirect.
Allow Chunked Uploads
Enable (on) or disable (off, the default) the ability to send Content-Type
Chunked Encoded documents to the backend server.

130

IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

When the appliance uses the HTTP 1.1 protocol, the body of the
document can be delimited by either Content-Length or chunked
encoding. While all servers can interpret Content-Length, many
applications fail to understand Chunked Encoded documents. For this
reason, Content-Length is the standard method.
Retaining the default value interferes with the ability of the appliance to
stream full documents. To stream full documents toward the backend
server, enable this property. When enabled, the backend server must be
RFC 2616 compatible. This feature cannot be renegotiated at run time. All
other HTTP 1.1 features can be negotiated at run time.
Alternatively, this property can be enabled at the User Agent on a
per-URL basis. Refer to User Agent on page 117 for more information.
HTTP Client IP Label
Retain X-Client-IP, the default value, or provide another value (for
example, X-Forwarded-For).
3. Click Apply to save the object to the running configuration.
4. Optionally, click Save Config to save the object to the startup configuration.

Source Addresses tab


Source addresses determine the IP addresses and TCP ports to assign to the
service. Remote clients connect to these addresses. At least one source address
must be configured.
To
1.
2.
3.

add a source address, use the following procedure:


Click the Source Addresses tab to display the Source Addresses catalog.
Click Add.
Provide the following inputs:
Local IP Address
Specify the IP address, host name, or host alias on which the service
listens. The default is 0.0.0.0. This value indicates that the service is
active on all addresses.
Port Number
Specify the TCP port on which the service listens. Use an integer in the
range of 1 through 65535. The default is 3000.
SSL Indicates whether the service acts as an SSL server for requesting clients.
v Select the check box to enable.
v Ensure that the check box is not selected to disable.

When enabled, the Crypto Profile of the selected SSL Proxy Profile
handles these requests.
4. Click Save.
5. Repeat steps 2 through 4 to define additional source addresses.
6. Click Apply to save the object to the running configuration.
7. Optionally, click Save Config to save the object to the startup configuration.

Appendix A. Referenced objects

131

Web Request Profile


A Web Request Profile establishes the security policy to apply to requests that
originate from clients. A Web Request Profile can do any or all of the following:
v Allow or deny SSL communications
v Perform authentication, authorization and audit
v Rate limit traffic
v Filter access by IP address
v Establish error handling
v Manage sessions
v Filter HTTP methods
v Filter HTTP header, URL-encoded HTTP POST, and HTTP Query String values
v Manage XML traffic
v Allow or disallow, encrypt or sign, and filter cookies
v Provide service threat protection, such as filtering SQL injection attacks
Select Objects Web Applications Web Request Profile to display the Web
Request Profile catalog. This catalog lists all Web Request Profile objects.
Click the name of an existing object to edit it. Click Add to create a new Web
Request Profile. The Web Request Profile configuration screen is displayed.
Provide the following inputs:
Name Specify a name for this object. This name appears in the catalog listing and
in all lists of available Web Request Profiles.
Admin State
Retain the default setting. To place the object in an inactive administrative
state, click disabled.
Comments
Specify a descriptive object-specific summary.
Mode Select the satisfaction style.
Admission
If a request passes the criteria defined in this profile, the clients
request (the transaction request) is immediately forwarded to the
backend service. No other matching profile is run.
Prerequisite
If a request passes the criteria defined in this profile, any other
profile that matches the request can now run. The request is not
necessarily forwarded to the backend service. However, if there are
no other matching profile and the request passes this profile, the
request is passed to the backend service.
Each transaction could match more than a single request profile on the
same transaction. If this happens, the satisfaction style helps determine
how the results of those profiles are combined. A failed profile always
results in the failure of the transaction; however, a passed profile of the
prerequisite satisfaction style does not, on its own, guarantee acceptance of
the transaction. In those circumstances, any other matching profiles will be
run and the whole transaction only passes if no failure is found. The
admission style, on the other hand, passes the transaction as soon as the
profile is declared passing.

132

IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

Most profiles will be admission style, but a typical use of a prerequisite


profile would be a broad match that enforces some very basic items
(maximum sizes for example) that is followed up with more specific
matches for stronger criteria.

Profile tab
Click the Profile tab.
Provide the following inputs:
Allow SSL
Select a profile policy regarding SSL communications.
Allow
Allow SSL communications to the appliance. The connection might
employ SSL. If the Web Application Firewall is not configured as an
SSL server and the client attempts to use SSL, the connection is
refused before this policy executes.
Deny
Do not allow SSL communications to the appliance. When this option
is selected, an SSL connection request will be refused even when Web
Application Firewall is configured to accept SSL connections from
clients. This profile will only run when the corresponding match rule,
established in the Application Security Policy, is met.
Require
Require SSL communications links to the appliance. The connection
will not succeed unless the Web Application Firewall is configured as
an SSL Server and the client requests SSL communications.
AAA Policy
Select an AAA Policy to establish AAA filtering on Web requests. Only
those requests that successfully pass the AAA policy selected will be
forwarded to the backend service. Leave the default selection (none) to
enforce no authentication and authorization policy on requests. Any input
to this transaction as XML, application/www-url-encoded, or
multipart/form-data MIME types will be automatically provided to the
AAA processing policy.
Refer to AAA Policy on page 57 for more information.
Rate Limiting
Select a Rate Limit Policy to enforce rate limiting on Web requests. A Rate
Limit Policy restricts identities (as determined by AAA or the client IP
address if AAA has not been selected) to a specific number of transactions
per second or a specific number of concurrent transaction connections.
Refer to Rate Limiter on page 112 for more information.
Retain the default value of (none) to not enforce rate limiting.
To limit connections from a given IP address (after a count of requests
from that address results in an error) hits a certain level, use an Error
Policy (refer to Error Policy on page 99). An Error Policy allows for error
count monitoring.
Access Control List
Select an Access Control List. This Access Control List will be used to
allow or deny access to this service based on the IP address of the client.
When attached to a service, an Access Control List denies all access by
Appendix A. Referenced objects

133

default. To deny access to only selected addresses, first grant access to all
addresses (allow 0.0.0.0) and then create deny entries for the desired
hosts.
Retain the default value of (none) to not enforce access control.
Error Policy
Select an Error Policy. This Error Policy will run when any client request
violates this Web Request Profile. The Error Policy selected will also
override any Error Policy selected at the Web Application Firewall object
level.
Retain the default value of (none) to not enforce no Error Policy. Refer to
Error Policy on page 99 for more information.
Session Policy
Select a Session Policy. A Session Policy establishes the URLs that are
acceptable starting points (start pages) for a Web application session. In
addition, a Session Policy limits the duration of any session.
Retain the default value of (none) to not enforce session management.
Refer to Session Management Policy on page 113 for more information.
Content-Type List
Specify which content-type headers to allow on the request. Use a PCRE
to define the allowed content types, such as text/xml. If you do not define
any content type, all content types are allowed.
v Requests without a content type are assumed to have their content-type
header set to an empty string.
v Requests without a body are not subject to this constraint.

Methods & Versions tab


Click the Methods & Versions tab to control the HTTP methods and versions
accepted by this Profile.
Provide the following inputs:
Methods
Use the check boxes to establish accepted HTTP methods. Any request that
does not employ one of the checked methods will be rejected by the Profile.
Versions
Use the check boxes to establish accepted HTTP versions. Any request that
does not employ one of the checked versions will be rejected by the Profile.

Processing tab
It is possible to perform actions on Web requests (such as transform XML content,
if encountered, or send a copy of request content to a third location). Click the
Processing tab to access these configuration options.
Provide the following inputs:
XML Processing
Select how requests containing an XML MIME type in the HTTP header
Content-type: field (text/xml, for example), are processed.
No processing
(Default) No processing performed.

134

IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

Well Formed XML


The appliance parses the request to validate that the request is
well-formed XML. The XML Transformation Rule specified then
runs on the request and the result is used as the request content.
Well Formed SOAP
The appliance parses the request to validate that the request
adheres to the SOAP specifications. The XML Transformation Rule
specified then runs on the request and the result is used as the
request content.
XML Transformation Rule
Select a Processing Rule for requests when they contain an XML MIME
type and the XML processing policy is set to Well Formed XML or Well
Formed SOAP. Refer to Processing Rule on page 111 for more
information.
Non-XML Processing
Select how requests that do not contain an XML MIME type in the HTTP
header Content-Type field (www-url-encoded, for example), are processed.
No processing
(Default) No processing performed.
Side-Effect Rule
The appliance executes the Non-XML Processing Rule specified.
This rule cannot alter the content of the request (cannot access the
INPUT and OUTPUT multistep processing contexts). The Rule can
perform such actions as authenticate and authorize, or send a copy
of the request content to a third destination.
Binary Rule
The appliance executes the Non-XML Processing Rule specified.
The request payload is submitted as an non-parsed binary object.
This rule can alter the content of the request. The Rule can perform
such actions as authenticate and authorize, convert to XML,
repackage with additional information retrieved from elsewhere or
send a copy of the request content to a third destination. The result
of this rule is then used as the request payload for further
processing.
Non-XML Processing Rule
Select a Processing Rule for requests when they do not contain an XML
MIME type and the XML processing policy is set to Side Effect or Binary.
Refer to Processing Rule on page 111 for more information.

Name Value tab


The profile can filter the names and corresponding values of HTTP headers,
URL-encoded HTTP Post body content or HTTP Query strings. These values can
also be mapped to alternate values. This provides a means to control the
name-value pairs passed to the backend server, thus providing both content control
and threat protection. This is done using the inputs available on the Name Value
tab.
Provide the following inputs:
Header Name-Value Profile
Select a Name-Value Profile. Each HTTP header name-value pair will be

Appendix A. Referenced objects

135

subjected to the rules set forth in the selected Profile. If no profile is


specified, any header is allowed. Refer to Name-Value Profile on page
108 for more information.
URL-Encoded Body Name-Value Profile
Select a Name-Value Profile. Each element in the HTTP POST body will be
subjected to the rules set forth in the selected Profile. If no profile is
specified, any element is allowed. Refer to Name-Value Profile on page
108 for more information.
Allow Query String
Select an option to determine how to handle HTTP Query Strings.
Allow Query strings are allowed. When selected, the Query String
Name-Value Profile input is displayed.
Deny

Query strings are not allowed. Requests that contain query strings
are rejected by this profile.

Require
Query strings must be present in the request. Requests without
query strings are rejected by this profile. When selected, the Query
String Name-Value Profile input is displayed.
Query String Name-Value Profile
Select a Name-Value Profile. Each query string name-value pair in the
HTTP request is subject to the rules in the selected profile. If no profile is
specified, any query string pair is allowed. Refer to Name-Value Profile
on page 108 for more information.

Cookie tab
A Web Request Profile can manage cookies. Cookies can be allowed, denied or
required. When cookies are not denied, the Profile can sign or encrypt cookies, as
well as enforce filters on the name-value pairs contained in the cookie. Click the
Cookie tab to access these configuration properties.
Provide the following inputs:
Allow Cookies
Select how cookies are handled by this profile.
Allow Cookies are allowed. When this option is selected, the
Sign/Encrypt Cookies, and Cookie Content Name-Value Profile
inputs appear.
Deny

Cookies are not allowed. Requests containing cookies will be


rejected by this profile.

Require
Cookies must be present in the request. Requests with no cookies
will be rejected by this profile. When this option is selected, the
Sign/Encrypt Cookies, and Cookie Content Name-Value Profile
inputs appear.
Sign/Encrypt Cookies
Select how to enable signing or encrypting of cookie content.
Encrypt
When this option is selected, the appliance encrypts outbound
cookies sent by the backend application. When the client returns
the cookie on a subsequent request, the appliance decrypts the

136

IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

cookie before passing it back to the server. The Secret Key and IP
Address-specific Cookie inputs appear when this option is
selected.
(none) (Default) Cookies are neither signed nor encrypted. This is the
default.
Sign

When this option is selected, the appliance signs outbound cookies


sent by the backend application. When the client returns the cookie
on a subsequent request, the appliance verifies and removes the
signature before passing it back to the server. The Secret Key and
IP Address-specific Cookie inputs appear when this option is
selected.

Secret Key
Signing or Encrypting cookies requires a secret password phrase for the
cryptographic operation. If this key is the same on multiple appliances,
then each appliance can verify or decrypt a cookie generated by another
appliance without the need to maintain any state information.
IP Address-specific Cookies
Normally the signed or encrypted cookie contains the client IP address and
this prevents the client from using this cookie from any other host. Some
environments make this behavior undesirable. Disabling this property
makes the generated cookies address independent.
Cookie Content Name-Value Profile
Select a Name-Value Profile. Each name-value pair in the cookie will be
subjected to the rules set forth in the selected Profile. If no profile is
specified, any query string pair is allowed. Refer to Name-Value Profile
on page 108 for more information.

Multipart Form tab


This Web Request Profile can impose limits on multipart/form submissions. Click
the Multipart Form tab to access these configuration options. Here is an example
of a multipart/form submission.
POST 116.xml HTTP/1.0
Host: patriot
User-Agent: Mozilla/5.0 (X11; U; Linux i686; en-US; rv:1.7.12)
Gecko/20051010 Firefox/1.0.7 (Ubuntu package 1.0.7)
Accept: text/xml,application/xml,application/xhtml+xml,text/html;
q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5
Accept-Language: en-us,en;q=0.5
Accept-Encoding: gzip,deflate,rot13
Accept-Charset: ISO-8859-1,utf-8;q=0.7,*;q=0.7
Content-Type: multipart/form-data; boundary=
-----------------------------1943549852707912569510983863
Content-Length: 1289
-----------------------------1943549852707912569510983863
Content-Disposition: form-data; name="upfile"; filename="NOTES"
Content-Type: application/octet-stream
/home/mcm/iso>sudo cdrecord dev=ATAPI:0,1,0 -v speed=4 x86-basic-1.4-20030911.iso
-----------------------------1943549852707912569510983863
Content-Disposition: form-data; name="hdrx21"
PRE1776
-----------------------------1943549852707912569510983863
Content-Disposition: form-data; name="hdrx25"

Appendix A. Referenced objects

137

Post2000
-----------------------------1943549852707912569510983863

Provide the following inputs:


Max Number of Parts
Specify an integer to determine the maximum number of parts
allowed in the request. This defaults to 4.
Max Size Per Part
Specify an integer to determine the maximum size, in bytes, per
part. This defaults to 5000000.
Max Aggregate Size of All Parts
Specify an integer to determine the maximum size, in bytes, of all
parts combined. This defaults to 5000000.
Restrict Sub-Content Types
Use the toggle to restrict types (on) or to allow all types (off). If
enabled, this setting forces the individual form-data content types
to be matched against the general list of request acceptable
content-type expressions provided on the Main configuration panel
for this Web Request Profile.

Threat Protection tab


Click the Threat Protection tab to access the configuration options that provide
basic threat protection services, such as filtering for SQL Injection attacks, limiting
the size of requests, or filtering potentially dangerous content based on URI.
Provide the following inputs:
Minimum Size
Specify an integer to determine the minimum request body size in bytes if
the HTTP method provides a body. The defaults is 0.
Maximum Size
Specify an integer to determine the maximum request body size in bytes if
the HTTP method provides a body. The default is 128000000.
SQL Injection Filter
Set to on to cause the appliance to pass data parameters from the query
string, application/www-urlencoded requests, and multipart/form-data
requests through the standard SQL Injection filter.
Maximum URI Length
Specify an integer to determine the maximum URI length, in characters.
Defaults to 1024.
Filter Unicode
Reject (on) or allow (off) requests if Unicode is detected in the URI. Defaults
to on.
Filter Dot Dot
Reject (on) or allow (off) requests containing .. in URI after URI
normalization has been performed. Defaults to on.
Filter .exe
Reject (on) or allow (off) requests containing exe in URI after URI
normalization has been performed. Defaults to on.

138

IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

Fragmented URI Policy


A URI fragment is the portion of a URI after the hash (#) symbol. Select an
option to determine a policy for handling URI fragments.
Allow URI fragments are allowed.
Reject If the request contains URI fragments, the request will be rejected by
this profile.
Truncate
If the request contains URI fragments, the fragments will be removed
from the request.

Web Response Profile


A Web Response Profile establishes the security policy applied to responses
returned from application servers. A Web Response Profile can do any or all of the
following:
v Establish error handling
v Filter HTTP methods
v Filter HTTP header values
v Manage XML traffic
v Provide service threat protection by managing response sizes
Select Objects Web Applications Web Response Profile to display the Web
Response Profile catalog. This catalog lists all Web Response Profile objects.
Click the name of an existing object to edit it. Click Add to create a new Web
Response Profile. The Web Response Profile configuration screen is displayed.
Provide the following inputs:
Name
Specify a name for this object. This name appears in the catalog listing and in
all lists of available Web Response Profiles.
Admin State
Retain the default setting. To place the object in an inactive administrative
state, click disabled.
Comments
Specify a descriptive object-specific summary.
Mode
Select the satisfaction style.
Admission
If a response passes the criteria defined in this profile, the server
response (the transaction response) is immediately forwarded to the
client. No other matching profile is run.
Prerequisite
If a response passes the criteria defined in this profile, any other
profile that matches the response can now run. The response is not
necessarily forwarded to the backend service. However, if there are
no other matching profile and the response passes this profile, the
response is passed to the backend service.
Each transaction could match more than a single response profile on the
same transaction. If this happens, the satisfaction style helps determine how
Appendix A. Referenced objects

139

the results of those profiles are combined. A failed profile always results in
the failure of the transaction; however, a passed profile of the prerequisite
satisfaction style does not, on its own, guarantee acceptance of the
transaction. In those circumstances, any other matching profiles will be run
and the whole transaction only passes if no failure is found. The admission
style, on the other hand, passes the transaction as soon as the profile is
declared passing.
Most profiles will be admission style, but a typical use of a prerequisite
profile would be a broad match that enforces some very basic items
(maximum sizes for example) that is followed up with more specific matches
for stronger criteria.

Profile tab
Click the Profile tab.
Provide the following inputs:
Error Policy
Select an Error Policy. This Error Policy will run when any client response
violates this Web response Profile. The Error Policy selected will also
override any Error Policy selected at the Web Application Firewall object
level.
Leave the default (none) selected to enforce no Error Policy. Refer to Error
Policy on page 99 for more information.
Content-Type List
Specify which content-type headers to allow on the response. Use a PCRE
to define the allowed content types, such as text/xml. If you do not define
any content type, all content types are allowed.
v Responses without a content type are assumed to have their
content-type header set to an empty string.
v Responses without a body are not subject to this constraint.

Codes & Versions tab


Click the Codes & Versions tab to control the HTTP methods and versions
accepted by this Profile.
Provide the following inputs:
Response Codes
Use the check boxes to establish accepted HTTP methods. Any response
codes that do not employ one of the checked methods will be rejected by
the Profile.
Response Versions
Use the check boxes to establish accepted HTTP versions. Any response
version that does not employ one of the checked versions will be rejected
by the Profile.

Processing tab
It is possible to perform actions on Web responses (such as transform XML content,
if encountered, or send a copy of response content to a third location).
Click the Processing tab to access these configuration options.

140

IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

Provide the following inputs:


XML Processing
Select how responses containing an XML MIME type in the HTTP header
Content-Type field (text/xml, for example), are processed.
No processing
(Default) No processing performed.
Well Formed XML
The appliance parses the response to validate that the response is
well-formed XML. The XML Transformation Rule specified then
runs on the response and the result is used as the response content.
Well Formed SOAP
The appliance parses the response to validate that the response
adheres to the SOAP specifications. The XML Transformation Rule
specified then runs on the response and the result is used as the
response content.
XML Transformation Rule
Select a Processing Rule. The appliance applies this Processing Rule to
responses when the response contains an XML MIME type and the XML
processing policy is set to Well Formed XML or Well Formed SOAP. Refer
to Processing Rule on page 111 for more information.
Non-XML Processing
Select how responses that do not contain an XML MIME type in the HTTP
header Content-Type field (www-url-encoded, for example), are processed.
No processing
(Default) No processing performed.
Side-Effect Rule
The appliance executes the Non-XML Processing Rule specified.
This rule cannot alter the content of the response (cannot access the
INPUT and OUTPUT multistep processing contexts). The Rule can
perform such actions as authenticate and authorize, or send a copy
of the response content to a third destination.
Binary Rule
The appliance executes the Non-XML Processing Rule specified.
The response payload is submitted as an non-parsed binary object.
This rule can alter the content of the response. The Rule can
perform such actions as authenticate and authorize, convert to
XML, repackage with additional information retrieved from
elsewhere or send a copy of the response content to a third
destination. The result of this rule is then used as the response
payload for further processing.
Non-XML Processing Rule
Select a Processing Rule. The appliance applies this Processing Rule to
responses when the response does not contain an XML MIME type and the
XML processing policy is set to Side Effect or Binary. Refer to Processing
Rule on page 111 for more information.

Name Value tab


The Profile can filter the names and corresponding values of HTTP headers. These
values can also be mapped to alternate values. This is done using the inputs
available on the Name Value tab.
Appendix A. Referenced objects

141

Provide the following inputs:


Header Name-Value Profile
Select a Name-Value Profile. Each HTTP header name-value pair will be
subjected to the rules set forth in the selected Profile. If no profile is
specified, any header is allowed. Refer to Name-Value Profile on page
108 for more information.

Threat Protection tab


Click the Threat Protection tab to access the configuration options that provide
basic threat protection services, by limiting the size of responses.
Provide the following inputs:
Minimum Size
Specify an integer to determine the minimum response body size in bytes
if the HTTP method provides a body. This defaults to 0.
Maximum Size
Specify an integer to determine the maximum response body size in bytes
if the HTTP method provides a body. This defaults to 128000000.

XML Manager
The firmware creates a default XML Manager object in the default domain and in
each application. The default instance in each domain can be edited like any other
instance of an XML Manager object. The default instance in each domain operates
independently of each other.
An XML Manager object obtains and manages XML documents, style sheets, and
other document resources on behalf of one or more services. An XML Manager
also provides the following capabilities:
v Basic network configuration, such as load balancing and accessing remote
servers.
v Set manager-associated limits on the parsing of XML documents. By default, the
appliance imposes limits on various characteristics of XML documents. These
limitations provide for increased security and stability to protect against DoS
attacks or runaway data. Parser limits defined by the XML Manager object that
is associated with a service can be overridden by service-specific settings.
v Enable the caching of documents that this XML Manager object obtains. XML
Manager objects obtain documents via HTTP. The number of documents in the
cache depends on the availability of allocated memory.
v Define extension function mapping. An XML Manager object can automatically
map custom style sheet extension functions to DataPower extension functions.
This ability removes the need to alter or rewrite a style sheet for use by the
appliance. The most common example is the node-set() extension function. If a
service uses style sheets that reference the Microsoft node-set, Oracle node-set,
or Salon nodeset XSLT extension functions, you must map these extensions to
their DataPower equivalent. It is possible to map any extension function to a
DataPower extension function.
v Define the caching policy for documents. This policy allows an administrator to
determine how to cache documents. The policy defines the time-to-live, the
priority, and the type.
v Enable schema validation by defining schema-validation rules. These rules apply
to all documents that match predefined criteria. Alternatively, the appliance can

142

IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

validate documents with a validate action in a processing rule. Do not mix and
match schema validation strategies. Policy-based schema validation is the
preferred strategy.
v Schedule processing rules. Certain applications might require the running of a
scheduled processing rule. Integration with a CA Unicenter Manager is
facilitated by a regularly scheduled processing rule that obtains relationship data
from the Unicenter Manager.

Configure XML Manager objects


The specification of the name completes the required configuration. The remaining
properties modify default values or implement enhanced behavior. For information
about the configuration properties, refer to the online help.
To configure an XML Manager:
1. Select Objects XML Processing XML Manager to display the catalog.
2. Click Add to display the configuration screen.
3. On the Main tab, define the basic configuration.
4. On the XML Parser Limits tab, define the limits to impose when parsing XML
documents.
5. On the Document Cache tab, define the caching of documents that are
obtained via HTTP.
6. On the Extension Functions tab, define the maps for custom extension
functions to DataPower extension functions.
7. On the Document Cache Policy tab, define the documents to store in the
document cache.
8. On the Schema Validation Rules tab, define rules to enforce validation of all
documents that match the defined criteria.
9. On the Scheduled Processing Policy Rule tab, define scheduled processing
rules.
10. Click Apply to save the object to the running configuration.
11. Optionally, click Save Config to save the object to the startup configuration.

Flushing the document cache


The appliances maintains a cache of documents. To flush the cache, click Flush
Document Cache.
This function is available from the following screens:
v The configuration screen for an XML Manager object (Objects XML Processing
XML Manager)
v The status screen for the document cache (Status XML Processing
Document Cache)

Flushing the stylesheet cache


The appliances maintains a cache of style sheets. To flush the cache, click Flush
Stylesheet Cache.
Note: After a change to a Compile Options Policy object, flush the stylesheet
cache. Otherwise, the XML Manger object continues to use the previous
compiled style sheets until they are recompiled.
This function is available from the following screens:
Appendix A. Referenced objects

143

v The configuration screen for an XML Manager object (Objects XML Processing
XML Manager)
v The status screen for the stylesheet cache (Status XML Processing Stylesheet
Cache)

z/OS NSS Client


The z/OS NSS client enables integration with RACF on the z/OS
Communications Server. The z/OS NSS Client object specifies the authentication
information required to allow the DataPower appliance to function as an NSS
client. The z/OS NSS Client object specifies the following properties:
v Remote Address
v Remote Port
v
v
v
v
v

SSL Proxy Profile


Client ID
System Name
User Name
Password

Based on these properties and the request type, the following actions occur:
v DataPower requests a secure connection to the z/OS Communications Server
v RACF performs authentication of users
v RACF performs authorization to resources
v RACF logs authorized and unauthorized attempts to access RACF-protected
resources
v z/OS Communications Server NSS protocol provides return codes and reason
codes for connectivity requests
To support this functionality, the NSS server must be configured to support the
NSS client. See the following z/OS Communications Server documentation for
these configuration steps:
v Enable the XMLAppliance discipline support. For further information, refer to the
section on network security services server in the z/OS Communications Server: IP
Configuration Reference.
v Authorize the client userid to SAF profiles representing security services and
resources. For further information, refer to the section on preparing to provide
network security services in the z/OS Communications Server: IP Configuration
Guide.
v Configure SSL for the TCP connection between the client and server. For further
information, refer to the section on configuring the NSS server in the z/OS
Communications Server: IP Configuration Guide.
Only one physical connection per Remote Address, Remote Port, and Client ID is
allowed. Additional z/OS NSS Client objects might be configured, but if more than
one client with the same tuple try to connect, the connection will fail. If the
connection is not established or the provided parameters are not valid, the object
operational state is down and shows one of the following event codes:
v Invalid registration parameters
v TCP connection retry (interval is 1 minute)
v TCP connection in progress
v Communication failed

144

IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

v Cannot connect to host


For additional information on logged NSS protocol return codes and reason codes,
refer to http://www.ibm.com/support/docview.wss?rs=852&uid=swg21329236 for
z/OS Communications Server: IP Diagnosis Guide updates.
Contact NSS for SAF Authentication is selected as the Authenticate method in the
AAA policy configuration and Contact NSS for SAF Authorization is selected for
the Authorization method.

Creating the z/OS NSS Client


To configure a z/OS NSS client, use the following procedure:
1. Select OBJECTS z/OS Configurations z/OS NSS Client to display the
catalog.
2. To display the configuration screen, click Add.
3. Specify the name of the object in the Name field.
4. Retain the default setting for the Admin State toggle. To place the object in an
inactive administrative state, click disabled.
5. Specify a descriptive object-specific summary in the Comment field.
6. Specify the IP address or hostname of the NSS server in the Remote Address
field.
7. Specify the port on which the NSS server listens in the Remote Port field.
8. Select an SSL Proxy Profile in the SSL Proxy field to provide a secure
connection to the remote authentication server.
9. Specify the client ID to be used for registration with the NSS server in the
Client ID field.
10. Specify the system name to identify the NSS client to the NSS server in the
System Name field.
11. Specify the user name to use to authenticate with the SAF in the User Name
field.
12. Specify the password to use to authenticate with the SAF in the Password
field.
13. Reenter the password in the Confirm Password field.
14. Click Apply to save the object to the running configuration.
15. Optionally, click Save Config to save the object to the startup configuration.

Appendix A. Referenced objects

145

146

IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

Appendix B. Working with variables


Variables can be used in most context, except PIPE. To use a variable, you must
create it with the Set Variable action. This action creates a variable in a specified
context and assigns it a value.
There are the following distinct variable types, each expressed in the var://URL
format:
var://local/variable
A local context variable to addresses a variable called variable in the default
(current) context. The following example transforms the document in the
tmp1 context with a style sheet that is referenced by the stylesheet-1
variable (also in the tmp1 context) and stores the transformed document in
the tmp2 context:
xform tmp1 var://local/stylesheet-1 tmp2

The local context does not persist beyond the scope of the multistep
transaction. A multistep transaction can include both a request component
and a response component. The local context cannot be accessed by any
object outside of the scope of the multistep transaction. In other words, the
service cannot read and use the variable.
A local context variables can be user-defined or based on an extension
variable. For a complete list of the available extension variables, refer to
Extension variables on page 156.
var://context/context/variable
Addresses a variable called variable in a context called context. The
following example transforms the document in the tmp1 context with a
style sheet that is referenced by the stylesheet-1 variable (in the apple
context) and stores the transformed document in the tmp2 context:
xform tmp1 var://context/apple/stylesheet-1 tmp2

A named context does not persist beyond the scope of the multistep
transaction. A multistep transaction can include both a request component
and a response component. The local context cannot be accessed by any
object outside of the scope of the multistep transaction. In other words, the
service cannot read and use the variable.
Note: Creating variables in a named context is the recommended
approach. This form decouples the variable from the input and
output contexts and allows the variable to be accessed from any step
in a multistep scope.
A named context variables can be user-defined or based on an extension
variable. For a complete list of the available extension variables, refer to
Extension variables on page 156.
var://service/variable
Address a variable that is made available to a service (such as HTTP or
XSL Co-Processor) that is attached to a multistep session. The majority of
service variables are read-only and cannot be set.

Copyright IBM Corp. 2002, 2009

147

For a complete list of the available service variables, refer to Service


variables.
var://system/variable
Addresses a global variable that is available in all contexts. System
variables persist beyond the multistep scope and can be read by other
objects in the system. If the content of a variable needs to be read or set
outside the scope of the multistep process, use a system variable.
For a complete list of the available global system variables, refer to
System variables on page 158.
Note: Refer to List of available variables on page 159 for the list of variables that
you can define for document processing.

Service variables
Service variables enable the setting and retrieval of pieces of state that usually
reflect the state of the current transaction.
The available service variables are separated alphabetically into the following
categories:
v Service variables that are available to all DataPower services
v Service variables that are available to only Multi-Protocol Gateway and Web
Service Proxy services
v Configuration services
v Load balancer service
v Legacy MQ-specific services

General service variables


This section contains information about general variables in alphabetic order by
permission category. General variables are available to all services. Table 1 lists the
names and permission for these variables.
Table 1. Names and permissions for variables that are available to all DataPower services
Variable name

Permission

var://service/soap-fault-response

Read-write

Read-write variables
var://service/soap-fault-response
Set when the response input rule is treated as a SOAP fault.

Multi-Protocol Gateway and Web Service Proxy service


variables
This section contains information about general service variables for Multi-Protocol
Gateway and Web Service Proxy services in alphabetic order by permission
category. Table 2 lists the names and permission for these variables.
Table 2. Names and permissions for general service variables that are available to only
Multi-Protocol Gateway and Web Service Proxy services

148

Variable name

Permission

var://service/mpgw/backend-timeout

Read-write

IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

Table 2. Names and permissions for general service variables that are available to only
Multi-Protocol Gateway and Web Service Proxy services (continued)
Variable name

Permission

var://service/mpgw/skip-backside

Write-only

var://service/reply-to-q

Write-only

var://service/reply-to-qm

Write-only

Write-only variables
var://service/mpgw/skip-backside
For Multi-Protocol Gateway and Web Service Proxy services only, indicates
that the service skips backside processing.
Set this variable to 1 to prevent backside processing. Use this variable as a
custom redirect implementation, not as the point of the service. Because
the service is not aware of the processing flow, unusual messages might be
written to the event log.

Read-write variables
var://service/mpgw/backend-timeout
For Multi-Protocol Gateway and Web Service Proxy services only, gets or
sets the backend timeout, in seconds. Setting this variable overrides the
default timeout. Use an integer in the range of 1 through 86400.
var://service/reply-to-q
Read and write the value in the ReplyToQ (Reply to Queue) MQ header.
When read, shows the input message value. When write, changes the
dynamic routing.
var://service/reply-to-qm
Read and write the value in the ReplyToQMgr (Reply to Queue Manager)
MQ header. When read, shows the input message value. When write,
changes the dynamic routing.

Configuration services service variables


This section contains information about variables for configuration services in
alphabetic order by permission category. Table 3 lists the names and permission for
these variables.
Table 3. Names and permissions for variables that are available for configuration services
Variable name

Permission

var://service/config-param

Write-only

var://service/max-call-depth

Read-write

Write-only variables
var://service/config-param/parameterName value
Sets the specified stylesheet parameter to the specified value.

Read-write variables
var://service/max-call-depth
Gets or sets the maximum call depth for each transaction. This variable
controls how many levels of called rules can be layered before an error is
thrown. The default is 128.
Appendix B. Working with variables

149

Load balancer service variables


This section contains information about load balancer variables in alphabetic order
by permission category. Table 4 lists the names and permission for these variables.
Table 4. Names and permissions for variables that are available for load balancers
Variable name

Permission

var://service/lbhealth/

Write-only

Write-only variables
var://service/lbhealth/
Sets the member and state of a load balancer group.

Legacy MQ-specific service variables


This section contains information about MQ-specific variables in alphabetic order
by permission category. MQ-specific variables are available to only the legacy MQ
Host and MQ Proxy services. Table 5 lists the names and permission for these
variables.
Table 5. Names and permissions for service variables that are available to MQ Host and
MQ Proxy services
Variable name

Permission

var://service/correlation-identifier

Read-write

var://service/expiry

Read-write

var://service/format

Read-write

var://service/message-identifier

Read-write

var://service/message-type

Read-write

var://service/mq-ccsi

Write-only

var://service/mqmd-reply-to-q

Write-only

var://service/mqmd-reply-to-qm

Write-only

var://service/persistence

Read-write

var://service/priority

Read-write

var://service/reply-to-q

Read-write

var://service/reply-to-qm

Read-write

var://service/report

Read-write

Write-only variables
var://service/mq-ccsi
Sets the MQ message descriptor character set for an MQ Host or MQ
Proxy service.
var://service/mqmd-reply-to-q
Sets the output MQ message descriptor.ReplyToQ value for an MQ Host
or MQ Proxy service.
var://service/mqmd-reply-to-qm
Sets the output MQ message descriptor.ReplyToQMgr value for an MQ
Host or MQ Proxy service.

150

IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

Read-write variables
var://service/correlation-identifier
Read and write the MQ value in the Correlation Identifier header for
MQ Host and MQ Proxy services.
var://service/expiry
Read and write the MQ value in the Expiry header for MQ Host and MQ
Proxy services.
var://service/format
Read and write the MQ value in the Format header for MQ Host and MQ
Proxy services.
var://service/message-identifier
Read and write the MQ value in the Message Identifier header for MQ
Host and MQ Proxy services.
var://service/message-type
Read and write the MQ value in the Message Type header for MQ Host
and MQ Proxy services.
var://service/persistence
Read and write the MQ value in the Persistence for MQ Host and MQ
Proxy services.
var://service/priority
Read and write the MQ value in the Priority header for MQ Host and
MQ Proxy services.
var://service/reply-to-q
Read and write the MQ value in the ReplyToQ (Reply to Queue) header for
MQ Host and MQ Proxy services. When read, shows the input message
value. When write, changes the dynamic routing.
var://service/reply-to-qm
Read and write the MQ value in the ReplyToQMgr (Reply to Queue
Manager) header for MQ Host and MQ Proxy services. When read, shows
the input message value. When write, changes the dynamic routing.
var://service/report
Read and write the MQ value in the Report header for MQ Host and MQ
Proxy services.

Multistep variables
This section contains information about system variables in alphabetic order by
permission category. Multistep variables usually impact the behavior of specific
actions in the context of a processing rule. Table 6 lists the names and permission
for these variables.
Table 6. Names and permissions for variables that are available to all services
Variable name

Permission

var://service/log/soapversion

Read-write

Read-write variables
var://service/log/soapversion
Gets or sets the version of SOAP for use by a SOAP log targets. Use a
setvar action before a log action to change the version of SOAP to use
when logging this message.
Appendix B. Working with variables

151

Supports the following values:


soap11 Uses SOAP 1.1.
soap12 (Default) Uses SOAP 1.2.

Transaction variables
The available transaction variables are separated alphabetically into the following
categories:
v Asynchronous transactions
v Error handling
v Headers
v Persistent connections
v Routing
v URL
v Web Services Management (WSM)

Asynchronous transaction variables


This section contains information about asynchronous transaction variables in
alphabetic order by permission category. Table 7 lists the names and permission for
these variables.
Table 7. Names and permissions for variables that are available for asynchronous
transactions
Variable name

Permission

var://service/soap-oneway-mep

Read-write

var://service/transaction-key

Write-only

var://service/transaction-name

Write-only

var://service/transaction-timeout

Write-only

Write-only variables
var://service/transaction-key
Sets the token for asynchronous transactions.
var://service/transaction-name
Sets the name for asynchronous transactions.
var://service/transaction-timeout
Sets the timeout for asynchronous transactions.

Read-write variables
var://service/soap-oneway-mep
Gets or sets the SOAP one-way Message Exchange Pattern (MEP)
notification.
v When true, notifies the service layer that this transaction is performing a
one-way MEP operation. This setting enables the service layer to
optimize resource usage while preventing Web Services Addressing
(WSA) from waiting for and faulting on a response that will never
arrive.
v When false, no notification is sent. When using WSA and one-way
MEPs, the service layer will time out waiting for a response.
When a DataPower service is configured for WSA-to-WSA and it receives a
WSA annotated message without the wsa:MessageId, the DataPower service

152

IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

assumes that this is a one-way MEP and notifies the service layer by
setting this value of this variable to true.
This variable is not needed for Web Service Proxy services, as one-way
MEPs are identified by reviewing the specifics of the port operation.

Error handling transaction variables


This section contains information about error handling variables in alphabetic
order by permission category. Table 8 lists the names and permission for these
variables.
Table 8. Names and permissions for variables that are available for error handling
Variable name

Permission

var://service/error-code

Read-write

var://service/error-ignore

Read-write

var://service/error-message

Read-write

var://service/error-protocol-reason-phrase

Write-only

var://service/error-protocol-response

Write-only

var://service/error-subcode

Read-write

var://service/strict-error-mode

Read-write

Write-only variables
var://service/error-protocol-reason-phrase
Sets the protocol-specific reason phrase for an error. This variable
overwrites the reason phrase in the response to provide a short description
that an be understood by people.
var://service/error-protocol-response
Sets the protocol-specific response for an error. This variable overwrites the
protocol-specific response code in an error condition.

Read-write variables
var://service/error-code
Gets or sets the assigned error code from the Result Code table.
var://service/error-ignore
Gets or sets a flag that controls how the Front Side Handler processes error
condition. If the value is set and greater than zero, it does not run any
error handling action and produces a regular response. The content of the
message is produced by an error rule.
The default value is 0.
Currently, on the TIBCO EMS and WebSphere JMS Front Side Handler use
this variable. If any error happens and the variable is set, the Front Side
Handler acknowledges a request message and puts the response message
in the PUT queue. This response message will be a SOAP-fault or any
output that error rule generates.
var://service/error-message
Gets or sets the generic error message that is sent to the client. This
variable contains the error condition that stopped multistep processing.
Setting this variable overwrites the error response that is sent to the client
in an error condition. To set the error message that is written to the log
file, use the var://service/formatted-error-message variable.
Appendix B. Working with variables

153

var://service/error-subcode
Gets or sets the error sub-code. This variable can help to disambiguate the
reason for which the error rule was invoked. Often, the sub-code is the
same as the value of the var://service/error-code variable. Sometimes,
the sub-code is a more specific result code.
var://service/strict-error-mode
Gets or sets the strict error mode. This variable controls the error mode for
multistep processing.
v If the value is set, an invocation of the dp:reject extension element
stops multistep processing.
v If the value is not set, an invocation of the dp:reject extension element
logs a message but does not stop multistep processing.

Headers transaction variables


This section contains information about header variables in alphabetic order by
permission category. Table 9 lists the names and permission for these variables.
Table 9. Names and permissions for variables that are available for headers
Variable name

Permission

var://service/append-request-header/

Write-only

var://service/append-response-header/

Write-only

var://service/set-request-header/

Write-only

var://service/set-response-header/

Write-only

Write-only variables
var://service/append-request-header/
Appends to the protocol request header.
var://service/append-response-header/
Appends to the protocol response header.
var://service/set-request-header/
Sets the protocol request header. This variable directly correlates to the
dp:set-request-header() extension function. Setting the
var://service/set-request-header/FOO variable to the value BAR would
set the request header FOO to BAR.
var://service/set-response-header/
Sets the protocol response header. This variable directly correlates to the
dp:set-response-header() extension function. Setting the
var://service/set-response-header/FOO variable to the value BAR would
set the response header FOO to BAR.

Persistent connection transaction variables


This section contains information about persistent connection variables in
alphabetic order by permission category. Table 10 lists the names and permission
for these variables.
Table 10. Names and permissions for variables that are available for persistent connections

154

Variable name

Permission

var://service/connection/note

Read-write

IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

Read-write variables
var://service/connection/note
Gets or sets the annotation for the current connection. This variable allows
the user to annotate the current protocol session. The value could be an
identifier that could be used to maintain the state based on an existing
protocol session.

Routing transaction variables


This section contains information about routing variables in alphabetic order by
permission category. Table 11 lists the names and permission for these variables.
Table 11. Names and permissions for variables that are available for routing
Variable name

Permission

var://service/routing-url

Write-only

var://service/routing-url-sslprofile

Write-only

Write-only variables
var://service/routing-url
For XML Firewall, Multi-Protocol Gateway, and Web Service Proxy
services, sets the routing URL. This variable can be set one time only and
takes the following format:
<dp:set-variable name="var://service/routing-url"
value="'protocol://target/URI'" />

v For XML Firewall services:


The protocol must be HTTP or HTTPS. If any other protocol, the
service generates an error.
The URI is stripped. To specify the URI, use the var://service/URI
variable, as shown in the following excerpt:
<dp:set-variable name="'var://service/routing-url'"
value="'http://10.10.36.11:2064'" />
<dp:set-variable name="'var://service/URI'"
value="'/service'" />

v For Multi-Protocol Gateway and Web Service Proxy services:


The protocol can be any valid backend protocol.
The URI is absolute and cannot be controlled with the Propagate URI
toggle (WebGUI) or propagate-uri command.
The var://service/routing-url variable is an addition to the
dp:set-target and dp:xset-target extension elements. These extension
elements do not allow the specification of a protocol. These extension
element, if provided, overrides the value of the target server that is
specified in this variable.
var://service/routing-url-sslprofile
Sets the SSL proxy profile for the routing URL (dynamic route). Use this
variable when the ssl property for the DataPower service is not sufficient
for the route to be selected. Use this variable before using the
var://service/routing-url variable.

URL-based transaction variables


This section contains information about URL-based transaction variables in
alphabetic order by permission category. Table 12 on page 156 lists the names and
permission for these variables.
Appendix B. Working with variables

155

Table 12. Names and permissions for variables that are available for URL-based
transactions
Variable name

Permission

var://service/URI

Read-write

Read-write variables
var://service/URI
Gets or sets the request URI of the transaction.

Web Services Management transaction variables


This section contains information about Web Services Management (WSM)
variables in alphabetic order by permission category. Table 13 lists the names and
permission for these variables.
Table 13. Names and permissions for variables that are available to WSM
Variable name

Permission

var://service/wsa/timeout

Read-write

var://service/wsa/genpattern

Read-write

var://service/wsm/wsdl-error

Write-only

var://service/wsm/wsdl-warning

Write-only

Write-only variables
var://service/wsm/wsdl-error
Sets the WSDL error.
var://service/wsm/wsdl-warning
Sets the WSDL warning.

Read-write variables
var://service/wsa/timeout
Gets or sets the timeout value for the WS-Addressing asynchronous reply.
var://service/wsa/genpattern
Gets or sets the pattern for the WS-Addressing asynchronous reply.

Extension variables
This section contains information about system variables in alphabetic order by
permission category. Extension variables usually impact the behavior of specific
actions, particularly fetch, results, and results-async actions. Table 14 lists the
names and permission for these variables.
Table 14. Names and permissions for extension variables

156

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

IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

Write-only variables
var://local/_extension/allow-compression
Enables compression of HTTP requests. Set this variable to allow
compression of outgoing results content and negotiate the returned
document to be compressed if the underlying protocol supports it. For
HTTP, this means the content-encoding and accept-encoding headers.
var://local/_extension/donot-follow-redirect
Disables HTTP redirects. Set this variable to prevent the following of
protocol-level redirect sequences on the outgoing results and fetch calls
that are associated with this context. By default, redirects are followed.
var://local/_extension/header/
Appends the specified header field to the protocol connection. Variables of
the following form can be set to append headers to the dp:url-open()
extension function or results action or fetch action connection when a
context that contains them is used as the input context:
_extension/header/*

The following example would add the HTTP header X-foo: bar to the
HTTP request:
setvar tmpvar2 var://local/_extension/header/X-foo bar
results tmpvar2 http://foo.bar.com/foome.asp tmpvar3"

var://local/_extension/http-10-only
Restricts HTTP to version 1.0. Set this variable to prevent the use of
HTTP/1.1 on the related context of a results action or fetch action.
var://local/_extension/prevent-persistent-connection
Disables HTTP persistent connection. Set this variable to prevent persistent
connections of the outgoing a results action call or fetch action call that is
associated with this context. Persistent connections are supported by
default, where appropriate.
var://local/_extension/sslprofile
Sets the SSL proxy profile for the request. This variable can be set on the
input context to a dp:url-open() extension function or to a results action or
to a fetch action to override the selection of an SSL Proxy Profile. For
instance:
results tmpvar2 https://foo.bar.com/foome.asp tmpvar3

would normally use the SSL Proxy Profile that is associated with any
user-agent configuration for the URL
https://foo.bar.com/foome.asp

If the profile needed to be determined programmatically, perhaps based on


AAA, it could be set up as follows to dynamically resolve the value of
*sslprofiletouse:
setvar tmpvar2 var://local/_extension/sslprofile
var://context/notepad/sslprofiletouse
results tmpvar2 https://foo.bar.com/foome.asp tmpvar3

var://local/_extension/timeout
Sets the request timeout on an input context to override any previously set
timeout parameter. Set the value in seconds.

Appendix B. Working with variables

157

System variables
This section contains information about system variables in alphabetic order by
permission category. Table 15 lists the names and permission for these variables.
Table 15. Names and permissions for system variables
Variable name

Permission

var://system/map/debug

Read-write

var://system/tasktemplates/debug

Read-write

Read-write variables
var://system/map/debug
Gets or sets the debugging level for role-based management (RBM).
var://system/tasktemplates/debug
Gets or sets the debugging level for task templates.

158

IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

List of available variables


Table 16 lists the variables that you can define for document processing.
Table 16. All available variables
Short variable name

Full variable name

Category

allow-compression

var://local/_extension/allow-compression

Extension

append-request-header

var://service/append-request-header

Transaction,
headers

append-response-header

var://service/append-response-header

Transaction,
headers

backend-timeout

var://service/mpgw/backend-timeout

Service, general

config-param

var://service/config-param

Service,
configuration

correlation-identifier

var://service/correlation-identifier

Service, MQ

debug

var://system/map/debug

System

var://system/tasktemplates/debug
donot-follow-redirect

var://local/_extension/donot-follow-redirect

Extension

error-code

var://service/error-code

Transaction, error
handling

error-ignore

var://service/error-ignore

Transaction, error
handling

error-message

var://service/error-message

Transaction, error
handling

error-protocol-reason-phrase

var://service/error-protocol-reason-phrase

Transaction, error
handling

error-protocol-response

var://service/error-protocol-response

Transaction, error
handling

error-subcode

var://service/error-subcode

Transaction, error
handling

expiry

var://service/expiry

Service, MQ

format

var://service/format

Service, MQ

genpattern

var://service/wsa/genpattern

Transaction, WSM

header

var://local/_extension/header

Extension

http-10-only

var://local/_extension/http-10-only

Extension

lbhealth

var://service/lbhealth

Service, load
balancer

max-call-depth

var://service/max-call-depth

Service,
configuration

message-identifier

var://service/message-identifier

Service, MQ

message-type

var://service/message-type

Service, MQ

mq-ccsi

var://service/mq-ccsi

Service, MQ

mqmd-reply-to-q

var://service/mqmd-reply-to-q

Service, MQ

mqmd-reply-to-qm

var://service/mqmd-reply-to-qm

Service, MQ

note

var://service/connection/note

Transaction,
persistent
connection

Appendix B. Working with variables

159

Table 16. All available variables (continued)


Short variable name

Full variable name

Category

persistence

var://service/persistence

Service, MQ

prevent-persistent-connection

var://local/_extension/prevent-persistentconnection

Extension

priority

var://service/priority

Service, MQ

reply-to-q

var://service/reply-to-q

Service, MQ

reply-to-qm

var://service/reply-to-qm

Service, MQ

report

var://service/report

Service, MQ

routing-url

var://service/routing-url

Transaction,
routing

routing-url-sslprofile

var://service/routing-url-sslprofile

Transaction,
routing

set-request-header

var://service/set-request-header

Transaction,
headers

set-response-header

var://service/set-response-header

Transaction,
headers

skip-backside

var://service/mpgw/skip-backside

Service, general

soap-fault-response

var://service/soap-fault-response

Service, general

soap-oneway-mep

var://service/soap-oneway-mep

Transaction,
asynchronous

soapversion

var://service/log/soapversion

Service, multistep

sslprofile

var://local/_extension/sslprofile

Extension

strict-error-mode

var://service/strict-error-mode

Transaction, error
handling

timeout

var://service/wsa/timeout

Transaction, WSM

transaction-key

var://service/transaction-key

Transaction,
asynchronous

transaction-name

var://service/transaction-name

Transaction,
asynchronous

transaction-timeout

var://service/transaction-timeout

Transaction,
asynchronous

URI

var://service/URI

Transaction, URL

wsdl-error

var://service/wsm/wsdl-error

Transaction, WSM

wsdl-warning

var://service/wsm/wsdl-warning

Transaction, WSM

160

IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

Appendix C. Getting help and technical assistance


This section describes the following options for obtaining support for IBM
products:
v Searching knowledge bases
v Getting a fix
v Contacting IBM Support on page 162

Searching knowledge bases


If you encounter a problem, you want it resolved quickly. You can search the
available knowledge bases to determine whether the resolution to your problem
was already encountered and is already documented.
Documentation
The IBM WebSphere DataPower documentation library provides extensive
documentation in Portable Document Format (PDF). You can use the
search function of Adobe Acrobat to query information. If you download
and store the documents in a single location, you can use the search facility
to find all references across the documentation set.
IBM Support
If you cannot find an answer in the documentation, use the Search Support
feature from the product-specific support page.
From the Search Support (this product) area of the product-specific
support page, you can search the following IBM resources:
v IBM technote database
v IBM downloads
v IBM Redbooks
v IBM developerWorks

Getting a fix
A product fix might be available to resolve your problem. To determine what fixes
are available for your IBM product, check the product support site by performing
the following steps:
1. Go to the IBM Support site at the following Web address:
http://www.ibm.com/support
2. Select Support & Downloads Download to open the Support & downloads
page.
3. From the Category list, select WebSphere.
4. From the Sub-Category list, select WebSphere DataPower SOA Appliances.
5. Click the GO icon to display the list of most recent updates.
6. Click the link for the firmware and documentation download that is specific to
your WebSphere DataPower product.
7. Follow the instructions in the technote to download the fix.

Copyright IBM Corp. 2002, 2009

161

Contacting IBM Support


IBM Support provides assistance with product defects. Before contacting IBM
Support, the following criteria must be met:
v Your company has an active maintenance contract.
v You are authorized to submit problems.
To contact IBM Support with a problem, use the following procedure:
1. Define the problem, gather background information, and determine the severity
of the problem. For help, refer to the Software Support Handbook. To access the
online version of this handbook, use the following procedure:
a. Access the IBM Software Support Web page at the following Web address:
http://www.ibm.com/software/support
b. Scroll down to the Additional support links section of the page.
c. Under Support tools, click the Software Support Handbook link.
d. Bookmark this page for future reference.
From this page, you can obtain a PDF copy of the handbook.
2. Gather diagnostic information.
a. Access the product support at the following Web address:
http://www.ibm.com/software/integration/datapower/support
b. Locate the Assistance area of the product support page.
c. Click Information to include to access that technote that lists the
information that is required to report a problem.
3. Submit the problem in one of the following ways:
Online
From the IBM Support Web site (http://www.ibm.com/support), select
Support & Downloads Open a service request. Following the
instructions.
By phone
For the phone number to call in your country, refer to Contacts in the
Software Support Handbook. From the Software Support Handbook Web
site, click Contacts. In the U.S. and Canada, call 1800IBM-SERV
(18004267378) and select option 2 for software.
If the problem you should submit is for a software defect or for missing or
inaccurate documentation, IBM Support creates an authorized program analysis
report (APAR). The APAR describes the problem in detail. Whenever possible, IBM
Support provides a workaround that you can implement until the APAR is
resolved and a fix is delivered.

162

IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

Notices and trademarks


This information was developed for products and services offered in the U.S.A.
IBM may not offer the products, services, or features discussed in this document in
other countries. Consult your local IBM representative for information about the
products and services currently available in your area. Any reference to an IBM
product, program, or service is not intended to state or imply that only that IBM
product, program, or service may be used. Any functionally equivalent product,
program, or service that does not infringe any IBM intellectual property right may
be used instead. However, it is the users responsibility to evaluate and verify the
operation of any non-IBM product, program, or service.
IBM may have patents or pending patent applications covering subject matter
described in this document. The furnishing of this document does not grant you
any license to these patents. You can send license inquiries, in writing, to:
IBM Director of Licensing
IBM Corporation
North Castle Drive
Armonk, NY 10504-1785
U.S.A.
The following paragraph does not apply to the United Kingdom or any other
country where such provisions are inconsistent with local law: INTERNATIONAL
BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION AS IS
WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED,
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR
PURPOSE. Some states do not allow disclaimer of express or implied warranties in
certain transactions, therefore, this statement may not apply to you.
This information could include technical inaccuracies or typographical errors.
Changes are periodically made to the information herein; these changes will be
incorporated in new editions of the publication. IBM may make improvements or
changes in the product(s) or the program(s) described in this publication at any
time without notice.

Trademarks
IBM, the IBM logo, CICS, developerWorks, DB2, DataPower, IMS, RACF,
Redbooks, Tivoli, WebSphere, and z/OS are registered trademarks of the
International Business Machines Corporation in the United States or other
countries.
Adobe, the Adobe logo, PostScript, and the PostScript logo are either registered
trademarks or trademarks of Adobe Systems Incorporated in the United States,
and/or other countries.
Microsoft and Windows are trademarks of Microsoft Corporation in the United
States, other countries, or both.
Java and all Java-based trademarks and logos are trademarks or registered
trademarks of Sun Microsystems, Inc. in the United States and other countries.
Copyright IBM Corp. 2002, 2009

163

Other company, product, and service names may be trademarks or service marks
of others.

164

IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

Index
Special characters
... button
list of referenced object 3
referenced object 2
.java.policy file 37
[configuration-database] stanza, file
entry 89
[ldap] stanza, ssl-keyfile-pwd entry 89
[manager] stanza, replica entry 89
+ button
list of referenced object 3
referenced object 2

A
AAA
authentication
search parameters 100
search parameters 100
TFIM 90
AAA Info File
Authenticate element 84
Authorize element 85
editor
authenticated identities 85
authorized access to resources
confirmation 88
credentials 85
default credential 85
file information 87
map credentials 86
map resources 86
overview 85
unauthenticated identity 85
MapCredentials element 84
MapResource element 84
overview 83
AAA Policy
AAA Info File
Authenticate element 84
Authorize element 85
MapCredentials element 84
MapResource element 84
overview 83
file editor
authenticated identities 85
authorized access to resources
confirmation 88
credentials 85
default credential 85
file information 87
map credentials 86
map resources 86
overview 85
unauthenticated identity 85
LTPA, adding user attributes 83
namespace mappings
XPath bindings 82
object pages
Authenticate 62
Copyright IBM Corp. 2002, 2009

87

87

AAA Policy (continued)


object pages (continued)
Authorize 71
Identity 60
LTPA Attributes 81
Main 57
Map Credentials 68
Map Resource 70
Namespace Mapping 80
Post Processing 77
Resource 69
SAML Attributes 81
Transaction Priority 82
SAML attributes
defining 82
z/OS NSS Client 144
AAAInfo.xsd file 83
accepted configuration
deployment policy 54
Add button
list of referenced object 3
admin account
exporting configuration data 43
Administration menu 1
administrative states, objects 6
AP-REQ message, Kerberos 92
appliance configuration
backing up 43, 44
comparing 52
configuration checkpoints 48
copying
files 47
objects 47
exporting 43
select objects and files 45
importing configuration 50
managing configuration changes 52
moving
files 47
objects 47
reading change report 53
reverting changes 53
undoing changes 53
appliance-wide log
location 33
application domains
backing up configuration 44
Application Security Policy
configuring 30
object pages
Error Maps 31, 99
General 30
Main 97
Request Maps 30, 98
Response Maps 31, 98
Apply button 4
asynchronous transaction variables
service/transaction-timeout 152
asynchronous transactions variables
listing 152
service/transaction-key 152

asynchronous transactions variables


(continued)
service/transaction-name 152
asynchronous variables
service/soap-oneway-mep 152
audit log
location 33
viewing 33
audit: directory 33
Authenticate element, AAA Info File 84
authentication
LDAP 100
search parameters 100
Authorize element, AAA Info File 85
auto-config.cfg file 4

B
backend-timeout variable 149
bold typeface ix
builder
deployment policy 55
buttons
... 2
+ 2
Apply 4
Cancel 4
Delete 5
Edit 3
Logout 1
Save Config 1, 4
Undo 5
View 3

C
CA Unicenter Manager 142
caches
flushing
document cache 143
stylesheet cache 143
Cancel button 4
cert: directory 33
certificate files
location 33
Certificate objects
export packages 43
certificates
DER 9
exporting 11
generating 10
importing 12
PEM 9
PKCS #12 9
PKCS #8 9
security
location, shared 34
location, Web browsers
supported formats 9
uploading 37

34

165

checkpoint configuration files


location 33
chkpoints: directory 33
clear pdp cache CLI 97
clear xsl cache CLI 97
Clone link 6
commands
clear pdp cache 97
clear xsl cache 97
web-mgmt 1
config: directory 33
configuration
managing appliance configuration 41
configuration checkpoints
defining number to allow 48
deleting 50
listing 49
loading 50
overwriting 49
rolling back 50
saving 49
configuration data
applying 4
backing up
WebGUI 43, 44
backing up application domains 44
comparing
WebGUI 52
configuration checkpoints 48
copying
files 47
objects 47
different release level 43
exchanging 43
exporting
location of files 33
select objects and files 45
WebGUI 43
files not included 43
importing
WebGUI 43, 50
managing changes 52
moving
files 47
objects 47
objects not included 43
reading change report 53
reading changes 53
saving 4
undoing changes 53
configuration files
exported, location 33
location 33
TAM
ASCII 88
creating 89
modifying 89
obfuscated 88
configuration service variables
listing 149
service/config-param/ 149
service/max-call-depth 149
configuration states, objects 6
Control Panel
File Management 35
count monitors
configuring 99

166

credentials
identification
configuring 15
creating 15
credentials mapping
LDAP 100
search parameters 100
Crypto Certificate
configuring 13
creating 13
object pages 13
Crypto Firewall Credentials
object pages 14
Crypto Identification Credentials
object pages 15
Crypto Key
configuring 16
creating 16
object pages 16
Crypto Profile
configuring 17
creating 17
object pages 17
Crypto Shared Secret Key
configuring 18
creating 18
object pages 18
Crypto Tools
exporting certificates 11
exporting keys 11
generating certificates 10
generating keys 10
importing certificates 12
importing keys 12
Crypto Validation Credentials
object pages 21
customer support
contacting 162
obtaining fixes 161
searching knowledge bases 161

D
dashboard 1
default log
location 33
Delete button 5
list of referenced object 3
deployment policy
accepted configuration 54
creating 54
filtered configuration 54
modified configuration 54
using the builder 55
Deployment Policy
object pages 54
deployment policy builder
creating matching statements
DER
certificate format 9
key format 9
directories
audit: 33
available 33
cert: 33
chkpoints: 33
config: 33

55

directories (continued)
displaying contents 35
dpcert: 33
export: 33
hiding contents 35
image: 33
local: 33
logstore: 33
logtemp: 33
managing 33
pubcert: 34
refreshing contents 36
sharedcert: 34
store: 34
tasktemplates: 35
temporary: 35
disabled administrative state 6
documentation conventions, typefaces
Domain list 1
down operation state 6
dpcert: directory 33

E
Edit button 3
enabled administrative state 6
error handling variables
listing 153
service/error-code 153
service/error-ignore 153
service/error-message 153
service/error-protocol-reasonphrase 153
service/error-protocol-response 153
service/error-subcode 153
service/strict-error-mode 154
Error Policy
object pages 99
Export link 5
export packages
admin account 43
files not included 43
objects not included 43
permission 43
export: directory 33
Extensible Access Control Markup
Language
See XACML PDP
extension functions
node-set() 142
extension variables
listing 156
local/_extension/allowcompression 157
local/_extension/donot-followredirect 157
local/_extension/header/ 157
local/_extension/http-10-only 157
local/_extension/prevent-persistentconnection 157
local/_extension/sslprofile 157
local/_extension/timeout 157

IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

ix

F
file entry, [configuration-database]
stanza 89
File Management utility, launching 35
file system
See directories
files
.java.policy 37
AAAInfo.xsd 83
auto-config.cfg 4
certificates
location 33
checkpoint configurations
location 33
configurations
location 33
copying 38
remote URL 38
deleting 40
editing
during configuration 4
File Management utility 40
exported, location 33
fetching 38
healthcheck.xml 106
healthcheck.xsl 106
managing 33
moving 39
not in export packages
firmware files 43
log files 43
private keys
location 33
renaming 39
TAM
ASCII configuration 88
creating configuration 89
modifying configuration 89
obfuscated configuration 88
SSL key 88
SSL stash 88
uploading
JKS 37
remote 38
workstation 36
viewing
during configuration 4
File Management utility 40
filtered configuration
deployment policy 54
Firewall Credentials
configuring 14
creating 14
firmware files
between release levels 43
export packages 43
firmware images
location 33
fixes, obtaining 161
flash drive
See directories

G
general variables
listing 148

general variables (continued)


service/soap-fault-response

148

H
health check
filter 106
SOAP request 106
healthcheck.xml file 106
healthcheck.xsl file 106

I
IBM Tivoli Access Manager
See TAM
IBM Tivoli Federated Identity Manager
See TFIM
Identification Credentials
configuring 15
creating 15
image: directory 33
Import Package
creating 42
Include Configuration File
creating 41
object pages 41
installation images
See firmware images
intellectual property 163
italics typeface ix

J
J2RE (j2re1.4.2) 37
j2re1.4.2 (J2RE) 37
j2sdk1.4.2 (SDK) 37
Java Crypto Extension
See SunJCE
Java Crypto Extension Key Store
See JCEKS
Java Key Store
See JKS
java.security package 37
JCE
See SunJCE
JCEKS 37
JKS
crypto extension 37
granting permissions 37
java.security package 37
keytool utility 37
managing 37
required software 37
uploading certificates 37
working with 37

K
KDC, Kerberos 92
Kerberos
AP-REQ message 92
configuring KDC server
KDC 92
keytab 92
principal 92

94

Kerberos KDC server


configuring 94
creating 94
object pages 94
Kerberos keytab
configuring 94
definition 92
Kerberos Keytab File
object pages 94
Key Distribution Center
See KDC
Key objects
export packages 43
key-certificate pairs
creating 9
keys
DER 9
exporting 11
generating 10
importing 12
PEM 9
PKCS #12 9
PKCS #7 9
supported formats 9
knowledge bases
searching 161

L
LDAP
authentication
search parameters 100
credentials mapping
search parameters 100
search parameters 100
licensing
sending inquiries 163
links
Clone 6
Export 5
Show Probe 7
View Logs 5
View Status 6
load balancer group
creating 101
server state 101
Load Balancer Group
adding members 104
assigning weight 104
configuring, basic 103
health
convalescent (down) 102
healthy (up) 102
quarantined (softdown) 102
health checks
enabling 105
overriding port 104
health of members 101
object pages
Health 105
Main 103
Members 104
service/lbhealth/ variable 102
load balancer service variables
listing 150
service/lbhealth/ 150
local: directory 33
Index

167

local/_extension/allow-compression
variable 157
local/_extension/donot-follow-redirect
variable 157
local/_extension/header/ variable 157
local/_extension/http-10-only
variable 157
local/_extension/prevent-persistentconnection variable 157
local/_extension/sslprofile variable 157
local/_extension/timeout variable 157
log files
export packages 43
log/soapversion variable 151
Logout button 1
logs
appliance-wide
location 33
audit
location 33
viewing 33
default
location 33
viewing from catalog 5
viewing from configuration screen 5
viewing object-specific logs 5
logstore: directory 33
logtemp: directory 33
LTPA
adding user attributes, AAA
Policy 83

M
MapCredentials element, AAA Info
File 84
MapResource element, AAA Info File 84
Matching Rule
object pages 106
matching statements
deployment policy builder 55
deployment policy, manual 56
message catalogs 34
message monitors
count monitors 99
modified configuration
deployment policy 54
Modified configuration state 6
monitors
count monitors
configuring 99
message monitors
count monitors 99
monospaced typeface ix
MQ Host variables
listing 150
service/correlation-identifier 151
service/expiry 151
service/format 151
service/message-identifier 151
service/message-type 151
service/mq-ccsi 150
service/mqmd-reply-to-q 150
service/mqmd-reply-to-qm 150
service/persistence 151
service/priority 151
service/reply-to-q 151

168

MQ Host variables (continued)


service/reply-to-qm 151
service/report 151
MQ Proxy variables
listing 150
service/correlation-identifier 151
service/expiry 151
service/format 151
service/message-identifier 151
service/message-type 151
service/mq-ccsi 150
service/mqmd-reply-to-q 150
service/mqmd-reply-to-qm 150
service/persistence 151
service/priority 151
service/reply-to-q 151
service/reply-to-qm 151
service/report 151
Multi-Protocol Gateway
service variables
backend-timeout 149
service/reply-to-q 149
service/reply-to-qm 149
skip-backside 149
multistep variables
log/soapversion 151

N
Name-Value Profile
object pages
Main 108
Validation List 110
namespace mappings, AAA Policy
navigation
Administration menu 1
Network menu 1
Objects menu 1
Services menu 1
Status menu 1
Network menu 1
New configuration state 6
node-set() extension function 142
notices 163

O
object pages
AAA Policy
Authenticate 62
Authorize 71
Identity 60
LTPA Attributes 81
Main 57
Map Credentials 68
Map Resource 70
Namespace Mapping 80
Post Processing 77
Resource 69
SAML Attributes 81
Transaction Priority 82
Application Security Policy
Error Maps 31, 99
General 30
Main 97
Request Maps 30, 98

82

object pages (continued)


Application Security Policy (continued)
Response Maps 31, 98
Crypto Certificate 13
Crypto Firewall Credentials 14
Crypto Identification Credentials 15
Crypto Key 16
Crypto Profile 17
Crypto Shared Secret Key 18
Crypto Validation Credentials 21
Deployment Policy 54
Error Policy 99
Include Configuration File 41
Kerberos KDC server 94
Kerberos Keytab File 94
Load Balancer Group
Health 105
Main 103
Members 104
Matching Rule 106
Name-Value Profile
Main 108
Validation List 110
Processing Rule 111
Rate Limiter 112
Session Management Policy 113
SSL Proxy Profile 19
TAM 89
TFIM 90
URL Rewrite Policy
Main 114
URL Rewrite Rule 114
User Agent
Allow-Compression Policy 121
Basic-Auth Policy 119
Chunked Uploads Policy 123
FTP Client Policies 124
Inject Header Policy 122
Main 117
Proxy Policy 118
Pubkey-Auth Policy 120
Restrict to HTTP 1.0 Policy 122
Soap-Action Policy 120
SSL Proxy Profile 118
Web Application Firewall
General 27
HTTP Options 130
Main 127
Proxy Settings 129
Source Addresses 131
Timeout/Protocol 29
Web Request Profile
Cookies 136
Main 132
Methods & Versions 134
Multipart Form 137
Name Value 135
Processing 134
Profile 133
Threat Protection 138
Web Response Profile
Codes & Versions 140
Main 139
Name Value 141
Processing 140
Profile 140
Threat Protection 142

IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

object pages (continued)


XACML PDP 95
XML Manager 142
objects
administrative state 6
configuration state 6
not in export packages
Certificate 43
Key 43
User 43
operational state 6
referenced
... button 2
+ button 2
creating 2
modifying 2
selecting 2
status 6
TFIM 90
Objects menu 1
operational states, objects 6

P
patents 163
PEM
certificate format 9
key format 9
persistent connections variables
listing 154
service/connection/note 155
PKCS #12
certificate format 9
key format 9
PKCS #7
certificate format 9
PKCS #8
key format 9
Policy Decision Point
See XACML PDP
principal, Kerberos 92
private key files
location 33
private keys
uploading 37
Processing Rule
object pages 111
pubcert: directory 34

R
Rate Limiter
object pages 112
referenced objects
... button 2
+ button 2
creating 2
modifying 2
selecting 2
referenced objects, lists
... button 3
+ button 3
Add button 3
adding 3
creating 3
Delete button 3

referenced objects, lists (continued)


deleting 3
modifying 3
selecting 3
replica entry, [manager] stanza 89

S
SAML attributes
defining, AAA Policy 82
Save Config button 1, 4
Saved configuration state 6
scenarios
Web Application Firewall
benefits management site 26
college enrollment form 25
trading site 26
schemas
location 34
SDK (j2sdk1.4.2) 37
search parameters, LDAP 100
security certificates
shared
location 34
Web browsers
location 34
server pool
See load balancer group
server state
load balancer group 101
service variables
listing 148
types 148
service/append-request-header/
variable 154
service/append-response-header/
variable 154
service/config-param/ variable 149
service/connection/note variable 155
service/correlation-identifier
variable 151
service/error-code variable 153
service/error-ignore variable 153
service/error-message variable 153
service/error-protocol-reason-phrase
variable 153
service/error-protocol-response
variable 153
service/error-subcode variable 153
service/expiry variable 151
service/format variable 151
service/lbhealth/ variable 102, 150
service/max-call-depth variable 149
service/message-identifier variable 151
service/message-type variable 151
service/mq-ccsi variable 150
service/mqmd-reply-to-q variable 150
service/mqmd-reply-to-qm variable 150
service/persistence variable 151
service/priority variable 151
service/reply-to-q variable 149, 151
service/reply-to-qm variable 149, 151
service/report variable 151
service/routing-url variable 155
service/routing-url-sslprofile
variable 155
service/set-request-header/ variable 154

service/set-response-header/
variable 154
service/soap-fault-response variable 148
service/soap-oneway-mep variable 152
service/strict-error-mode variable 154
service/transaction-key variable 152
service/transaction-name variable 152
service/transaction-timeout variable 152
service/URI variable 156
service/wsa/genpattern variable 156
service/wsa/timeout variable 156
service/wsm/wsdl-error variable 156
service/wsm/wsdl-warning
variable 156
Services menu 1
Session Management Policy
object pages 113
sharedcert: directory 34
Show Probe link 7
skip-backside variable 149
SOAP request
healthcheck.xml 106
SSL
client proxy, creating 19
forward proxy, creating 19
reverse, proxy, creating 19
server proxy, creating 19
two-way proxy, creating 20
SSL authentication 17
SSL Proxy Profile
creating
client proxy 19
forward proxy 19
reverse proxy 19
server proxy 19
two-way proxy 20
object pages 19
ssl-keyfile-pwd entry, [ldap] stanza 89
Status menu 1
store: directory 34
style sheets
flushing the cache 143
healthcheck.xsl 106
location 34
subdirectories
creating 35
deleting 36
SunJCE
JCEKS 37
support
See customer support
system variables
listing 158
system/map/debug 158
system/tasktemplates/debug 158
system/map/debug variable 158
system/tasktemplates/debug
variable 158

T
TAM
ASCII configuration file 88
authorization server replicas 89
configuration, general 88
configuring TAM objects 89
creating configuration files 89
Index

169

TAM (continued)
creating TAM objects 89
licensing 88
modifying configuration files 89
obfuscated configuration file 88
object pages 89
refreshing certificates 90
security 88
SSL key file 88
SSL stash file 88
tasktemplates: directory 35
temporary: directory 35
TFIM
AAA 90
object 90
object pages 90
TFIM endpoint
WS-Trust messages 90
Tivoli Access Manager
See TAM
trademarks 163
transaction headers variables
listing 154
service/append-request-header/ 154
service/append-response-header/
154
service/set-request-header/ 154
service/set-response-header/ 154
transaction routing variables
listing 155
service/routing-url 155
service/routing-url-sslprofile 155
transaction URL variables
listing 155
service/URI 156
transaction variables
listing 152
types 152
typeface conventions ix

U
Undo button 5
up operational state 6
URL Rewrite Policy
object pages
Main 114
URL Rewrite Rule 114
User Agent
object pages
Allow-Compression Policy 121
Basic-Auth Policy 119
Chunked Uploads Policy 123
FTP Client Policies 124
Inject Header Policy 122
Main 117
Proxy Policy 118
Pubkey-Auth Policy 120
Restrict to HTTP 1.0 Policy 122
Soap-Action Policy 120
SSL Proxy Profile 118
User objects
export packages 43
utilities
keytool 37

170

V
Validation Credentials
creating
non expiring, non-passwordprotected certificates 21
select certificates 21
types of lists 21
variables
asynchronous
service/soap-oneway-mep 152
asynchronous transactions
listing 152
service/transaction-key 152
service/transaction-name 152
service/transaction-timeout 152
configuration service
listing 149
service/config-param/ 149
service/max-call-depth 149
error handling
listing 153
service/error-code 153
service/error-ignore 153
service/error-message 153
service/error-protocol-reasonphrase 153
service/error-protocolresponse 153
service/error-subcode 153
service/strict-error-mode 154
extension
listing 156
local/_extension/allowcompression 157
local/_extension/donot-followredirect 157
local/_extension/header/ 157
local/_extension/http-10-only 157
local/_extension/preventpersistent-connection 157
local/_extension/sslprofile 157
local/_extension/timeout 157
general
listing 148
service/soap-fault-response 148
list, all available 159
load balancer service
listing 150
service/lbhealth/ 102, 150
MQ Host
listing 150
service/correlation-identifier 151
service/expiry 151
service/format 151
service/message-identifier 151
service/message-type 151
service/mq-ccsi 150
service/mqmd-reply-to-q 150
service/mqmd-reply-to-qm 150
service/persistence 151
service/priority 151
service/reply-to-q 151
service/reply-to-qm 151
service/report 151
MQ Proxy
listing 150
service/correlation-identifier 151

variables (continued)
MQ Proxy (continued)
service/expiry 151
service/format 151
service/message-identifier 151
service/message-type 151
service/mq-ccsi 150
service/mqmd-reply-to-q 150
service/mqmd-reply-to-qm 150
service/persistence 151
service/priority 151
service/reply-to-q 151
service/reply-to-qm 151
service/report 151
Multi-Protocol Gateway
backend-timeout 149
service/reply-to-q 149
service/reply-to-qm 149
skip-backside 149
multistep
log/soapversion 151
persistent connections
listing 154
service/connection/note 155
service
listing 148
type 148
system
listing 158
system/map/debug 158
system/tasktemplates/debug 158
transaction
listing 152
type 152
transaction headers
listing 154
service/append-request-header/
154
service/append-response-header/
154
service/set-request-header/ 154
service/set-response-header/ 154
transaction routing
listing 155
service/routing-url 155
service/routing-url-sslprofile 155
transaction URL
listing 155
service/URI 156
types 147
using 147
Web Service Proxy
backend-timeout 149
service/reply-to-q 149
service/reply-to-qm 149
skip-backside 149
WSM
listing 156
service/wsa/genpattern 156
service/wsa/timeout 156
service/wsm/wsdl-error 156
service/wsm/wsdl-warning 156
View button 3
View Logs link 5
View Status link 6

IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide

W
Web Application Firewall
configuring 27
object pages
General 27
HTTP Options 130
Main 127
Proxy Settings 129
Source Addresses 131
Timeout/Protocol 29
scenarios
benefits management site 26
college enrollment form 25
trading site 26
Web Management Interface 1
Web Request Profile
object pages
Cookies 136
Main 132
Methods & Versions 134
Multipart Form 137
Name Value 135
Processing 134
Profile 133
Threat Protection 138
Web Response Profile
object pages
Codes & Versions 140
Main 139
Name Value 141
Processing 140
Profile 140
Threat Protection 142
Web Service Proxy
service variables
backend-timeout 149
service/reply-to-q 149
service/reply-to-qm 149
skip-backside 149
web-mgmt command 1
WebGUI
accessing 1
Administration menu 1
applying configuration changes 4
canceling changes 4
cloning services 6
common tasks 4
dashboard 1
deleting objects 5
Domain list 1
exporting objects 5
logging in 1
Logout button 1
Network menu 1
Objects menu 1
resetting configuration 5
reverting changes 5
Save Config button 1
saving configuration changes 4
Services menu 1
Status menu 1
viewing object status 6
viewing object-specific logs 5
viewing probe data 7
Welcome screen 1
Welcome screen 1

workstation
uploading files 36
WS-Security Management
See WSSM
WS-Trust messages
TFIM endpoint 90
WSM variables
listing 156
service/wsa/genpattern 156
service/wsa/timeout 156
service/wsm/wsdl-error 156
service/wsm/wsdl-warning 156

X
XACML PDP
configuring 95
object pages 95
XML Manager
caches
flushing the document cache 143
flushing the stylesheet cache 143
configuring 142
document cache, flushing 143
modifying 142
object pages 142
XPath bindings
AAA Policy 82

Z
z/OS NSS Client
creating 145
overview 144

Index

171

172

IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide



Printed in USA