WebSphere DataPower Integration Appliance XI50

Version 3.8.0

Web Application Firewall Developers Guide



WebSphere DataPower Integration Appliance XI50

Version 3.8.0

Web Application Firewall Developers Guide



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

First Edition (November 2009)

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

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

Defining Identification Credentials objects .

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

.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.

19
20
20
21
22
24
24
24
25
25
26

.
.

.
.

. 26
. 27

Chapter 1. Introduction . . . . . . . . 1

Chapter 4. Creating a Web application

firewall from the Control Panel . . . . 29

Scenarios
Scenario
Scenario
Scenario

Defining the general configuration.

Enabling secured communication .
Modifying advanced settings . .
Advanced settings . . . . . .

. . . . . . . . . . .
one: College enrollment form .
two: Benefits management site
three: Trading site . . . .

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

1
1
2
2

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

29
30
30
31

Chapter 2. WebGUI basics . . . . . . . 5

Chapter 5. Managing files. . . . . . . 33

Objects on the appliance . . . . . . . . . . 5

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

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

Chapter 6. Managing the configuration

of the appliance . . . . . . . . . . . 41

Supported cryptographic formats .

Working with keys and certificates
Creating key-certificate pairs .
Generating keys and certificates
Exporting keys and certificates .
Importing keys and certificates .
Working with Certificate objects .
Working with z/OS certificates .
Defining Certificate objects . .
Defining Firewall Credentials objects

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

Copyright IBM Corp. 2002, 2009

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

13
13
13
14
15
16
17
17
17
19

.
.
.
.
.
.
.
.

41
42
43
44
44
45
47
48

. 48

iii

Saving configuration checkpoints . . .

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

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

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

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

49
49
50
50
50
52
52
53
53
54
54
55
56

Appendix A. Referenced objects. . . . 57

Creating AAA Policy objects . . . . . . . . . 57
Main tab . . . . . . . . . . . . . . 57
Identity tab . . . . . . . . . . . . . 60
Authenticate tab . . . . . . . . . . . . 62
Map Credentials tab . . . . . . . . . . 68
Resource tab . . . . . . . . . . . . . 69
Map Resource tab . . . . . . . . . . . 70
Authorize tab. . . . . . . . . . . . . 70
Post Processing tab . . . . . . . . . . . 77
Namespace Mapping tab . . . . . . . . . 80
SAML Attributes tab . . . . . . . . . . 80
LTPA Attributes tab. . . . . . . . . . . 81
Transaction Priority tab . . . . . . . . . 81
Setting namespace data for XPath bindings . . . 82
Defining SAML attributes . . . . . . . . 82
Adding LTPA user attributes . . . . . . . 82
Using an AAA Info file . . . . . . . . . 83
IBM Tivoli Access Manager Integration . . . . 87
IBM Tivoli Federated Identity Manager
Integration . . . . . . . . . . . . . 89
Kerberos objects . . . . . . . . . . . . 92
XACML Policy Decision Point objects. . . . . 95
Application security policies . . . . . . . . . 97
Creating an application security policy . . . . 97
Adding request maps . . . . . . . . . . 98
Adding response maps . . . . . . . . . 99
Adding error maps . . . . . . . . . . . 99
Count Monitor . . . . . . . . . . . . . 99
Creating Error Policy objects . . . . . . . . 100
Defining LDAP Search Parameters objects . . . . 101
Load balancer groups . . . . . . . . . . 102
Intelligent load distribution. . . . . . . . 102
Algorithms for making load balancing decisions 104
Membership . . . . . . . . . . . . . 106
Health checks . . . . . . . . . . . . 106
Session affinity . . . . . . . . . . . . 107
Configuring a load balancer group . . . . . 109
Modifying to use workload management
information . . . . . . . . . . . . . 112
Assigning weight to members . . . . . . . 113
Disabling members . . . . . . . . . . 113
Enabling the retrieval of workload management
information . . . . . . . . . . . . . 114
Defining Matching Rule objects . . . . . . . 117
Name-Value Profile . . . . . . . . . . . 117
Validation List tab . . . . . . . . . . . 119

iv

Defining Processing Rule objects . . . . . .

Creating Rate Limiter objects . . . . . . .
Session Management Policy . . . . . . .
URL Rewrite Policy . . . . . . . . . .
Creating a URL Rewrite Policy . . . . .
User Agent . . . . . . . . . . . . .
Creating a user agent. . . . . . . . .
Modifying the basic configuration . . . .
Adding an HTTP proxy policy . . . . .
Adding an SSL proxy policy . . . . . .
Adding a basic authentication policy . . .
Adding a SOAP action policy . . . . . .
Adding a public key authentication policy. .
Adding a compression policy . . . . . .
Adding a header retention policy. . . . .
Adding an HTTP 1.0 restriction policy . . .
Adding a header injection policy . . . . .
Adding a chunked upload policy. . . . .
Adding an FTP client policy . . . . . .
Creating or editing a Web Application Firewall .
Modifying default Proxy Settings . . . . .
Modifying default HTTP Options. . . . .
Configuring Source Addresses . . . . . .
Web request profiles . . . . . . . . . .
Creating Web request profiles . . . . . .
Defining the basic configuration . . . . .
Modifying the profile. . . . . . . . .
Controlling accepted HTTP methods and
versions . . . . . . . . . . . . .
Defining document processing. . . . . .
Filtering with name-value profiles . . . .
Managing cookies . . . . . . . . . .
Multipart forms . . . . . . . . . .
Protecting against threats . . . . . . .
Forms-based authentication and authorization
Enabling forms-based authentication and
authorization . . . . . . . . . . .
Web response profiles . . . . . . . . .
Creating Web response profiles . . . . .
Main tab . . . . . . . . . . . . .
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

157

Service variables . . . . . . . . .
General service variables . . . . .
Multi-Protocol Gateway and Web Service
service variables . . . . . . . .
Configuration services service variables
Load balancer service variables . . .
Legacy MQ-specific service variables .
Multistep variables . . . . . . .

IBM WebSphere DataPower Integration Appliance XI50: Web Application Firewall Developers Guide

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

120
121
122
123
123
126
127
127
128
128
129
129
130
130
131
131
132
132
133
134
136
137
138
139
139
139
140

.
.
.
.
.
.

141
141
141
142
143
144
144

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

145
148
148
148
149
150
150
151
151
151
152
153
153
153
154

. . .
. . .
Proxy
. . .
. . .
. . .
. . .
. . .

158
158
158
159
160
160
161

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

162
162
163
164
164
165
165
166
166
168
169

Appendix C. Getting help and

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

.
.
.

.
.
.

.
.
.

.
.
.

.
.
.

.
.
.

.
.
.

. 171
. 171
. 172

Notices and trademarks . . . . . . . 173

Trademarks .

. 173

Index . . . . . . . . . . . . . . . 175

Contents

vi

IBM WebSphere DataPower Integration Appliance XI50: 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, Introduction, on page 1
Provides introductory information about Web Application Firewall services on a
DataPower appliance as well as implementation scenarios.
v Chapter 2, WebGUI basics, on page 5
Provides basic informations about using the DataPower graphical interface,
which is referred to as the WebGUI, as well as information about performing
common tasks in the WebGUI.
v Chapter 3, Securing communication, on page 13
Provide information about securing communication to and from the DataPower
appliance. The appliance provide these capabilities with a combination of
utilities and objects.
v Chapter 4, Creating a Web application firewall from the Control Panel, on
page 29
Provide detailed information about developing Web Application Firewall
services on a DataPower appliance.
v Chapter 5, Managing files, on page 33
Provides information about managing files on the appliance.
v Chapter 6, Managing the configuration of the appliance, on page 41
Copyright IBM Corp. 2002, 2009

vii

Provide information about managing the configuration of application domains

and importing and exporting configurations.
v Appendix A, Referenced objects, on page 57
Provides detailed information about configuring objects that are referenced while
developing services on a DataPower appliance.
v Appendix B, Working with variables, on page 157
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 ix
v Reference documentation on page ix
v Integration documentation on page ix
v Problem determination documentation on page x
v Supplemental documentation on page x
You can access and download documents in the DataPower library from the IBM
WebSphere DataPower Product Documentation Portal. These details are discussed
in technical flash 1377654.
http://www.ibm.com/support/docview.wss?rs=2362&uid=swg21377654

Installation and upgrade documentation

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

Administration documentation
v IBM WebSphere DataPower SOA Appliances: Appliance Overview
Provides an introduction and understanding of the IBM Websphere DataPower
SOA appliances.
v IBM WebSphere DataPower Integration Appliance XI50: Administrators Guide

viii

IBM WebSphere DataPower Integration Appliance XI50: Web Application Firewall Developers Guide

Provides instructions for using the DataPower GUI for managing user access,
network access, appliance configuration and system configuration of the
appliance.
v IBM WebSphere DataPower SOA Appliances: Hardware Security Module Guide
A user guide for using a Hardware Security Module (HSM) installed in the
appliance.

Development documentation
v IBM WebSphere DataPower Integration Appliance XI50: XSL Accelerator Developers
Guide
Provides instructions for using the WebGUI to configure XSL Proxy and XSL
Coprocessor services.
v IBM WebSphere DataPower Integration Appliance XI50: XML Firewall Developers
Guide
Provides instructions for using the WebGUI to configure XML Firewall services.
v IBM WebSphere DataPower Integration Appliance XI50: Web Application Firewall
Developers Guide
Provides instructions for using the WebGUI to configure Web Application
Firewall services.
v IBM WebSphere DataPower Integration Appliance XI50: Multi-Protocol Gateway
Developers Guide
Provides instructions for using the WebGUI to configure Multiple-Protocol
Gateway services.
v IBM WebSphere DataPower Integration Appliance XI50: Web Service Proxy Developers
Guide
Provides instructions for using the WebGUI to configure Web Service Proxy
services.

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

Integration documentation
The following documents are available for managing the integration of related
products that can be associated with the DataPower appliance:
v Integrating with Tivoli Composite Application Management for SOA
Provides concepts for integrating the DataPower appliance with IBM Tivoli
Composite Application Management for SOA.
v IBM WebSphere DataPower SOA Appliances: Integrating with Tivoli Security Policy
Manager
Provides detailed information about integrating the DataPower appliance with
IBM Tivoli Security Policy Manager.
v IBM WebSphere DataPower SOA Appliances: Integrating with WebSphere MQ
Preface

ix

Explains the concepts and common use patterns for connecting DataPower
services to WebSphere MQ systems.
v IBM WebSphere DataPower SOA Appliances: Integrating with WebSphere
Transformation Extender
Provides detailed information about integrating the DataPower appliance with
WebSphere Transformer Extender.

Problem determination documentation

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

Supplemental documentation
v Converting between JSON and JSONx
Provides information about and procedures for converting between JavaScript
Object Notation (JSON) and JSONx. JSONx is the JSON as XML.
v Configuring DoD PKI
Provides conceptual information about and procedures for configuring the
DataPower appliance with Department of Defense (DoD) Public Key
Infrastructure (PKI).
v Optimizing through Streaming
Provides conceptual information about and procedures for optimizing the
DataPower appliance through streaming.
v Securing the Last Mile
Provides conceptual information about and procedures for understanding the
DataPower appliance while securing the last mile.
v Understanding LTPA
Provides conceptual information about how the DataPower appliance can use
Lightweight Third Party Authentication (LTPA).
v Understanding SPNEGO
Provides conceptual information about how the DataPower appliance can use
Simple and Protected GSSAPI Negotiation Mechanism (SPNEGO). SPNEGO is
also referred to as Integrated Windows Authentication.
v Understanding Web Services Policy
Provides conceptual information about how the DataPower appliance can use
Web Services Policy (WS-Policy).
v Understanding WS-Addressing
Provides conceptual information about how the DataPower appliance can use
WS-Addressing.

External resources
Beyond the online help, no other informational resource is available on the
appliance. You can access the following external resources if a problem occurs or if
you need help.
DataPower Product Documentation Portal
You can access and download documents in the DataPower library using
the details in technical flash 1377654.

IBM WebSphere DataPower Integration Appliance XI50: Web Application Firewall Developers Guide

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

File naming guidelines

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

xi

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

Object naming guidelines

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

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

Identifies commands, programming keywords, and GUI controls.

italics

Identifies words and phrases used for emphasis and user-supplied

variables.

monospaced
Identifies user-supplied input or computer output.

xii

IBM WebSphere DataPower Integration Appliance XI50: Web Application Firewall Developers Guide

Chapter 1. Introduction
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 Session Start and Timeout Enforcement
v URL-Encoded Name-Value Input Processing
v
v
v
v
v

HTTP Protocol Filtering

Threat Protection, such as SQL Injection
Cookie Handling, including Sign and Encrypt
Error Handling
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 Proxies Destination Address (real host address not exposed)
v Applies SSL Server Proxy Profile
v Default Threat Protections
v Default Multi-Part Form Protections
v Error Handling Policy redirects to friendly page

Copyright IBM Corp. 2002, 2009

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
v Error Handling Policy redirects to friendly page

IBM WebSphere DataPower Integration Appliance XI50: Web Application Firewall Developers Guide

v
v
v
v

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

Chapter 1. Introduction

IBM WebSphere DataPower Integration Appliance XI50: Web Application Firewall Developers Guide

Chapter 2. WebGUI basics

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

Objects on the appliance

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

Working with objects

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

Accessing the WebGUI

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

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

Copyright IBM Corp. 2002, 2009

This screen is separated into the following areas:

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

Common WebGUI conventions

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

Working with referenced objects

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

Input

Figure 1. Input field for referenced objects

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

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

Input

Delete

Add

Figure 2. Input list for referenced objects

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

Viewing and editing local files during configuration

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

Chapter 2. WebGUI basics

Viewing local files

To
1.
2.
3.

view a local file, use the following procedure:

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

4. Click Cancel.

Editing local files

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

Select the file from the lists.

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

Common WebGUI tasks

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

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

Applying and saving changes

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

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

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

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

Viewing messages from the catalog

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

Viewing messages from the configuration pane

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

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

Viewing object status

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

Cloning services
You might want to create a service that is similar to an existing service. For
example, you need two equivalent services, but each service communicates with a
different remote server. In these cases, you can create a clone of an existing service
and edit the clone. The cloning process can expedite the creation of a similar
service.
Use the following procedure to clone a server:
1. Display the catalog for the service. The catalog lists the available instances of
this service.
2.
3.
4.
5.

Click the name of the service to clone to display the configuration screen.
Click Clone.
When the screen refreshes, specify the name of the clone.
Specify the Ethernet interface that the service monitors for incoming client
requests in the Device Address field. Use the default address (0.0.0.0) to specify
all interfaces.

6. Specify the Ethernet port that the service monitors for incoming client requests
in the Device Port field.
7. As necessary, edit the other properties.
8. Click Apply to save the changes to the running configuration.

10

IBM WebSphere DataPower Integration Appliance XI50: Web Application Firewall Developers Guide

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

Accessing probe captures

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

Chapter 2. WebGUI basics

11

12

IBM WebSphere DataPower Integration Appliance XI50: Web Application Firewall Developers Guide

Chapter 3. Securing communication

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

Supported cryptographic formats

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

Working with keys and certificates

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

Creating key-certificate pairs

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

13

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

Generating keys and certificates

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

Creates the entry in reverse RDN order.

off
(Default) Create the entry in forward RDN order.
b. Optionally specify a country name in the Country Name (C) field.
c. Optionally specify a state or province name in the State or Province (ST)
field.
d. Optionally specify a locality name in the Locality (L) field.
e. Optionally specify the name of an organization in the Organization (O)
field.
f. Optionally specify the name of an organizational unit in the Organizational
Unit (OU) field.

3.
4.

5.
6.
7.

g. Optionally specify the names of additional organizational units in the

Organizational Unit 2 (OU), Organizational Unit 3 (OU), and
Organizational Unit 4 (OU) fields.
h. Specify a common name in the Common Name (CN) field.
Select a key length from the RSA Key Length list. This defaults to 1024.
Specify the name of the key file to generate in the File Name field. The value
takes the directory:///name form. Leave blank to allow the action to create
the name.
Specify the number of days that the key is valid in the Validity Period field.
Specify a password to access the key file in the Password field. The password
must be at least 6 characters in length.
Specify a password alias to access the key file in the Password Alias field.

8. Use the Export Private Key toggle to indicate whether the action writes the
key file to the temporary: directory.

14

on

Writes the key file to the temporary: directory.

off

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

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

15

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.

16

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

Working with Certificate objects

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

Working with z/OS certificates

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

Defining Certificate objects

To create and configure a Certificate, use the following procedure:
1. Select Objects Crypto Configuration Crypto Certificate.
2. Click Add to display the configuration pane.
3. Provide the following inputs:
Name Specify the name of the object.
Admin State
Retain the default setting. To place the object in an inactive
administrative state, click disabled.
File Name
Specify the local certificate file or the remote z/OS certificate file.
For a local certificate file, access a list of files, contained in the cert: or
pubcert: file repository, and select the file that contains the certificate
referenced by this Certificate object.
v Click Upload or Fetch to transfer the file.
Chapter 3. Securing communication

17

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

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

nssclient
Specifies an existing NSS client object.
ZOSCERTLABEL
Specifies the label name of an existing SAF certificate
residing on the z/OS system.
Password
Depending of business security policies, provide one of the following:
v If local security policies provide for password-protected keys, specify
the password (or a password alias).
v If local polices do not support password protection, leave blank.
v If key files are protected by a plaintext password, specify the
password.
Note: Plaintext passwords appear as such in the configuration script.
v If key files are protected by an aliased password, specify the alias.
The CLI provides a password-map command that uses a
locally-generated key to 3DES encrypt a password used to access a
private key file. The command maps the encrypted password to a
password alias in a password map file. The password map and the
locally-generated key are saved to separate files on the appliance.
Plaintext passwords are not stored in memory or saved on the
appliance.
Password Alias
Use the toggle to specify if the text entered in the Password field is a
plaintext password or a password alias.
on

Identifies the text as a password alias for an encrypted

password

off

(Default) Identifies the text as a plaintext password

Ignore Expiration Dates

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

(Default) Prevents the creation of certificates outside of their

internal expiration values.

on

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

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

18

IBM WebSphere DataPower Integration Appliance XI50: Web Application Firewall Developers Guide

Credentials that references the certificate adhere to the internal

expiration values. If the certificate is used for a certificate chain
validation from a Validation Credentials and the certificate is
not valid, validation fails. Similarly, if the certificate is used
from an Identification Credentials, the DataPower appliance
sends the certificate to the SSL peer for an SSL connection, but
the peer can reject the certificate as not valid.
4. Click Apply to save the changes to the running configuration.
5. Optional: Click Save Config to save the changes to the startup configuration.

Defining Firewall Credentials objects

A Firewall Credentials object consists of a list of Key and Certificate objects.
Certificates and keys that are not referenced in the Firewall Credentials object are
unavailable. If no Firewall Credentials object exists, all keys and certificates that are
stored locally are available.
To create a Firewall Credentials object, use the following procedure:
1. Click Objects Crypto Configuration Crypto Firewall Credentials.
2. Click Add to display the configuration pane.
3. Provide the following inputs:
Name Specify the name of the object.
Admin State
Retain the default setting. To place the object in an inactive
administrative state, click disabled.
Private Key
Select Key objects to add. Refer to Defining Key objects on page 21
for more information.
Shared Secret Key
Select Shared Secret Key objects to add. Refer to Defining shared
secret keys on page 24 for more information.
Certificates
Select Certificate objects to add. Refer to Defining Certificate objects
on page 17 for more information.
4. Click Apply to save the changes to the running configuration.
5. Optional: Click Save Config to save the changes to the startup configuration.

Defining Identification Credentials objects

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

create an Identification Credentials object, use the following procedure:

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

19

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 21
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 17 for more information.
Intermediate CA Certificate
Intermediate CA certificates might be required when the CA that is
signing this certificate is not widely-recognized. If the intermediate CA
certificate is also signed by a less recognized CA, an additional
intermediate CA certificate might be required for that CA. You can
specify as many intermediate certificates as are required.
If necessary, use the list of available Certificate objects to establish a
verifiable trust-chain. A trust-chain consists of one or more Certification
Authority (CA) certificates and provides a linked path from the
certificate that is in the Identification Credentials to a CA that is trusted
by a remote appliance. The trust chain enables the appliance to
authenticate the certificate.
4. Click Apply to save the changes to the running configuration.
5. Optional: Click Save Config to save the changes to the startup configuration.

Working with Key objects

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

Working with z/OS keys

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

Create key objects using retrieved keys

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

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

20

IBM WebSphere DataPower Integration Appliance XI50: Web Application Firewall Developers Guide

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

Defining Key objects

To create and configure a Key object, use the following procedure:
1. Select Objects Crypto Configuration Crypto Key.
2. Click Add to display the configuration pane.
3. Provide the following inputs:
Name
Specify the name of the object.
Admin State
Retain the default setting. To place the object in an inactive administrative
state, click disabled.
File Name
Specify the local private key file or the remote z/OS private key file.
For a local key file, access a list of files, contained in the cert: file
repository, and select the file that contains the private key aliased by this
Key object. Click Upload or Fetch to transfer the file.
Note: Keys can be retrieved from a Java Key Store residing on the local
workstation. Click Java Key Store on the Upload field. Refer to
Uploading files from the workstation on page 36 for more
information.
For a remote z/OS key file, specify the location and the file name.
v Select saf-key:// or saf-remote-key:// from the File Name list.
v Specify the file name using the following format:
nssclient/ZOSKEYLABEL

nssclient
Specifies an existing NSS client object.
ZOSKEYLABEL
Specifies the label name of an existing SAF key residing on the
z/OS system. A saf-key:// must be a SAF key that is not stored
in ICSF. A saf-remote-key:// must be a SAF key that is stored in
ICSF.
Password
Depending on business security policies, provide one of the following:
v If local security policies provide for password-protected keys, specify
the password (or a password alias).
v If local polices do not support password protection, leave blank.
Chapter 3. Securing communication

21

v If key files are protected by a plaintext password, specify the password.

Note: Plaintext passwords appear as such in the configuration script.
v If key files are protected by an aliased password, specify the alias.
The CLI provides a password-map command that uses a locally-generated
key to 3DES encrypt a password used to access a private key file. The
command maps the encrypted password to a password alias in a
password map file. The password map and the locally-generated key are
saved to separate files on the appliance. Plaintext passwords are not
stored in memory or saved on the appliance.
Password Alias
Use the toggle to specify if the text entered in the Password field is a
plaintext password or a password alias.
on

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

off

(Default) Identifies the text as a plaintext password.

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

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

Defining Profile objects

A Profile object identifies a collection of SSL resources that support SSL
connections with remote peer appliances.
To create and configure a Profile object, use the following procedure:
1. Select Objects Crypto Crypto Profile to display the catalog.
2. Click Add to display the configuration screen.
3. Provide the following inputs:
Name
Specify the name of the object.
Admin State
Retain the default setting. To place the object in an inactive administrative
state, click disabled.
Identification Credentials
Select the Identification Credentials to assign to this Profile object, or
retain the default value, none, when no Identification Credentials is
needed.
The Identification Credentials provides the PKI certificate-key pair that
will be used to authenticate the appliance during the SSL handshake.
Refer to Defining Identification Credentials objects on page 19 for more
information.
Validation Credentials
Select the Validation Credentials for this Profile object, or retain the
default value, none, when no Validation Credentials is needed. Refer to
Validation credentials on page 26 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

22

Includes all cipher suites, except the eNULL ciphers.

IBM WebSphere DataPower Integration Appliance XI50: Web Application Firewall Developers Guide

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

Includes all low encryption cipher suites. These ciphers support

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

EXPORT
Includes all cipher suites that support a key length of 40 or 56 bits
and are eligible for export outside of the United States.
For a detailed list of ciphers, refer to the profile command in the
product-specific version of the Command Reference.
Options
Use the check boxes to disable support for SSL versions and variants. By
default, SSL Version 2, SSL Version 3, and Transaction Level Security
(TLS) Version 1 are enabled.
v To disable SSL Versions 2, click Disable-SSLv2.
v To disable SSL Version 3, click Disable-SSLv3.
v To disable TLS Version 1, click Disable-TLSv1.
Send Client CA List
Use the toggle to enable the transmission of a Client CA List during the
SSL handshake.
Note: Transmission of a Client CA List is meaningful only when this
Profile object supports a reverse (or server) proxy and when this
Profile object has an assigned Validation Credentials.
on

Enables transmission of a Client CA List.

off

(Default) Disables transmission of a Client CA List.

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

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

Chapter 3. Securing communication

23

Defining shared secret keys

A shared secret key provides an added layer of security by supplying an indirect
reference (or alias) to a shared secret key. A shared secret key is used by mutual
agreement between a sender and receiver for encryption, decryption, and digital
signature purposes. A shared secret key uses a text file that contain the key
material to perform cryptographic operations.
To create a shared secret key:
1. Click Objects Crypto Configuration Crypto Shared Secret Key.
2. Click Add.
3. In the Name field, enter the name for the object.
4. Retain the default setting for Admin State. To place in an inactive
administrative state, click disabled.
5. From the File Name list, select the file that contains the key material.
6. Click Apply to save the changes to the running configuration.
7. Optional: Click Save Config to save the changes to the startup configuration.

SSL Proxy Profile objects

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

Creating a forward (or client) proxy

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

24

IBM WebSphere DataPower Integration Appliance XI50: Web Application Firewall Developers Guide

Creating a reverse (or server) proxy

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

Client authentication is not required. When there is no client

certificate, the request does not fail.

off

(Default) Requires client authentication only when the server

cryptographic profile has an assigned Validation Credentials.

11. Use the Always Request Client Authentication toggle to control when to
request SSL client authentication.
on

Always requests client authentication.

off

(Default) Requests client authentication only when the server

cryptographic profile has an assigned Validation Credentials.

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

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

Creating a two-way proxy

To create an SSL Proxy Profile, use the following procedure:
1. Select Objects Crypto SSL Proxy Profile to display the SSL Proxy Profile
catalog.
2. Click Add to display the SSL Proxy Profile Configuration screen.
3. In the Name field, enter the name for the object.
4. Retain the default setting for Admin State. To place in an inactive
administrative state, click disabled.
5. Select Two Way from the SSL Direction list.
6. Select the profile that defines SSL service to the backend server from the
Forward (Client) Crypto Profile list.
7. Select the profile that defines SSL service to frontend clients from the Reverse
(Server) Crypto Profile list.
8. Use the Server-side Session Caching toggle to enable or disable server side
caching.

Chapter 3. Securing communication

25

9. Specify the time that session-specific state data is maintained in the server
cache in the Server-side Session Cache Timeout field.
10. Specify the maximum size of the server-side cache in the Server-side Session
Cache Size field.
11. Use the Client-side Session Caching toggle to enable or disable client side
caching.
12. Use the Client Authentication is optional toggle to control when SSL client
authentication is optional.
on

Client authentication is not required. When there is no client

certificate, the request does not fail.

(Default) Requires client authentication only when the server

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

on

Always requests client authentication.

off

(Default) Requests client authentication only when the server

cryptographic profile has an assigned Validation Credentials.

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

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

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

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

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

26

IBM WebSphere DataPower Integration Appliance XI50: Web Application Firewall Developers Guide

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

Creating for select certificates

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

(Default) Checks the CRLs.

off

Does not check CRLs.

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

Processing fails.

off

(Default) Processing succeeds.

CRL Distribution Points Handling

Determines how to handle Certificate Revocation List (CRL) checking of
X.509 CRL Distribution Points extensions during processing of the
certificate chain and controls how to handle certificates in the Validation
Credentials.
Chapter 3. Securing communication

27

Ignore Ignores extensions.

Require
Checks, but does not retrieve, extensions.
Initial Certificate Policy Set
When the mode is PKIX, defines the certificate chain validation input that
RFC 3280 calls the user-initial-policy-set. This set of OIDs specifies the
only allowable values of Certificate Policies at the end of chain
processing.
If you define an initial certificate policy set, you will want to enable the
Require Explicit Certificate Policy field. Otherwise, these certificate
policy sets will be used only when there are Policy Constraints extensions
in the certificate chain.
The default contains the OID for anyPolicy.
Require Explicit Certificate Policy
When the mode is PKIX, controls whether the validation chain
(algorithm) can end with an empty policy tree (that RFC 3280 calls the
initial-explicit-policy).
on

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

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

28

IBM WebSphere DataPower Integration Appliance XI50: Web Application Firewall Developers Guide

Chapter 4. Creating a Web application firewall from the

Control Panel
When creating or editing a Web application firewall service from the Web
Application Firewall icon on the Control Panel, the configuration pane does not
provide all available settings.
To
1.
2.
3.
4.
5.

create a Web Application Firewall service from the Control Panel:

Click the Web Application Firewall icon.
Click Add Advanced.
On the General tab, define the general configuration.
Optional: On the Timeout/Protocol tab, modify the predefined default settings.
Click Apply to save the changes to the running configuration.

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

Defining the general configuration

To define the base configuration of a Web application firewall:
1. From the control panel, click the Web Application Firewall icon.
2. Click Add Advanced.
3. In the Web Application Firewall Name field, enter the name for the service.
4. Optional: In the Comment field, enter a descriptive summary.
5. From the XML Manager list, select the XML manager to associate with the
service.
6. Optional: From the SSL Proxy Profile list, select the SSL proxy profile to
secure connections. Refer to Enabling secured communication on page 30
for information about whether to assign an SSL proxy profile.
7. Optional: From the Default Error Handling Policy list, select the policy to
handle violations to the application service policy. This policy handles
responses to clients. Without a policy, all policy violations generate an error. If
the application security policy defines an error handling policy, the policy in
the application security policy overrides this default policy.
Refer to Creating Error Policy objects on page 100 for more information
about creating an error policy.
8. From the Security Policy list, select the security policy to enforce. Although
this security policy can contain policies for requests and responses, you can
disable them on the Timeout/Protocol tab.
Refer to Application security policies on page 97 for more information about
creating a security policy.
9. Define service-to-server settings.
a. Navigate to the Back side settings area.
b. In the Remote Host Address field, enter the host name or IP address of
the remote server. To use a load balancer, enter the name of an existing
load balancer group.
c. In the Remote IP Port field, enter the listening TCP port on the remote
server.
10. Define client-to-service settings.
Copyright IBM Corp. 2002, 2009

29

a. Navigate to the Front side settings area.

b. Define source addresses.
1) In the IP field, enter the IP address or host alias of the DataPower
interface on which the service listens.
2) In the Port field, enter the listening TCP port on the DataPower
appliance.
3) Optional: Set the SSL check box to enable secured communication.
4) Click Add.
c. Optional: Repeat the previous step to create another source address.
11. Optional: Click the Timeout/Protocol tab and modify predefined, advanced
settings. Refer to the online help for additional information.
12. Click Apply to save the changes to the running configuration.
13. Optional: Click Save Config to save the changes to the startup configuration.

Enabling secured communication

An SSL proxy profile can be assigned to a Web application firewall to secure the
communication between requesting clients and the service, between the service and
the remote server, or between the service to both requesting clients and the remote
server. The communication that the SSL proxy profile secures depends on the
assigned crypto profiles.
v To secure communication with requesting clients, use an SSL proxy profile with
a crypto profile that is configured as a server (reverse) profile. Under Source
Addresses, set the Use SSL check box for at least one source address.
v To secure communication with the remote server, use an SSL proxy profile with
a crypto profile that is configured as a client (forward) profile.
v To communication with both requesting clients and the remote server, use an
SSL proxy profile with a crypto profile that is configured for two-way SSL.
Refer to SSL Proxy Profile objects on page 24 for more information.
To enable a Web application firewall for secured communication:
1. From the control panel, click the Web Application Firewall icon.
2. Click the name of the Web application firewall to modify.
3. From the SSL Proxy Profile list, select the SSL proxy profile to secure
connections.
4. For securing with requesting clients: In the Source Addresses section, set the
Use SSL check box for at least one address.
5. Click Apply to save the changes to the running configuration.
6. Optional: Click Save Config to save the changes to the startup configuration.

Modifying advanced settings

To modify advanced Web Application Firewall settings:
1. From the control panel, click the Web Application Firewall icon.
2.
3.
4.
5.
6.

30

Click the name of the Web application firewall to modify.

Click the Timeout/Protocol tab.
Modify the required settings.
Click Apply to save the changes to the running configuration.
Optional: Click Save Config to save the changes to the startup configuration.

IBM WebSphere DataPower Integration Appliance XI50: Web Application Firewall Developers Guide

For a listing of advanced settings, refer to Advanced settings.

Advanced settings
The Timeout/Protocol configuration pane contains the predefined, advanced
settings that handle the majority of implementation scenarios. However, you might
need to make modification to meet your requirements. These settings are separated
into the following categories:
v Connection timeout
v Protocol
v Streaming
v Security
For details information about these settings, refer to the online help.
Table 1 lists the connection timeout setting that you can modify to meet the your
requirements.
Table 1. Advanced timeout settings for a Web Application Firewall
Label

Purpose

Front Side Timeout

The amount of time to maintain an idle connection with the

client.

Back Side Timeout

The amount of time to maintain an idle connection with the

server.

Front Persistent Timeout

The amount of time to maintain an idle persistent TCP

connection with the client.

Back Persistent Timeout

The amount of time to maintain an idle persistent TCP

connection with the server.

Table 2 lists the protocol setting that you can modify to meet the your
requirements.
Table 2. Advanced protocol settings for a Web Application Firewall
Label

Purpose

HTTP Response Version

The HTTP version for client responses.

HTTP Version to Server

The HTTP version for server connections.

Service Priority

The service scheduling priority.

Follow Redirects

Whether to attempt to transparently resolve redirects.

Table 3 lists the streaming setting that you can modify to meet the your
requirements.
Table 3. Advanced streaming settings for a Web Application Firewall
Label

Purpose

Stream Output to Front

Whether to stream responses to requesting clients.

Stream Output to Back

Whether to stream requests to the remote server.

Table 4 on page 32 lists the security setting that you can modify to meet the your
requirements.
Chapter 4. Creating a Web application firewall from the Control Panel

31

Table 4. Advanced security settings for a Web Application Firewall

32

Label

Purpose

Normalize URI

Whether to rewrite URI to make URI RFC-compliant to

make checking for attack sequences more reliable.

Request Security

Whether to enforce request security policies in the defined

application security policy.

Response Security

Whether to enforce response security policies in the defined

application security policy.

IBM WebSphere DataPower Integration Appliance XI50: Web Application Firewall Developers Guide

Chapter 5. Managing files

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

Directories on the appliance

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

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

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

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

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

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 Integration Appliance XI50: 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 5. 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 Integration Appliance XI50: 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 5. 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 Integration Appliance XI50: 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 5. 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 Integration Appliance XI50: Web Application Firewall Developers Guide

Chapter 6. Managing the configuration of the appliance

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

Creating Include Configuration File objects

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

(Default) Imports the configuration package at startup. The

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

Imports the configuration package when manually triggered. The

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

on

Retrieves the configuration file after the local interface is up.

off

(Default) Retrieves the configuration file at appliance reload without

waiting for the local interface to be up.

Copyright IBM Corp. 2002, 2009

41

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

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

Creating Import Configuration File objects

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

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

the format is ZIP, the bundle is unzipped automatically.

XML

Indicates that the configuration package in XML format.

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

on

(Default) Overwrites files of the same name.

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

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

Backing up and exporting configuration data

The backup and export utility copies specified configuration data from the
appliance to a file in the export: directory. You can optionally download the file to
your workstation.
Note: Exported configuration data should not be imported to an appliance with an
earlier release level. Between releases, configuration data for properties can
change. If you attempt to import configuration data from an appliance of a
later release level into an appliance of an earlier release level, the operation
might report success, but the configuration data might not be the same.
Therefore, use this utility to exchange configuration data among appliances
of the same release level.
You can use this utility to perform the following operations:
v Create a backup of the entire appliance
v Create a backup of one or more application domains
v Export select objects from the current domain
v Copy or move select objects between domains
Note: The following objects are never exported:
v User account objects
v Certificate objects
v Key objects (HSM appliances only)
The following files are never exported:
v Log files
v Firmware files
Chapter 6. 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. Optional: In the Comment field, enter a descriptive summary.
b. Optionally create or select the name of a Deployment Policy to accept, filter,
or modify a configuration during import.
c. The Export File Name defaults to export (.zip). If a file of this name exists
in the export: directory, it is overwritten.
d. Click Next. The configuration of the entire appliance is backed up.
When the backup completes, the file is in the export: directory. You can optionally
download the export file to your workstation.
Note: The Import Configuration utility requires that the export file resides on your
workstation.
3. Optionally click Download to download the file to your workstation.
4. Click Done to close this window and return to the Control Panel.
The export file can be accessed from the export: directory. If downloaded, the
export file is on your workstation.

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

44

IBM WebSphere DataPower Integration Appliance XI50: 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. Optional: In the Comment field, enter a descriptive summary.
b. Optionally create or select the name of a Deployment Policy to accept, filter,
or modify a configuration during import.
c. The Export File Name defaults to export (.xml or .zip depending on the
selected export format). If a file of this name exists in the export: directory,
it is overwritten.
d. Use the To radio buttons to specify the export format.
XML Config
Exports configuration data as XML files. Include Configuration files
are referenced in the XML document only, they are not included.
ZIP Bundle
Exports configuration data in compressed ZIP format. Include
Configuration files are in the bundle.
e. Use the Configuration radio button to specify the data to export.
Currently running configuration
Exports the configuration data from the running configuration, not
the startup configuration.
Last persisted configuration
Exports the configuration data from the startup configuration, not
the current running configuration.
f. Use the Referenced Objects radio buttons to specify the scope of the data to
export.
Include only the selected base objects
Exports only the configuration data for the selected objects.

Chapter 6. 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 Integration Appliance XI50: 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 6. 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 Integration Appliance XI50: 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 changes to the running configuration.
6. Optional: Click Save Config to save the changes to the startup configuration.

Saving configuration checkpoints

Do not click Save Config to save a configuration checkpoint. This button does not
allow you the option of saving a configuration checkpoint.
To save a configuration checkpoint, use the following procedure:
1. Select Administration Configuration Configuration Checkpoints.
2. Specify the name of the configuration checkpoint in the Checkpoint Name
field.
3. Click Save Checkpoint.
4. Respond to WebGUI prompts.
A ZIP-formatted configuration file of the specified name is written to the
chkpoints: directory.
You cannot overwrite a configuration checkpoint. You must first delete the original
configuration checkpoint before saving a new configuration checkpoint of the same
name. For details, refer to Deleting configuration checkpoints on page 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 6. 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 matching statement in a deployment policy
with the Use Deployment Policy list (optional).

50

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

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

Adds the property with the identified value during the import.

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

Creating deployment policies

A deployment policy is a sequence of accepted, filtered, and modified
configurations that respectively include, delete, or change configuration data in the
configuration package during the import. When specifying the matching statement,
you can use the builder or manually specify the statement.
v For details about using the builder to define the statement, refer to Using the
deployment policy builder on page 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 Integration Appliance XI50: Web Application Firewall Developers Guide

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

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

Using the deployment policy builder

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

To access the builder, click Build. This button is associated with the following
properties:
v Accepted Configuration on the Main tab
v Filtered Configuration on the Main tab
v Configuration Match in the properties Window that the WebGUI displays after
clicking Add on the Modified Configuration tab
To create a matching statement with the builder, use the following procedure:
1. Click Build to open the builder.
Chapter 6. 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. Optional: In the Name Match (PCRE) field, specify a name match for a
resource. This property limits the matching statement to resources of the
specified name. Use a PCRE to select groups of resource instances. For
example, foo* would match all resources with names that start with foo.
6. Optional: From the Configuration Property list, select the name of the
configuration property. This property limits the matching statement to resources
of the specified property.
7. Optional: In the Configuration Value Match (PCRE) field, specify the value for
the configuration property. This property limits the matching statement to
resources of the specified value. Use a PCRE Match Expression to select groups
of configuration property values.
8. Click Save.
The statement is added to the list of matching statements.

Specifying the matching statement

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

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

56

IBM WebSphere DataPower Integration Appliance XI50: Web Application Firewall Developers Guide

Appendix A. Referenced objects

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

Select Objects XML Processing AAA policy.

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

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

13. Optional: On the LTPA User Attributes tab, define LTPA user attributes.
14. Optional: On the Transaction Priority tab, define the priority of transactions.
15. Click Apply to save the changes to the running configuration.
16. Optional: Click Save Config to save the changes to the startup configuration.

Main tab
Name Specify the name of the object.
Admin State
Retain the default setting. To place the object in an inactive administrative
state, click disabled.
Comments
Specify a descriptive object-specific summary.
Authorized counter
Although the configuration supports count monitors, Web Application
Firewall services do not support this type of monitor
Rejected counter
Although the configuration supports count monitors, Web Application
Firewall services do not support this type of monitor
SAML Signature Validation Credentials
Optional and only if the AAA policy uses SAML-based identity extraction,
authentication, or authorization: Select the Crypto Validation Credentials to
validate digitally-signed SAML assertions from the Credentials list. Refer
to Validation credentials on page 26 for more information.
SAML Message Signing Key
Optional and only if the AAA policy uses SAML-based identity extraction,
authentication: Select the Crypto Key to sign SAML assertions. Refer to
Defining Key objects on page 21 for more information.
SAML Message Signing Certificate
Optional and only if the AAA policy uses SAML-based identity extraction,
Copyright IBM Corp. 2002, 2009

57

authentication: Select the matching Crypto Certificate that is the public

certificate associated with the private key designated by the SAML
message signing key. Refer to Defining Certificate objects on page 17 for
more information.
SAML Signing Message Digest Algorithm
Select the hash algorithm for SAML signing message. The default is sha1.
SAML Message Signing Algorithm
Select the algorithm to sign SAML messages. RSA and DSA are supported
by older releases. rsa is same as rsa-sha1, and dsa is same as dsa-sha1. The
default is rsa.
LDAP Suffix
Optional if LDAP authentication or authorization is used by this AAA
policy. Specify an LDAP base DN.
LDAP-based authentication implementations require an X.500 DN (for
example, cn=Alice,dc=datapower,dc=com) and a password. When
configuring LDAP for authentication, it is typical to create a base DN (such
as dc=datapower,dc=com) and then create one entry under this base for each
user.
To make LDAP authentication more usable, the AAA policy provides the
LDAP suffix. Set the LDAP suffix to the base name under which user
entries are found. If the LDAP suffix is not an empty string, the AAA
Policy builds an X.509-compliant DN by prepending cn= to the surname
and appending a comma followed by the value of the LDAP suffix. Hence,
an LDAP suffix of dc=datapower,dc=com, the user name Alice is mapped to
the DN cn=Alice,dc=datapower,dc=com.
Log Allowed
By default, the AAA policy generates log messages at the indicated level
for every access allowed. Set to off to change this behavior.
Log Allowed Level
When Log Allowed set to on, change the default level. Log messages
generated for each access allowed by this AAA policy will be set at the
level selected.
Log Rejected
By default, the AAA policy generates log messages at the indicated level
for every access rejected. Set to off to change this behavior.
Log Rejected Level
When Log Rejected set to on, change the level. Log messages generated
for each access rejected by this AAA policy will be set at the level selected.
Note: Log targets capture messages at or above the level configured for
the target. The higher the level, the more likely one or more log
targets will catch the message. To be sure log targets capture these
AAA messages, coordinate these levels.
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

58

IBM WebSphere DataPower Integration Appliance XI50: Web Application Firewall Developers Guide

endpoints are encoded in the artifact itself (per the SAML specification). If
there is only one artifact retrieval URL, it can be specified by the SAML
artifact responder URL in the authentication phase.
Ping Identity Compatibility
Select whether to enable (on) or disable (off) Ping Identity compatibility.
Enable Ping Identity compatibility when using SAML for authentication or
authorization.
SAML 2.0 Metadata File
This file contains information about the various SAML Authorities that
might be used for SAML 2.0 authentication and authorization. From the
list, select a file, and click Upload to upload a file.
The file must conform to the SAML 2.0 metadata schema
(xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata").
DoS Flooding-Attack Valve
Specifies the number of times to perform the same XML processing per
user request. Use a value in the range of 1 through 1000. The default is 3.
This property limits the number of times to perform the same XML
processing per user request. XML processing includes encryption,
decryption, message signing, and signature validation. At this time, the
AAA Policy supports this property in the following cases:
v Identity extraction when the method is Subject DN from Certificate in
the Messages signature
v Authentication when the method is Validate the Signer Certificate for a
Digitally Signed Message
When used with the value of 1, the AAA Policy extracts the first signature
and its first reference from the security header and ignores all other
signatures or signing references. If the security header contains more
signatures or a single signature contains more signing references, these
signatures and signing references are ignored. During signature
verification, the processing fails if the needed signature is not part of
extracted identity.
For example if dos-valve is 2 and the needed information to verify the
signature was the third signing reference, the verification would fail.
However if the information was the second signing reference, the
verification would succeed.
LDAP Version
Select the LDAP protocol version (2, the default version, or 3) used when
accessing the authorization server.
Enforce Actor/Role for WS-Sec Message
Most of the times a WS-Security message has a S11:actor or S12:role
attribute for its wsse:Security header, we can enforce those attributes
when AAA tries to use wsse:Security header, for example, there should be
only one wsse:Security element having same actor/role, and AAA should
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.
Appendix A. Referenced objects

59

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

60

IBM WebSphere DataPower Integration Appliance XI50: Web Application Firewall Developers Guide

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 19 for more information.
Token extracted from the message
The claimed identity of the requester is extracted using an XPath expression.
If this is checked, the XPath Expression field is displayed. If selected, the
WebGUI prompts for the following property:
XPath expression
Provide the operative XPath expression. The XPath expression is
applied to the entire message.
If you require name spaces in the XPath expression, refer to Setting
namespace data for XPath bindings on page 82 for procedural and
configuration details.
Token extracted as Cookie value
The claimed identity of the requester is extracted from a Cookie value. If
selected, the WebGUI prompts for the following property:
Cookie name
Specify the cookie name.
LTPA Token
The claimed identity of the requester is extracted from an LTPA (Lightweight
Third Party Authentication) token value. LTPA tokens, which are opaque
signed and encrypted strings, are carried via HTTP, specifically in the
Set-Cookie response and Cookie request headers.
Refer to Understanding LTPA for more information.
Custom template
The claimed identity of the requester is extracted by a custom or proprietary
identification resource (for example, a style sheet). If selected, the WebGUI
prompts for the following property:
Custom URL
Specify the local or remote URL of the identification resource.
Click Apply to commit AAA Policy properties.
Optional: Click Save Config to save the changes to the startup configuration.
Appendix A. Referenced objects

61

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

Specify the IP address or domain name of the LDAP

authentication server.

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,

62

IBM WebSphere DataPower Integration Appliance XI50: Web Application Firewall Developers Guide

LDAP queries will be load balanced in accordance with the

settings in the group. Load balancing allows for failover. Refer to
Configuring a load balancer group on page 109 for more
information.
When specified, this property overrides the settings for the Host
and Port properties.
SSL Proxy Profile
Select an SSL Proxy Profile to provide a secure connection to
remote authentication server. Retain the default value to use a
non-SSL connection.
LDAP Bind DN
Specify the Distinguished Name for the LDAP bind operation.
LDAP Bind Password and Confirm LDAP Bind Password
Specify and confirm the password for the LDAP bind operation.
LDAP Search Attribute
Specify the name of the LDAP attribute that contains the cleartext
password. The default is userPassword.
This property is meaningful only when the identity extraction
method is Password-carrying UsernameToken Element from
WS-Security Header and the <Username> element in the header
has the Type attribute set to PasswordDigest. In this case, the
LDAP server returns the text in the specified LDAP attribute for
the user in the UsernameToken. If the hashed value of the
returned text does not match the value in the <Password> element,
authentication fails.
Search for DN
Indicate whether to perform an LDAP search retrieve the DN of
the user.
on

Enables an LDAP search for the users group. The login

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

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

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

LDAP Search Parameters

Select the LDAP Search Parameters from the list. Refer to
Defining LDAP Search Parameters objects on page 101
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:

Appendix A. Referenced objects

63

SAML Authentication Query Server

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

Requires client entropy. The DataPower appliance sends

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

off

(Default) Does not require client entropy.

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

the Client Entropy Size field. The size refers to the length of the
client entropy before Base64 encoding. Use an integer in the range
of 8 through 128. The default is 32.
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

64

IBM WebSphere DataPower Integration Appliance XI50: Web Application Firewall Developers Guide

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

Generates a WS-Trust RequestSecurityTokenCollection.

off

(Default) Generates a WS-Trust RequestSecurityToken.

Require AppliesTo SOAP Header

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

Generates a WS-Addressing AppliesTo header.

off

(Default) Does not generate a WS-Addressing AppliesTo

header.

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

Specify the IP address or domain name of the Netegrity

authentication server.

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.

Appendix A. Referenced objects

65

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
153 for more information.
Contact Tivoli Access Manager
The requester is authenticated by a Tivoli Access Manager. A Tivoli Access
Manager object must exist and be in an enabled state for this method to
succeed. Refer to Creating Tivoli Access Manager objects on page 89 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.
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:

66

IBM WebSphere DataPower Integration Appliance XI50: Web Application Firewall Developers Guide

X.509 BinarySecurityToken Validation Credentials

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

Appendix A. Referenced objects

67

Disabled
Disables caching of authentication data
Maximum
Compares the explicit TTL with the received TTL (if any). Use the
data-specific TTL if it is less than the explicit TTL. Otherwise, use
the explicit value.
Minimum
Compares the explicit TTL specified by the Cache Lifetime
property with the received TTL (if any). Use the data-specific TTL
if it is greater than the explicit TTL. Otherwise, use the explicit
value.
Cache Lifetime
Specify the explicit TTL in seconds. This defaults to 3.
3. Click Apply to commit AAA Policy properties.
4. Optional: Click Save Config to save the changes to the startup configuration.

Map Credentials tab

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

Authentication credentials are not mapped.

Credentials from Tivoli Federated Identity Manager

The authentication credentials are mapped by Tivoli Federated Identity
Manager (TFIM). If selected, the WebGUI prompts for the following
property:
TFIM Configuration
Select an existing TFIM object. Refer to Creating TFIM objects
on page 90 for more information.
Credentials from WS-SecureConversation Token
The authentication credentials are mapped via a
WS-SecureConversation exchange.

68

IBM WebSphere DataPower Integration Appliance XI50: Web Application Firewall Developers Guide

AAA Info File

The authentication credentials are mapped using an XML file as the
mapping resource. If selected, the WebGUI prompts for the following
property:
AAA Info File URL
Specify the location of the XML file used for authentication
purposes.
To identify a local resource, use the form store:///authfile.xml.
Open store://authfile.xml to examine a sample AAA Info file.
Apply XPath Expression
The authentication credentials are mapped using an XPath expression
as the mapping resource. If selected, the WebGUI prompts for the
following property:
XPath Expression
Specify the operative XPath expression.
3. Click Apply to commit AAA Policy properties.
4. Optional: Click Save Config to save the changes to the startup configuration.

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

69

XPath Expression
Specify the operative XPath expression.
3. Click Apply to commit AAA Policy properties.
4. Optional: Click Save Config to save the changes to the startup configuration.

Map Resource tab

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

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.

70

IBM WebSphere DataPower Integration Appliance XI50: Web Application Firewall Developers Guide

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

Appendix A. Referenced objects

71

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

72

r (Read)
u (Update)

IBM WebSphere DataPower Integration Appliance XI50: Web Application Firewall Developers Guide

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

Authorization requires the presence of all configured SAML

attributes

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

Authorization requires the presence of a single SAML

attribute

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

73

All-Values
Authorization requires that all configured attribute names and
values be present in the SAML attribute statement
Any Authorization requires the presence of a single SAML attribute
Any-Value
Authorization requires that a single configured attribute name
and value be present in the SAML attribute statement
XPath
Authorization requires that SAML server responses are
evaluated with an XPath expression
SAML XPath
If SAML Match is XPath, specifies the operative XPath expression
SAML Name Qualifier
Optionally specify the value of the NameQualifier attribute of the
NameIdentifier in the generated SAML query. Some SAML
implementations require this value to be present.
SAML Version
Select the SAML protocol version to use when employing SAML for
authorization. Versions 1.0, 1.1 and 2.0 are supported. The version
selected affects the format of the messages sent to SAML authorities.
SSL Proxy Profile
Select an SSL Proxy Profile to provide a secure connection to remote
authorization server. Retain the default value to use a non-SSL
connection.
Contact Tivoli Access Manager
The requester is authorized by a Tivoli Access Manager (TAM). A TAM
object must exist for this method to succeed. Refer to Creating Tivoli
Access Manager objects on page 89 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.
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

74

IBM WebSphere DataPower Integration Appliance XI50: Web Application Firewall Developers Guide

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
obligations, the client is rejected only if the AAA Policy,
acting as a PEP, can understand and discharge the
conditions.
Any other XACML response results in the clients
authorization.
Use On Box PDP
Use this toggle to specify the location of the PDP.
on

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

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

off

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

WebGUI displays the following property value:

Appendix A. Referenced objects

75

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

76

IBM WebSphere DataPower Integration Appliance XI50: Web Application Firewall Developers Guide

Absolute
(Default) Caches all authorization data with an explicit TTL
(time-to-live), specified by the Cache Lifetime property
Disabled
Disables caching of authorization data
Maximum
Compares the explicit TTL with the received TTL (if any). Use the
data-specific TTL if it is less than the explicit TTL. Otherwise, use
the explicit value.
Minimum
Compares the explicit TTL (specified by the Cache Lifetime
property) with the received TTL (if any). Use the data-specific TTL if
it is greater than the explicit TTL. Otherwise, use the explicit value.
Cache Lifetime
Specify the explicit TTL in seconds. Defaults to 3.
3. Click Apply to commit AAA Policy properties.
4. Optional: Click Save Config to save the changes to the startup configuration.

Post Processing tab

After authorizing the client, an AAA policy can perform post processing activities.

Post processing activities

You can define the following post processing activities:
v Run a custom post processing style sheet
v Generate a SAML assertion that contains an authentication statement for the
authenticated identify
v Include an AP-REQ token to act as a Kerberos client
v Process a WS-Trust SecurityContextToken (SCT) request
v Add a WS-Security UsernameToken to the message
v Generate an LTPA token
v Generate a Kerberos SPNEGO token
v Request a Tivoli Federated Identity Manager (TFIM) token map
v Generate an ICRX token for z/OS identity propagation
Running a custom style sheet: After authorizing the client, the AAA policy can
run a custom style sheet. The AAA policy runs the actions that are defined in a
custom style sheet. To perform this activity, the AAA policy needs the location of
the custom style sheet.
Generating a SAML assertion: After authorizing the client, the AAA policy can
generate a SAML assertion that contains a SAML authentication statement for the
authenticated user identity. The message that is sent to the server is placed in a
SOAP envelop whose header contains the generated SAML assertions.
An AAA policy supports SAML versions 1.0, 1.1, and 2.0. The version determines
the protocol level of SAML messages. The version affects the extraction of the
identity from the original message and the format of messages.
To perform this activity, the AAA policy needs the following data:
v The SAML version
Appendix A. Referenced objects

77

v The assertion originator (issuer identity)

v Optional: The NameQualifier as defined by the SAML protocol version
v Optional: The key-certificate pair to generate digital signatures
If a custom style sheet generates a SAML assertion, this activity will not generate
additional SAML assertions.
Including an AP-REQ token to act as a Kerberos client: When the DataPower
appliance acts as a gateway to a Kerberos-secured network, the appliance can act
as an authorized Kerberos client. When enabled, the appliance:
1. Obtains a Kerberos ticket from the Kerberos Key Distribution Center (KDC).
2. Includes the Kerberos ticket that attests to the authenticity of the requesting
client. The WS-Security header includes an AP-REQ BinarySecurityToken for
the client and server principals.
3. Transmits the ticket with the authorized client request to the target server.
To perform this activity, the AAA policy needs the following data:
v The client identity (cname of the Kerberos ticket) for the Kerberos client principal
v The location of the Kerberos keytab file
v The server identity (sname of the Kerberos ticket) for the Kerberos server
principal
v The value type for the generated Kerberos BinarySecurityToken (BST)
Processing a WS-Trust SecurityContextToken request: For a valid WS-Trust
SecurityContextToken (SCT) request, the AAA Policy can generate the appropriate
security token response. This processing works as an on-box WS-Trust Secure
Token Service (STS) that is backed by WS-SecureConversation.
The WS-Trust token requires a symmetric shared secret key to initialize the security
context. This processing can handle Issue, Renew, Validate, and Cancel operations
against a request security token or request security token collection. You can define
the renewal behavior. During a token renewal, the processing locates
<wst:RenewTarget> and updates the referenced <wsc:SecurityContextToken> token
by resetting its created time. The renewed token is returned in the response
message.
To perform this activity, the AAA policy needs the following data:
v Whether to place the generated token in the SOAP body or as a SOAP header
If the body, the generated token is in the wst:RequestSecurityTokenResponse
element
If a header, the generated token is the wst:RequestSecurityTokenResponse
element but is wrapped in a wst:IssuedToken element
v The validity duration for the SCT
A negative integer makes the token never expire.
A value of 0 uses the value of the var://system/AAA/defaultexpiry variable if
defined; otherwise, 14400
A positive integer makes the token expire after the specified duration.
v Whether to generate a WS-Trust token timestamp
v The source for the symmetric shared key to initialize the security context
v Whether to allow WS-Trust token renew and, if allowed, how to process a
renewal request

78

IBM WebSphere DataPower Integration Appliance XI50: Web Application Firewall Developers Guide

Adding a WS-Security UsernameToken: An AAA policy can add a WS-Security

UsernameToken to the message that is forwarded to the server. The AAA policy
uses the user name and password from the credential mapping phase.
To perform this activity, the AAA policy needs the following data:
v Whether to replace the existing UsernameToken
v The identifier for the SOAP 1.1 actor or SOAP 1.2 role in processing a
WS-Security security header
v Whether to include the password in the token
Generating an LTPA token: An AAA policy can generate an LTPA token and add
it to the HTTP headers that are sent to the server.
To perform this activity, the AAA policy needs the following data:
v The format (or version) of the LTPA token
v The name of the key file that contains the cipher keys for encryption and
decryption
v The cleartext password for the key file
v The lifetime for the token (from the cookie creation to its expiration)
v Whether to wrap the token in the standard <Security/> WS-Security header
For information about LTPA, refer to Understanding LTPA.
Generating a Kerberos SPNEGO token: An AAA policy can generate a Kerberos
SPNEGO token and add it to the HTTP headers that are sent to the server.
To perform this activity, the AAA policy needs the following data:
v The client identity (cname of the Kerberos ticket) for the Kerberos client principal
v The location of the Kerberos keytab file
v The server identity (sname of the Kerberos ticket) for the Kerberos server
principal
For information about SPNEGO, refer to Understanding SPNEGO.
Requesting a TFIM token map: An AAA policy can request a Tivoli Federated
Identity Manager (TFIM) token map.
To perform this activity, the AAA policy needs the name of an existing TFIM
configuration. For more information, refer to Creating TFIM objects on page 90.
Generating an ICRX token for z/OS identity propagation: An AAA policy can
create an ICRX token from the authenticated credentials. When generated, the
WS-Security binary token with the ICRX token is inserted into the WS-Security
header. This token can be used for interoperability with the CICS Transaction
Server for z/OS identity propagation support.
To perform this activity, the AAA policy needs the name of the ICRX realm as
defined in the SAF configuration. Generally, this setting is the equivalent of the
prefix for a DN in a user registry.

Defining post processing activities

To define one or more post processing activities:
1. Click the Post Processing tab.
Appendix A. Referenced objects

79

2. Define a post processing activity.

a. Select the check box associated with the activity to define.
b. Define the properties for this activity. Refer to the online help for additional
information.
3. Repeat the previous step to define another post processing activity.
4. Click Apply to save the changes to the running configuration.
5. Optional: Click Save Config to save the changes to the startup configuration.

Namespace Mapping tab

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

SAML Attributes tab

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

80

IBM WebSphere DataPower Integration Appliance XI50: Web Application Firewall Developers Guide

LTPA Attributes tab

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

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

XPath Use an XPath expression to set the value dynamically

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

Appendix A. Referenced objects

81

Setting namespace data for XPath bindings

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

Defining SAML attributes

To define SAML attributes, use the following procedure:
1. Click SAML Attributes to display the SAML Attributes catalog.
2. To create new SAML attribute, click Add.
3. Define the following properties:
Namespace URI
The URI for the namespace of the Local Name.
Local Name
The local attribute name. This name can be used for matching.
Attribute Value
The attribute value. This value can be used for matching.
All of these fields are optional, depending on the specific context or the SAML
Match Type selected.
4. Click Save to save the configuration.
5. Repeat step 2 through step 4 to create as many SAML attributes as needed.
6. After defining all SAML attribute, click Done.

Adding LTPA user attributes

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

(Default) Use the explicitly assigned value.

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

selected, the expression is evaluated against the input context of
the AAA action with the result of the evaluation assigned as
the value portion of the name-value pair at runtime.

82

IBM WebSphere DataPower Integration Appliance XI50: Web Application Firewall Developers Guide

LTPA User Attribute Static Value

Meaningful only when the type is Static. The explicit value of the
attribute.
LTPA User Attribute XPath Value
Meaningful only when the type is XPath. The XPath expression used to
extract a value dynamically.
For assistance in creating the XPath expression, click XPath Tool. This
tool allows you to load an XML document and build the expression by
selecting the desired node.
If the defined expression contains namespace elements, click XPath
Binding to provide namespace/prefix data. Refer to Setting
namespace data for XPath bindings on page 82 for more information.

Using an AAA Info file

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

Structure of an AAA Info file

The AAA Info XML file has the following basic structure, which mirrors the steps
of an AAA Policy. The following is a reproduction of the AAAInfo.xsd file in the
store: directory.
<xsd:element name="Authenticate" type="tns:AuthenticateType"
maxOccurs="unbounded">
</xsd:element>
<xsd:element name="MapCredentials" type="tns:MapCredentialsType"
maxOccurs="unbounded">
</xsd:element>
<xsd:element name="MapResource" type="tns:MapResourceType"
maxOccurs="unbounded">
</xsd:element>
<xsd:element name="Authorize" type="tns:AuthorizeType"
maxOccurs="unbounded">
</xsd:element>

Note: An XML file could be used for one or more of these operations. Only the
part of the file that supports the desired operation needs to be completed.
For example, if the file is only used for Map Credentials, it does not need to
include an Authenticate, Map Resource, or Authorize section.
The schema for an AAA Info file uses the AAAInfo.xsd file in the store: directory.
One or more XML files could be used for these operations. In each case, the field
that offers the ability to select an XML file has the + (create) and ... (modify)
buttons. Clicking either button launches the AAA Info file editor. Refer to AAA
Info file editor on page 84 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:
Appendix A. Referenced objects

83

v
v
v
v
v
v

User name
Password
IP address or host name
IP network
Distinguished name (DN)
Custom token

Each identity is given a credential by this element.

MapCredentials element: The MapCredentials element takes in a credential string
and maps it to another. The input can be matched by a PCRE regular expression.
This element can be fed directly from an Authenticate element contained in this
file. Usually, however, this element is used to map an identity extracted from a
message to another identity more meaningful to the authorization method.
MapResource element: The MapResource element takes in a resource string
extracted from the message and maps it to another, perhaps more meaningful to
the authorization method. Input resources can be one or more of the following
types:
v Original (client) URL
v URL sent to server (target URL)
v SOAP Operation Namespace (request URI)
v SOAP Operation Name (request operation)
v HTTP method
v Token extracted by XPath
These resource inputs map to Resource Extraction methods used by the AAA
Policy. The input resource name can be matched by a PCRE regular expression.
Authorize element: The Authorize element takes in a Credential and a Resource
and returns an access status (allow or deny). Both the Credential and the Resource
can be matched by a PCRE regular expression.

AAA Info file editor

The AAA Info file editor, launched by the WebGUI, steps through each section in
an AAA Info file. Click Next or Back to move between pages.
The AAA Info file editor has the following pages:
v Default credential (unauthenticated identity)
v Credentials (authenticated identities)
v Map credentials
v Map resources
v Authorized access to resources
v File information
At any point, click Cancel to abandon all changes and close the file editor.
Default credential (unauthenticated identity): The initial screen presents the
opportunity to set the default credentials for unauthenticated identities. This is the
credential assigned to identities for which no other credential can be found in the
Authenticate section. If left blank, all unauthenticated identities are denied access.
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.

84

IBM WebSphere DataPower Integration Appliance XI50: Web Application Firewall Developers Guide

Click Next if this file will not be used for authentication. Click Add to create new
identities that this file can authenticate. A new window opens with a form for
adding identities.
Host Name or IP Address
The host name or IP address of the client that submitted the message. The
IP address takes dotted decimal form w.x.y.z. The entry 0.0.0.0 (or 0) is
not allowed.
v Use this field only when the identity extraction method is set to Client
IP address.
v If this field is used, you cannot use the IP Network field.
IP Network
The IP network of the client that submitted the message. This entry takes
the form x.y.z.a/b (for example 192.168.2.25/24).
v Use this field only when the identity extraction method is set to Client
IP address.
v If this field is used, you cannot use the Host Name or IP Address field.
User name
The user name extracted from the message. User names can be extracted
from messages in a number of ways, including HTTP Basic Authentication,
WS-Security UserName, and Name from SAML headers. If those AAA
Policy identity extraction methods are not used, do not use this field.
Password
The password extracted from the message. Passwords can be extracted
from messages by HTTP Basic Authentication and WS-Security UserName.
If the Identity Extraction method used by the AAA Policy does not use
either of these methods, do not use this field.
Distinguished Name
The DN extracted from the message. The AAA Policy identity extraction
methods Subject DN from SSL certificate or Subject DN from SAML
signature return this value. If those methods are not used, do not use this
field.
Custom token
A custom token is extracted from the message. The AAA Policy identity
extraction methods Token extracted from the message and Token extracted
as cookie value return this value. If those methods are not used for
extraction, do not use this field.
Credential Name
The credential returned by the authentication. This can be the same as the
extracted identity or different. The value should be meaningful either to
the AAA Policy Map Credentials method or to the AAA Policy Authorize
method.
All of the fields that contain information must be matched for the authentication to
succeed. If the identity extraction method returns only a user name (such as with
SAML) and the Authenticate Identity entry contains both user name and password,
authentication will fail. The AAA policy, however, tests an extracted identity
against all entries in the order in which they are listed, stopping after it finds a
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.
Appendix A. Referenced objects

85

Map credentials: The Map Credentials page presents a list of all credential maps
contained in the file. When creating a new file, this list is empty.
Click Next to move to the next page if this file will not be used for mapping
credentials. Click Add to create a new credential map.
Input Credential
The credential input to the mapping. This field accepts PCRE expressions,
allowing a single expression to match more than one input credential.
Entering foo causes the AAA policy to match all input credentials that
contain the string foo.
Credential Name
The credential to output in place of the input credential. This is the value
to which the input credential is mapped. This is not a regular expression.
Click Submit to add the new map to the list of maps. Create as many mapping
entries as needed by clicking Add for each new entry.
Note: If this file is used for mapping credentials, any input credential that does
not match a map is converted to a blank credential for the purposes of
authorization.
Map resources: The Map Resource page presents a list of all resource mappings
contained in the file. Resource mapping is used to map the resource identifier
extracted from the message to something else. If the AAA Policy uses more than
one resource extraction method, all methods will be executed.
Click Next if this file will not be used for resource identity mapping. Click Add to
create a new map.
Original URL
The URL sent by the client submitting the message. This is a PCRE
expression.
Target URL
The URL used to send the message to the back end server, after the
firewall URL Rewrite Policy has executed. This is a PCRE expression.
Request URI
The Namespace URI of the action or method requested in the body of the
SOAP message. This is identified as the topmost element in the SOAP:Body
element.
Request Operation
The name of the operation requested in the body of the SOAP message.
HTTP Method
Select the desired method. Select any to allow any method.
Result of XPath Expression
Any value that is extracted from the message by an XPath expression. This
is a PCRE expression.
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.

86

IBM WebSphere DataPower Integration Appliance XI50: Web Application Firewall Developers Guide

Authorized access to resources: The Authorize page presents a list of all

authorization pairs contained in this file. Authorization is based on an input
credential (after mapping, if any) and an input resource (after mapping, if any).
If this file is not used for authorization, click Next. To create an authorization entry,
click Add.
Credential
The credential to match for authorization. This field accepts PCRE
expressions.
Resource
The resource to match for authorization. This field accepts PCRE
expressions.
Access
Select allow or deny as the authorization result.
Note: When this file is used for authorization, access is denied by default. Any
unmatched entries result in denied access. Access is allowed only if a match
is found and the Access for that match is allow.
File Information: The file information page provides a means to name the file
and add a comment if desired.
This file is typically placed in the local: directory.
Confirmation: The last page of the reflects the name of the file and offers the
opportunity to make changes or save the changes to the file.
v Click Cancel to abandon all changes and close the window.
v Click Back to move backward through the file to make any additional changes
needed.
v Click Commit to save the file and close the window.

IBM Tivoli Access Manager Integration

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

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.

Appendix A. Referenced objects

87

Although native TAM supports both local and remote clients, the appliance
supports only remote client operations. The TAM configuration supports only one
policy server and supports only LDAP directories. Although the configuration files
allow specifications for Microsoft Active Directory and Lotus Domino, the
appliance does not support these directory servers.

Tivoli Access Manager security

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

Creating Tivoli Access Manager configuration files

Before configuring a TAM object, you need to have the TAM configuration files on
the appliance. Both the ASCII and obfuscated versions of the configuration files are
needed. You can create TAM configuration files either on the appliance or using
the native TAM configuration utilities.
The following files are needed to create the TAM object or are created using the
appliance:
v The ASCII version of the configuration file (.conf extension)
v The obfuscated version of the configuration file (.conf.obf extension) using the
same file name as the ASCII version
v The TAM SSL key file (.kdb extension)
v The TAM SSL stash file (.sth extension)
Notes:
v If you use the native TAM configuration utilities to create the
configuration files, you might need to modify them before creating the
TAM object.
v During the creation of TAM object, you might need to upload the SSL
key file for the LDAP server (.kdb extension). When using secure
communication, ensure that this file is on the workstation.
Modifying native Tivoli Access Manager configuration files: When the
configuration files are generated by the native TAM utilities, you might need to
make the following modifications:
v Unless the LDAP key stash file is uploaded to the appliance, modify the TAM
configuration file by defining the ssl-keyfile-pwd entry in the [ldap] stanza.
v The TAM object needs at least one authorization server replica. You can create
authorization server replicas during the creation of the TAM object, or you can
define replica entries in the [manager] stanza. When defined in the
configuration file, the replicas are not shown in the Authorization Server Replica
catalog.
v Ensure that the obfuscated version of the configuration file is on the workstation
and is the same name as the ASCII version. If not the same name, ensure that
the file entry in the [configuration-database] stanza defines the location of
the obfuscated version of the configuration file on the appliance.
Creating Tivoli Access Manager configuration files on the appliance: To create a
TAM configuration file:
1. Select Administration Miscellaneous IBM Tivoli Access Manager Tools.
2. Define the operational properties. Refer to the online help for details.

88

IBM WebSphere DataPower Integration Appliance XI50: Web Application Firewall Developers Guide

3. Click Create Tivoli Access Manager Configuration.

4. Follow the prompts.
The ASCII version and the obfuscated version of the TAM configuration files are
stored in the local: directory. The key file and the stash file that TAM uses are
stored in the cert: directory. If you set the Create File Copies to Download
property to on, copies of the key file and the stash file are stored in the temporary:
directory.

Creating Tivoli Access Manager objects

After creating the TAM configuration, key, and stash files, you can now create and
configure a TAM object. Each TAM object requires at least one authorization server
replica. A replica indicates the network location of a remote TAM authorization
server. If necessary, configure additional replicas for failover purposes.
To
1.
2.
3.
4.

create and configure a TAM object:

Select Objects Access IBM Tivoli Access Manager.
Click Add to display the configuration pane.
Define the operational parameters. Refer to the online help for details.
Define at least one authorization server replica.
a. Click the Authorization Server Replica tab.
b. Define a replica.
1) Click Add to display the properties window. Use this window to specify
the operational parameters.
2) Define the operational parameters. Refer to the online help for details.
3) Click Save.
c. If necessary, repeat the previous step to create another replica.

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

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

Refreshing Tivoli Access Manager certificates

Refreshing Tivoli Access Manager (TAM) certificates first refreshes the password of
the keystore associated with the TAM object and then refreshes the client certificate
in the keystore with the configured TAM server. The clients associated with this
configuration and any other configuration which use the same keystore will be
stopped if running and restarted when the refresh is complete.
To refresh certificates:
1. Select Administration Miscellaneous IBM Tivoli Access Manager Tools.
2. 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 Integration

DataPower appliances integrate with IBM Tivoli Federated Identity Manager
(TFIM) through the exchange of WS-Trust SOAP messages. The TFIM management
object centralizes the configuration of the TFIM endpoint and prevents parameter
duplication between the Map Credential and the Post Processing phases in an
AAA Policy. During the Map Credential phase, an authenticated identity can be

Appendix A. Referenced objects

89

mapped to the identity for authorization. During the post processing, an

authorized identity can be mapped to the output AAA identity.
When integrating with TFIM, the provided input credentials must be able to be
expressed in the request token format for the TFIM endpoint. For example, a
WS-Security Username token as the request token cannot be created when the
available user credential is an X.509 certificate.

Creating TFIM objects

To
1.
2.
3.

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

Select Objects Access Settings IBM Tivoli Federated Identity Manager.
Click Add to display the configuration pane.
Use this pane to specify operational parameters.
a. Specify the name for the object in the Name field.
b. Retain the default setting for Admin State. To place in an inactive
administrative state, click disabled.
c. Optional: In the Comment field, enter a descriptive summary.
d. Specify the host name or IP address of the TFIM server in the Server field.
e. Specify the port number of the TFIM server in the Port field. The default is
9080.
f. Select the currently configured version of TFIM from the Compatibility
Mode list. The value determines the details for the namespace and WS-Trust
messages.
Note: Selecting Version 6.2 as the compatibility mode will cause the TFIM
client/endpoint to generate WS-Trust messages using version 1.3 of
the WS-Trust specification. In this case, trust chains in the TFIM 6.2
server must use the Validate OASIS URI as the Request Type. To use
WS-Trust version 1.2 messages with a TFIM 6.2 server, select TFIM 6.1
as the compatibility mode. If the 6.1 compatibility mode is selected,
TFIM 6.2 will behave the same as TFIM 6.1.
Version 6.0
Indicates Tivoli Federated Identity Manager, version 6.0.
Version 6.1
(Default) Indicates Tivoli Federated Identity Manager, version 6.1.
Version 6.2
Indicates Tivoli Federated Identity Manager, version 6.2.
g. Select the format of the request token from the Request Token Format list.
The available formats depend on the selected value for Compatibility
Mode.
v If Version 6.0, the following formats are available:
Custom
Indicates a custom style sheet for generating the TFIM request.
When selected, requires the specification of a Custom Request.
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.

90

IBM WebSphere DataPower Integration Appliance XI50: Web Application Firewall Developers Guide

v If Version 6.1 or Version 6.2, the following formats are available:

Binary Security Token
Indicates a WS-Security BinarySecurityToken.
Custom
Indicates a custom token. When selected, requires the
specification of a Custom Request.
Custom Token
Indicates a custom token.
SAML 1.0
Indicates a SAML Assertion 1.0.
SAML 1.1
Indicates a SAML Assertion 1.1.
SAML 2.0
Indicates a SAML Assertion 2.0.
Kerberos Token
Indicates a WS-Security Kerberos Token.
Username Token
(Default) Indicates a WS-Security Username Token Type.
X.509 Token
Indicates a WS-Security X.509 Token.
h. When using TFIM 6.0, TFIM 6.1, or TFIM 6.2 and when Request Token
Format is Custom, select the location of the custom style sheet in the
Custom Request field. The custom style sheet file must be in the local: or
store: directory. Click Upload or Fetch to upload the custom style sheet file.
i. When Request Token Format is not Custom, define the following properties:
1) When using TFIM 6.0, TFIM 6.1, or TFIM 6.2, specify the scope for this
security token in the Applies-To Address field. For example, specify the
services to which this token applies:
http://tfim.ibm.com:9080/EchoApplication/Services/EchoServiceUser
http://9.33.97.251:9080/EchoApplication/Services/EchoServiceUser

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

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

The TFIM trust service uses this information to determine which trust
chain to invoke. To determine the correct value, consult your TFIM
administrator.
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

Appendix A. Referenced objects

91

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

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

Responses are schema-validated.

off

(Default) Responses are not schema-validated.

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

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

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

92

IBM WebSphere DataPower Integration Appliance XI50: Web Application Firewall Developers Guide

The ticket is encrypted with the shared secret of the FTP service principal.
Consequently, there are two encrypted copies of the session key (one for Alice, and
one for the FTP service).
At this point, Alice uses her shared secret to decrypt her copy of the session key
and generates an authenticator (which proves that the person talking to the FTP
service is the client for which this ticket was issued, and not a malicious user
replaying a previously issued ticket) that she sends along with her ticket to the
FTP service. The ticket plus authenticator is called an AP-REQ message.
When the FTP service receives the AP-REQ from Alice, it decrypts the ticket and
verifies the authenticator. At this point the FTP server has authenticated Alice, and
they share a session key which can be used to secure the rest of their
communications.

Points to remember when using Kerberos

When using Kerberos, keep the following points in mind:
v Both clients and servers are principals in the KDC database. More accurately,
services running on server computers are principals in the KDC database.
v A client principal must request a separate ticket for each server with which it
communicates.
v Services must have a name and shared secret registered with the KDC.
v A service must have access to its shared secret to decrypt Kerberos tickets.
v A Kerberos ticket that is issued by a KDC contains the cryptographic material
that allows both the client and the server to generate the same session key.
v All Kerberos cryptographic operations are symmetric in nature.
v In an AAA Policy, Kerberos is an idobj extraction, authentication protocol, or
both.
v Kerberos is not an authorization protocol.
There is no restriction in Kerberos that specifies which clients can request tickets
for a particular service.
Note: Microsoft Windows, when configured to use an Active Directory domain, is
based on a security infrastructure that is, at its core, Kerberos. As of
Windows 2000, authentication in a Windows domain is handled by
Kerberos. Such authentication is entirely transparent to the user. Refer to
Understanding SPNEGO for implementation details.

Configuring a Kerberos KDC Server object

Use the following procedure to configure a Kerberos KDC Server:
1. Select Objects Crypto Kerberos KDC server to display the Kerberos KDC
Server catalog.
2. Click Add to display the Kerberos KDC Server configuration screen.
3. Provide the following inputs:
Name
Specify the name of the object.
Admin State
Retain the default setting. To place the object in an inactive administrative
state, click disabled.
Comments
Specify a descriptive object-specific summary.
Appendix A. Referenced objects

93

Kerberos realm name

Specify the name of the Kerberos realm that is serviced by this KDC.
There is exactly one KDC per Kerberos realm.
Kerberos KDC Server
Specify the host name or IP address of the KDC server. Click Ping to
verify connectivity.
Use TCP
Select whether to use UDP or TCP as the Transport Layer protocol to
access the KDC server.
on

Use Transmission Control Protocol (TCP)

off

(Default) Use User Datagram Protocol (UDP)

Server Port Number

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

Configuring a Kerberos Keytab File object

A Kerberos Keytab file contains the keys needed to decrypt the ticket presented by
a client attempting to obtain services. Previously, only a password was required.
This has been changed to an encrypted key for added security. The Kerberos
Keytab File object identifies the file that contains the keys needed to decrypt the
ticket.
Use the following procedure to configure a Kerberos Keytab File:
1. Select Objects Crypto Kerberos Keytab.
2. Click Add to display the configuration pane.
3. Provide the following inputs:
Name
Specify the name of the object.
Admin State
Retain the default setting. To place the object in an inactive administrative
state, click disabled.
Comments
Specify a descriptive object-specific summary.
File Name
Select the keytab file. This list includes files that are stored in the
encrypted and protected cert: directory of the appliance. If the file does
not reside on the appliance, click Upload or Fetch to transfer the file.
Note: This file is not generated on the DataPower appliance. It is
generated through the Kerberos system itself.
4. Click Apply to save the changes to the running configuration.
5. Optional: Click Save Config to save the changes to the startup configuration.

94

IBM WebSphere DataPower Integration Appliance XI50: Web Application Firewall Developers Guide

XACML Policy Decision Point objects

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

Defining a XACML PDP

Use
1.
2.
3.

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

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

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

administrative state, click disabled.
5. Optional: In the Comment field, enter a descriptive summary.
6. Use the Evaluate Individual Policies Equally toggle to signal the presence of
a comprehensive top-level XACML policy-set.
on

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

will be used in the authorization decision.

off

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

is specified by the General Policy File property.

In the event of multiple authorization matches, a policy combining algorithm,

which defines a procedure for arriving at an authorization decision given the
individual results of evaluation by a set of policies, is employed to render the
final decision.
7. In the General Policy File field, specify the location of the top-level XACML
policy-set.
This property is meaningful only if Evaluate Individual Policies Equally is
set to off.
8. From the Dependent Policies Combining list, select the policy combining
algorithm.
Deny Overrides
The deny-overrides policy-combining algorithm evaluates each policy
in the order that it appears in the XACML policy set. If any policy in
the set evaluates to deny, the policy combination evaluates
immediately to deny. In other words a single deny takes precedence
over other policy evaluations. If all policies are determined to be
NotApplicable, the policy combination evaluates to NotApplicable.
First Applicable
(Default) The first-applicable policy combining algorithm evaluates
each policy in the order that it appears in the XACML policy set. For
an individual policy, if the target (resource) evaluates to TRUE and the
policy conditions evaluate unambiguously to permit or deny,
evaluation is immediately halted, and the policy combination
evaluates to the effect of that individual policy. If the individual policy
evaluates the target as FALSE or the policy conditions as

Appendix A. Referenced objects

95

NotApplicable, then the next policy in the order is evaluated; if no

further policy exists in the order, the policy combination evaluates to
NotApplicable.
Only One Applicable
The only-one-applicable policy combining algorithm evaluates each
policy in the order that it appears in the XACML policy set; unlike the
other policy combining algorithms, only-one-applicable must evaluate
all policies to render a final evaluation. If after evaluating all policies,
no policy is considered applicable by virtue of its target (the requested
resource), the policy combination evaluates to NotApplicable. If after
evaluating all policies, more than one policy is considered applicable
by virtue of its target, the policy combination evaluates to
Indeterminate. If after evaluating all policies, only one single policy is
considered applicable by virtue of its target, the policy combination
evaluates to the result of evaluating that single policy.
Permit Overrides
The permit-overrides policy combining algorithm evaluates each
policy in the order that it appears in the XACML policy set. If any
policy in the set evaluates to permit, the policy combination evaluates
immediately to permit. In other words a single permit takes
precedence over other policy evaluations. If all policies are determined
to be NotApplicable, the policy combination evaluates to
NotApplicable.
This property is meaningful only if Evaluate Individual Policies Equally is
set to on.
9. Use the Dependent Policy Files field with the Add and Delete buttons to
construct a list of dependent policy files.
Policy sets can be local or remote to the appliance; use local or standard URLs
to locate files.
10. Use the Other Policy Files from Directory field with the Add and Delete
buttons to construct a list of local directories that contain dependent files.
All files in noted directories with a .xml or .xacml extension are considered as
potentially available to the current XACML PDP.
11. In the XACML Policies Cache Lifetime field, type an integer in the range
from 0 through 2678400 to specify the time, in seconds, to maintain compiled
XACML policies in the PDP cache. The default value of 0 specifies that
policies in the cache never expire.
12. Click Apply to save the changes to the running configuration.
13. Optional: Click Save Config to save the changes to the startup configuration.

Controlling the PDP cache

There are several ways to control the cache.
Explicitly clear the cache
Use the clear pdp cache command to clear the cache.
Specify the TTL for the PDP
During PDP configuration, specify a cache lifetime.
Use the XML Manager
When the PDP is used by an AAA policy for authorization, users can
access the XML manager that is associated with the AAA policy with the
clear xsl cache command. This command also clears the compiled XACML
policies that are referenced by AAA polices that are supported by the XML
manager.

96

IBM WebSphere DataPower Integration Appliance XI50: Web Application Firewall Developers Guide

Use a URL Refresh Policy

Use a URL Refresh Policy whose conditions match the internal URL
xacmlpolicy:///pdpName to perform periodic cache refreshes.
v When TTL for the PDP is 0 (cache never expires), the URL Refresh
Policy controls cache refresh
v When the URL Refresh Policy is no-cache, XACML policies are never
cached, regardless of any assigned TTL value
v When the URL Refresh Policy is protocol-specified, the TTL setting for
the PDP will govern cache refresh unless its value is 0
v When the URL Refresh Policy is default with a refresh interval, the TTL
for the PDP is ignored and the URL Refresh Policy refresh interval
controls cache refresh
v When the URL Refresh Policy is no-flush with a refresh interval, the
greater of the URL Refresh Policy refresh interval or the TTL for the PDP
controls cache refresh

Application security policies

An application security policy establishes the policies and rules that enforce
security for a Web application firewall. To enforce security, this policy employs the
following maps:
Request maps
Request maps select the Web request profile to execute on client requests
based on a set of matching criteria. If the client request matches the
defined criteria, the application security policy executes the corresponding
Web request profile.
Response maps
Response maps select the Web responses profiles to execute on server
responses based on a set of matching criteria. If the server response
matches the defined criteria, the application security policy executes the
corresponding Web response profile.
Error maps
Error maps select the processing rule to execute on error conditions based
on a set of matching criteria. If the error matches the defined criteria, the
application security policy executes the corresponding processing rule.
The sequence of these maps in the application security policy is important. The
application security policy checks these maps from the top of the list to the bottom
and uses the first map the matches the defined criteria.
To create an application security policy you must defined at least one request map
and at least one response map. Although that application security policy requires
at least one of each of these maps, you can override whether the Web application
firewall enforces them.

Creating an application security policy

To create an application security during the configuration of a Web Application
Firewall:
1. Click + beside the Security Policy field.
2. In the Application Security Policy Name field, enter the name for this policy.
3. Define request maps.
a. Click the Request Maps tab.
Appendix A. Referenced objects

97

b. Define a request map.

1) From the Matching Rule list, select a matching rule. Refer to Defining
Matching Rule objects on page 117 for more information.
2) From the Request Profile list, select a Web request profile. Refer to
Web request profiles on page 139 for more information.
3) Click Add Request Map.
c. Optional: Repeat the previous step to create another request map.
4. Define response maps.
a. Click the Response Maps tab.
b. Define a request map.
1) From the Matching Rule list, select a matching rule. Refer to Defining
Matching Rule objects on page 117 for more information.
2) From the Response Profile list, select a Web response profile. Refer to
Creating Web response profiles on page 148 for more information.
3) Click Add Response Map.
c. Optional: Repeat the previous step to create another response map.
5. Optional: Define error maps.
a. Click the Error Maps tab.
b. Define an error map.
1) From the Matching Rule list, select a matching rule. Refer to Defining
Matching Rule objects on page 117 for more information.
2) From the Processing Rule list, select a processing rule. Refer to
Defining Processing Rule objects on page 120 for more information.
3) Click Add Response Map.
c. Optional: Repeat the previous step to create another error map.
6. Click Commit.
Alternatively, you can create an application security policy outside of the
configuration of a Web Application Firewall server. The configuration procedure is
the same, but the entry point is by clicking Objects Web Applications
Application Security Policy. The difference between these configuration
approaches is that the approach from the Objects menu allows you the following
additional settings:
v The ability to control its administrative state.
v The ability to add or modify its brief, descriptive summary.

Adding request maps

To add a request map after creating an application security policy:
1.
2.
3.
4.
5.

98

Click Objects Web Applications Application Security Policy.

Click on the name of the application security policy to modify.
Click the Request Maps tab.
Click Add.
Define the request map.
a. From the Matching Rule list, select a matching rule. Refer to Defining
Matching Rule objects on page 117 for more information.
b. From the Request Profile list, select a Web request profile. Refer to Web
request profiles on page 139 for more information.
c. Click Apply

IBM WebSphere DataPower Integration Appliance XI50: Web Application Firewall Developers Guide

6. Optional: Repeat the previous step to add another request map.

7. Click Apply to save the changes to the running configuration.
8. Optional: Click Save Config to save the changes to the startup configuration.

Adding response maps

To
1.
2.
3.
4.

add a response map after creating an application security policy:

Click Objects Web Applications Application Security Policy.
Click on the name of the application security policy to modify.
Click the Response Maps tab.
Click Add.

5. Define the response map.

a. From the Matching Rule list, select a matching rule. Refer to Defining
Matching Rule objects on page 117 for more information.
b. From the Response Profile list, select a Web response profile. Refer to
Creating Web response profiles on page 148 for more information.
c. Click Apply
6. Optional: Repeat the previous step to add another response map.
7. Click Apply to save the changes to the running configuration.
8. Optional: Click Save Config to save the changes to the startup configuration.

Adding error maps

To add an error map after creating an application security policy:
1. Click Objects Web Applications Application Security Policy.
2. Click on the name of the application security policy to modify.
3. Click the Error Maps tab.
4. Click Add.
5. Define the error map.
a. From the Matching Rule list, select a matching rule. Refer to Defining
Matching Rule objects on page 117 for more information.
b. From the Processing Rule list, select a processing rule. Refer to Defining
Processing Rule objects on page 120 for more information.
c. Click Apply
6. Optional: Repeat the previous step to add another error map.
7. Click Apply to save the changes to the running configuration.
8. Optional: Click Save Config to save the changes to the startup configuration.

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

Appendix A. Referenced objects

99

Creating Error Policy objects

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.
To
1.
2.
3.

create an Error Policy object:

Select Objects Web Applications Error Policy.
Click Add to display the 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.
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
Although the configuration supports count monitors, Web Application
Firewall services do not support this type of monitor
4. Click Apply to save the changes to the running configuration.
5. Optional: Click Save Config to save the changes to the startup configuration.

100

IBM WebSphere DataPower Integration Appliance XI50: Web Application Firewall Developers Guide

Defining LDAP Search Parameters objects

The LDAP Search Parameters object serves as a container for the parameters that
are used to perform an LDAP search operation.
Authentication
The parameters for an LDAP search to retrieve the DN of the user.
Credentials mapping
The parameters for an LDAP search to retrieve the group name (DN or
attribute) based on the DN of the authenticated user.
You need to add a prefix and optionally add a suffix to create the LDAP filter. The
prefix and suffix are constructs of the LDAP filter expression, as defined in LDAP:
String Representations of Search Filters. This filter is used to perform the LDAP
search and return matching entries.
To create an LDAP Search Parameters object, use the following procedure:
1. Select Objects Access Settings LDAP Search Parameters.
2. Click Add to display the configuration pane.
3. In the Name field, enter the name for the object.
4. Retain the default setting for Admin State. To place in an inactive
administrative state, click disabled.
5. Optional: In the Comment field, enter a descriptive summary.
6. Specify the base DN to begin the search in the LDAP Base DN field. This
value identifies the entry level of the tree used by the LDAP Scope property.
7. Specify the name of the attribute to return for each entry that matches the
search criteria in the LDAP Returned Attribute field. The default is the dn
attribute.
8. Specify the prefix of the LDAP filter expression in the LDAP Filter Prefix
field.
If the prefix is mail= and the user name is 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 changes to the running configuration.
12. Optional: Click Save Config to save the changes to the startup configuration.

Appendix A. Referenced objects

101

Load balancer groups

A load balancer group is a server pool that can provide redundancy among a
collection of servers. A load balancer group can be used as the remote server for a
DataPower service or can be used to provide failover support for LDAP or IMS
Connect servers. A request to connect to a load balancer group results in the
selection of a healthy server to receive an incoming client request.
Figure 3 shows the load balancer group with four members

DataPower
appliance

Load Balancer
Group

Application
server A

Application
server B

Application
server C

Application
server D

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

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

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

Intelligent load distribution

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

102

IBM WebSphere DataPower Integration Appliance XI50: Web Application Firewall Developers Guide

Figure 4 shows the required configuration.

DataPower
appliance

WebSphere
Cell

WebSphere Application Server

cell
Deployment
manager

ODCInfo

Load Balancer
Group

Figure 4. Configuration to support intelligent load distribution

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

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

Advantages with WebSphere servers

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

Appendix A. Referenced objects

103

 When an application server is overloaded, its weight is reduced to receive less

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

Advantages with non-WebSphere servers

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

Algorithms for making load balancing decisions

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

Hash
Least connections
Round robin
Weighted least connections
Weighted round robin

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

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

104

IBM WebSphere DataPower Integration Appliance XI50: Web Application Firewall Developers Guide

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

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

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

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

Weighted least connections

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

Weighted round robin

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

Appendix A. Referenced objects

105

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

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

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

Health checks
A health check is essentially a scheduled rule that sends the same request to each
member. The successful completion of the health check requires that the server
passes normal TCP and HTTP connection criteria. Optionally, the health check
contains a filter to test the response from the server. If the filter accepts the
response, the server is considered to be healthy; otherwise, it is considered to be
convalescent.

Health states of members

The health of each member of a load balancer group is one of the following states:
v Healthy or up
v Quarantined or softdown
v Convalescent or down
Healthy: By default, all servers are considered healthy and are eligible to receive
forwarded client requests. When healthy, its health state is up.

106

IBM WebSphere DataPower Integration Appliance XI50: Web Application Firewall Developers Guide

Quarantined: During a normal HTTP transaction or the TCP ping, a failure to

connect to a server causes the server to be quarantined until a dampening period
elapses. When the dampening period elapses, the server returns to the healthy
state and becomes eligible to receive forwarded client requests. When quarantined,
its health state is softdown.
While quarantined, the server is:
v Removed from the server pool
v Ineligible to receive forwarded client requests
v Excluded from the optional health check
Convalescent: Optionally, you can associate a periodic health check with a load
balancer group. If the health check fails, the server is convalescent. The server is not
considered to be healthy until it passes a health check. When convalescent, its
health state is down.
While convalescent, the server is:
v Removed from the server pool
v Ineligible to receive forwarded client requests

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

Types of session affinity

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

Appendix A. Referenced objects

107

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

Passive session affinity

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

Active session affinity

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

Active-conditional session affinity

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

Session affinity modes and where to configure

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

Passive session affinity

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

Active session affinity

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

108

IBM WebSphere DataPower Integration Appliance XI50: Web Application Firewall Developers Guide

To configure active session affinity from the DataPower appliance, override

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

Active-conditional session affinity

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

Configuring a load balancer group

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

5.
6.
7.
8.

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

Defining the base configuration

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

109

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

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

Adding static members

To add static members to an existing load balancer group:
1. Click Objects Network Load Balancer Group.
2. Click the name of the load balancer group to modify.
3. Click the Members tab.
4. Add static members.
a. Click Add.
b. In the Actual Host field, enter the IP address or the domain-qualified host
name of the member.
c. For weighted algorithms: In the Weight field, enter the relative weight
(preference). The greater the value, the more likely this server is to receive a
connection request.
d. In the Mapped Server Port field, enter the member-specific target port or
retain the default value to use the DataPower service-defined port.
By default, member servers are contacted on the DataPower service-defined
port. However, if you have services running on different ports for different
member servers, explicitly identify the member-specific target port. If you
specify a nonzero value, that member server will always be contacted on
this port.
e. In the Health Port field, enter the member-specific health port or retain the
default value to use the load balancer group-defined port.
A nonzero value overrides the value for the Remote Port property of the
health check. This property is available during the configuration of the
health check on the Health tab.
f. Retain the default setting for Admin State. To place in an inactive
administrative state, click disabled.

110

IBM WebSphere DataPower Integration Appliance XI50: Web Application Firewall Developers Guide

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

Overriding session affinity in a WebSphere cell

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

Before you begin

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

About this task

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

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

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

Defining health checks

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

Click the name of a load balancer group to modify.

Click the Health tab.
Set Enabled to on.
For standard health checks: In the URI field, enter the non-server (file path)
portion of the target URI. That is, specify the URI to receive the client request
that is generated by the rule.
Appendix A. Referenced objects

111

6. In the Remote Port field, enter the port on the target server to receive the
query.
You can override this value for one or more members of the load balancer
group with the Health Port property. This property is available during the
configuration of member servers in the group.
The response from the server is evaluated to determine the health status of
each member server in the group. The request is sent to the target URI and
remote port.
7. From the Health Check Type list, select the type of health check to perform.
8. Optional for standard health checks: Set Send SOAP Request? to off to access
the target URI with an HTTP GET operation instead of the default HTTP
POST operation.
9. For SOAP requests with an HTTP POST operation: In the SOAP Request
Document field, enter the location (URL) of the SOAP message to send as the
request.
10. In the Timeout field, enter the number of seconds to wait for the completion
of the health check.
11. In the Frequency field, enter the number of seconds between health checks.
12. For standard health checks: Define the filter for a valid server response.
a. In the XPath Expression, enter the XPath expression that must be found in
a valid server response. Use the XPath tool to help define the expression.
b. In the XSL Health Check Filter field, enter the location (URL) of the style
sheet to filter the server response.
13. Optional for standard health checks: From the SSL proxy profile list, select
the SSL proxy profile to provide for a secured connection.
14. Click Apply to save the changes to the running configuration.
15. Optional: Click Save Config to save the changes to the startup configuration.

Modifying to use workload management information

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

Before you begin

Configure a load balancer group.

About this task

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

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

112

IBM WebSphere DataPower Integration Appliance XI50: Web Application Firewall Developers Guide

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

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

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

Assigning weight to members

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

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

Click Objects Network Load Balancer Group.

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

113

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

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

Enabling the retrieval of workload management information

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

Before you begin

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

About this task

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

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

Installing the ODCInfo application

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

Before you begin

Ensure the WebSphere Application Server product is installed and is running
before installing the ODCInfo application.
Note: Uninstall any previous version of the ODCInfo application before installing
another version.

About this task

Install the ODCInfo application on the application server that contains the
deployment manager for a cell. The ODCInfo application collects information
about application servers in the cluster, such as changes in weights or if an
application server was added or removed from the cluster.

114

IBM WebSphere DataPower Integration Appliance XI50: Web Application Firewall Developers Guide

Procedure
1. Copy the ODCInfo.war file, ODCInfoCheckInstall.jacl, ODCInfoStart.jacl, and
ODCInfoDeploy.jacl to a local directory on the deployment manager.
2. Choose the Web archive file that matches the version of WebSphere Application
Server product.
v For version 6.0.x, use ODCInfo_ND60.war
v For version 6.1.x or version 7.0.x, use ODCInfo_ND61.war
3. Log in from the command line to the deployment manager.
4. Navigate to the /bin directory under the deployment manager profile. For
example:
cd /opt/IBM/WebSphere/AppServer/profiles/Dmgr01/bin
5. Install the ODCInfo application by entering:
./wsadmin.sh -f script_path/ODCInfoDeploy.jacl dmgr_server_name
dmgr_node_name path_to_war_file ODCInfo
For example:
./wsadmin.sh -f /tmp/ODCInfoDeploy.jacl dmgr wasnode2CellManager01
/tmp/ODCInfo_ND61.war ODCInfo
6. Verify the installation by entering:
./wsadmin.sh -f script_path/ODCInfoCheckInstall.jacl cellName
dmgr_server_name ODCInfo
A message is displayed indicating whether the application is installed.
7. Ensure that you define the host name and port for the ODCInfo application as
a host_alias for the default_host under WebSphere Application Server virtual
hosts.

What to do next
Start the ODCInfo application.

Starting the ODCInfo application

Start the ODCInfo application to begin collecting the remote host information, such
as weights or if a host was added or deleted.

Before you begin

The ODCInfo application must be installed and running on the deployment
manager of the WebSphere cell (WebSphere environment).

About this task

Start the ODCInfo application to begin collecting information about the application
servers in the WebSphere cell (WebSphere environment).

Procedure
1. Copy ODCInfoStart.jacl to a local directory on the deployment manager.
2. Log in from the command line to the deployment manager.
3. Navigate to the /bin directory under the deployment manager profile.
Appendix A. Referenced objects

115

cd /opt/IBM/WebSphere/AppServer/profiles/Dmgr01/bin
4. Start the application by entering:
./wsadmin.sh -f script_path/ODCInfoStart.jacl cellName
dmgr_node_name ODCInfo
For example:
./wsadmin.sh -f /tmp/ODCInfoStart.jacl dpblade34Cell01
dpblade34CellManager01 ODCInfo
5. Verify that the ODCInfo application started.
a. Log in to the WebSphere Administrative Console.
b. Click Applications Enterprise Applications.

What to do next
Create or modify a DataPower load balancer group.

Uninstalling the ODCInfo application

To remove the ODCInfo application from the deployment manager, run the
ODCInfoUninstall script.

About this task

Before installing a new version of the ODCInfo application, you must uninstall the
old version.

Procedure
1. Copy the ODCInfoCheckUninstall.jacl file to a local directory on the
WebSphere deployment manager.
2. Log in from the command line to the deployment manager.
3. Navigate to the bin directory of the deployment manager profile. For example:
cd /opt/IBM/WebSphere/AppServer/profiles/Dmgr01/bin
4. Uninstall the application by entering:
./wsadmin.sh -f script_path/ODCInfoUninstall.jacl cellName
dmgr_server_name ODCInfo
For example:
./wsadmin.sh -f /tmp/ODCInfoUninstall.jacl wasnode2Cell01 dmgr
ODCInfo
5. Verify by entering:
./wsadmin.sh -f script_path/ODCInfoCheckInstall.jacl cellName
dmgr_server_name ODCInfo
The response indicates success or failure.

What to do next
Install the ODCInfo application.

116

IBM WebSphere DataPower Integration Appliance XI50: Web Application Firewall Developers Guide

Defining Matching Rule objects

To configure a Matching Rule, use the following procedure:
1. Select Objects XML Processing Matching Rule to display the catalog.
2. Click Add to display the configuration screen.
3. In the Name field, enter the name for the object.
4. Retain the default setting for Admin State. To place in an inactive
administrative state, click disabled.
5. Optional: In the Comment field, enter a descriptive summary.
6. Use the Match with PCRE toggle to indicate whether match patterns use
PCRE expression or shell-style expressions.
on

Uses PCRE expressions.

off

(Default) Uses shell style expressions.

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

match criteria with OR semantics or with AND semantics.
on

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

condition needs to be true for the match to succeed.

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

conditions must be true for the match to succeed.
8. Define matching rules on the Matching Rule tab
a. Click Add to display the Property window.
b. Select the desired match type from the Matching Type list.
c. Define the matching criteria.
off

d. Click Save.
Repeat this step to define another matching rule.
9. Click Apply to save the changes to the running configuration.
10. Optional: Click Save Config to save the changes to the startup configuration.

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

117

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

118

IBM WebSphere DataPower Integration Appliance XI50: Web Application Firewall Developers Guide

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

119

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.

Defining Processing Rule objects

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

A specialized bidirectional rule used for error handling

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

The message will be decompressed using the gzip algorithm.

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

The message will be decompressed using the gzip algorithm.

PKZIP
The message will be decompressed using the pkzip algorithm.
The created archive contains only one file. If the message contains
attachments, the attachments are contained in the one file.
Non-XML Processing
Select whether to enable or disable the processing of non-XML
documents.

120

IBM WebSphere DataPower Integration Appliance XI50: Web Application Firewall Developers Guide

on

Enables the processing of non-XML documents.

off

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

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

Creating Rate Limiter objects

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.
To create a Rate Limiter object:
1. Select Objects Web Applications Rate Limiter.
2. Click Add to display the configuration pane.
3. Provide the following inputs:
Name Specify the name of the object.
Admin State
Retain the default setting. To place the object in an inactive
administrative state, click disabled.
Comments
Specify a descriptive object-specific summary.
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.
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.

Appendix A. Referenced objects

121

Concurrent Connections
The number of simultaneous connections allowed per user. Set to 0 to
disable this enforcement.
4. Click Apply to save the changes to the running configuration.
5. Optional: Click Save Config to save the changes to the startup configuration.

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
enforced on the page, these pages will then issue a session cookie. Refer to
Defining Matching Rule objects on page 117 for more information.

122

IBM WebSphere DataPower Integration Appliance XI50: Web Application Firewall Developers Guide

URL Rewrite Policy

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

Applies to both client requests and server responses.

Request
Applies to client requests only.
Response
Applies to server responses only.
4. Continue with Creating a URL Rewrite Policy.

Creating a URL Rewrite Policy

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

Appendix A. Referenced objects

123

post-body
Rewrites the body of an HTTP POST request. The POST body
contains the input values for a basic HTTP POST request.
rewrite
This rule type is deprecated.
Match Expression
Specify a PCRE (Perl-compatible regular expression) that defines the
match condition that triggers the rewrite rule. Depending on the rule
type, a candidate URL or specific HTTP header field is matched against
the expression.
v For absolute-rewrite, content-type, and post-body, defines the
expression to be matched against the URL.
.* or *
Matches any string.
(.*)xsl=(.*)\?(.*)
Matches a string of the following format:
a. A text subpattern.
b. Followed by xsl=.
c. Followed by a text subpattern.
d. Followed by ?. The backward slash (\) in the PCRE is a
URL escape.
e. Followed by a text subpattern.
(.*)&[Xx][Ss][Ll]=([^&]+)(.*)
Matches a string of the following format:
a. A text subpattern.
b. Followed by &.
c. Followed by X or x.
d. Followed by S or s.
e. Followed by L or l.
f. Followed by =.
g. Followed by a text subpattern that does not contain an
ampersand (&) character.
h. Followed by a text subpattern.
v For header-rewrite, defines the expression to be matched against the
contents of a specific HTTP header field. For example *.* matches
any value.
PCRE documentation is available at http://www.pcre.org.
Input Replace Expression
Specify a PCRE-style replacement that defines the rewritten URL, HTTP
header field, or HTTP POST body.
v For absolute-rewrite, defines the rewritten URL.
If the match pattern is .* or *, specify the complete replacement.
If the match pattern is (.*)xsl=(.*)\?(.*), specify the evaluation
replacement for any text subpattern or retain the original text
subpattern. To retain the first text subpattern, specify $1; to retain
the second text subpattern, specify $2, and so forth. To replace the
second text subpattern only, specify $1xsl=ident.xsl?$3.
If a rewritten URL begins with a host name or port that is different
from the configured remote address, the host name or port portion of
the rewritten URL is ignored.

124

IBM WebSphere DataPower Integration Appliance XI50: Web Application Firewall Developers Guide

v For content-type, defines the replacement value for the Content-Type

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

Enables the substitution of literal characters for URL-encoded

characters.

off

(Default) Disables the substitution of literal characters for

URL-encoded characters.

Stylesheet URL Unescape

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

(Default) Enables the substitution of literal characters for

URL-encoded characters.

off

Disables the substitution of literal characters for URL-encoded

characters.

Header Name
Identifies the name of the header to have its value rewritten. The
header name must be entered exactly as it is defined in the message.
This option is for header-rewrite only.
URL Normalization
Select whether to enable normalization of URL strings. Normalizing a
URL compresses "." and ".." and converts backward slashes (\) to
forward slashes (/).
on

(Default) Enables normalization.

off
Disables normalization.
4. Click Save to return to the URL Rewrite Policy Configuration (Main) screen.
Appendix A. Referenced objects

125

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

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

User Agent
A user agent is a client that initiates a request for a local service to establish a
connection to a remote server. An XML manager uses a user agent, for example, to
retrieve resources from elsewhere on the network. The settings for a user agent can
affect messages that a DataPower service sends out.
The DataPower provides the default user agent in each application domain. The
configuration of the default user agent is as follows:
v Allows a maximum of eight HTTP redirect messages before declaring the target
as unreachable
v Set the idle timeout to 300 seconds before timing out and closing the connection.
The default user agent does not provide configuration for the following types of
policies:
HTTP proxy
The user agent forwards requests that match the URL expression to an
HTTP server instead of to the target server.
SSL proxy
The user agent establishes a secure connection to the remote server for
requests that match the URL expression.
Basic authentication
The user agent uses these credentials for authentication with the remote
server for requests that match the URL expression. This feature is useful
for HTTP connections.
SOAP Action
The user agent includes the specified contents in the SOAPAction header in
requests that match the URL expression.
Public key authentication
The user agent uses these credentials for authentication with the remote
server for requests that match the URL expression. This feature is useful
for SCP and SFTP connections.
Allow compression
The user agent compresses the payload for requests that match the URL
expression.
Header retention
The user agent retains the specified message headers for requests that
match the URL expression.
Restrict to HTTP 1.0
The user agent restricts HTTP communication to HTTP 1.0 for requests that
match the URL expression.
Inject header
The user agent injects the specified headers into requests that match the
URL expression.

126

IBM WebSphere DataPower Integration Appliance XI50: Web Application Firewall Developers Guide

Chunked uploads
The user agent uses HTTP 1.1 Chunked content encoding for requests that
match the URL expression. This feature is useful for streaming large
documents.
FTP client
The user agent controls the client settings for outgoing FTP connections for
requests that match the URL expression. These client settings can be
overridden by query parameters in the URL that initiates the file transfer.
Each type of these policies uses URL matching patterns. When there are multiple
configurations for a policy type, the policy evaluates each candidate URL against
the matching pattern in sequential order. Therefore, order is important.
When you create a new user agent, the configuration defines these default settings.

Creating a user agent

To create a basic user agent:
1. Click Network Other User Agent.
2. Click Add.
3. In the Name field, enter the name for the object.
4. Retain the default setting for Admin State. To place in an inactive
administrative state, click disabled.
5. Optional: In the Comment field, enter a descriptive summary.
6. Optional: In the HTTP Request-Header field, enter the value the user agent
transmits as the HTTP request-header field.
7. Optional: In the Maximum Redirects field, change the maximum number of
HTTP redirect messages to allow before declaring the target as unreachable.
8. Optional: In the Timeout field, change the idle timeout to allow in seconds
before timing out and closing the connection.
9. On the Proxy Policy tab, define HTTP proxy policies.
10. On the SSL Proxy Profile Policy tab, define secure connection policies for
HTTP proxy servers.
11. On the Basic-Auth Policy tab, define basic authentication policies.
12. On the Soap-Action Policy tab, define SOAP action policies.
13. On the Pubkey-Auth Policy tab, define public key authentication policies.
14. On the Allow-Compression Policy tab, define policies that disable
compression.
15. On the Header-Retention Policy tab, define header retention policies.
16. On the Restrict to HTTP 1.0 Policy tab, define HTTP 1.0 restriction policies.
17. On the Inject Header Policy tab, define header injection policies.
18. On the Chunked Uploads Policy tab, define policies that disable HTTP 1.1
chunked content encoding.
19. On the FTP Client Policies tab, define FTP client policies.
20. Click Apply to save the changes to the running configuration.
21. Optional: Click Save Config to save the changes to the startup configuration.

Modifying the basic configuration

To modify the basic configuration of a user agent:
1. Click Network Other User Agent.
Appendix A. Referenced objects

127

2. Click the name of an existing user agent.

3. Optional: In the HTTP Request-Header field, change the value the user agent
transmits as the HTTP request-header field.
4. Optional: In the Maximum Redirects field, change the maximum number of
HTTP redirect messages to allow before declaring the target as unreachable.
5. Optional: In the Timeout field, change the idle timeout to allow in seconds
before timing out and closing the connection.
6. Click Apply to save the changes to the running configuration.
7. Optional: Click Save Config to save the changes to the startup configuration.

Adding an HTTP proxy policy

A user agent can forward requests that meet the matching expression to an HTTP
proxy server instead of to the target server. By default, the user agent forwards
request to the target server.
To
1.
2.
3.

add an HTTP proxy policy to a user agent:

Click Network Other User Agent.
Click the name of an existing user agent.
Click the Proxy Policy tab.

4. Add a policy.
a. Click Add.
b. In the URL Matching Expression field, enter a shell-style expression to be
the pattern to match against the URL set.
c. Set Skip to on to forward request to the specified HTTP server.
d. Define the remote HTTP server to forward requests.
1) In the Remote Host field, enter the host name or IP address of the
HTTP server.
2) In the Remote Port field, enter the listening port on the HTTP server.
e. Click Save to add this policy to the list.
5. Repeat the previous step to add another policy.
6. Click Apply to save the changes to the running configuration.
7. Optional: Click Save Config to save the changes to the startup configuration.
To secure the connection using SSL, add an SSL proxy policy.

Adding an SSL proxy policy

A user agent requests can require a secured (SSL-enabled) connection. The user
agent requires an SSL proxy profile to secure the connection. The SSL proxy profile
supports secure access to the HTTP proxy server. The SSL proxy profile must be
either a client or two-way profile. If the target URL matches the expression, the
connection will use the SSL proxy profile to secure the connection. Refer to SSL
Proxy Profile objects on page 24 for more information.
To add an SSL proxy policy to a user agent:
1. Click Network Other User Agent.
2. Click the name of an existing user agent.
3. Click the SSL Proxy Profile Policy tab.
4. Add a policy.
a. Click Add.

128

IBM WebSphere DataPower Integration Appliance XI50: Web Application Firewall Developers Guide

b. In the URL Matching Expression field, enter a shell-style expression to be

the pattern to match against the URL set.
c. From the SSL Proxy Profile list, select the SSL proxy profile to support
secure access to the HTTP proxy.
d. Click Save to add this policy to the list.
5. Repeat the previous step to add another policy.
6. Click Apply to save the changes to the running configuration.
7. Optional: Click Save Config to save the changes to the startup configuration.

Adding a basic authentication policy

A user agent requests require basic HTTP authentication (user name and
password). If the target URL matches this expression, an HTTP Authorization
header will be added. This header contains the supplied credentials. The URL set
defined by this matching expression could be identical to the set defined by the
HTTP proxy policy, or it could be a subset.
To add a basic authentication policy to a user agent:
1. Click Network Other User Agent.
2. Click the name of an existing user agent.
3. Click the Basic-Auth Policy tab.
4. Add a policy.
a. Click Add.
b. In the URL Matching Expression field, enter a shell-style expression to be
the pattern to match against the URL set.
c. Define credentials for authentication.
1) In the User name field, enter the name of the user.
2) In the Password and Confirm Password fields, enter the password for
the user.
d. Click Save to add this policy to the list.
5. Repeat the previous step to add another policy.
6. Click Apply to save the changes to the running configuration.
7. Optional: Click Save Config to save the changes to the startup configuration.

Adding a SOAP action policy

A user agent can require that the contents of the HTTP SOAPAction request header
field be supplied. The HTTP header contains the SOAP action (a URI that identifies
the intent of the SOAP HTTP request). If the header contains the SoapAction:
http://example.org/add header, the URI of http://example.org/add is the value.
To
1.
2.
3.
4.

add a SOAP action policy to a user agent:

Click Network Other User Agent.
Click the name of an existing user agent.
Click the Soap-Action Policy tab.
Add a policy.
a. Click Add.
b. In the URL Matching Expression field, enter a shell-style expression to be
the pattern to match against the URL set.
c. In the Soap Action field, enter the URI of the SOAP action.
Appendix A. Referenced objects

129

d. Click Save to add this policy to the list.

5. Repeat the previous step to add another policy.
6. Click Apply to save the changes to the running configuration.
7. Optional: Click Save Config to save the changes to the startup configuration.

Adding a public key authentication policy

A user agent can use public key authentication to establish a connection to remote
resources. Public key authentication requires a private key on the appliance and a
certificate on the remote server. This feature is useful when the agent uses the SCP
or SFTP protocol.
If the private key (file and object) is not on the appliance, upload the key file to the
appliance to create a key object. The remote server must have the appropriate
certificate in $HOME/.ssh/authorized_keys directory.
Examples URL patterns include the following matching expression:
v https://server.domain.com/transactions/*
v sftp://user@server.com/images/*
v scp://user[a-c]@10.10.[0-4].23/inbound/*
To
1.
2.
3.
4.

add a private key authentication policy to a user agent:

Click Network Other User Agent.
Click the name of an existing user agent.
Click the PubKey-Auth Policy tab.
Add a policy.
a. Click Add.
b. In the URL Matching Expression field, enter a shell-style expression to be
the pattern to match against the URL set.
c. From the Private Key list, select the desired private key.

d. Click Save to add this policy to the list.

5. Repeat the previous step to add another policy.
6. Click Apply to save the changes to the running configuration.
7. Optional: Click Save Config to save the changes to the startup configuration.

Adding a compression policy

A user agent can compress the payload of its communications with remote
resources. Compression is useful when the payload is large. The default is to allow
compression.
To disable an allow compression policy for a user agent:
1. Click Network Other User Agent.
2. Click the name of an existing user agent.
3. Click the Allow-Compression Policy tab.
4. Add a policy.
a. Click Add.
b. In the URL Matching Expression field, enter a shell-style expression to be
the pattern to match against the URL set.
c. Set Allow Compression to off.
d. Click Save to add this policy to the list.

130

IBM WebSphere DataPower Integration Appliance XI50: Web Application Firewall Developers Guide

5. Repeat the previous step to add another policy.

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

Adding a header retention policy

A user agent can retain certain message headers with a header retention policy.
Several DataPower services can inject or suppress HTTP headers. The user agent
operates on the message after the service. The policy can be defined to retain the
following headers:
Accept-Encoding
The HTTP Accept-Encoding request header. If selected, the traffic includes
the Accept-Encoding header independent of whether the DataPower service
specifies compression. Compressed responses are accepted.
Range

The HTTP Range request header.

TE

The HTTP TE request header.

MQMD

The WebSphere MQ MQMD header.

To
1.
2.
3.

add a header retention policy to a user agent:

Click Network Other User Agent.
Click the name of an existing user agent.
Click the Header-Retention Policy tab.

4. Add a policy.
a. Click Add.
b. In the URL Matching Expression field, enter a shell-style expression to be
the pattern to match against the URL set.
c. From the Header Retention list, select the check boxes for the headers to
retain.
d. Click Save to add this policy to the list.
5. Repeat the previous step to add another policy.
6. Click Apply to save the changes to the running configuration.
7. Optional: Click Save Config to save the changes to the startup configuration.

Adding an HTTP 1.0 restriction policy

A user agent can restrict HTTP communications to the HTTP 1.0 specification, if
desired.
To add an HTTP 1.0 restriction policy to a user agent:
1. Click Network Other User Agent.
2. Click the name of an existing user agent.
3. Click the Restrict to HTTP 1.0 Policy tab.
4. Add a policy.
a. Click Add.
b. In the URL Matching Expression field, enter a shell-style expression to be
the pattern to match against the URL set.
c. Set Restrict to HTTP 1.0 to on.
d. Click Save to add this policy to the list.
5. Repeat the previous step to add another policy.
Appendix A. Referenced objects

131

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

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

Adding a header injection policy

A user agent can inject an HTTP header (name-value pair) into a request to the
remote server. Several DataPower services can also inject HTTP headers. The user
agent operates on the request after the service.
To
1.
2.
3.
4.

add a header injection policy to a user agent:

Click Network Other User Agent.
Click the name of an existing user agent.
Click the Inject Header Policy tab.
Add a policy.
a. Click Add.
b. In the URL Matching Expression field, enter a shell-style expression to be
the pattern to match against the URL set.
c. Define the header to inject.
1) In the Header Name field, enter the name of the header.

2) In the Header Value field, enter the value for the header.
d. Click Save to add this policy to the list.
5. Repeat the previous step to add another policy.
6. Click Apply to save the changes to the running configuration.
7. Optional: Click Save Config to save the changes to the startup configuration.

Adding a chunked upload policy

The user agent uses HTTP 1.1 chunked content encoding that is useful for
streaming large documents. When the appliance employs HTTP 1.1, the body of
the document can be delimited by either Content-Length or chunked encoding.
While all servers understand how to interpret Content-Length, many applications
will fail to understand chunked encoding. For this reason, Content-Length is the
standard method. However doing so interferes with the ability of the appliance to
fully stream.
To stream full documents toward the remote server, keep this property enabled.
For chunked encoding, the remote server must be compliant with RFC 2616. This
HTTP 1.1 feature cannot be renegotiated at run time.
Several DataPower services can also control chunked uploads. The user agent
operates on the message after the service.
To
1.
2.
3.
4.

disable the chunked uploads policy for a user agent:

Click Network Other User Agent.
Click the name of an existing user agent.
Click the Chunked Uploads Policy tab.
Add a policy.
a. Click Add.
b. In the URL Matching Expression field, enter a shell-style expression to be
the pattern to match against the URL set.
c. Set Enable/Disable HTTP 1.1 Chunked Request Bodies to off.

132

IBM WebSphere DataPower Integration Appliance XI50: Web Application Firewall Developers Guide

d. Click Save to add this policy to the list.

5. Repeat the previous step to add another policy.
6. Click Apply to save the changes to the running configuration.
7. Optional: Click Save Config to save the changes to the startup configuration.

Adding an FTP client policy

A user agent can associate a set of FTP URLs with a specified policy. This policy
controls the default values of many FTP client options for outgoing FTP
connections. These settings can be further overridden by query parameters in the
URL that initiates the file transfer.
To
1.
2.
3.
4.

add an FTP client policy to a user agent:

Click Network Other User Agent.
Click the name of an existing user agent.
Click the FTP Client Policies tab.
Add a policy.
a. Click Add.
b. In the URL Matching Expression field, enter a shell-style expression to be
the pattern to match against the URL set.
c. From the Passive Mode list, select how the use of FTP passive mode to
control the direction in which FTP data connections are made.
d. From the Encrypt Command Connection list, select how to control the use
of TLS to secure the FTP command connection.
e. From the Stop Command Encryption After Authentication list, select how
to control the cessation of FTP command channel encryption after user
authentication. Encryption must be stopped for compatibility with NAT
(Network Address Translation) and other firewall applications. Although
this behavior might be a security risk, this behavior is the only option when
a NAT is in use.
f. From the Encrypt File Transfers list, select how to control the encryption of
file transfers. All setting are compatible with NAT.
g. From the Data Type list, select the default data type of file transfers. In
most cases, the default value of binary is appropriate.
h. From the Write Unique Filename if Trailing Slash list, select whether the
FTP server creates unique file names. Some FTP servers provide the STOU
command where the FTP server chooses the unique file name in the current
directory to which to write. When enabled and the URL end in a slash, the
STOU command, not the STOR command, chooses the unique file name.
Before enabling, ensure that the FTP server supports the STOU command.
i. From the Quoted Commands list, select the FTP quoted commands list to
send to the FTP server before each STOU, STOR, or RETR command.
j. From the Size Check list, select whether to perform a size check after a
transfer.

k. Click Save to add this policy to the list.

5. Repeat the previous step to add another policy.
6. Click Apply to save the changes to the running configuration.
7. Optional: Click Save Config to save the changes to the startup configuration.

Appendix A. Referenced objects

133

Creating or editing a 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
v
v
v
v
v
v
v

Rate limiting
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
Error handling
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
this handler. When selected, communication with clients, the backend
server, or both will use SSL in accordance with the configured Crypto
Profile.

134

IBM WebSphere DataPower Integration Appliance XI50: Web Application Firewall Developers Guide

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 SSL Proxy Profile objects on page 24 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 policies on page 97 for more
information.
XML Manager
Select an existing XML Manager to assign 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.
Refer to XML Manager on page 151 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 Creating Error Policy objects on page 100 for more
information.
Request Security
If disabled (off), no request-side security policies are enforced. All
requests are allowed through. This property overrides the request
security policy that is defined in the selected Application Security
Policy.

Appendix A. Referenced objects

135

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

Modifying default Proxy Settings

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.
Back Persistent Timeout
Specify the maximum amount of time, in seconds (in the range 0

136

IBM WebSphere DataPower Integration Appliance XI50: Web Application Firewall Developers Guide

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 123 for more information.
3. Click Apply to save the changes to the running configuration.
4. Optional: Click Save Config to save the changes to the startup configuration.

Modifying default HTTP Options

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.

Appendix A. Referenced objects

137

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

Configuring 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, use the following procedure:
1. Click the Source Addresses tab to display the Source Addresses catalog.
2. Click Add.
3. 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 changes to the running configuration.
7. Optional: Click Save Config to save the changes to the startup configuration.

138

IBM WebSphere DataPower Integration Appliance XI50: Web Application Firewall Developers Guide

Web request profiles

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

Manage sessions
Filter HTTP methods
Filter HTTP header, URL-encoded HTTP POST, and HTTP Query String values
Manage XML traffic
Allow or disallow, encrypt or sign, and filter cookies
Provide service threat protection, such as filtering SQL injection attacks

Creating Web request profiles

To create a Web request profile:
1. Select Objects Web Applications Web Request Profile.
2.
3.
4.
5.
6.

Click Add to display the configuration pane.

On the Main tab, define the basic configuration.
Optional: On the Profile tab, define acceptable content type.
Optional: On the Methods & Versions tab, filter HTTP methods and versions.
Optional: On the Processing tab, define how to process requests.

7. Optional: On the Name Value tab, filter on HTTP headers (names and
corresponding values).
8. Optional: On the Cookie tab, define how to manage cookies.
9. Optional: On the Multipart Form tab, define how to impose limits on
multipart/form submissions.
10. Optional: On the Threat Protection tab, define protection against threats in
requests.
11. Click Apply to save the changes to the running configuration.
12. Optional: Click Save Config to save the changes to the startup configuration.

Defining the basic configuration

To define the basic configuration for a Web response profile:
1. Click Objects Web Applications Web Request Profile.
2. Click Add.
3. In the Name field, enter the name for the object.
4. Retain the default setting for Admin State. To place in an inactive
administrative state, click disabled.
5. Optional: In the Comment field, enter a descriptive summary.
6. Optional: From the Mode list, 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.
Appendix A. Referenced objects

139

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

Modifying the profile

To modify the profile:
1. Click Objects Web Applications Web Request Profile.
2. Click the name of the Web request profile to modify.
3. Click the Profile tab.
4. Optional: From the Allow SSL list, select a profile policy regarding SSL
communications.
5. Optional: From the AAA Policy list, select the AAA policy to establish
filtering on Web requests. Only requests that pass authentication and
authorization are forwarded to the remote application service. 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 Creating AAA Policy objects on page 57 for more information.
6. Optional: From the Rate Limiting list, select the rate limiter policy for Web
requests. This policy restricts identities (as determined by AAA or the client IP
address if AAA was not selected) to a specific number of transactions per
second or a specific number of concurrent transaction connections. Refer to
Creating Rate Limiter objects on page 121 for more information.
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 Creating Error Policy objects on page 100). An error policy allows for
error count monitoring.
7. Optional: From the Access Control List list, select the ACL to allow or deny
access to this service based on the IP address of the client.
8. Optional: From the Error Policy list, select the error policy to run when any
client request violates the Web request profile. This error policy overrides the
error policy that is defined at the Web application firewall level. Refer to
Creating Error Policy objects on page 100 for more information.
9. Optional: From the Session Policy list, select the session policy that
establishes the URLs that are acceptable starting points (start pages) for a Web

140

IBM WebSphere DataPower Integration Appliance XI50: Web Application Firewall Developers Guide

application session. In addition, a session policy limits the duration of any

session. Refer to Session Management Policy on page 122 for more
information.
10. Optional: In the Content-Type List field, define which content types to allow.
If undefined, 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.
11. Click Apply to save the changes to the running configuration.
12. Optional: Click Save Config to save the changes to the startup configuration.

Controlling accepted HTTP methods and versions

To modify which HTTP methods and version that the Web request profile accepts:
1. Click Objects Web Applications Web Request Profile.
2. Click the name of the Web request profile to modify.
3. Click the Methods & Versions tab.
4. Optional: From the Methods list, select which HTTP methods to accept. The
profile rejects any request that does not employ one of these methods.
5. Optional: From the Versions list, select which HTTP versions to accept. The
profile rejects any request that does not employ one of these versions.
6. Click Apply to save the changes to the running configuration.
7. Optional: Click Save Config to save the changes to the startup configuration.

Defining document processing

It is possible to perform document processing on Web requests (such as transform
XML content, if encountered, or send a copy of request content to a third location).
To define document processing:
1. Click Objects Web Applications Web Request Profile.
2. Click the name of the Web request profile to modify.
3. Click the Processing tab.
4. Optional: From the XML Processing list, select how to process requests that
contain an XML MIME type in the Content-type header (for example,
text/xml).
5. If processing XML requests: From the XML Transformation Rule list, select the
processing rule. For information about creating a processing rule, refer to
Defining Processing Rule objects on page 120.
6. Optional: From the Non-XML Processing list, select how to process requests
that do not contain an XML MIME type in the Content-type header (for
example, www-url-encoded).
7. If processing non-XML requests: From the Non-XML Processing Rule list,
select the processing rule. For information about creating a processing rule,
refer to Defining Processing Rule objects on page 120.
8. Click Apply to save the changes to the running configuration.
9. Optional: Click Save Config to save the changes to the startup configuration.

Filtering with name-value profiles

The profile can filter the names and corresponding values of HTTP headers,
URL-encoded body content, or query strings. These values can also be mapped to
Appendix A. Referenced objects

141

alternate values. Mappings provide ways to control the name-value pairs that are
passed to the remote application server. Using mappings provide both content
control and threat protection.
To
1.
2.
3.
4.

define mappings:
Click Objects Web Applications Web Request Profile.
Click the name of the Web request profile to modify.
Click the Name Value tab.
Optional: From the Header Name-Value Profile list, select the name-value
profile to filter HTTP headers. This profile defines the rules to apply to HTTP
headers.
5. Optional: From the URL-Encoded Body Name-Value Profile list, select the
name-value profile to filter URL-encoded HTTP POST body content. This
profile defines the rules to apply to each element in the POST body.
6. Optional: From the Allow Query String list, select how to handle query strings.
7. If allowing or requiring query strings: From the Query String Name-Value
Profile list, select the name-value profile to filter query strings. This profile
defines the rules to apply to each query string.
8. Click Apply to save the changes to the running configuration.
9. Optional: Click Save Config to save the changes to the startup configuration.
For information about creating a name-value profile, refer to Name-Value Profile
on page 117.

Managing cookies
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 in the cookie.
To manage cookies:
1. Click Objects Web Applications Web Request Profile.
2. Click the name of the Web request profile to modify.
3. Click the Cookie tab.
4. From the Allow Cookies list, select how to handle cookies.
5. Optional: From the Sign/Encrypt Cookies list, select how to enable signing or
encrypting of cookie content.
6. If signing or encrypting: Define cryptographic materials:
v Use a shared secretSigning or encrypting cookies requires a secret
password phrase for the cryptographic operation. If this key is the same on
multiple appliances, each appliance can verify or decrypt a cookie from
another appliance without the need to maintain state information.
v Use an IP address-specific cookieNormally a signed or encrypted cookie
contains the client IP address, which prevents another client from using this
cookie. Some environments make this behavior undesirable.
7. Optional: From the Cookie Content Name-Value Profile list, select the
name-value profile for cookie contents. This profile allows the validation of
data members. Validation can filter out unknown ones or map certain names
to known values. For information about creating a name-value profile, refer to
Name-Value Profile on page 117.
8. Optional: Clear Sign or Encrypt All Cookies to sign or encrypt specific
cookies.

142

IBM WebSphere DataPower Integration Appliance XI50: Web Application Firewall Developers Guide

9. If signing or encrypting specific cookies: In the Cookie Names field, create the
list of cookies.
10. Click Apply to save the changes to the running configuration.
11. Optional: Click Save Config to save the changes to the startup configuration.

Multipart forms
A Web request profile can impose limits on multipart form submissions. The
following example shows 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"
Post2000
-----------------------------1943549852707912569510983863

Imposing limits on multipart forms

To impose limits on multipart forms:
1. Click Objects Web Applications Web Request Profile.
2. Click the name of the Web request profile to modify.
3. Click the Multipart Form tab.
4. Define maximum number and size of parts.
a. In the Max Number of Parts field, enter the maximum number of parts to
allow.
b. In the Max Size Per Part field, enter the maximum number of parts to
allow in bytes.
5. Optional: In the Max Aggregate Size of All Parts field, enter the maximum
size of all parts in bytes.
6. Optional: Set Restrict Sub-Content Types to force individual form-data content
types to be matched against the general list of request-acceptable content-type
expressions.
7. Click Apply to save the changes to the running configuration.
8. Optional: Click Save Config to save the changes to the startup configuration.

Appendix A. Referenced objects

143

Protecting against threats

To define threat protection:
1. Click Objects Web Applications Web Request Profile.
2. Click the name of the Web request profile to modify.
3. Click the Threat Protection tab.
4. Optional: Define the minimum and maximum size of the request body in
bytes.
5. Optional: Define a SQL injection filter.
a. Set SQL Injection Filter to filter against:
v URIs
v Query strings
v Payloads with a content header of application/www-urlencoded or
multipart/form-data
b. In the SQL Injection Patterns File field, select the file containing the
regular expressions to be used to filter out potentially malicious requests.
You can use the default file, store:///SQL-Injection-Patterns.xml, or you
can create a custom file in either the local:/// or the store:/// directory.
Note: If you modify the default file in the store:/// directory without
renaming it, the next firmware upgrade will overwrite the changes.
6. Optional: In the Maximum URI Length field, define the maximum URI
length.
7. Optional: Change the setting to Filter against Unicode, .. (dot dot), or .exe
attack. By default, these profile protects against these attacks.
v Filters against Unicode in the URI.
v Filters against .. in the URI after normalization
v Filters against .exe in the URI after normalization
8. Optional: From the Fragmented URI Policy list, select how to handle URI
fragments. A URI fragment is the portion of a URI after the hash (#) symbol.
9. Click Apply to save the changes to the running configuration.
10. Optional: Click Save Config to save the changes to the startup configuration.

Forms-based authentication and authorization

Forms-based authentication lets you use an HTML form to obtain credentials from
users who are attempting to access secured (private) Web pages on an application
server. Typically this information is an account name, a password, or both.
When a user attempts to access a secured Web page, the Web application firewall
redirects the request to a forms-based login page. This page provides fields where
the user can provide credentials.
v If the request passes authentication and authorization, the Web application
firewall sets a cookie in the client browser and forwards the request to the
application server. The application server starts a session. The session uses this
cookie to preserve authentication for all subsequent requests.
v If the request fails authentication, the Web application firewall redirects the user
to an error page.
The provided login page (store:///loginPage.htm) defines the following
JavaScript form:

144

IBM WebSphere DataPower Integration Appliance XI50: Web Application Firewall Developers Guide

<form name="LoginForm" method="post" action="j_security_check">

<input type="text" name="j_username"/>
<input type="password" name="j_password"/>
<input type="submit" name="login" value="Login"/>
<input type="hidden" name="originalUrl"/>
</form>

The significant content of the login form is as follows:

v The user name and password fields (j_username and j_password) are in
accordance with the J2EE specification.
v A hidden redirection URL field (originalUrl) records the URL that the user was
attempting to contact before being redirected to the login form. After
authentication, the user is redirected to this URL.
v An form action (post) that tells the browser what to do when a user clicks
Login. In accordance with the J2EE specification, j_security_check is the
security check.
Note: To work with form-based authentication, this value must be a path
fragment within the URL (j_security_check).

Enabling forms-based authentication and authorization

About this task
Enable form-based authentication and authorization for a Web application firewall
service.

Procedure
1. Define an HTML forms-based authentication policy.
2. Create an AAA policy for secured (private) Web pages and a Web request
profile referencing this AAA policy.
3. Create an AAA policy for unsecured (public) Web pages and a Web request
profile referencing this AAA policy.

Creating an HTML forms login policy

Before you begin
Store the HTML login, logout and error files where you want the appliance to
access them. They can be stored either on the appliance or on the application
server.

About this task

Create an HTML forms login policy that identifies the location of the Web pages
(login, logout, and error) for use by the Web application firewall.

Procedure
1.
2.
3.
4.
5.

Click Objects Web Applications HTML Forms Login Policy.

Click Add.
Enter the name of the policy.
Optional: In the General section, enter the required information.
Optional: In the Security section, override the default security configuration.
By default, Use SSL for login is enabled. the defined port must correspond to
the SSL port for the Web application firewall.
Appendix A. Referenced objects

145

a. Specify whether to use SSL or HTTP to retrieve login information.

v For SSL, set Use SSL for login to on.
v For HTTP, set Use SSL for login to off.
b. When using SSL, enter the SSL port for the Web application firewall
c. Specify whether users must re-authenticate if their session moves to
another appliance.
v For use existing authentication, set Enable Session Migration to on.
v To require re-authentication, set Enable Session Migration to off.
d. When allowing session migration, specify the shared secret. Each appliance
must use the same cryptographic material for the shared secret.
6. Optional: In the Client-side URL fragments section, override the default
fragments.
a. Select the path fragments for the login, logout, and error pages.
b. For the Default URL field, enter the URL of the Web page to display after
a user successfully logs in if the user went directly to the login page.
Otherwise, the user is sent to the secured web page that the user was
attempting to contact before being redirected to the login form.
7. In the Location of HTML pages section, indicate whether the Web pages are
local (or the appliance) or remote (on the application server).
Choice

Notes

Appliance (local)

You can accept the default location of the

Web pages or you can override the default
locations.

Application server (remote)

Maps the Client-side URL fragments to the

application server.

8. Optional: In the Login form properties section, override the HTML form
content for the login page.
9. Optional: In the Timeouts section, modify the default values.
10. Click Apply to save the changes to the running configuration information.
11. Optional: Click Save Config to save the changes to the startup configuration.

What to do next
Create your AAA policies for user authentication and authorization on your
application server.

Creating an AAA policy for secured Web pages

To specify who can access secured (private) Web pages on the application server,
create an AAA policy.

Before you begin

Create an HTML forms login policy.

About this task

Define an AAA policy to specify who can access secured Web pages on the
application server.

146

IBM WebSphere DataPower Integration Appliance XI50: Web Application Firewall Developers Guide

Procedure
1.
2.
3.
4.

Click Object XML Processing AAA Policy.

Click Add.
In the Name field, enter a name of the policy.
Define the identity extraction method.
a. Click the Identity tab.
b. From the Methods list, select HTML Forms-based Login Policy. The pane
refreshes.

c. From the HTML Forms-based Authentication list, select the appropriate

policy.
5. Define the authentication method
a. Click the Authentication tab.
b. From the Method list, select the method to authenticate users. For more
information, refer to the online help.
6. Define the resource extraction method.
a. Click the Resource tab.
b. From the Resource Information list, select URL Sent by client.
7. Define the authorization method.
a. Click the Authorize tab.
b. From the Method list, select Allow any Authenticated.
8. Click Apply to save the changes to the running configuration information.
9. Optional: Click Save Config to save the changes to the startup configuration.

What to do next
Create a Web request profile referencing this AAA policy where the match section
identifies the secure pages. If you have not already done so, create an AAA policy
to specify who can access unsecured (public) Web pages.

Creating an AAA policy for unsecured Web pages

To specify who can access unsecured (public) Web pages including the login,
logout and error pages on the application server, create an AAA policy.

Before you begin

Create an HTML forms login policy.

About this task

Define an AAA policy to specify who can access unsecured Web pages on the
application server.

Procedure
1. Click Object XML Processing AAA Policy.
2. Click Add.
3. In the Name field, enter a name of the policy.
4. Define the identity extraction method.
a. Click the Identity tab.
b. From the Methods list, select HTML Forms-based Login Policy. The pane
refreshes.
Appendix A. Referenced objects

147

c. From the HTML Forms-based Authentication list, select the appropriate

policy.
5. Define the authentication method
a. Click the Authentication tab.
b. From the Method list, select Pass Identity Token to the Authorized Step.
6. Define the resource extraction method.
a. Click the Resource tab.
b. From the Resource Information list, select URL Sent by client.
7. Define the authorization method.
a. Click the Authorize tab.
b. From the Method list, select Always Allow.
8. Click Apply to save the changes to the running configuration information.
9. Click Save Config to save the changes to the startup configuration.

What to do next
Create a Web request profile referencing this AAA policy where the match section
identifies the unsecure pages. If you have not already done so, create an AAA
policy to specify who can access secured (private) Web pages.

Web response profiles

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

Creating Web response profiles

To create a Web Response Profile object:
1. Select Objects Web Applications Web Response Profile.
2. Click Add to display the configuration pane.
3. On the Main tab, define the basic configuration.
4. On the Profile tab, define acceptable content type.
5. On the Code & Versions tab, filter HTTP methods and versions.
6. On the Processing tab, define how to process responses.
7. On the Name Value tab, filter on HTTP headers (names and corresponding
values).
8. On the Threat Protection tab, limit size of responses.
9. Click Apply to save the changes to the running configuration.
10. Optional: Click Save Config to save the changes to the startup configuration.

Main tab
Provide the following inputs:
Name Specify the name of the object.

148

IBM WebSphere DataPower Integration Appliance XI50: Web Application Firewall Developers Guide

Admin State
Retain the default setting. To place the object in an inactive administrative
state, click disabled.
Comments
Specify a descriptive object-specific summary.
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 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.
Retain the default (none) to enforce no error policy. Refer to Creating
Error Policy objects on page 100 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.

Appendix A. Referenced objects

149

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.
Provide the following inputs:
XML Processing
Select how to process responses containing an XML MIME type in the
HTTP header Content-Type field (for example, text/xml).
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 Defining Processing Rule objects on page 120 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

150

IBM WebSphere DataPower Integration Appliance XI50: Web Application Firewall Developers Guide

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 Defining
Processing Rule objects on page 120 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.
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
117 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:

Appendix A. Referenced objects

151

v Basic network configuration, such as load balancing and accessing remote

servers.
v Set manager-associated limits on the parsing of XML documents. By default, the
appliance imposes limits on various characteristics of XML documents. These
limitations provide for increased security and stability to protect against DoS
attacks or runaway data. Parser limits defined by the XML Manager object that
is associated with a service can be overridden by service-specific settings.
v Enable the caching of documents that this XML Manager object obtains. XML
Manager objects obtain documents via HTTP. The number of documents in the
cache depends on the availability of allocated memory.
v Define extension function mapping. An XML Manager object can automatically
map custom style sheet extension functions to DataPower extension functions.
This ability removes the need to alter or rewrite a style sheet for use by the
appliance. The most common example is the node-set() extension function. If a
service uses style sheets that reference the Microsoft node-set, Oracle node-set,
or Salon nodeset XSLT extension functions, you must map these extensions to
their DataPower equivalent. It is possible to map any extension function to a
DataPower extension function.
v Define the caching policy for documents. This policy allows an administrator to
determine how to cache documents. The policy defines the time-to-live, the
priority, and the type.
v Enable schema validation by defining schema-validation rules. These rules apply
to all documents that match predefined criteria. Alternatively, the appliance can
validate documents with a validate action in a processing rule. Do not mix and
match schema validation strategies. Policy-based schema validation is the
preferred strategy.
v Schedule processing rules. Certain applications might require the running of a
scheduled processing rule. Integration with a CA Unicenter Manager is
facilitated by a regularly scheduled processing rule that obtains relationship data
from the Unicenter Manager.

Configure XML Manager objects

The specification of the name completes the required configuration. The remaining
properties modify default values or implement enhanced behavior. For information
about the configuration properties, refer to the online help.
To configure an XML Manager:
1. Select Objects XML Processing XML Manager to display the catalog.
2. Click Add to display the configuration screen.
3. On the Main tab, define the basic configuration.
4. On the XML Parser Limits tab, define the limits to impose when parsing XML
documents.
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.

152

IBM WebSphere DataPower Integration Appliance XI50: Web Application Firewall Developers Guide

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

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

Flushing the document cache

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

Flushing the stylesheet cache

The appliances maintains a cache of style sheets. To flush the cache, click Flush
Stylesheet Cache.
Note: After a change to a Compile Options Policy object, flush the stylesheet
cache. Otherwise, the XML Manger object continues to use the previous
compiled style sheets until they are recompiled.
This function is available from the following screens:
v The configuration screen for an XML Manager object (Objects XML Processing
XML Manager)
v The status screen for the stylesheet cache (Status XML Processing Stylesheet
Cache)

z/OS NSS Client

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

Client ID
System Name
User Name
Password

Based on these properties and the request type, the following actions occur:
DataPower requests a secure connection to the z/OS Communications Server
RACF performs authentication of users
RACF performs authorization to resources
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
v
v
v
v

Appendix A. Referenced objects

153

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

TCP connection retry (interval is 1 minute)

TCP connection in progress
Communication failed
Cannot connect to host

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

Creating the z/OS NSS Client

To configure a z/OS NSS client, use the following procedure:
1. Select OBJECTS z/OS Configurations z/OS NSS Client to display the
catalog.
2. To display the configuration screen, click Add.
3. In the Name field, enter the name for the object.
4. Retain the default setting for Admin State. To place in an inactive
administrative state, click disabled.
5. Optional: In the Comment field, enter a descriptive summary.
6. Specify the IP address or hostname of the NSS server in the Remote Address
field.
7. Specify the port on which the NSS server listens in the Remote Port field.
8. Select an SSL Proxy Profile in the SSL Proxy field to provide a secure
connection to the remote authentication server.
9. Specify the client ID to be used for registration with the NSS server in the
Client ID field.
10. Specify the system name to identify the NSS client to the NSS server in the
System Name field.

154

IBM WebSphere DataPower Integration Appliance XI50: Web Application Firewall Developers Guide

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

Appendix A. Referenced objects

155

156

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

157

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 168.
Note: Refer to List of available variables on page 169 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 5 lists the
names and permission for these variables.
Table 5. 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 6 lists the names and permission for these variables.
Table 6. Names and permissions for general service variables that are available to only
Multi-Protocol Gateway and Web Service Proxy services

158

Variable name

Permission

var://service/mpgw/backend-timeout

Read-write

IBM WebSphere DataPower Integration Appliance XI50: Web Application Firewall Developers Guide

Table 6. 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 7 lists the names and permission for
these variables.
Table 7. 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

159

Load balancer service variables

This section contains information about load balancer 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 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 9 lists the names and permission for these
variables.
Table 9. 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.

160

IBM WebSphere DataPower Integration Appliance XI50: 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 10 lists the names and permission
for these variables.
Table 10. 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

161

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 11 lists the names and permission
for these variables.
Table 11. 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

162

IBM WebSphere DataPower Integration Appliance XI50: 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 12 lists the names and permission for these
variables.
Table 12. 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

163

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 13 lists the names and permission for these variables.
Table 13. 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 14 lists the names and permission
for these variables.
Table 14. Names and permissions for variables that are available for persistent connections

164

Variable name

Permission

var://service/connection/note

Read-write

IBM WebSphere DataPower Integration Appliance XI50: 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 15 lists the names and permission for these variables.
Table 15. 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 16 on page 166 lists the names and
permission for these variables.
Appendix B. Working with variables

165

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

Permission

var://service/protocol-method

Read-write

var://service/URI

Read-write

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

Web Services Management transaction variables

This section contains information about Web Services Management (WSM)
variables in alphabetic order by permission category. Table 17 lists the names and
permission for these variables.
Table 17. 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 18 lists the
names and permission for these variables.
Table 18. Names and permissions for extension variables

166

Variable name

Permission

var://local/_extension/allow-compression

Write-only

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

Write-only

var://local/_extension/header/

Write-only

IBM WebSphere DataPower Integration Appliance XI50: Web Application Firewall Developers Guide

Table 18. Names and permissions for extension variables (continued)

Variable name

Permission

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

Write-only

var://local/_extension/prevent-persistent-connection

Write-only

var://local/_extension/sslprofile

Write only

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

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

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

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

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

AAA, it could be set up as follows to dynamically resolve the value of
*sslprofiletouse:

Appendix B. Working with variables

167

setvar tmpvar2 var://local/_extension/sslprofile

var://context/notepad/sslprofiletouse
results tmpvar2 https://foo.bar.com/foome.asp tmpvar3

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

System variables
This section contains information about system variables in alphabetic order by
permission category. Table 19 lists the names and permission for these variables.
Table 19. 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.

168

IBM WebSphere DataPower Integration Appliance XI50: Web Application Firewall Developers Guide

List of available variables

Table 20 lists the variables that you can define for document processing.
Table 20. 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

169

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

170

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

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

171

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.

172

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

173

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

174

IBM WebSphere DataPower Integration Appliance XI50: Web Application Firewall Developers Guide

Index
Special characters
.. (dot dot) filter
threat protection
Web request profiles 144
... button
list of referenced object 7
referenced object 6
.exe filter
threat protection
Web request profiles 144
.java.policy file 37
[configuration-database] stanza, file
entry 88
[ldap] stanza, ssl-keyfile-pwd entry 88
[manager] stanza, replica entry 88
+ button
list of referenced object 7
referenced object 6

A
AAA
authentication
search parameters 101
search parameters 101
TFIM 89
AAA Info file
Authenticate element 83
Authorize element 84
editor
authenticated identities 84
authorized access to resources
confirmation 87
credentials 84
default credential 84
file information 87
map credentials 86
map resources 86
overview 84
unauthenticated identity 84
MapCredentials element 84
MapResource element 84
overview 83
AAA policy
Web request profile
enabling 145
secured Web pages 146
unsecured Web pages 147
AAA Policy
AAA Info file
Authenticate element 83
Authorize element 84
MapCredentials element 84
MapResource element 84
overview 83
file editor
authenticated identities 84
authorized access to resources
confirmation 87
credentials 84
Copyright IBM Corp. 2002, 2009

87

87

AAA Policy (continued)

file editor (continued)
default credential 84
file information 87
map credentials 86
map resources 86
overview 84
unauthenticated identity 84
LTPA, adding user attributes 82
namespace mappings
XPath bindings 82
object pages
Authenticate 62
Authorize 70
creating 57
Identity 60
LTPA Attributes 81
Main 57
Map Credentials 68
Map Resource 70
Namespace Mapping 80
Resource 69
SAML Attributes 80
Transaction Priority 81
post processing
available activities 77
CICS Transaction Server 79
custom style sheet 77
ICRX token 79
Kerberos AP-REQ 78
LTPA 79
SAML assertion 77
SPNEGO 79
TFIM 79
WS-Security UsernameToken 79
WS-Trust 78
z/OS identity propagation 79
SAML attributes
defining 82
z/OS NSS Client 153
AAAInfo.xsd file 83
Accept-Encoding header, retaining 131
accepted configuration
deployment policy 54
Add button
list of referenced object 7
admin account
exporting configuration data 43
Administration menu 5
administrative states, objects 10
allow compression policy, user
agent 130
AP-REQ message, Kerberos 92
appliance configuration
backing up 43, 44
comparing 52
configuration checkpoints 48
copying
files 47
objects 47
exporting 43

appliance configuration (continued)

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
concept 97
error maps 97
request maps 97
response maps 97
Apply button 8
asynchronous transaction variables
service/transaction-timeout 162
asynchronous transactions variables
listing 162
service/transaction-key 162
service/transaction-name 162
asynchronous variables
service/soap-oneway-mep 162
audit log
location 33
viewing 33
audit: directory 33
Authenticate element, AAA Info file 83
authentication
LDAP 101
search parameters 101
authentication policy
user agent
basic 129
public key 130
SCP protocol 130
SFTP protocol 130
Authorization header, HTTP 129
Authorize element, AAA Info file 84
auto-config.cfg file 8

B
backend-timeout variable 159
body size
threat protection
Web request profiles 144
bold typeface xii
builder
deployment policy 55
buttons
... 6
+ 6
Apply 8
Cancel 8
Delete 9

175

buttons (continued)
Edit 7
Logout 5
Save Config 5, 8
Undo 9
View 7

C
CA Unicenter Manager 151
caches
flushing
document cache 153
stylesheet cache 153
Cancel button 8
cert: directory 33
certificate files
location 33
Certificate objects
export packages 43
certificates
DER 13
exporting 15
generating 14
importing 16
PEM 13
PKCS #12 13
PKCS #8 13
security
location, shared 34
location, Web browsers 34
supported formats 13
uploading 37
checkpoint configuration files
location 33
chkpoints: directory 33
CICS Transaction Server 79
clear pdp cache CLI 96
clear xsl cache CLI 96
Clone link 10
commands
clear pdp cache 96
clear xsl cache 96
web-mgmt 5
compression policy, user agent 130
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 8
backing up
WebGUI 43, 44
backing up application domains 44
comparing
WebGUI 52
configuration checkpoints 48
copying
files 47
objects 47

176

configuration data (continued)

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 8
undoing changes 53
configuration files
exported, location 33
location 33
TAM
ASCII 88
creating 88
modifying 88
obfuscated 88
configuration service variables
listing 159
service/config-param/ 159
service/max-call-depth 159
configuration states, objects 10
Content-Length header 132
Control Panel
File Management 35
Web Application Firewall icon
cookies
Web request profiles 142
count monitors
configuring 99
credentials
identification
configuring 19
creating 19
credentials mapping
LDAP 101
search parameters 101
Crypto Certificate
configuring 17
creating 17
object pages 17
Crypto Firewall Credentials
object pages 19
Crypto Identification Credentials
object pages 19
Crypto Key
configuring 20
creating 20
object pages 20
Crypto Profile
configuring 22
creating 22
object pages 22
Crypto Tools
exporting certificates 15
exporting keys 15
generating certificates 14

Crypto Tools (continued)

generating keys 14
importing certificates 16
importing keys 16
Crypto Validation Credentials
object pages 26
cryptography
shared secrets 24
customer support
contacting 172
obtaining fixes 171
searching knowledge bases

171

29

dashboard 5
DataPower discussion forum x
DataPower product Web site x
default log
location 33
Delete button 9
list of referenced object 7
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 55
DER
certificate format 13
key format 13
developerWorks Web site x
directories
audit: 33
available 33
cert: 33
chkpoints: 33
config: 33
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 10
discussion forum, DataPower x
documentation conventions,
typefaces xii
Domain list 5
down operation state 10
dpcert: directory 33

IBM WebSphere DataPower Integration Appliance XI50: Web Application Firewall Developers Guide

E
Edit button 7
enabled administrative state 10
encoding, chunked content 132
error handling variables
listing 163
service/error-code 163
service/error-ignore 163
service/error-message 163
service/error-protocol-reasonphrase 163
service/error-protocol-response 163
service/error-subcode 163
service/strict-error-mode 164
error maps
application security policy
purpose 97
Error Policy
object pages 100
Export link 9
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() 151
extension variables
listing 166
local/_extension/allowcompression 167
local/_extension/donot-followredirect 167
local/_extension/header/ 167
local/_extension/http-10-only 167
local/_extension/prevent-persistentconnection 167
local/_extension/sslprofile 167
local/_extension/timeout 168
external resources, accessing x

F
file entry, [configuration-database]
stanza 88
File Management utility, launching
file system
See directories
files
.java.policy 37
AAAInfo.xsd 83
auto-config.cfg 8
certificates
location 33
checkpoint configurations
location 33
configurations
location 33
copying 38
remote URL 38
deleting 40

35

files (continued)
editing
during configuration 8
File Management utility 40
exported, location 33
fetching 38
loginPage.htm 144
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 88
modifying configuration 88
obfuscated configuration 88
SSL key 88
SSL stash 88
uploading
JKS 37
remote 38
workstation 36
viewing
during configuration 8
File Management utility 40
filtered configuration
deployment policy 54
Firewall Credentials
configuring 19
creating 19
firmware files
between release levels 43
export packages 43
firmware images
location 33
fixes, obtaining 171
flash drive
See directories
FTP client
command channel
encrypting 133
stopping encryption after
authentication 133
data (ASCII, binary) 133
encrypting file transfers 133
NAT compatibility 133
passive mode 133
sending command to server 133
unique file names (STOU, STOR) 133
user agent 133

G
general variables
listing 158
service/soap-fault-response

158

H
header injection policy, user agent 132
header retention policy, user agent 131

HTML forms login policy

AAA policy
secured Web pages 146
unsecured Web pages 147
creating 145
enabling 145
loginPage.htm 144
purpose 144
HTTP 1.0 restriction policy, user
agent 131
HTTP 1.1
chunked contents 132
Content-Length header 132
HTTP headers
Accept-Encoding, retaining 131
Authorization 129
Content-Length 132
MQMD, retaining 131
Range, retaining 131
request-header 127
SoapAction 129
TE, retaining 131
HTTP proxy policy
securing with SSL proxy policy 128
user agent 128

I
IBM Tivoli Access Manager
See TAM
IBM Tivoli Federated Identity Manager
See TFIM
icons
Web Application Firewall 29
ICRX token 79
Identification Credentials
configuring 19
creating 19
image: directory 33
Import Package
creating 42
Include Configuration File
creating 41
object pages 41
installation images
See firmware images
intellectual property 173
italics typeface xii

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
Index

177

JKS (continued)
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 93
KDC 92
keytab 92
principal 92
Kerberos AP-REQ
post processing, AAA 78
Kerberos KDC server
configuring 93
creating 93
object pages 93
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 13
keys
DER 13
exporting 15
generating 14
importing 16
PEM 13
PKCS #12 13
PKCS #7 13
supported formats 13
knowledge bases
searching 171

L
LDAP
authentication
search parameters 101
credentials mapping
search parameters 101
search parameters 101
licensing
sending inquiries 173
links
Clone 10
Export 9
Show Probe 11
View Logs 9
View Status 10
load balancer group
adding members 110
basic configuration 109

178

load balancer group (continued)

creating 102, 109
health
convalescent (down) 107
healthy (up) 106
quarantined (softdown) 107
health checks
enabling 111
overriding port 109
health of members 106
members
assigning weight 113
disabling members 113
server state 102
load balancer service variables
listing 160
service/lbhealth/ 160
local: directory 33
local/_extension/allow-compression
variable 167
local/_extension/donot-follow-redirect
variable 167
local/_extension/header/ variable 167
local/_extension/http-10-only
variable 167
local/_extension/prevent-persistentconnection variable 167
local/_extension/sslprofile variable 167
local/_extension/timeout variable 168
log files
export packages 43
log/soapversion variable 161
Logout button 5
logs
appliance-wide
location 33
audit
location 33
viewing 33
default
location 33
viewing configuration-specific logs 9
viewing from catalog 9
viewing from configuration pane 9
logstore: directory 33
logtemp: directory 33
LTPA
adding user attributes, AAA
Policy 82
post processing, AAA 79

M
MapCredentials element, AAA Info
file 84
MapResource element, AAA Info file
Matching Rule
object pages 117
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 10

84

monitors
count monitors
configuring 99
message monitors
count monitors 99
monospaced typeface xii
MQ Host variables
listing 160
service/correlation-identifier 161
service/expiry 161
service/format 161
service/message-identifier 161
service/message-type 161
service/mq-ccsi 160
service/mqmd-reply-to-q 160
service/mqmd-reply-to-qm 160
service/persistence 161
service/priority 161
service/reply-to-q 161
service/reply-to-qm 161
service/report 161
MQ Proxy variables
listing 160
service/correlation-identifier 161
service/expiry 161
service/format 161
service/message-identifier 161
service/message-type 161
service/mq-ccsi 160
service/mqmd-reply-to-q 160
service/mqmd-reply-to-qm 160
service/persistence 161
service/priority 161
service/reply-to-q 161
service/reply-to-qm 161
service/report 161
MQMD header, retaining 131
Multi-Protocol Gateway
service variables
backend-timeout 159
service/reply-to-q 159
service/reply-to-qm 159
skip-backside 159
multistep variables
log/soapversion 161

N
Name-Value Profile
object pages
Main 117
Validation List 119
name-value profiles
Web request profiles
HTTP headers, filtering 141
query strings, filtering 141
URL-encoded content,
filtering 141
namespace mappings, AAA Policy 82
NAT
FTP clients 133
navigation
Administration menu 5
Network menu 5
Objects menu 5
Services menu 5
Status menu 5

IBM WebSphere DataPower Integration Appliance XI50: Web Application Firewall Developers Guide

Network Address Translation

See NAT
Network menu 5
New configuration state 10
node-set() extension function 151
notices 173

O
object pages
AAA Policy
Authenticate 62
Authorize 70
Identity 60
LTPA Attributes 81
Main 57
Map Credentials 68
Map Resource 70
Namespace Mapping 80
Resource 69
SAML Attributes 80
Transaction Priority 81
Crypto Certificate 17
Crypto Firewall Credentials 19
Crypto Identification Credentials 19
Crypto Key 20
Crypto Profile 22
Crypto Validation Credentials 26
Deployment Policy 54
Error Policy 100
Include Configuration File 41
Kerberos KDC server 93
Kerberos Keytab File 94
Matching Rule 117
Name-Value Profile
Main 117
Validation List 119
Processing Rule 120
Rate Limiter 121
Session Management Policy 122
SSL Proxy Profile 24
TAM 89
TFIM 90
URL Rewrite Policy
Main 123
URL Rewrite Rule 123
Web Application Firewall
HTTP Options 137
Main 134
Proxy Settings 136
Source Addresses 138
Web Response Profile
Codes & Versions 150
Main 148
Name Value 151
Processing 150
Profile 149
Threat Protection 151
XACML PDP 95
XML Manager 151
objects
administrative state 10
configuration state 10
not in export packages
Certificate 43
Key 43
User 43

objects (continued)
operational state 10
referenced
... button 6
+ button 6
creating 6
modifying 6
selecting 6
status 10
TFIM 89
Objects menu 5
operational states, objects

10

P
patents 173
PEM
certificate format 13
key format 13
persistent connections variables
listing 164
service/connection/note 165
PKCS #12
certificate format 13
key format 13
PKCS #7
certificate format 13
PKCS #8
key format 13
Policy Decision Point
See XACML PDP
post processing, AAA
available activities 77
CICS Transaction Server 79
custom style sheet 77
ICRX token 79
Kerberos AP-REQ 78
LTPA 79
SAML assertion 77
SPNEGO 79
TFIM 79
WS-Security UsernameToken 79
WS-Trust 78
z/OS identity propagation 79
principal, Kerberos 92
private key files
location 33
private keys
uploading 37
Processing Rule
object pages 120
product documentation Web site x
product Web site, DataPower x
pubcert: directory 34

R
Range header, retaining
Rate Limiter
object pages 121
Redbooks Web site x
referenced objects
... button 6
+ button 6
creating 6
modifying 6

131

referenced objects (continued)

selecting 6
referenced objects, lists
... button 7
+ button 7
Add button 7
adding 7
creating 7
Delete button 7
deleting 7
modifying 7
selecting 7
replica entry, [manager] stanza 88
request maps
application security policy
purpose 97
request-header, HTTP 127
response maps
application security policy
purpose 97
restriction policy for HTTP 1.0, user
agent 131
RFC 2616 132

S
SAML assertion
post processing, AAA 77
SAML attributes
defining, AAA Policy 82
Save Config button 5, 8
Saved configuration state 10
scenarios
Web Application Firewall
benefits management site 2
college enrollment form 1
trading site 2
schemas
location 34
SCP protocol
authentication policy, user agent 130
public keys 130
SDK (j2sdk1.4.2) 37
search parameters, LDAP 101
security certificates
shared
location 34
Web browsers
location 34
SecurityContextToken, WS-Trust
post processing, AAA 78
server pool
See load balancer group
server state
load balancer group 102
service variables
listing 158
types 158
service/append-request-header/
variable 164
service/append-response-header/
variable 164
service/config-param/ variable 159
service/connection/note variable 165
service/correlation-identifier
variable 161
service/error-code variable 163
Index

179

service/error-ignore variable 163

service/error-message variable 163
service/error-protocol-reason-phrase
variable 163
service/error-protocol-response
variable 163
service/error-subcode variable 163
service/expiry variable 161
service/format variable 161
service/lbhealth/ variable 160
service/max-call-depth variable 159
service/message-identifier variable 161
service/message-type variable 161
service/mq-ccsi variable 160
service/mqmd-reply-to-q variable 160
service/mqmd-reply-to-qm variable 160
service/persistence variable 161
service/priority variable 161
service/protocol-method variable 166
service/reply-to-q variable 159, 161
service/reply-to-qm variable 159, 161
service/report variable 161
service/routing-url variable 165
service/routing-url-sslprofile
variable 165
service/set-request-header/ variable 164
service/set-response-header/
variable 164
service/soap-fault-response variable 158
service/soap-oneway-mep variable 162
service/strict-error-mode variable 164
service/transaction-key variable 162
service/transaction-name variable 162
service/transaction-timeout variable 162
service/URI variable 166
service/wsa/genpattern variable 166
service/wsa/timeout variable 166
service/wsm/wsdl-error variable 166
service/wsm/wsdl-warning
variable 166
Services menu 5
Session Management Policy
object pages 122
SFTP protocol
authentication policy, user agent 130
public keys 130
Shared Secret Key
configuring 24
creating 24
shared secrets 24
sharedcert: directory 34
Show Probe link 11
skip-backside variable 159
SoapAction header 129
SPNEGO
post processing, AAA 79
SQL injection filter
threat protection
Web request profiles 144
SSL
client proxy, creating 24
forward proxy, creating 24
reverse, proxy, creating 25
server proxy, creating 25
two-way proxy, creating 25
SSL authentication 22
SSL proxy policy, user agent 128

180

SSL Proxy Profile

creating
client proxy 24
forward proxy 24
reverse proxy 25
server proxy 25
two-way proxy 25
object pages 24
ssl-keyfile-pwd entry, [ldap] stanza 88
Status menu 5
store: directory 34
style sheets
flushing the cache 153
location 34
subdirectories
creating 35
deleting 36
SunJCE
JCEKS 37
support
See customer support
system variables
listing 168
system/map/debug 168
system/tasktemplates/debug 168
system/map/debug variable 168
system/tasktemplates/debug
variable 168

T
TAM
ASCII configuration file 88
authorization server replicas 89
configuration, general 87
configuring TAM objects 89
creating configuration files 88
creating TAM objects 89
licensing 87
modifying configuration files 88
obfuscated configuration file 88
object pages 89
refreshing certificates 89
security 88
SSL key file 88
SSL stash file 88
tasktemplates: directory 35
TE header, retaining 131
temporary: directory 35
TFIM
AAA 89
object 89
object pages 90
post processing, AAA 79
TFIM endpoint
WS-Trust messages 90
threat protection
Web request profiles 144
Tivoli Access Manager
See TAM
trademarks 173
transaction headers variables
listing 164
service/append-request-header/ 164
service/append-response-header/
164
service/set-request-header/ 164

transaction headers variables (continued)

service/set-response-header/ 164
transaction routing variables
listing 165
service/routing-url 165
service/routing-url-sslprofile 165
transaction URL variables
listing 165
service/protocol-method 166
service/URI 166
transaction variables
listing 162
types 162
typeface conventions xii

U
Undo button 9
Unicode filter
threat protection
Web request profiles 144
up operational state 10
URI fragments
threat protection
Web request profiles 144
URI length
threat protection
Web request profiles 144
URL Rewrite Policy
object pages
Main 123
URL Rewrite Rule 123
User Agent
creating 127
default configuration 126
modifying basic configuation 127
overview 126
policies
allow-compression policy 130
basic authentication 126, 129
chunked upload 132
chunked uploads, HTTP 1.1 126
compression 126
compression policy 130
FTP client 126, 133
header injection 126, 132
header retention 126, 131
HTTP 1.0 restriction policy 131
HTTP proxy 126
HTTP proxy policy 128
public key authentication 126, 130
restriction, HTTP 1.0 126
SOAP action 129
SOAPAction 126
SSL proxy 126
SSL proxy policy 128
User objects
export packages 43
UsernameToken
post processing, AAA 79
utilities
keytool 37

IBM WebSphere DataPower Integration Appliance XI50: Web Application Firewall Developers Guide

V
Validation Credentials
creating
non expiring, non-passwordprotected certificates 26
select certificates 27
types of lists 26
variables
asynchronous
service/soap-oneway-mep 162
asynchronous transactions
listing 162
service/transaction-key 162
service/transaction-name 162
service/transaction-timeout 162
configuration service
listing 159
service/config-param/ 159
service/max-call-depth 159
error handling
listing 163
service/error-code 163
service/error-ignore 163
service/error-message 163
service/error-protocol-reasonphrase 163
service/error-protocolresponse 163
service/error-subcode 163
service/strict-error-mode 164
extension
listing 166
local/_extension/allowcompression 167
local/_extension/donot-followredirect 167
local/_extension/header/ 167
local/_extension/http-10-only 167
local/_extension/preventpersistent-connection 167
local/_extension/sslprofile 167
local/_extension/timeout 168
general
listing 158
service/soap-fault-response 158
list, all available 169
load balancer service
listing 160
service/lbhealth/ 160
MQ Host
listing 160
service/correlation-identifier 161
service/expiry 161
service/format 161
service/message-identifier 161
service/message-type 161
service/mq-ccsi 160
service/mqmd-reply-to-q 160
service/mqmd-reply-to-qm 160
service/persistence 161
service/priority 161
service/reply-to-q 161
service/reply-to-qm 161
service/report 161
MQ Proxy
listing 160
service/correlation-identifier 161

variables (continued)
MQ Proxy (continued)
service/expiry 161
service/format 161
service/message-identifier 161
service/message-type 161
service/mq-ccsi 160
service/mqmd-reply-to-q 160
service/mqmd-reply-to-qm 160
service/persistence 161
service/priority 161
service/reply-to-q 161
service/reply-to-qm 161
service/report 161
Multi-Protocol Gateway
backend-timeout 159
service/reply-to-q 159
service/reply-to-qm 159
skip-backside 159
multistep
log/soapversion 161
persistent connections
listing 164
service/connection/note 165
service
listing 158
type 158
system
listing 168
system/map/debug 168
system/tasktemplates/debug 168
transaction
listing 162
type 162
transaction headers
listing 164
service/append-request-header/
164
service/append-response-header/
164
service/set-request-header/ 164
service/set-response-header/ 164
transaction routing
listing 165
service/routing-url 165
service/routing-url-sslprofile 165
transaction URL
listing 165
service/protocol-method 166
service/URI 166
types 157
using 157
Web Service Proxy
backend-timeout 159
service/reply-to-q 159
service/reply-to-qm 159
skip-backside 159
WSM
listing 166
service/wsa/genpattern 166
service/wsa/timeout 166
service/wsm/wsdl-error 166
service/wsm/wsdl-warning 166
View button 7
View Logs link 9
View Status link 10

W
Web Application Firewall
configuring 29
Control Panel icon 29
enabling secured communication 30
general configuration 29
high-level configuration 29
object pages
HTTP Options 137
Main 134
Proxy Settings 136
Source Addresses 138
scenarios
benefits management site 2
college enrollment form 1
trading site 2
Web Management Interface 5
Web request profiles
AAA policy
enabling 145
secured Web pages 146
unsecured Web pages 147
basic configuration 139
cookies 142
creating 139
description 139
HTTP headers, filtering 141
HTTP methods 141
HTTP versions 141
modifying profile 140
multipart forms submission 143
processing rules 141
query strings, filtering 141
request processing 141
threat protection 144
URL-encoded content, filtering 141
Web Response Profile
creating 148
object pages
Codes & Versions 150
Main 148
Name Value 151
Processing 150
Profile 149
Threat Protection 151
overview 148
Web Service Proxy
service variables
backend-timeout 159
service/reply-to-q 159
service/reply-to-qm 159
skip-backside 159
Web sites
DataPower product x
developerWorks x
discussion forum x
product documentation x
Redbooks x
web-mgmt command 5
WebGUI
accessing 5
Administration menu 5
applying configuration changes 8
canceling changes 8
cloning services 10
common tasks 8
dashboard 5
Index

181

WebGUI (continued)
deleting objects 9
Domain list 5
exporting objects 9
logging in 5
Logout button 5
Network menu 5
Objects menu 5
resetting configuration 9
reverting changes 9
Save Config button 5
saving configuration changes 8
Services menu 5
Status menu 5
viewing configuration-specific logs
viewing object status 10
viewing probe data 11
Welcome screen 5
Welcome screen 5
workstation
uploading files 36
WS-Security Management
See WSSM
WS-Trust
post processing, AAA 78
WS-Trust messages
TFIM endpoint 90
WSM variables
listing 166
service/wsa/genpattern 166
service/wsa/timeout 166
service/wsm/wsdl-error 166
service/wsm/wsdl-warning 166

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

Z
z/OS identity propagation
z/OS NSS Client
creating 154
overview 153

182

79

IBM WebSphere DataPower Integration Appliance XI50: Web Application Firewall Developers Guide




Printed in USA