WebSphere DataPower SOA Appliances® Version 3.7.3 Web Application Firewall Developers Guide WebSphere DataPower SOA Appliances ® Version 3.7.3 Web Application Firewall Developers Guide . US Government Users Restricted Rights – Use. 2009. release 7. read the information in “Notices and trademarks” on page 163. modification 3 of IBM WebSphere DataPower SOA Appliances and to all subsequent releases and modifications until otherwise indicated in new editions. © Copyright International Business Machines Corporation 2002.Note Before using this information and the product it supports. First Edition (May 2009) This edition applies to version 3. duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp. . . Creating key-certificate pairs . . . . . . 9 . . . . . . . v How this document is organized . . . . . . . . Importing keys and certificates . . . . . Cloning services . . . . . Copying or moving select objects . . . Scenario two: Benefits management site . . . . . Chapter 2. . . . . . . . Viewing object-specific logs . . . . . 20 . . . . . . . . . . . . . . . . . . . . . . . . . Creating a forward (or client) proxy . . Error Maps . . . . . . . . . . . . . . . . . . Scenario one: College enrollment form . . . . . . . . . . . . . Editing files . . . . 16 . Accessing probe captures . . . . Moving files . . . . . . . Granting permissions . . . . . . Deleting files . . . . . . . . . . . . . . . . . . . 21 Chapter 3. . . . . . . . vii Reference documentation. . . . . Backing up domains . . . . Viewing files . . . . Timeout/Protocol . 18 . . . . . Editing local files . . . Working with objects . Creating for select certificates . . . . . Configuring an Application Security Policy . . . . . . . . . . . . . . 33 Directories on the appliance . . . . . . . . . . . . Defining Identification Credentials objects . . . Backing up and exporting configuration data . . . . . 19 . . . . . . . . . . . 13 . WebGUI basics . . . . . . 21 . . . . . . . . . . . Saving configuration checkpoints . . . . . . . . . . . . . . . . . . . . . . 48 49 49 50 iii . . . . . Uploading files from the workstation . . . . . . . . . . . . . . . . . . . . Managing the configuration of the appliance . . . . . 14 . . . . . . 9 . Securing communication Supported cryptographic formats . . Defining number configuration checkpoints to allow . . . . . . . . . 41 42 43 44 44 45 47 48 . . vii Integration documentation . . . . . . . . . . . . Creating a reverse (or server) proxy . . . viii Supplemental documentation . . Managing files. . . . . . . . . . . . . . . . . . Working with lists of referenced objects . . . . . General configuration . . . . . Defining SSL Proxy Profile objects . . . v Publications . v Who should read this document . . . . . . . . . . . . 9 . . Displaying directory contents . . . . . . . . . . . Working with keys and certificates . . . . . Viewing object status . . . . . . . . . . Copying files . . . . 25 Scenarios . . . . . . . . . . Common WebGUI conventions . . . Configuring Web Application Firewall services . . . . . vii Problem determination documentation . Launching the File Management utility . . . . . viii File naming guidelines . . . . . viii Object naming guidelines . . Welcome screen . . . . . . ix Chapter 1. . . . Applying and saving changes . . . . . . . . . . Generating keys and certificates . . . . . 9 . . . . . . . . . . .Contents Preface . . . vi Development documentation . . . . . . . 25 25 26 26 27 27 29 30 30 30 31 31 Chapter 4. . . . Request Maps . . . . . . . Common WebGUI tasks . 41 Creating Include Configuration File objects . . . . . . . . . . . . . vi Installation and upgrade documentation . . . Rolling back to a configuration checkpoint . . . . 2002. . . . Exporting objects . . . Refreshing directory contents . . . . . . . . Defining Firewall Credentials objects . . . Creating a two-way proxy . . Renaming files . . . . . . . non-passwordprotected certificates . . . . 19 . . . . . . . 11 . . . . . . . . . . . . . . . . . . . . . . . Managing configuration checkpoints . . . . . . . . . 17 . . . . . . . 19 . . . . . . . . . . . . Canceling changes . . . . . . . . . . . Response Maps . . . . . . . . . Resetting objects . . . Exporting select objects . . . . . . . . . . . . . . . . . . Creating Import Configuration File objects . . . . . . . . . . Scenario three: Trading site . Backing up the entire appliance . . . . . . . . . . . . . vi Administration documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 . . . . . . Configuring a Web Application Firewall . . . . Deleting a directory . . . . . . . . . . . . . . 21 Creating for non-expiring. . . . . Defining Shared Secret Key objects . . . . . Defining Certificate objects . . . . Listing configuration checkpoints . 2009 . . . . . . . Exporting keys and certificates . . Deleting objects . . . . Working with Java Key Stores . . Accessing the WebGUI . . . . . . . . . General configuration . . . . ix Typeface conventions . . . . . . . . Uploading a file from a Java Key Store Fetching files . . . Defining Profile objects . . Working with Validation Credentials objects © Copyright IBM Corp. . . . . . . . . . . . . . . . . . . . Viewing and editing local files during configuration Viewing local files . . 10 . 1 1 1 1 2 2 3 3 4 4 4 4 4 5 5 5 5 6 6 7 . . . . . . . . . . . Defining Key objects . . . . Required software . . 1 Objects on the appliance . Creating a subdirectory . . . . . . . Working with referenced objects . . . . . . Types of key stores . . . . . . . . . . . . . . . 15 . . . . . . . . . . 33 35 35 35 36 36 36 37 37 37 37 37 38 38 39 39 40 40 40 Chapter 5. 81 . . . . . . . . Adding LTPA user attributes . . . . . . . . . . . . . . 122 123 124 127 129 130 131 132 133 134 134 135 136 137 138 139 140 140 140 141 142 142 143 143 143 144 145 147 Service variables . . . Namespace Mapping tab . . . . . . . . . . . . . . . . . . . . . . 101 . . . Multistep variables . . Response Maps tab . . . . . 118 . . . . . . . . . . Configuring Load Balancer Group objects . . Basic HTTP Authentication . iv . . . . . . 102 . . . . . . . . Threat Protection tab . . . . . . . . . . . . 97 . Transaction Priority tab . . . . . . 80 . . . . . . . . . . . . . . URL Rewrite Policy . . . . . . . . Processing tab . 99 . . . . . . . . . . . . . Using the deployment policy builder . . . . . . . Name Value tab . . . . . . . . . . Working with variables . . . . . . . . . . . . . . . . . . . . z/OS NSS Client . . . . Creating the z/OS NSS Client . . . Transaction variables . Application Security Policy . Proxy Policy . . . . . . . . . . . Load balancer service variables . . . . Defining an LDAP Search Parameters object . . . . . . . . . . 98 . . . . . . . . . . . . . . . . . . . Configuration services service variables . . . 163 Index . . . . . . . . . . . System variables . . . . . . . . . . . . . . . Persistent connection transaction variables. . . . . . . 92 . 88 . . . . . . . . Main tab . URL Rewrite Rule tab . . . . . . . . . . 62 . . . . Error Maps tab . . . . . . . 162 Notices and trademarks . . . Reverting changes . . . . Allow Compression Policy . . . . . . . . . . . . . . . 102 . 90 . . . . . . . . . General service variables . . . . . . . . 113 . . . . . . . . . . . . . . . . . . . . . . Creating a Deployment Policy object . . Comparing configurations . . . . . . . . . . Map Credentials tab . . . . . . . . Legacy MQ-specific service variables . . . Specifying the matching statement. . . . .Deleting configuration checkpoints . . . . . . . . Importing configuration data . . . List of available variables . Name-Value Profile . IBM Tivoli Federated Identity Manager . . . . . . 70 . Configuring deployment policies . . . . . . . . . . 106 . . . . . Contacting IBM Support. . . . . . . . 120 . . . . . . . Identity tab . . . . . . . . . . . . . . . . . . . . Cookie tab . . 118 . Health of member servers . . . . . . . Methods & Versions tab . . . . . . . . . 161 . . . . . . . Web Request Profile . 120 . . . Request Maps tab . . . . . . . . . . . . . . . . . . . . Setting the health state with a variable . . LTPA Attributes tab. . . . . Web Services Management transaction variables Extension variables . . 82 . . . . . . . Rate Limiter . . . . . . . 50 50 52 52 53 53 54 54 55 56 Appendix A. Asynchronous transaction variables . Configure XML Manager objects Flushing the document cache . . . . . . Load Balancer Group . . . . . Matching Rule . . . . . . . . . 71 . . . . . . . . 121 . . . . . . .0 Policy . . . 161 Searching knowledge bases . . 82 . . Restrict to HTTP 1. . . . 112 . 82 . . . . . . . 163 Trademarks . . Headers transaction variables . . . . 99 . . . Count Monitor . SOAP Action Policy . . . . . . . . . . . . . . . . . . . . . 83 . . . . . . . . . . . FTP Client Policies . . . . . Public Key Authentication Policy . . . HTTP Options tab . . . . . . Multipart Form tab . . Error Policy . . . . . Working with Kerberos objects . . Setting namespace mappings (XPath bindings) Defining SAML attributes . . . . . Threat Protection tab . . . . . . . . . . . . . . . . 161 . . . . . 110 . Authorize tab. . . . . . . . . . . . . XACML Policy Decision Point . . . . . . . . 57 . . Flushing the stylesheet cache . . . . . . Using an AAA Info file . 81 . . . Chunked Uploads Policy . . . . . . XML Manager . . Web Response Profile. . . . . . . . . . . Profile tab . . . 111 . . 114 . . Reading the change report . . Processing Rule. . 117 . . . . . . . . . . . Source Addresses tab . . . 77 . . . User Agent . URL-based transaction variables . . Proxy Settings tab . . . . . . . . . . Authenticate tab . . Map Resource tab . . . . . . Validation List tab . . Getting help and technical assistance . 101 . . Codes & Versions tab. . . . . 114 . . . Post Processing tab . . . . 108 . . 57 AAA Policy . . . . . . Error handling transaction variables . . . . . . . . . . . . . . . . . . . SAML Attributes tab . . . . . . . . . . . . . Getting a fix . . . . Session Management Policy . . . . . . . . . . Processing tab . . Appendix B. . . Routing transaction variables . . . . . . IBM Tivoli Access Manager . . . . . . . . Multi-Protocol Gateway and Web Service Proxy service variables . . . . . . . . 95 . . . . . Resource tab . . . . . . . 60 . . . . 99 . 100 . . . . . . Name Value tab . . . . . . . . . . . . . . . Web Application Firewall . SSL Proxy Profile . . . . . 83 . . . . . . . . . 148 148 148 149 150 150 151 152 152 153 154 154 155 155 156 156 158 159 Appendix C. . . . . . 122 Inject Header Policy . . . 69 . . . 119 . . . . . . . . . . . . . . Profile tab . . . . . . . 68 . . . . . . . . . . . Referenced objects. . . . . . . . . . . . . . . . . 57 . . . . . . . . . . . . . . . . . . . . . . . . . . 98 . . . Managing changes in configuration data. . . 165 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide . . . . . . . Preface IBM® WebSphere® DataPower® SOA Appliances are purpose-built.” on page 1 Provides basic informations about using the DataPower graphical interface. and certificate authorities. depending on the model type. v Chapter 3.” on page 33 Provides information about managing files on the appliance.” on page 25 Provide detailed information about developing Web Application Firewall services on a DataPower appliance. “Configuring Web Application Firewall services. “WebGUI basics. key exchange (public and private).” on page 41 Provide information about managing the configuration of application domains and importing and exporting configurations. and accelerate your XML and Web Services deployments while extending your SOA infrastructure. v Chapter 2. v Chapter 4. “Referenced objects. 2002. “Managing the configuration of the appliance. v Appendix A. 2009 v . Developers should have the following knowledge: v Network architecture and concepts v Internet protocols. and networking infrastructure investments. digital signatures. objects. and associated referenced objects on the DataPower appliance. cryptographic algorithms. which is referred to as the WebGUI. v Chapter 5. security. “Managing files. 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. easy-to-deploy network appliances that simplify. help secure. The appliance provide these capabilities with a combination of utilities and objects.” on page 9 Provide information about securing communication to and from the DataPower appliance.” on page 57 © Copyright IBM Corp. as well as information about performing common tasks in the WebGUI. including HTTP. How this document is organized This document is organized across the following broad concepts: v Chapter 1. “Securing communication. pragmatic approach to harness the power of SOA while simultaneously enabling you to leverage the value of your existing application. These appliances offer an innovative. Who should read this document This document is intended for developers who manage the configuration of Web Application Firewall services. 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. and placing the appliance in operation. “Getting help and technical assistance” Provides details about contacting IBM Support. creating a startup configuration script. Administration documentation v IBM WebSphere DataPower SOA Appliances: Appliance Overview Provides an introduction and understanding of the IBM Websphere DataPower SOA appliances. v IBM WebSphere DataPower SOA Appliances: Hardware Security Module Guide A user guide for using a Hardware Security Module (HSM) installed in the appliance.” on page 147 Provides information about using variables in document processing. v IBM WebSphere DataPower SOA Appliances: Upgrade and Rollback Guide: Generation 2 Firmware Provides instructions for upgrading Generation 2 firmware and for rolling back firmware upgrades. Publications The IBM WebSphere DataPower library is organized into the following categories: v “Installation and upgrade documentation” v “Administration documentation” v “Development documentation” on page vii v v v v “Reference documentation” on page vii “Integration documentation” on page vii “Problem determination documentation” on page viii “Supplemental documentation” on page viii Installation and upgrade documentation v IBM WebSphere DataPower SOA Appliances: 9003: Installation Guide Provides instructions for installing and powering up the Type 7993 (9003) appliance. vi IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide . ordering consumable replacement parts.Provides detailed information about configuring objects that are referenced while developing services on a DataPower appliance. v IBM WebSphere DataPower SOA Appliances: Administrators Guide Provides instructions for using the DataPower GUI for managing user access. network access. 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. “Working with variables. and replacing parts. appliance configuration and system configuration of the appliance. v IBM WebSphere DataPower SOA Appliances: Type 9235: Installation Guide Provides instructions for installing and powering up the Type 9235 appliance. v Appendix B. v Appendix C. creating a startup configuration script. Development documentation v IBM WebSphere DataPower SOA Appliances: XSL Accelerator Developers Guide Provides instructions for using the WebGUI to configure XSL Proxy and XSL Co-Processor services. v IBM WebSphere DataPower SOA Appliances: Low Latency Messaging Developers Guide Provides instructions for using the WebGUI to configure a DataPower appliance for low latency messaging. – IBM WebSphere DataPower XML Accelerator XA35: Command Reference – IBM WebSphere DataPower XML Security Gateway XS40: Command Reference – IBM WebSphere DataPower XML Integration Appliance XI50: Command Reference – IBM WebSphere DataPower B2B Appliance XB60: Command Reference – IBM WebSphere DataPower Low Latency Messaging Appliance XM70: Command Reference v IBM WebSphere DataPower SOA Appliances: Extension Elements and Functions Catalog Provides programming information about the usage of DataPower XSLT extension elements and extension functions. v IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide Provides instructions for using the WebGUI to configure Multiple-Protocol Gateway services. v IBM WebSphere DataPower SOA Appliances: Web Service Proxy Developers Guide Provides instructions for using the WebGUI to configure Web Service Proxy services. v IBM WebSphere DataPower SOA Appliances: B2B Gateway Developers Guide Provides instructions for using the WebGUI to configure B2B Gateway services. Each document provides an alphabetical listing of all commands with syntactical and functional descriptions. Integration documentation The following documents are available for managing the integration of related products that can be associated with the DataPower appliance: v Integrating with ITCAM Provides concepts for integrating the DataPower appliance with IBM Tivoli Composite Application Management for SOA. v IBM WebSphere DataPower SOA Appliances: XML Firewall Developers Guide Provides instructions for using the WebGUI to configure XML Firewall services. The documentation is specific to each of the following products. Reference documentation v Product-specific documentation for using commands from the command line. v IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide Provides instructions for using the WebGUI to configure Web Application Firewall services. v IBM WebSphere DataPower SOA Appliances: Integrating with WebSphere Transformation Extender Preface vii . and temporary:. If the directory (or domain) supports subdirectories. v IBM WebSphere DataPower SOA Appliances: Integrating with WebSphere MQ Explains the concepts and common use patterns for connecting DataPower services to WebSphere MQ systems. When you create a domain. store:. The base file is the part after the name of the DataPower directory. the path to the file can have a length of 4000 characters. its name is the base file name in several DataPower directories when viewed from the default domain. v Configuring the DoD PKI Provides conceptual information about and procedures for configuring the DataPower appliance with Department of Defense Public Key Infrastructure. File naming guidelines The maximum length for a file name can be approximately 4128 characters. The name of the base file can be up to 128 characters in length. Examples of directories are local:. Supplemental documentation v Understanding Web Services Policy Provides conceptual information about how the DataPower appliance can use Web Services Policy (WS-Policy). v Securing the Last Mile Provides conceptual information about and procedures for understanding the DataPower appliance while securing the last mile. Problem determination documentation v IBM WebSphere DataPower SOA Appliances: Problem Determination Guide Provides troubleshooting and debugging tools. v Understanding LTPA Provides conceptual information about how the DataPower appliance can use Lightweight Third Party Authentication. v Understanding WS-Addressing Provides conceptual information about how the DataPower appliance can use WS-Addressing. The following characters are valid in directory and file names: v a through z v A through Z v 0 through 9 v _ (underscore) viii IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide . v Optimizing through Streaming Provides conceptual information about and procedures for optimizing the DataPower appliance through streaming. v Understanding SPNEGO Provides conceptual information about how the DataPower appliance can use SPNEGO.Provides concepts for integrating the DataPower appliance with WebSphere Transformer Extender. Object naming guidelines The object name must be unique in the object namespace. (period) Note: Names cannot contain two consecutive periods (. 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 . Preface ix .. and GUI controls. Typeface conventions The following typeface conventions are used in the documentation: bold Identifies commands.. programming keywords.v .). italics Identifies words and phrases used for emphasis and user-supplied variables. (period) Note: Names cannot contain two consecutive periods (. monospaced Identifies user-supplied input or computer output.(dash) v .(dash) v .). x IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide . The flexibility in configuration and association of referenced object allow you to meet your business-processing criteria and security requirements. the Web Management Interface must be configured. From the Domain list. 4. complex and highly detailed objects. The address uses the HTTPS protocol and has the https://address:port format. 2. Object view Working in the object view allows expert-level users to build specific. © Copyright IBM Corp. 2009 1 . use the following procedure: 1. During configuration. Working with objects When configuring services on the appliance. Click Login. the WebGUI displays its Welcome screen. select the domain to which to log in. To access the WebGUI. WebGUI basics The WebGUI is the primary interface for managing the appliance itself and for configuring objects. the configuration of a service references an instance of the XML Manager object that references an instance of the User Agent object. generic objects.Chapter 1. the WebGUI provides an object view and a service view. This interface was defined during the initial firmware setup (during appliance installation) or afterward with the web-mgmt command. specify an account name and password. 2002. the WebGUI displays the Control Panel. Direct your browser to the WebGUI login screen. reference another object. An object is any entity that you configure on the appliance. You can use either view to create or edit the service. Welcome screen After successfully logging in. Service view Working in the service view allows less-than-expert level users to build basic. Accessing the WebGUI To use the WebGUI. Objects on the appliance Objects that can be configured on the appliance range from simple to complex. an object can reference another object that can. 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. After verifying credentials. For example. In the login fields. Use the IP address and port number assigned during the configuration of the Web Management interface. in turn. 3. you can specify the referenced object in the following ways: v Select the name of an existing referenced object from the list. the WebGUI displays the object view for the object. Figure 1. v The navigation bar along the left side provides access to related configuration suites and to related management suites. Many of these objects are available in the default domain. 2 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide . – The Save Config button that allows the administrator to persist configuration changes. – The middle area contains icons to access monitoring and troubleshooting utilities. When the administrator selects the item. When you click any icon on the dashboard or select any item from the menu. – The Logout button that allows the administrator to end the WebGUI session. This area contains the following menus: – The Control Panel returns the administrator to the Welcome screen. Figure 1 illustrates this type of input field. – The Status menu provides access to logs and status providers. the WebGUI uses custom controls to help during the configuration of objects. Common WebGUI conventions In addition to the standard interface controls. When the administrator selects the item. – The bottom area contains icons to access file management and administration utilities. – The Network menu provide access to network configuration objects. – The Services menu provides access to service configuration objects and objects referenced by service objects. These objects are to define the network in which the appliance connects. the configuration screen might display an input field to select a referenced object. – 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. Input field for referenced objects When the WebGUI displays this type of input field. v The dashboard that is separated into the following areas: – The top area contains icons to access top-level objects for the appliance. These controls generally pertain to defining referenced objects. the WebGUI replaces the dashboard with the details for the selected item.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 WebGUI displays the service view for the object. Working with referenced objects When using the WebGUI to create and modify objects. – The Objects menu provides access to service configuration objects and objects referenced by service objects. v Use the + button to create a new referenced object. button to modify the referenced object whose name is in the input field. Click Add to add it to the list of referenced objects. button.. When created. The input for this configuration item is the list of referenced objects.. When modified. Input list for referenced objects When the WebGUI displays this type of list. v Select the name of a referenced object from the list (either the input field or the list of referenced objects). button... the WebGUI launches a new window that displays the configuration screen for that type of object. the configuration screen might display the View and Edit buttons beside the selection lists. When you click the + button or . you can manage referenced objects in the following ways: v Select the name of an existing referenced object from the list. Figure 2. When modified. the WebGUI launches a new window that displays the configuration screen for that type of object. the input field retains the name of the referenced object. the input field retains the name of the referenced object. Viewing and editing local files during configuration As you use the WebGUI to select a local file during configuration. Click Delete to remove it from the list of referenced objects. When created. WebGUI basics 3 . v Use the . 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. button to modify the referenced object whose name is in the input field. Figure 2 illustrates this type of input list. Click Add to add it to the list of referenced objects. 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. v Use the ... When you click the + button or . the input field contains the name of the new referenced object. Chapter 1.. the input field contains the name of the newly created referenced object. Click Add to add it to the list of referenced objects. v Use the + button to create a new referenced object. Review the file. but are not persisted to the startup configuration. Select the file from the lists. click Apply to save these changes to the running configuration. 4. you return to object catalog and lose all changes. click Cancel to not save the current changes to the running configuration. 3. use the following procedure: Select the file from the lists. 3. click Save Config. By default. Click Cancel. Click Submit to save changes.cfg file. Changes that are made to the running configuration take effect immediately. To retain applied changes across an appliance restart. 5. Click Edit to open the file editor in edit mode. Click View to open the file editor in view mode. 4. The changes are saved to the startup configuration. use the following procedure: 1. The startup or persistent configuration is persisted across an appliance restart. If you click Cancel. Click Close. view a local file. Edit the file as required. 2. v Applying and saving configuration changes v Canceling changes before saving to the running configuration v Resetting changes to an object v v v v v v Deleting an object Exporting the configuration of an object Viewing object-specific logs Viewing object status Cloning a service Accessing probe captures Applying and saving changes As you use the WebGUI to manage object and service configurations. 2. 4 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide . To edit a local file. Canceling changes As you use the WebGUI to manage objects. Common WebGUI tasks The majority of objects provide the following common tasks.Viewing local files To 1. the appliance reads the startup configuration from the auto-config. Not all of these tasks are available to all objects. Editing local files The edited file overwrites the original file. During an appliance restart these changes are lost. you can view log messages that are specific to an object. 3. Click Export. Display the catalog for the object. The catalog lists the available instances of this object. 3. Deleting objects You might want to delete objects that are no longer needed. Follow the prompts. WebGUI basics 5 . 4. Display the catalog for the object. Viewing log files from the catalog To view object-specific logs from the catalog. Deleting an object deletes that object only. 2. The catalog lists the available instances of this object. 2. Click the name of the object to export to display the configuration screen. Viewing object-specific logs Instead of filtering the log for the default log or a configured log target. The catalog lists the available instances of this object. Display the catalog for the object. 4. use the following procedure: 1. 4. Use the following procedure to delete an object: 1. you can delete it at any time. Use the following procedure to revert changes to a specific object: 1. 3. Conversely. Deleting an object does not delete any referenced object. click View Logs. Chapter 1. Because a DataPower service is a top-level object. Click the name of the object for which to reset to display the configuration screen. you cannot delete an object that is active and that is in use by a higher-level object. Click Undo. Display the catalog for the object. you can delete it at any time. Viewing log files from the configuration screen To view object-specific logs from the configuration screen. The catalog lists the available instances of this object. Click the name of the object to delete to display the configuration screen. Click Delete. If no other object depends on the object to be deleted. 2. Follow the prompts.Resetting objects Independent of whether the settings are saved to the configuration. Exporting objects Use the following procedure to export an object: 1. Follow the prompts. 2. Click the magnifying glass icon. you can reset an object to its default configuration. but each service communicates with a different remote server. specify the name of the clone. 3. The catalog lists the available instances of this object. Hiding unused properties is the default behavior. Click Apply to save the object to the running configuration.0) to specify all interfaces. you need two equivalent services. Click View Status. 6 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide . you can create a clone of an existing service and edit the clone. Click the name of the object to view to display the configuration screen. In these cases.0. Click the name of the service to clone to display the configuration screen. Specify the Ethernet interface that the service monitors for incoming client requests in the Device Address field. Display the catalog for the object. 9. 2. Display the catalog for the service. the WebGUI opens a new window. 5.Viewing object status You can view the status of an object and all its referenced objects to help determine why a configuration object is in a down state. 3. This window provides the ability to show or hide unused properties. Optionally.0. Specify the Ethernet port that the service monitors for incoming client requests in the Device Port field. As necessary. The cloning process can expedite the creation of a similar service. Use the default address (0. edit the other properties. Click Clone. or Saved v It operational state: up or down v Its administrative state: enabled or disabled v Details about the detected error. When the screen refreshes. Use the following procedure to clone a server: 1. 4. 2. When viewing the object status. The catalog lists the available instances of this service. 7. Cloning services You might want to create a service that is similar to an existing service. For example. 6. click Save Config to save the object to the startup configuration. When you view the object status. Modified. 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. click Hide to hide these properties. v If the display lists unused properties. 8. 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. v To show the unused properties. click Show. Click the magnifying glass icon to view details about that captured transactions. 3. you can view the captured transactions. For complete details about using the probe. defining the triggers. Click Show Probe. 2. WebGUI basics 7 . and sending transactions that match the conditions defined by the triggers. Use the following procedure to access probe captures: 1. Chapter 1. 4. refer to the IBM WebSphere DataPower SOA Appliances: Problem Determination Guide. The catalog lists the available instances of this object. Display the catalog for the service object.Accessing probe captures After enabling the probe. Click the name of the service for which to view the probe captures to display the configuration screen. 8 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide . Store the private key on the box and create a Key object that references it. 2009 9 . use the following procedure to create the key-certificate pair: 1. 3. The appliance provide these capabilities with a combination of utilities and objects. 2002. © Copyright IBM Corp. The CA signs the CSR and returns it to you. 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. Creating key-certificate pairs When you generate a key. refer to the IBM WebSphere DataPower SOA Appliances: Hardware Security Module Guide. In other words.Chapter 2. Send the CSR to a Certificate Authority (CA). Do not store it on the box (except in the temporary: directory). such as VeriSign. The CSR file from the initial key generation is not a signed certificate. Use the Crypto Tool to create the key and CSR 2. 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. Send the CSR to VeriSign. With the provided cryptographic tools. you cannot export or import keys. Securing communication This chapter provide information about securing communication to and from the DataPower appliance. you get a key file and a Certificate Signing Request (CSR) file. Load this certificate on the box. Working with keys and certificates The DataPower appliance provides actions that allow you to work with keys and certificates. For details about using an HSM-enabled appliance. which effectively creates the certificate. Select Administration → Miscellaneous → Crypto Tools to display the Generate Key page. Use the Export Private Key toggle to indicate whether the action writes the key file to the temporary: directory. Store the signed certificate on the box and create a Certificate object that references it. and Organizational Unit 4 (OU) fields. Optionally specify a locality name in the Locality (L) field. f. Specify the number of days that the key is valid in the Validity Period field. The Certificate Signing Request (CSR) needed by a certificate authority (CA) is created by default. To generate a key. Select a key length from the RSA Key Length list. 5. Creates the entry in reverse RDN order. e. The password must be at least 6 characters in length. Optionally. 4. create an Identification Credentials object that references the key and certificate objects. d. If the file is stored in the cert: directory. Organizational Unit 3 (OU). Optionally specify the name of an organizational unit in the Organizational Unit (OU) field. on b. Define the LDAP entry. 3. The value takes the directory:///name form. Use the LDAP (reverse) Order of RDNs toggle to indicate whether to create the LDAP entry in reverse RDN order. Specify a password alias to access the key file in the Password Alias field. h.4. use the following procedure: 1. off (Default) Does not write the key file to the temporary: directory. 8. Optionally specify a state or province name in the State or Province (ST) field. c. IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide . off (Default) Create the entry in forward RDN order. If a file is stored in the local: directory or in the temporary: directory. When you create the Identification Credentials object. Optionally specify the names of additional organizational units in the Organizational Unit 2 (OU). the key-certificate pair is validated to ensure that pair is ready for use. it can be deleted and edited. Generating keys and certificates You can generate a private cryptographic key and optionally a self-signed certificate from the Crypto Tools page. 6. a. 6. Specify a common name in the Common Name (CN) field. Optionally specify the name of an organization in the Organization (O) field. Optionally specify a country name in the Country Name (C) field. 2. it cannot be deleted or edited. This defaults to 1024. VeriSign returns the signed certificate. 5. 10 on Writes the key file to the temporary: directory. Specify a password to access the key file in the Password field. g. Specify the name of the key file to generate in the File Name field. Leave blank to allow the action to create the name. 7. 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. The CSR can be submitted to a certificate authority (CA) to receive a certificate that is based on this private key. off Does not write the self-signed certificate to the temporary: directory. cert:///sample-sscert. For details.pem v If Export Self-Signed Certificate is enabled. 11.pem v Creates the CSR in the temporary: directory. the appliance does not generate a new key. temporary:///samplesscert. a self-signed certificate. cert:///sample-privkey. temporary:/// sample. off Does not create the objects from the generated files. Use the Export Self-Signed Certificate toggle to indicate whether the action writes the self-signed certificate to the temporary: directory. Use the Generate Self-Signed Certificate toggle to indicate whether the action creates a self-signed certificate that matches the key. Follow the prompts. for example.9. for example. on (Default) Writes the self-signed certificate to the temporary: directory. Note: If the appliance has HSM hardware. if requested. 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). you can export Key objects. If supplied and valid. In this case. off Does not create a self-signed certificate.pem v If Generate Key and Certificate Objects is enabled. on (Default) Creates the objects from the generated files. for example. 14. 12. creates a self-signed certificate in the cert: directory. 15.csr v If Generate Self-Signed Certificate is enabled. 10. This action creates the following files and objects: v Creates the private key file in the cert: directory. Securing communication 11 . 13. on (Default) Creates a self-signed certificate. for example. Specify the name of an existing Key object in the Using Existing Key Object field. Chapter 2. the action generates a new certificate and a new Certificate Signing Request (CSR) that is based on the key in the identified Key object. creates a Key object and a Certificate object If the action creates a self-signed certificate. Use the Generate Key and Certificate Objects toggle to indicate whether the action automatically creates the objects from the generated files. Specify the name for the Key and Certificate objects in the Object Name field. refer to IBM WebSphere DataPower SOA Appliances: Hardware Security Module Guide. creates a copy of the self-signed certificate in the temporary: directory. A CSR is created automatically. Click Generate Key to generate a private key and. 3. Objects that are exported from one DataPower appliance can be imported to another appliance. Object Name Specify the name of the object to create on import. Importing objects. To view a list of all such objects. Do not specify a local directory or file extension. eliminates the need to create objects from files. Any appliance can export certificates. Use the File Management utility to access the file. The appliance writes the file to the temporary: directory. click Upload or Fetch to transfer the file. Provide the following information: Object Type Select the type of object to export. Object Name Type the exact name of the object. Select Administration → Miscellaneous → Crypto Tools to display the Crypto Tools screen. refer to IBM WebSphere DataPower SOA Appliances: Hardware Security Module Guide. rather than uploading files. This name must be a unique in the object namespace. 12 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide . Select Administration → Miscellaneous → Crypto Tools to display the Crypto Tools screen. 1. Output File Name Specify the name of a export package to contain the exported objects. 2. 3. Input File Name Use the controls to select the export package. Importing keys and certificates Use the Import Crypto Objects tab of the Crypto Tools screen to import key and certificate objects. Note: If the appliance has HSM hardware. Click Export Crypto Object to create the export package with the selected object. Click the Import Crypto Object tab. select Objects → Crypto Objects → Cryptographic Certificate (or Key). Any appliance can import certificates. you can import Key objects. 4. Encryption Mechanism Select Key-Wrapping-Key. Note: Available when the appliance has HSM hardware to specify the encryption mechanism to export private keys. Devices with HSM hardware can export private keys. Provide the following information: Object Type Select the type of object to import.1. For details. 2. Click the Export Crypto Object tab. Devices with HSM hardware can import private keys. If the file does not reside on the DataPower appliance. Provide the following inputs: Name Specify the name of the object. Click Add. To create and configure a Certificate. v If key files are protected by a plaintext password. Password Alias The password can optionally be given an alias. v If key files are protected by an aliased password. click disabled. specify the alias. an Identification Credentials. Select Objects → Crypto → Crypto Certificate. Defining Certificate objects A Certificate object that provides an added layer of security by supplying a indirect reference (or alias) to a certificate file. specify the password. An object with the specified name is created. leave blank. an error is returned. If an alias is established. specify the password (or a password alias). v If local polices do not support password protection. contained in the cert: or pubcert: file repository. use the following procedure: 1. Admin State Retain the default setting. 3. use the alias instead of the actual password. You can also click Details to display information about the selected certificate file. Password Depending of business security policies. Plaintext passwords are not stored in memory or saved on the appliance. Otherwise. 4. providing a level of indirection and thus additional security. File Name Access a list of files. The alias provided by the Certificate object is later used in the creation of a Firewall Credentials. To place the object in an inactive administrative state. 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. 2. Securing communication 13 . provide one of the following: v If local security policies provide for password-protected keys. The password map and the locally-generated key are saved to separate files on the appliance. Any entity or agent needing to access the file must supply this password. and select the file that contains the certificate referenced by this Certificate object. You can click Upload or Fetch to transfer the file. The command maps the encrypted password to a password alias in a password map file. Chapter 2.Password Optionally specify a password for accessing the file. or a Validation Credentials. Note: Plaintext passwords appear as such in the configuration script. Click Import Crypto Object. the certificate itself is in the up state. 4. click disabled. all keys and certificates stored locally are available. 5. or Identification Credentials that references the certificate adhere to the internal expiration values. the certificate itself is in the up state. or Identification Credentials that references the certificate adhere to the internal expiration values. click Save Config to save the object to the startup configuration. off (Default) Prevents the creation of certificates outside of their internal expiration values. but the peer can reject the certificate as not valid. Admin State Retain the default setting. Firewall Credentials. the DataPower appliance sends the certificate to the SSL peer for an SSL connection. but Validation Credentials. but Validation Credentials. 2. Select Objects → Crypto → Crypto Firewall Credentials to display the Crypto Firewall Credentials catalog. use the following procedure: 1. Similarly. If no Firewall Credentials exist. Optionally. Certificates and keys not referenced in the Firewall Credentials are unavailable. Although the certificate is in the up state. 3. if the certificate is used from an Identification Credentials. To place the object in an inactive administrative state. Click Add to display the Crypto Firewall Credentials Configuration screen. validation fails. Click Apply to save the object to the running configuration and return to the object catalog. Private Key Use the list to add Key objects to the Firewall Credentials.Password Alias Use the toggle to specify if the text entered in the Password field is a plaintext password or a password alias. Firewall Credentials. In other words. Provide the following inputs: Name Specify the name of the object. on Identifies the text as a password alias for an encrypted password. To create a Firewall Credentials. 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). If the certificate is used for a certificate chain validation from a Validation Credentials and the certificate is not valid. objects that reference the certificate use the internal expiration values. on Creates the certificate and places it in the up state. 14 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide . Defining Firewall Credentials objects A Firewall Credentials consists of a list of Key objects and Certificate objects. In other words. Refer to “Defining Key objects” on page 16 for more information. A Firewall Credentials provides a list of Key objects and Certificate objects. off (Default) Identifies the text as a plaintext password. 2. document decryption. an additional intermediate CA certificate might be required for that CA. 4. An Identification Credentials can be used in document encryption. To create an Identification Credentials. Defining Identification Credentials objects An Identification Credentials consists of a Key object and a Certificate object. Optionally. Refer to “Defining Shared Secret Key objects” on page 18 for more information. 5. Select Objects → Crypto → Crypto Identification Credentials to display the Crypto Identification Credentials catalog. Optionally. You can specify as many intermediate certificates as are required. Certificates Use the list to add Certificate objects to the Firewall Credentials. Refer to “Defining Certificate objects” on page 13 for more information. use the list of available Certificate objects to establish a verifiable trust-chain. If the intermediate CA certificate is also signed by a less recognized CA. If necessary. click disabled. click Save Config to save the object to the startup configuration. Refer to “Defining Certificate objects” on page 13 for more information. and select the Certificate object for this Identification Credentials. 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. 4. Certificate Access a list of all Certificate objects. Click Apply to save the object to the running configuration. Refer to “Defining Key objects” on page 16 for more information.Shared Secret Key Use the list to add Shared Secret Key objects to the Firewall Credentials. Provide the following inputs: Name Specify the name of the object. 5. Admin State Retain the default setting. The trust chain enables the appliance to authenticate the certificate. use the following procedure: 1. and select the Key object for this Identification Credentials. and digital signature operations. To place the object in an inactive administrative state. Crypto Key Access a list of all Key objects. Click Apply to save the object to the running configuration. An Identification Credentials identifies the matched public key cryptography public and private keys used by an object for SSL authentication. Click Add to display the Crypto Identification Credentials Configuration screen. 3. Securing communication 15 . Chapter 2. click Save Config to save the object to the startup configuration. Intermediate CA Certificate Intermediate CA certificates might be required when the CA that is signing this certificate is not widely-recognized. on Identifies the text as a password alias for an encrypted password. 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. Note: Plaintext passwords appear as such in the configuration script. v If key files are protected by a plaintext password. provide one of the following: v If local security policies provide for password-protected keys. Click Apply to save the object to the running configuration. 4.Defining Key objects A key is an object that provides an added layer of security by supplying a indirect reference (or alias) to a file that contains a private key. create and configure a Key object. The command maps the encrypted password to a password alias in a password map file. To place the object in an inactive administrative state. 2. Plaintext passwords are not stored in memory or saved on the appliance. v If key files are protected by an aliased password. off (Default) Identifies the text as a plaintext password. Optionally. specify the password (or a password alias). Password Depending on business security policies. specify the alias. Click Java Key Store on the Upload field. use the following procedure: Select Objects → Crypto → Crypto Key to display the Crypto Key catalog. leave blank. click Save Config to save the object to the startup configuration. Refer to IBM WebSphere DataPower SOA Appliances: Appliance Overview for more information. 5. Click Add to display the Crypto Key Configuration screen. You can click Upload or Fetch to transfer the file. Note: Keys can be retrieved from a Java™ Key Store residing on the local workstation. 16 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide . specify the password. v If local polices do not support password protection. Password Alias Use the toggle to specify if the text entered in the Password field is a plaintext password or a password alias. To 1. click disabled. 3. The alias provided by the Key object is later used in the creation of a Firewall Credentials object or an Identification Credentials object. Admin State Retain the default setting. Provide the following inputs: Name Specify the name of the object. File Name Access a list of files (contained in the cert: file repository) and select the file that contains the private key aliased by this Key object. The password map and the locally-generated key are saved to separate files on the appliance. but exclude EXPORT cipher suites. RSA. 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. and SSL version 2 ciphers HIGH Includes all “high” encryption cipher suites. use the following procedure: 1. These ciphers support a key length of 56 or 64 bits. except the eNULL ciphers. MEDIUM Includes all “medium” encryption cipher suites. Click Add to display the configuration screen. Securing communication 17 . 2. Common cipher values are as follows: ALL Includes all cipher suites. Admin State Retain the default setting.Defining Profile objects A Profile object identifies a collection of SSL resources that support SSL connections with remote peer appliances. Chapter 2. Identification Credentials Select the Identification Credentials to assign to this Profile object. Ciphers Use the field to identify the symmetric key-encryption algorithms for this Profile object. To create and configure a Profile object. DEFAULT Includes all cipher suites. click disabled. 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. 3. LOW Includes all “low” encryption cipher suites. when no Validation Credentials is needed. Validation Credentials Select the Validation Credentials for this Profile object. To place the object in an inactive administrative state. Refer to “Defining Identification Credentials objects” on page 15 for more information. Select Objects → Crypto → Crypto Profile to display the catalog. These ciphers support a key length in excess of 128 bits. These ciphers support a key length of 128 bits. Refer to “Working with Validation Credentials objects” on page 21 for more information. none. or retain the default value. 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. or retain the default value. none. Provide the following inputs: Name Specify the name of the object. Send Client CA List Use the toggle to enable the transmission of a Client CA List during the SSL handshake. SSL Version 3. refer to the profile command in the product-specific version of the Command Reference. Note: SSL servers are not required by the protocol to send a Client CA List. click Disable-SSLv3. Provide the following inputs: Name Specify the name of the object. 5. might mandate the use of Client CA lists. decryption. Optionally. 3. Select Objects → Crypto → Crypto Shared Secret Key to display the Crypto Shared Secret Key catalog. SSL Version 2. click disabled. click Disable-TLSv1. Click Add to display the Crypto Shared Secret Key Configuration screen. v To disable TLS Version 1. To place the object in an inactive administrative state. 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. 4. and digital signature purposes. Some implementations or local policies. off (Default) Disables transmission of a Client CA List. Click Apply to save the object to the running configuration. A Client CA List can be sent by an SSL server as part of the request for a client certificate. 2. The Client CA list provides the client with a list of approved CAs whose signatures are acceptable for authentication purposes. Generally.For a detailed list of ciphers. v To disable SSL Versions 2. use the following procedure: 1. A shared secret key is used by mutual agreement between a sender and receiver for encryption. on Enables transmission of a Client CA List. click Disable-SSLv2. A Client CA List consists of a listing of the CA certificates in the Validation Credentials for this Profile object. and Transaction Level Security (TLS) Version 1 are enabled. however. 18 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide . Options Use the check boxes to disable support for SSL versions and variants. By default. SSL servers do not send a Client CA list. To create and configure a Shared Secret Key. v To disable SSL Version 3. click Save Config to save the object to the startup configuration. Defining Shared Secret Key objects A Shared Secret Key objects provides an added layer of security by supplying an indirect reference (or alias) to a shared secret key. Admin State Retain the default setting. 4. Select Objects → Crypto → SSL Proxy Profile to display the SSL Proxy Profile catalog. Specify the name of the object in the Name field.File Name Access a list of files (contained in the cert: file repository) and select the file that contains the shared secret key aliased by this Shared Secret Key. Select the profile that defines SSL service to the backend server from the Forward (Client) Crypto Profile list. 3. 2. click Save Config to save the object to the startup configuration. 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). Click Apply to save the object to the running configuration. Creating a reverse (or server) proxy To create a reverse SSL Proxy Profile. Retain the default setting for the Admin State toggle. 4. Select Reverse from the SSL Direction list. Select Forward from the SSL Direction list. Optionally. 8. To place the object in an inactive administrative state. Creating a forward (or client) proxy To create a forward SSL Proxy Profile. Click Apply to save the object to the running configuration. Select Objects → Crypto → SSL Proxy Profile to display the SSL Proxy Profile catalog. The SSL proxy has the following modes: forward The SSL proxy acts as an SSL client (or acts in the forward direction). To place the object in an inactive administrative state. Retain the default setting for the Admin State toggle. Chapter 2. 4. Click Add to display the SSL Proxy Profile Configuration screen. Optionally. use the following procedure: 1. 9. Click Add to display the SSL Proxy Profile Configuration screen. 2. In server proxy mode. In client proxy mode. 5. reverse The SSL proxy acts as an SSL server (or acts in the reverse direction). In two-way mode. click disabled. Specify the name of the object in the Name field. 5. 6. 5. 3. Securing communication 19 . use the following procedure: 1. You can click Upload or Fetch to transfer the file. Use the Client-side Session Caching toggle to enable or disable client side caching. SSL is used over the appliance-to-server connection. click Save Config to save the object to the startup configuration. SSL is used over the appliance-to-server connection and the appliance-to-client-connection. Defining SSL Proxy Profile objects An SSL Proxy Profile defines a level of SSL service when operating as an SSL proxy. 7. click disabled. Select the profile that defines SSL service to the backend server from the Forward (Client) Crypto Profile list. Select the profile that defines SSL service to frontend clients from the Reverse (Server) Crypto Profile list. When there is no client certificate. 11. the request does not fail. 10. Specify the maximum size of the server-side cache in the Server-side Session Cache Size field. Use the Client Authentication is optional toggle to control when SSL client authentication is optional. 7. Optionally. off (Default) Requests client authentication only when the server cryptographic profile has an assigned Validation Credentials. click Save Config to save the object to the startup configuration. To place the object in an inactive administrative state. Specify the maximum size of the server-side cache in the Server-side Session Cache Size field. Specify the name of the object in the Name field. Select Two Way from the SSL Direction list. 8. 7. on 20 Client authentication is not required. Specify the time that session-specific state data is maintained in the server cache in the Server-side Session Cache Timeout field. Use the Client Authentication is optional toggle to control when SSL client authentication is optional. Creating a two-way proxy To create an SSL Proxy Profile. off on Always requests client authentication. 8.6. Retain the default setting for the Admin State toggle. Click Apply to save the object to the running configuration. 3. 9. Click Add to display the SSL Proxy Profile Configuration screen. Use the Server-side Session Caching toggle to enable or disable server side caching. IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide . 2. 4. Select Objects → Crypto → SSL Proxy Profile to display the SSL Proxy Profile catalog. on Client authentication is not required. 13. 12. 12. Use the Client-side Session Caching toggle to enable or disable client side caching. Select the profile that defines SSL service to frontend clients from the Reverse (Server) Crypto Profile list. Use the Server-side Session Caching toggle to enable or disable server side caching. (Default) Requires client authentication only when the server cryptographic profile has an assigned Validation Credentials. Specify the time that session-specific state data is maintained in the server cache in the Server-side Session Cache Timeout field. 9. use the following procedure: 1. 11. When there is no client certificate. 6. 5. Use the Always Request Client Authentication toggle to control when to request SSL client authentication. the request does not fail. click disabled. 10. Click Create Validation Credential from pubcert: to display a confirmation screen. use the following procedure: 1.(Default) Requires client authentication only when the server cryptographic profile has an assigned Validation Credentials. To refresh the Crypto Validation Credentials catalog. 4. 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. Click Apply to save the object to the running configuration. non-password-protected certificates in the pubcert: file repository. non-expired. non-password-protected certificates You can create a Validation Credential includes all valid. 13. To save the Validation Credentials to the startup configuration. 2. off Working with Validation Credentials objects A Validation Credentials consists of a list of certificate objects. Click Add. 3. Provide the following inputs: Name Specify the name of the object. select Objects → Crypto → Crypto Validation Credentials. Chapter 2. non-password-protected credentials v Select credentials Independent of which type of Validation Credentials. select Objects → Crypto → Crypto Validation Credentials. 15. Creating for select certificates To prepare a Validation Credentials that contains selected certificate objects from the pubcert: file repository. Securing communication 21 . (Default) Requests client authentication only when the server cryptographic profile has an assigned Validation Credentials. Select Objects → Crypto → Crypto Validation Credentials. Creating for non-expiring. off on Always requests client authentication. Click Refresh List. 3. click Save Config. You can create Validation Credentials with the following types of credentials: v All non-expiring. the creation starts at the same location. with the appliance-supplied name of pubcert. 2. click Close. Validation Credentials are used to validate the authenticity of received certificates and digital signatures. After the WebGUI reports successful completion. Click Confirm to create the Validation Credentials. To create any Validation Credential. Select Objects → Crypto → Crypto Validation Credentials. click Save Config to save the object to the startup configuration. 14. Use the Always Request Client Authentication toggle to control when to request SSL client authentication. Optionally. use the following procedure: 1. determines whether the processing should fail when no CRL is available. Use CRLs Determines whether each Certificate Revocation List (CRL) is checked during the processing of the certificate chain. Ignore Ignores extensions. defines the certificate chain validation input that RFC 3280 calls the “user-initial-policy-set”. 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. Certificates Use the list to add select Certificate objects to the Validation Credentials. which could be an intermediate CA or a root CA. on Processing fails. PKIPath tokens. click disabled. Validation succeeds only if the chain ends with a root certificate in the Validation Credentials.509 CRL Distribution Points extensions during processing of the certificate chain and controls how to handle certificates in the Validation Credentials. CRL Distribution Points Handling Determines how to handle Certificate Revocation List (CRL) checking of X. but that certificate is not a self-signed (root) certificate. Require CRLs When CRLs are checked during processing of the certificate chain. Additional untrusted intermediate certificates will be obtained dynamically from the context at hand (SSL handshake messages. off (Default) Processing succeeds. This mode is useful when you want to match the peer certificate exactly. This set of OIDs specifies the only allowable values of Certificate Policies at the end of chain processing. To place the object in an inactive administrative state. off Does not check CRLs. but does not retrieve. PKCS#7 tokens. Initial Certificate Policy Set When the mode is PKIX. 22 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide . Non-root certificates in the Validation Credentials will be used as untrusted intermediate certificates. extensions. Full certificate chain checking (PKIX) The complete certificate chain is checked from subject to root when using this Validation Credentials for certificate validation. and so forth). on (Default) Checks the CRLs.Admin State Retain the default setting. Require Checks. Optionally. Require Explicit Certificate Policy When the mode is PKIX. 4. The default contains the OID for anyPolicy.If you define an initial certificate policy set. Click Apply to save the object to the running configuration and return to the object catalog. on The algorithm must end with a non-empty policy tree. click Save Config to save the object to the startup configuration. 5. controls whether the validation chain (algorithm) can end with an empty policy tree (that RFC 3280 calls the “initial-explicit-policy”). Securing communication 23 . you will want to enable the Require Explicit Certificate Policy field. off Chapter 2. Otherwise. The algorithm can end with an empty policy tree unless Policy Constraints extensions in the chain require an explicit policy. these certificate policy sets will be used only when there are Policy Constraints extensions in the certificate chain. 24 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide . there is a requirement statement followed by the recommended configuration to meet those requirements. 2002. benefits management. or a trading system). Solution Web Application Firewall Configuration: v v v v v © Copyright IBM Corp. 2009 Proxies Destination Address (real host address not exposed) Applies SSL Server Proxy Profile Default Threat Protections Default Multi-Part Form Protections Error Handling Policy redirects to friendly page 25 . Configuring Web Application Firewall services This chapter documents the creation or editing of a Web Application Firewall service using the Advanced Web Application Firewall Configuration screen. For each scenario. ticket sales. including Sign and Encrypt v Error Handling v XML and Non-XML Content Processing Scenarios This section provides scenarios using the Web Application Firewall service. proxy. 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). Scenario one: College enrollment form Requirements A community college offers the opportunity to sign up for evening classes. threat mediation. The college IT administrators would also like to restrict the size and depth of inbound posts.Chapter 3. The Web Application Firewall offers: v Destination Service Proxy v SSL Termination v Authentication and Authorization Service v Rate Limiting v v v v v Session Start and Timeout Enforcement URL-Encoded Name-Value Input Processing HTTP Protocol Filtering Threat Protection. The entire transaction must be SSL-encrypted but the host does not have the necessary cycles to manage the encryption. and content processing services for a Web-based application (such as enrollment. A Web Applications Firewall provides security. to protect against malicious intent. 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. such as SQL Injection Cookie Handling. Scenario two: Benefits management site Requirements A large corporation offers complete online management of employee benefits. Users must supply a user name and password to access the site. In some cases. upload descriptions of items for trade. Due to the competitive nature of the business. As some forms are multi-page. preventing a single entity from flooding the site. The site offers third party participation. responses from the central trading systems must also be limited in size and vetted for correctness. a session cookie is required and this cookie must be encrypted for security reasons. connections must be rate limited. in which customers are trading nearly anything for anything. 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 are redirected to an error handling page when errors occur. Because of the speed of transactions. 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. SQL Injection Attack protection is required. Customers need to be able to search for desired objects. an offered item might draw more than one bidder (or trade offer). 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. a single signon system is needed and cookies are used. Certain partner sites are allowed to POST entire forms as XML data. and securely close the deal. Users must supply a user name and password to access the site. so every post must be vetted for size and correctness. Solution Web Application Firewall Configuration: v Proxies Destination Address (real host address not exposed) v Applies SSL Server Proxy Profile v AAA basic authentication verifies user name and password with LDAP v Custom threat protections and protection from SQL injection v Custom Multi-Part Form Protections v Requests Rate Limited v Requests Vetted for Correct Name-Value Pairs 26 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide . In addition. or both will use SSL in accordance with the configured Crypto Profile. When selected. the backend server. Chapter 3. Remote IP Port The TCP port number of the backend server. Under Source Addresses. SSL Proxy Profile Select an existing SSL Proxy Profile to assign the SSL Proxy Profile to this handler. use an SSL Proxy Profile that uses a Crypto Profile configured as a Server (reverse) profile. specify the name of the Load Balancer Group. Remote Host Address The host name or IP address of the backend server. and provides configuration constraints on the size and parsing depth of XML documents. the caching of XML documents. can affect the behavior of the gateway when communicating with backend servers or with clients when sending back responses. If the appliance should employ an SSL connection to the backend server. communication with clients. XML Manager An XML Manager manages the compilation and caching of XSL style sheets. The User Agent settings. The name must be unique throughout the appliance. configure an SSL Proxy Profile that in turn uses a Crypto Profile configured for client (or forward) connections. v To implement SSL communication with requesting clients. A default Manager is used if you do not create one. set the Use SSL check box for at least one source address. Configuring Web Application Firewall services 27 . Provide the following inputs. You can enable streaming XML operation by configuring an XML Manager to use a Streaming Compile Option Policy. Summary Brief summary for user annotation. This is optional.v v v v v Error Handling Policy redirects to friendly page Cookie Required Start Page Filtering Session Management Timeout Responses Vetted for Correct Name-Value Pairs Configuring a Web Application Firewall General configuration Select Services → Web Application Firewall → New Web Application Firewall to display the Web Application Firewall Configuration screen. More than one firewall can use the same XML Manager. An XML Manager can optionally employ a User Agent. Click the + button to create a new XML Manager that is assigned to this firewall. in turn. Name Specify a unique name for this object. To use a load balancer. Select an existing XML Manager to assign the Manager to this firewall. all failures of Policy will generate an error by default. Source Addresses Source addresses determine the IP addresses and TCP ports to assign to the service. Refer to “Error Policy” on page 99 for more information. select an Application Security Policy. the Error Policy established by the Application Security Policy overrides this default selection. the service will handle the violation. Refer to “Configuring an Application Security Policy” on page 30 for more information. Default Error Handling Policy If any part of the Application Security Policy selected below is violated. Click Add. This value indicates that the service is active on all addresses. An Application Security Policy can also establish an Error Policy. The new Source Address appears in the listing of all configured source addresses. To add a source address. If no Policy is selected (the list remains at (none)). or error. use an SSL Proxy Profile that uses a Crypto Profile configured as a Client (forward) profile. To establish the security policy enforced by this firewall. Refer to “Defining SSL Proxy Profile objects” on page 19 for more information. At least one source address must be configured. use an SSL Proxy Profile that uses a Crypto Profile configured for two-way SSL. in accordance with the rules set forth in the selected Error Policy. Port Specify the TCP port on which the service listens.0. Use an integer in the range of 1 through 65535. or host alias on which the service listens. provide the following information. Security Policy A Security Policy is required to create the service. IP Specify the IP address. This is the default policy that will handle the response sent to the client. v Ensure that the check box is not selected to disable. There is no default value. SSL Indicates whether the service acts as an SSL server for requesting clients. Either the Request security policy or the Response security policy that is established by the select Application Security Policy can be turned off using the Request Security or Response Security toggle on the Timeout/Protocol tab. Remote clients connect to these addresses. host name. v To implement SSL communication with both requesting clients and the backend server. v Select the check box to enable. The default is 0.0. When enabled. 28 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide .v To implement SSL communication with the backend server. the Crypto Profile of the selected SSL Proxy Profile handles these requests.0. such as chunked uploads. Chapter 3. Configuring Web Application Firewall services 29 .0 requests will always be replied to with 1. You can optionally set additional configuration parameters on the Timeout/Protocol tab. Buffer Messages Buffers submitted messages until all processing is verified as complete. Buffer Messages Buffers submitted messages until all processing is verified as complete.1 version of the protocol.1 to support chunked responses. click Commit. The defaults are set to handle the majority of scenarios.1. Certain HTTP 1.1) to be used on client responses.0 or 1.To create the new Web Application Firewall service using the standard defaults for the configuration options available on the Timeout/Protocol tab. Front Persistent Timeout Specifies the maximum number of seconds (in the range 0 through 86400.0 compatible responses regardless of this setting. HTTP Response Version Select the HTTP version (1. Provide the following inputs: Front Side Timeout Controls the amount of time a front side client connection can be idle before being abandoned in a transaction.1 features. Timeout/Protocol These configuration options control time outs and HTTP protocol-specific options. require the selection of 1. forward the message to the appropriate backend. with a default of 180) that a gateway maintains an idle persistent TCP connection on the front side. HTTP Version to Server Select the HTTP version (1. with a default of 180) that a gateway maintains an idle persistent TCP connection on the back side. Stream Output to Back Select the desired streaming behavior.0 or 1. After verification. Back Side Timeout Controls the amount of time a back side client connection can be idle before being abandoned in a transaction. After verification. Incoming version 1. Stream Messages Begins to send the message to the backend before all processing is complete. The backend server must also support HTTP 1. Use 1.1 for the connection to be established and maintained using the 1. This behavior potentially increases processing speed. forward the message to the appropriate requesting client. Stream Output to Front Select the desired streaming behavior.1) to use on the server-side connection. Select this option when the selected XML Manager has streaming enabled or when streaming of attachments is enabled. Back Persistent Timeout Specifies the maximum number of seconds (in the range 0 through 86400. Web Response Profile. Click Add Request Map to save the map. no response side security policies is enforced and all responses are allowed through. This makes checking for attack sequences more reliable. in turn. Select this option when the selected XML Manager has streaming enabled or when streaming of attachments is enabled. Response Map. Response Security If disabled (off). General configuration Provide the following input: Name Specify a name for this Policy. characters that are escaped that do not need to be are unescaped. 30 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide . Request Maps Request Maps select Web Request Profiles to execute on client requests based on a set of matching criteria. matches a Web Request Profile. If the client request meets the matching criteria. Each of these map objects. Refer to “Matching Rule” on page 106 for more information. or Error Policy object.Stream Messages Begins to send the message to the requesting client all processing is complete. Note: You must create at least one Request Map to complete the Policy creation. Rule Select an existing Web Request Profile. no request side security policies is enforced and all requests are allowed through. Provide the following inputs: Match Select an existing Matching Rule. Normalize URI When enabled (on). The new map is displayed in the catalog. the corresponding Web Request Profile executes. and Error Map objects. This setting overrides the previously selected Application Security Policy. Configuring an Application Security Policy An Application Security Policy establishes the rules that are used to enforce security for a Web Application Firewall service. Refer to “Web Request Profile” on page 132 for more information. Request Security If disabled (off). This behavior potentially increases processing speed. This setting overrides the previously selected Application Security Policy. the URI is rewritten to make the URI RFC-compliant. The selected profile object then provides the detailed security configuration. to client-requests that are based on a set of matching criteria. respectively. additionally. This is the name that appears in all Policy listings. Click the Request Maps tab to establish Web Request matching maps. This policy employs Request Map. Certain characters will be escaped. Click Commit to complete configuration of the Policy. The new map is displayed in the catalog. the first matching expression that returns true will execute. Provide the following inputs: Match Select an existing Matching Rule. Refer to “Matching Rule” on page 106 for more information. If the error meets the matching criteria. the corresponding Processing Rule executes. Note: The order of Request Maps is important. Click the Error Maps tab to establish Error Policy matching maps. the first matching expression that returns true will execute. Rule Select an existing Processing Rule. Click the Response Maps tab to establish Web Response matching maps. Refer to “Web Response Profile” on page 139 for more information. Refer to “Matching Rule” on page 106 for more information. Error Maps Error Maps select a Processing Rule to execute on errors based on a set of matching criteria. Refer to “Processing Rule” on page 111 for more information. Provide the following inputs: Match Select an existing Matching Rule. If the server response meets the matching criteria. The maps are checked from the top to the bottom of the list. Configuring Web Application Firewall services 31 . Click Add Response Map to save the map. Rule Select an existing Web Response Profile. The maps are checked from the top to the bottom of the list. Response Maps Response Maps select Web Request Profiles to execute on server responses based on a set of matching criteria. the corresponding Web Request Profile executes. The new map is displayed in the catalog. Click Add Error Map to save the map. Click Commit to complete configuration of the Policy. Use the Reorder button to establish the desired ordering of maps. Note: You must create at least one Response Map to complete the Policy creation. Use the Reorder button to establish the desired ordering of maps. Note: The order of Response Maps is important. Click Commit to complete configuration of the Policy. Chapter 3. 32 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide . and WSDL files. dpcert: This encrypted directory contains files that the appliance itself uses. To view the audit log from the WebGUI. This directory is available from the command line in the default domain only. Each application domain contains one local: directory. delete.Chapter 4. © Copyright IBM Corp. You can move log files to the logstore: directory. but you cannot modify these files while in the domain. chkpoints: This directory contains the configuration checkpoint files for the appliance. XSD. 2009 33 . This directory is not shared across domains. You can add. such as XSL. and view files. the storage space for files and other artifacts is limited. These directories and their contents are as follows: audit: This directory contains the audit logs. 2002. Each application domain contains one export: directory. image: This directory contains the firmware images (primary and secondary) for the appliance. Each appliance contains only one image: directory. the directory name changes from local: to the name of the application domain. Each appliance contains only one audit: directory. Each application domain contains one cert: directory. This directory is where firmware images are stored typically during an upload or fetch operation. Managing files The appliance contains no hard drive for file storage. This directory can be made visible to other domains. When viewed from other domains. This directory is available from the command line in the default domain only. Each application domain contains one chkpoints: directory. This directory cannot be the destination of a copy. Each application domain contains one logstore: directory. As a result. This directory is not shared across domains. cert: This encrypted directory contains private key and certificate files that services use in the domain. select Status → View Logs → Audit Log. logstore: This directory contains log files that are stored for future reference. This directory is not shared across domains. Each application domain contains one config: directory. This directory is not shared across domains. Directories on the appliance The file system contains many examples and critical configuration files. local: This directory contains miscellaneous files that are used by the services within the domain. Typically. export: This directory contains the exported configurations that are created with the Export Configuration utility. This directory is available in the default domain only. the logging targets use the logtemp: directory for active logs. This directory is not shared across domains. config: This directory contains the configuration files for the appliance. sharedcert: This encrypted directory contains security certificates that are shared with partners. such as the appliance-wide default log.logtemp: This directory is the default location of log files. dp 34 This encrypted subdirectory contains files that are used by the appliance itself. The contents of these subdirectories affect Web services policy. This directory is shared across domains. However. This directory is not shared across domains. Each application domain contains one logtemp: directory. store: This directory contains example style sheets. pubcert: This encrypted directory contains the security certificates that are used commonly by Web browsers. mappings This subdirectory contains mapping style sheets. msgcat This subdirectory contains the message catalogs. you must be in default domain to create or upload keys and certificates. custom This subdirectory contains custom style sheets. this directory is visible to all domains. Each appliance contains only one pubcert: directory. By default. Each appliance contains only one store: directory. The store: directory has the following subdirectories: meta This encrypted subdirectory contains files that are used by the appliance itself. These certificates are used to establish security credentials. Do not modify the files in this directory. policies This subdirectory contains the following subdirectories. This directory cannot be the destination of a copy. This subdirectory is available from the command line only. You can make changes to the contents of this directory from the default domain only. IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide . This directory can hold only 13 MB. templates This subdirectory contains XML files. This directory is shared across domains. schemas This subdirectory contains schemas that are used by DataPower services. Each appliance contains only one sharedcert: directory. default style sheets. profiles This subdirectory contains style sheets that are used by DataPower services. and schemas that are used by the local appliance. Each appliance contains only one tasktemplates: directory. 2. Creating a subdirectory Subdirectories can only be creates under the local: directory or one of its subdirectories. The initial screen shows the top level directories. Launch the File Management utility. v Select Administration → Main → File Management. Launch the File Management utility. perform the following procedure: 1. Enter the name of the new subdirectory in the directory Name field. Displaying directory contents To display (expand) the contents of a directory. Refer to “Launching the File Management utility” for details. 4.pubcerts This encrypted subdirectory contains files that are used by the appliance itself. Managing files 35 . Each application domain contains one temporary: directory. The File Management screen displays. This subdirectory is available from the command line only. 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. The File Management screen refreshes. click Actions aligned with the directory for the subdirectory to be created. This directory is visible to the default domain only. 6. Click Continue. tasktemplates: This directory contains the XSL files that define the display of specialized WebGUI screens. select that directory again. temporary: This directory is used as temporary disk space by processing rules. Refer to “Launching the File Management utility” for details. 5. This directory is not shared across domains. Chapter 4. Select the directory to display its contents. To hide (collapse) the content-view of a directory. Follow these steps to create a subdirectory under the local: directory or one of its subdirectories: 1. Either method displays the File Management screen. 3. The File Management screen displays the top-level directories only. Launching the File Management utility To manage files. From the Action column. Click Confirm Create. Click Create Subdirectory. 2. 36 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide . the file is not uploaded. When the appliance reports success (or an error is the file already existed). 3. Click Delete Directory. The target directory now contains the uploaded files. The File Management screen displays. or click Browse to locate the file on the workstation. The File Management screen displays the top-level directories only. 4. Click Upload. Launch the File Management utility. Click Actions in that row to open the Directory Actions menu. Launch the File Management utility. 5.Deleting a directory Directories can only be deleted in the local: directory or one of its subdirectories. If one of the files already exists in the selected directory and you want to overwrite this file. Follow these steps to delete a directory under the local: directory or one of its subdirectories: 1. To verify. Click Add. 2. 3. If you do not select this check box and the file already exists. To add another file to be uploaded: a. 10. 2. Refer to “Launching the File Management utility” on page 35 for details. click Continue to return to the File Management screen. Uploading files from the workstation Use the following procedure to upload a file from your workstation to the appliance: 1. use the procedure described in “Displaying directory contents” on page 35. Click Upload Files to display the File Upload screen. 5. 8. From the Action column. Note: If you used browsing to select the file or if you navigated to this field using the tab key. 4. Refreshing directory contents To refresh contents. 9. Specify the file name in the Save as field. 7. Repeat steps 5 and 6. Click Continue. the field contains the file name. check the Overwrite Existing Files check box. Specify the path-qualified name of the workstation file in the File to upload field. The screen displays the top-level directories only. click the Refresh Page icon. Refer to “Launching the File Management utility” on page 35 for details. b. Navigate to the directory into which you want to upload the file. 6. Click Confirm Delete. The File Management screen refreshes. The WebGUI redraws the File Management screen. click Actions aligned with the directory to be deleted. 1.4.policy file on the workstation that contains the Java Key Store files. v SunJCE (Java Crypto Extension) generates a JCEKS-type (Java Crypto Extension Key Store) file store with the provider name SunJCE.Working with Java Key Stores A Java Key Store (JKS) is a Sun-proprietary format file that contains private keys and certificates.2 runtime environment or SDK use a program called keytool to create and manage a JKS-type file store with no provider name. Required software JKS support requires the following software on the WebGUI workstation: v Version 1. the Java Console of the browser opens and shows whether the Java Key Store Access Chapter 4. Click Actions in that row to open the Directory Actions menu.security package and sub-packages access the data in the JKS to carry out their cryptographic operations. Launch the File Management utility. You must know the key store type to successfully upload files from a JKS. 2.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. Granting permissions In addition. Navigate to the directory into which you want to upload the file. Note: When you click the Java Key Store radio button.*". 3.sun.4.policy file should be defined on the workstation computer before starting the upload: grant { permission java."read".java. the user must have the grant permission for the upload in the . 4.2) v SDK (j2sdk1. Types of key stores Sun offers two common methods to support key store creation: v Sun Java 2.4. "read".PropertyPermission "*".FilePermission "<<ALL FILES>>". 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.RuntimePermission "accessClassInPackage.2 of the Java runtime environment (j2re1. Refer to “Launching the File Management utility” on page 35 for details. Managing files 37 .java. 5. }. It must be uploaded from a workstation.lang. Click Upload Files to display the File Upload screen.util. You can grant read-only permission to the JKS file. The following example .io. permission java. Click the Java Key Store radio button to display the JKS Upload screen. The Java Key Store file cannot reside on any of the local directories. permission java.4. The java. 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. 3. Click Fetch. 6. specify SunJCE (the provider name) in the Key store provider field. 7. Copying files Use the following procedure to copy a file from one directory to another: 38 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide . 14. When the appliance reports success.4. Identify the files to upload with the Key to upload list. To verify that the file exists. 15. 9. If you do not select this check box and the file already exists. Launch the File Management utility. 6.Applet is running. Specify the full path to the target JKS in the Java key store field or click Browse. If the applet cannot be accessed. Use the Refresh button. 2. 5. check the Overwrite Existing Files check box. Specify the key-specific password in the Key password field. if necessary. Specify the location of the file in the Source URL field. To verify. Navigate to the directory into which you want to upload the file. If the file already exists in the selected directory and you want to overwrite this file. The target directory now contains the uploaded key or certificate. 13. Click Upload. leave blank. 10. Specify the file name in the Save as field. the file is not uploaded. 7. use the procedure described in “Displaying directory contents” on page 35. Click Actions in that row to open the Directory Actions menu.2 applet. If you do not select this check box and the file already exists. Specify the JKS password in the Key store password field. look at the Java Console of the browser to determine whether an exception was thrown. Ensure that your browser is enabled to use the Java 1. check the Overwrite Existing Files check box. 9. 8. Specify JKS or JCEKS (the JKS type) in the Key store type field. If the type is JCEKS. Specify the file name in the Save as field. The target directory now contains the retrieved file. use the procedure described in “Displaying directory contents” on page 35. you cannot upload JKS files. Refer to “Launching the File Management utility” on page 35 for details. 11. the file is not uploaded. 4. If the file already exists in the selected directory and you want to overwrite this file. 8. click Continue to return to the File Management screen. 12. Otherwise. click Continue to return to the File Management screen. If the upload fails. Click Fetch Files to display the Fetch File screen. When the appliance reports success. check the Overwrite Existing Files check box. If one of the selected files already exists in its directory and you want to overwrite this file. Select files by clicking the box adjacent to the file name. If one of the selected files already exists in the target directory and you want to overwrite this file. the file is not copied. Scroll to the top or bottom of the screen and click Copy to display the File Copy screen. Chapter 4. Managing files 39 . To verify that the files exist. 3. Renaming files Use the following procedure to rename a file: 1. Select files by clicking the box adjacent to the file name. 6. 5. If you do not select this check box and the file already exists. 5. select the target directory. When the appliance reports success. Specify the name for the file. Specify the name of the file in the New File Name field. Click Confirm Copy to copy the files to the target directories. 3. Refer to “Launching the File Management utility” on page 35 for details. 8. 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. When the appliance reports success. use the procedure described in “Displaying directory contents” on page 35. select the Overwrite Existing Files check box. Click Move to display the Move File screen. Launch the File Management utility. 4. From the New Directory list. the file is not moved. Click Rename to display the File Rename screen. 2. Launch the File Management utility. 9. Navigate to the directory that contains the files to be moved. 2. click Continue to return to the File Management screen. 2. To verify that the files exist. From the New Directory Name list. if different. Click Confirm Rename. check the Overwrite Existing Files check box. 7. 6. Launch the File Management utility. 7. the file is not copied. The target directories now contain the renamed files. Refer to “Launching the File Management utility” on page 35 for details. Navigate to the directory that contains the files to be copied. If you do not select this check box and the file already exists. Refer to “Launching the File Management utility” on page 35 for details. Select files by clicking the box adjacent to the file name. If you do not select this check box and the file already exists. Navigate to the directory that contains the files to be copied. The target directories now contain the copied files. 6. 4. If one of the selected files already exists in its associated target directory and you want to overwrite this file. in the New File Name field. 8.1. 4. click Continue to return to the File Management screen. 5. 3. select the target directory. 5. 3. use the procedure described in “Displaying directory contents” on page 35. click Continue to return to the File Management screen. The selected files were deleted. Navigate to the directory that contains the files to be edited. Select files by clicking the box adjacent to the file name. 7. Refer to “Launching the File Management utility” on page 35 for details. The WebGUI displays a file preview. Editing files Use the following procedure to edit a text file: 1. 4. 6. When the appliance reports success. use the procedure described in “Displaying directory contents” on page 35. close the browser. When the appliance reports success. click Close to return to the File Management screen. Refer to “Launching the File Management utility” on page 35 for details. Scroll to the top or bottom of the screen and click Delete to display the Delete File screen. Click Confirm Move. Navigate to the directory that contains the files to be deleted. 8. To verify that the files exist. Refer to “Launching the File Management utility” on page 35 for details. 3. Launch the File Management utility. 40 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide . Select the file to be edited by clicking Edit in the row that is associated with that file. Click Submit to complete the edit process. 4. Viewing files Use the following procedure to view a text file: 1. Click the file to open a browser that contains the file. Click Edit to change to Edit Mode. Navigate to the directory that contains the file.7. To verify that the files no longer exist. The target directories now contain the moved files. click Continue to return to the File Management screen. Launch the File Management utility. Edit the file as required. 3. 2. Deleting files Use the following procedure to delete a file: 1. When finished viewing the file. Click Confirm Delete to delete the files. 5. 2. 6. When the appliance reports success. Launch the File Management utility. 2. To place the object in an inactive administrative state. This behavior is equivalent to importing the configuration one time. When retrieving the configuration file. Click the name of an existing Include Configuration File object to edit it. 5. Retain the default setting for the Admin State toggle. For example. 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. an Import Configuration File object is a configuration package that can include both configuration information and supporting files. The configuration is marked external and cannot be saved to the startup configuration. An Include Configuration File object can include configuration information only. Managing the configuration of the appliance This chapter provide information about managing the configuration of application domains and importing and exporting configurations. Use the Execute on Startup toggle to indicate whether to import the configuration package at startup. To append configuration information from an external file to the local configuration information. 2002. select when to retrieve the configuration file with the Interface Detection toggle. firmware reload. off (Default) Retrieves the configuration file at appliance reload without waiting for the local interface to be up. perform the following procedure: 1. 7. click disabled. 3. on (Default) Imports the configuration package at startup. or click Add to create a new one. The Include Configuration File configuration screen is displayed. Select Objects → Configuration Management → Include Configuration File to display the catalog.cfg. The configuration is not marked external and can be saved to the startup configuration.com/datapower/ firewalls. off on Retrieves the configuration file after the local interface is up. Specify a descriptive object-specific summary in the Comment field. This external file can be stored on a centralized configuration server or another DataPower appliance. This behavior is equivalent to always importing the configuration. specify https://config.Chapter 5. 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. 6. Imports the configuration package when manually triggered. 2. 2009 41 . On the other hand. © Copyright IBM Corp.server. Specify the URL of the configuration file in the URL of Configuration File field. Specify the name of the object in the Name field. 4. 8. or domain restart). off Does not import the objects if an objects of the same name exists.zip. Click the name of an existing configuration package to edit it. If the format is ZIP. Use the Overwrite Objects toggle to control the overwrite behavior. 2. the bundle is unzipped automatically. 7. The Import Configuration File configuration screen is displayed. 6. specify https://config. Specify the URL of the configuration package in the URL of Configuration Package field. Note: Unless you click Save Config. Select the package format from the Format of Configuration Package list. To place the object in an inactive administrative state. HTTPS. 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. Use the Overwrite Files toggle to control the overwrite behavior.server.9. For example.com/datapower/ firewalls. on (Default) Overwrites files of the same name. The default configuration of an Import Configuration File object does not provide warnings about conflicts with existing files and objects. Specify the name of the object in the Name field. Optionally. Select Objects → Configuration Management → Import Configuration File to display the catalog. 8. HTTP. off Does not import the file if a file of the same name exists. click Save Config to save the object to the startup configuration. firmware reload. 5. 10. XML Indicates that the configuration package in XML format. Retain the default setting for the Admin State toggle. the included configuration file will not take affect when the appliance is started. for example. An Import Configuration File object is a configuration package that can include both configuration information and supporting files. or domain restart). 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. click disabled. perform the following procedure: 1. Click Apply to save the object to the running configuration. 4. All other URL protocols are available. On the other hand. ZIP (Default) Indicates that the configuration package is in ZIP format. To import a configuration package from an external file to the local configuration information. 3. or click Add to create a new one. 42 on (Default) Overwrites objects of the same name. The external file can be stored on a centralized configuration server or another DataPower appliance. 9. Note: You cannot use the SCP or SFTP protocol to retrieve a configuration package. Specify a descriptive object-specific summary in the Comment field. IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide . or FTP. an Include Configuration File object can include configuration information only. You can optionally download the file to your workstation. 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. 14. off Retains the original IP address in the configuration package. Between releases. You can use this utility to perform the following operations: v Create a backup of the entire appliance v Create a backup of one or more application domains v Export select objects from the current domain v Copy or move select objects between domains Note: The following objects are never exported: v User account objects v Certificate objects v Key objects (HSM appliances only) The following files are never exported: v Log files v Firmware files Chapter 5. The configuration is marked external and cannot be saved to the startup configuration. Note: Exported configuration data should not be imported to an appliance with an earlier release level. Optionally. Imports the configuration package when manually triggered. click Save Config to save the object to the startup configuration. Therefore. the operation might report success. on (Default) Rewrites IP addresses to match the local configuration when imported. For more information. 11. Use the Import on Startup toggle to indicate whether to import the configuration package at startup. (Optional) Select a deployment policy that preprocesses the configuration package from the Deployment Policy list.10. a service in the configuration package that binds to eth1 is rewritten to bind to eth1 when imported. 13. This behavior is equivalent to importing the configuration one time. 12. configuration data for properties can change. For example. use this utility to exchange configuration data among appliances of the same release level. on (Default) Imports the configuration package at startup. Managing the configuration of the appliance 43 . This behavior is equivalent to always importing the configuration. Use the Local IP Rewrite toggle to indicate whether to rewrite local IP addresses on import. refer to “Configuring deployment policies” on page 54. Click Apply to save the object to the running configuration. If you attempt to import configuration data from an appliance of a later release level into an appliance of an earlier release level. The configuration is not marked external and can be saved to the startup configuration. but the configuration data might not be the same. or modify a configuration during import. Click Next. 1. 3. the file is in the export: directory. 4. 3. follow this procedure: 1. select Administration → Configuration → Export Configuration to display the initial Export Configuration screen. Click Done to close this window and return to the Control Panel. Select Create a backup of one or more application domains and click Next to display the selection screen. To start a back up or export operation. c. use the admin account. b. filter. 2. filter. Backing up domains Best practice is to periodically back up all domains individually. Optionally create or select the name of a Deployment Policy to accept. Specify a descriptive object-specific summary in the Comment field. The configuration of the entire appliance is backed up. Optionally click Download to download the file to your workstation. Optionally create or select the name of a Deployment Policy to accept. Specify a descriptive object-specific summary in the Comment field. Note: The Import Configuration utility requires that the export file resides on your workstation. Select Administration → Configuration → Export Configuration to display the Initial Export Configuration screen. or modify a configuration during import. The export file can be accessed from the export: directory. 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. Provide the following inputs: a. d. Select Administration → Configuration → Export Configuration to display the Initial Export Configuration screen. Select Create a backup of the entire system and click Next to display the File Name screen. a. To back up configuration information for one or more application domains. the export file is on your workstation. 2. it is overwritten. If a file of this name exists in the export: directory. When the backup completes.To ensure that all other objects and files are exported. For any other user. b.zip). 44 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide . The Export File Name defaults to export (. only objects and files that are accessible to that user are included in the export package. You can optionally download the export file to your workstation. If downloaded. Use the Configuration radio button to specify the data to export.c. ZIP Bundle Exports configuration data in compressed ZIP format. 5. The Export File Name defaults to export (. Specify a descriptive object-specific summary in the Comment field. the export file is on your workstation. they are not included. The Export File Name defaults to export (. Select Export configuration and files from the current domain and click Next to display the Export Configuration screen. Use the To radio buttons to specify the export format. f.zip). Include Configuration files are in the bundle. d. Exporting select objects The Export Configuration utility remains available from the initial Export Configuration screen. not the startup configuration. Select Administration → Configuration → Export Configuration to display the Initial Export Configuration screen. d. If downloaded. Currently running configuration Exports the configuration data from the running configuration. e. XML Config Exports configuration data as XML files. You can optionally download the export file to your workstation. Chapter 5. 3. filter. 2. Click Done to close this window and return to the Control Panel. e. not the current running configuration. Optionally click Download to download the file to your workstation. Managing the configuration of the appliance 45 . it is overwritten. Provide the following inputs: a. Last persisted configuration Exports the configuration data from the startup configuration. If a file of this name exists in the export: directory. If a file of this name exists in the export: directory. Include Configuration files are referenced in the XML document only. Note: The Import Configuration utility requires that the export file resides on your workstation. The export file can be accessed from the export: directory. 4. Select the check boxes adjacent to each domain to export. the file is in the export: directory. To export select objects and files. c. Use the Referenced Objects radio buttons to specify the scope of the data to export. use the following procedure: 1. Optionally create or select the name of a Deployment Policy to accept. Click Next When the backup completes. or modify a configuration during import. it is overwritten.xml or . Include only the selected base objects Exports only the configuration data for the selected objects.zip depending on the selected export format). b. i. j. g. the file is in the export: directory. When the backup completes. for example. if necessary. select objects in combination with the Shift and Control keys. Click Next. the export includes configuration data for the XSL Proxy. 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. For example. Note: The Import Configuration utility requires that the export file resides on your workstation. You can optionally download the export file to your workstation. and keys. From the Objects list. the selected objects use files. Export no files No files are included in the export. 1) Select the objects from the left-hand list. Adjust the Selected Base Objects list. such as a style sheet. Export files referenced by exported objects In addition to the selected objects (and possibly referenced objects). select objects in combination with the Shift and Control keys. exports public files that are associated with the selected objects. and all associated matching rules. Optionally click Download to download the file to your workstation. Use the Export Files radio buttons to specify the scope of the data to export. select the type or class of configuration data to export. if exporting an XSL Proxy. 5. cryptographic certificates. processing policies. These files are in the cert: and sharedcert: directories.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. 2) Click < to remove the selected objects or click <<to remove all objects from the Selected Base Objects list. the assigned XML manager. 2) Click > to move the selected object to the Selected Base Objects list. To select multiple objects. all instances of that type or class are listed in the left-hand box. This option is useful when the configuration data itself is all that is needed. To select multiple objects. 4. credentials. Click Done to close this window and return to the Control Panel. k. those files are not included. 1) Select objects in the right-hand list. Click Show Contents at any time to display all contents marked for inclusion in the export. Note: The export does not include private files. After selecting an entry. 46 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide . processing rules. If. The export file can be accessed from the export: directory. processing policies. Export no files No files are included in the export. off Indicates a copy operation. Use the Delete After Export toggle to indicate whether the operation is a copy operation or a move operation. if exporting an XSL Proxy. for example. These files are in the cert: and sharedcert: directories. processing rules. d. Chapter 5. such as a style sheet. b. those files are not included. If. e. To copy or move selected objects and files. and keys. on Indicates a move operation. credentials. not the current running configuration. Managing the configuration of the appliance 47 . the assigned XML manager. Include only the selected base objects Exports only the configuration data for the selected objects. Copying or moving select objects The copy or move utility is available from the initial Export Configuration screen. c. For example. Select Administration → Configuration → Export Configuration to display the Initial Export Configuration screen. Use the Configuration radio button to specify the data to export. Currently running configuration Exports the configuration data from the running configuration. or modify a configuration during import. Last persisted configuration Exports the configuration data from the startup configuration. cryptographic certificates. 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. exports public files that are associated with the selected objects. 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). Use the Export Files radio buttons to specify the scope of the data to export. the selected objects use files. Select Copy or move configuration and files between domains and click Next to display the Export Configuration screen. a. the export file is on your workstation. the export includes configuration data for the XSL Proxy. Optionally create or select the name of a Deployment Policy to accept. If downloaded. Note: The export does not include private files. Use the Referenced Objects radio buttons to specify the scope of the data to export. 2. use the following procedure: 1. not the startup configuration. filter. and all associated matching rules. You can save up to the allowed number of configuration checkpoints. 48 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide . 6. select objects in combination with the Shift and Control keys. a. the administrator who is associated with the admin account defines the number of configuration checkpoints to allow. 3. From the Domain list. Click Next to display the Import File window. 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. b. To define the number of checkpoint to allow for an existing domain. use the following procedure: 1. From the Objects list. if necessary. g. 4. When saved. a ZIP formatted file for the configuration checkpoint is written the chkpoints: directory for that application domain. all instances of that type or class are listed in the left-hand box. might be equivalent to the running configuration. 1) Select the objects from the left-hand list. 2) Click < to remove the selected objects or click <<to remove all objects from the Selected Base Objects list. Click Show Contents at any time to display all contents marked for inclusion in the export. or might be different from the persisted configuration or running configuration. To select multiple objects. select the domain where the configuration data is to imported. After selecting an entry. select the type or class of configuration data to export. Respond to WebGUI prompts. Click Done to close the Import File screen. 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. Adjust the Selected Base Objects list. The configuration checkpoint might be equivalent to the persistent configuration. Click Import to initiate file transfer. Managing configuration checkpoints A configuration checkpoint contains configuration data from a specific point in time.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. Select Administration → Configuration → Application Domain to display the Application Domain catalog. Within each application domain. To select multiple objects. 5. 1) Select objects in the right-hand list. 4. refer to “Deleting configuration checkpoints” on page 50. The default is 3. 2.2. Click Save Checkpoint. 4. use the following procedure: 1. A ZIP-formatted configuration file of the specified name is written to the chkpoints: directory. Saving configuration checkpoints Do not click Save Config to save a configuration checkpoint. Chapter 5. Optionally. This section of the screen provides the following actions: Rollback Loads the configuration that is defined in the configuration checkpoint. select Administration → Configuration → Configuration Checkpoints. For details. To save a configuration checkpoint. 3. Select the File Management icon from the Control Panel. 3. Specify the name of the configuration checkpoint in the Checkpoint Name field. 2. Click Apply to save the object to the running configuration. Select Administration → Configuration → Configuration Checkpoints. Expand the chkpoints: directory. refer to “Comparing configurations” on page 52. Managing the configuration of the appliance 49 . Use an integer in the range of 1 through 5. Select the Configuration tab. 5. Listing from the File Management utility To view from the File Management utility. You cannot overwrite a configuration checkpoint. This screen displays the list of saved configuration checkpoints at the time by name and timestamp. For details. 6. Select the specific application domain to open the domain-specific configuration screen. This button does not allow you the option of saving a configuration checkpoint. click Save Config to save the object to the startup configuration. Respond to WebGUI prompts. use the following procedure: 1. You must first delete the original configuration checkpoint before saving a new configuration checkpoint of the same name. Compare Launches the Compare Configuration utility. Specify the number of checkpoint configuration to allow in the Configuration Checkpoint Limit field. Remove Deletes the checkpoint configuration from the chkpoints: directory. 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. Expand the chkpoints: directory. Note: Exported configuration data should not be imported to an appliance with an earlier release level. v Add. Select Administration → Configuration → Configuration Checkpoints. Select the check box beside the configuration checkpoint file. 50 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide . use the following procedure: 1. use this utility to exchange configuration data among appliances of the same release level. 3. If you attempt to import configuration data from an appliance of a later release level into an appliance of an earlier release level. use the following procedure: 1. Respond to WebGUI prompts. Click Remove. modify or delete values in the configuration package being imported whose values match the defined match statement in a Deployment policy with the Use Deployment Policy list (optional). 3. Therefore. Deleting from the File Management screen To delete from the File Management screen. Importing configuration data The import utility copies specified configuration data from your workstation to the DataPower appliance. 2. Select the File Management icon from the Control Panel. This screen displays the list of saved configuration checkpoints at the time by name and timestamp. 2. While importing a configuration. use the following procedure: 1. 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). Between releases. configuration data for properties can change. the operation might report success. 2. Click Rollback. Click Delete. 3. but the configuration data might not be the same. Respond to WebGUI prompts. This screen displays the list of saved configuration checkpoints at the time by name and timestamp. Select Administration → Configuration → Configuration Checkpoints. 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. 5. Respond to WebGUI prompts.Rolling back to a configuration checkpoint To load the configuration that is defined in the configuration checkpoint. 4. Select Administration → Configuration→ Import Configuration to display the Import Configuration window. Only selected items are imported. it will be created. Retain the selection of (none) for the Use Deployment Policy list. 4. 1. Click Next to display the Import Object Selection List window. Click Browse to select the file to import. e. 6. Note: Warnings can appear on this screen that alert you to a range of possible conflicts that the imported configuration might cause. For more information. Chapter 5. use the admin account. a. To select all domains. Select each item to overwrite. or you might want to choose not to overwrite objects or files. click None. When importing from any domain other than default. Click Import to initiate file transfer. Click Next to display the Import Summary window. The WebGUI might display an error message when importing data that was exported from the default domain. click None. If a selected domain does not exist on the appliance. ZIP Bundle Imports configuration data in compressed ZIP format. The appliance to be restored must also first be re-initialized through the command line. Use the From radio buttons to specify the import format. d. the summary might indicate differences in file versions. Select the desired domains. To effectively complete an appliance import (restore). the imported configuration applies only to the current domain. click All. skip to step 6c on page 52. Note: Click Save Config to save the configuration for each domain that contains imported objects or files. which details the contents of the target file. off Does not allow local IP addresses to be rewritten. 5. Retain the selection of the File radio button. you might want to create a new application domain. as indicated. If there are no objects in the configuration you are importing. click All. 2. To deselect selected domains. Select the objects to import. To deselect selected items. c. In some cases. To select all item. a. modify or delete values in a configuration package is to use a Deployment policy while importing the configuration package. Click Next to display the Select Application Domains for Import window.Best practice when the goal is to add. Depending on the warning. refer to the “Configuring deployment policies” on page 54. Managing the configuration of the appliance 51 . 3. XML Config Imports configuration data as XML files. b. b. Use the Rewrite Local Service Addresses toggle to control whether to substitute IP addresses: on (Default) Allows local IP addresses to be rewritten. Use the following procedure to import configuration data. and from the To list. Domain Configuration The last saved or currently running domain configuration on the appliance. The source for each of the configurations can be one of the following: Persisted Configuration The last saved configuration on the appliance. you can compare either configuration to a saved version of the configuration. If more than one domain is being imported. Select Administration → Configuration → Compare Configuration to display the Configuration Comparison screen. 52 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide . select which configuration to be the second configuration source. the report provides a list of objects that changed between the two configurations and the changes that were made to these objects. which details the results. This file has a . This file has a . These saved versions of the configuration can be an exported configuration (XML format or ZIP format). c. a backup configuration (ZIP format only). This is the default in the To list. the WebGUI displays the Object Import Results window. This is the default in the From list. Click Done to close this window. select which configuration to be the first configuration source. 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. Generally.zip extension. 2. XML Configuration The XML file that was created during an export operation.xcfg extension. This file has an . Managing changes in configuration data You to create a report that lists the differences between two configurations. When you compare configurations. From the From list. or a configuration checkpoint. the two configurations that are being compared are the persisted configuration and the running configuration. the Import Summary window is displayed for the next domain to import. However. Backup ZIP Bundle A ZIP file that was created during backup operation. Export ZIP Bundle A ZIP file that was created during an export operation.At the completion of the import process.zip extension. Running Configuration The configuration that is currently running on the appliance. use the following procedure: 1. select the check box beside those objects. saved to a configuration checkpoint. This file has a . Reverting changes After running a comparison and reviewing the results. filter.zip extension and is in the chkpoint: directory. reverted to their original settings. specify or browse for and select the configuration file. Also. or modify a configuration. the results are displayed below the horizontal rule. use the object-specific configuration screens. When the source (From or To) is Checkpoint. Click Run Comparison to generate the report. select whether the report lists only changed objects between the configurations or all objects in the configurations. or Backup ZIP Bundle. 3. Click Undo Selected. To revert changes. When the source (From or To) is XML Configuration. Export ZIP Bundle. you can revert select changes or all changes between the two configurations. From the View list. click Select All. To revert changes to select properties for an object. Reading the change report After running a comparison. Managing the configuration of the appliance 53 . The default is changed objects only. create or select a deployment Policy that can be used to accept. v To revert all objects. Chapter 5. Review the report to determine whether these changes should be saved to the startup configuration. 6. select the checkpoint from the Checkpoint list. 2. You can revert changes at the property level only. use the following procedures: 1. 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. Determine which objects to revert: v To revert select objects. or a combination of these operations.Checkpoint A ZIP file that was created through a save checkpoint operation. 5. The change is one of the following values: v modified v added v deleted Beside each item is a check box. The results are displayed below the horizontal rule. 4. For example. you cannot delete certificates that are referenced by a validation credentials list until after the deletion of the validation credentials list itself. to always include resources that match. The processing sequence is as follows: 1.The results are displayed on a new screen. Depending on the clause type. To create a Deployment Policy object. the whitelist. v For details about manually specifying the statement. to always delete resources that match. Process the filtered configuration. use the following procedure: 1. You might need to run the comparison multiple times to delete referenced objects. When specifying the matching statement. If a selected object is a referenced object. refer to “Using the deployment policy builder” on page 55. Note: You cannot modify the administrative state of Deployment Policy objects. v Use a filtered configuration to delete resources in the package that match specified criteria. the blacklist. 2. 2. Process the accepted configuration. Changed Substitutes the value for the identified property during the import. Modified configurations support the following actions: Add Adds the property with the identified value during the import. Process the modified configuration to change the resources based on the defined action type. Select Objects → Configuration Management → Deployment Policy to display the catalog. v Use a modified configuration to modify resources in the package that match the specified criteria. Configuring deployment policies Deployment policies use fine-grained matching statements and clause types to control the inclusion of configuration data from imported configuration packages. it cannot be deleted until after the deletion of its parent object. 54 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide . and modified configurations that respectively include. refer to “Specifying the matching statement” on page 56. v For details about using the builder to define the statement. filtered. 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. Deleted Deletes the property during the import. Click Add to display the configuration screen. 3. or change configuration data in the configuration package during the import. delete. you can use the builder or manually specify the statement. Creating a Deployment Policy object A deployment policy is a sequence of accepted. e. specify the name of the property to add in the Configuration Property field. 6. Repeat this step to define another accept clause. Specify the matching statement for the modify clause in the Configuration Match field. 5. a. Optionally. 7.3. Add Configuration Adds a configuration setting. Define accept clauses. Specify the matching statement in the Accepted Configuration field. a. Specify the name of the object in the Name field. 4. Chapter 5. 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. or click Build. Delete Configuration Deletes a configuration setting. Click Save to return to the configuration screen. Click Add. or click Build. If adding or changing a configuration. or click Build. Repeat this step to define another filter clause. Define filter clauses. use the following procedure: 1. Click Apply to save the object to the running configuration. a. 8. Managing the configuration of the appliance 55 . click Build. Click Add to display the Modified Configuration property window. b. Change Configuration Changes a configuration setting. Specify a descriptive object-specific summary in the Comment field. 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. c. Select the type of configuration modification from the Modification Type list. f. If adding a configuration. Specify the matching statement in the Filtered Configuration field. 9. Click Add. b. specify the value of the property to add or modify in the Configuration Value field. Define modify clauses on the Modified Configuration tab. d. Click Build to open the builder. click Save Config to save the object to the startup configuration. Repeat this step to define another modify clause. b. 7. This property limits the matching statement to resources of the specified property. Optionally specify a name match for a resource in the Name Match (PCRE) field. 5. Specify the IP address or host alias in the Device Address field.org 56 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide . Name=resource-name Optionally specifies a name match for a resource. 8. resource Specifies the resource type. Property=property-name Optionally specifies the name of the configuration property. PCRE documentation is available at the following Web site: http://www. The selection (none) matches all domains. 3. This property limits the matching statement to resources of the specified property. Use a PCRE Match Expression to select groups of configuration property values. For example. domain Specifies the name of the application domain. The value * matches all IP addresses. The statement is added to the list of matching statements. The value * matches all IP addresses. This property limits the matching statement to resources of the specified value. Optionally specify the name of the configuration property in the Configuration Property field.pcre. This property limits the matching statement to resources of the specified name. Specifying the matching statement Instead of using the builder. This property limits the matching statement to resources of the specified property. Use a PCRE to select groups of resource instances. 6. Select the name of the application domain from the Application Domain list. Value=property-value Optionally specifies the value for the configuration property. This property limits the matching statement to resources of the specified name. Use a PCRE to select groups of resource instances. The value * matches all domains. Select the resource type from the Resource Type list. For example. you can manually specify the matching statement. foo* would match all resources with names that start with foo. Click Save. foo* would match all resources with names that start with foo. 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. Optionally specify the value for the configuration property in the Configuration Value Match (PCRE) field. 4. The select (all resources) matches all resource types. The value * matches all resource types.2. Click the Identify tab to define how to extract the identity. This counter should Measure type XPath to allow the AAA Policy to increment the counter on successful authorization. Rejected counter Optionally select a message-count monitor This object monitors and controls incoming messages rejected by this AAA Policy. Select Objects → XML Processing → AAA policy to display the AAA Policy catalog. 10. 12. Authorized counter Optionally select a message-count monitor. This object monitors and controls incoming messages authorized by this AAA Policy. SAML Signature Validation Credentials Optionally (and only if SAML-based identity extraction. This counter should Measure type XPath to allow the AAA Policy to increment the counter on rejected authorization. Optionally. Main tab Name Specify the name of the object. 9. click disabled. Optionally click the Namespace Mapping tab to define how to map namespaces. 5. Optionally click the Transaction Priority tab to define the priority of transactions. Optionally click the SAML Attributes tab to define SAML attributes. 14. 6. 2009 57 . Click the Map Credentials tab to how to map the credential. Use this screen to provide policy-wide. © Copyright IBM Corp. 3. 15.Appendix A. global configuration data. 13. Click Apply to save the object to the running configuration. To place the object in an inactive administrative state. Click Add to display the AAA Policy Configuration (Main) screen. 2. Optionally click the LTPA User Attributes tab to define LTPA user attributes. Admin State Retain the default setting. Comments Specify a descriptive object-specific summary. 11. Click the Authorize tab to define how to authorize the credential. Click Rejected Counter Tool to configure a counter for this purpose. click Save Config to save the object to the startup configuration. Optionally click the Post Processing tab to define post processing activities. Click the Authenticate tab to define how to authenticate the identity. 2002. Refer to “Count Monitor” on page 99 for more information. 8. 7. Click the Resource tab to define how to extract the resource. Referenced objects AAA Policy 1. authentication. Click the Map Resource tab to define how to map the resource. Refer to “Count Monitor” on page 99 for more information. 4. authentication. If the LDAP suffix is not an empty string. When configuring LDAP for authentication.dc=com. or authorization is used by this AAA Policy.dc=datapower.dc=com. Refer to “Defining Certificate objects” on page 13 for more information. rsa is same as rsa-sha1. SAML Message Signing Key Optionally if SAML-based identity extraction.and authorization is used by this AAA policy). RSA and DSA are supported by older releases. Log Allowed Level When Log Allowed set to on. select the matching crypto certificate — that is the public certificate associated with the private key designated by the SAML message signing key. Specify an LDAP base DN. The default is rsa. the AAA Policy builds an X. cn=Alice. authentication.509-compliant DN by prepending cn= to the surname and appending a comma followed by the value of the LDAP suffix. select the Crypto Validation Credentials used to validate digitally-signed SAML assertions from the Credentials list. or authorization is used by this AAA Policy. and dsa is same as dsa-sha1. Log messages generated for each access allowed by this AAA policy will be set at the level selected. the AAA policy provides the LDAP suffix. The default is sha1. change the level.500 DN (for example. Log messages generated for each access rejected by this AAA policy will be set at the level selected. Refer to “Working with Validation Credentials objects” on page 21 for more information. Hence. the AAA policy generates log messages at the indicated level for every access rejected. Set to off to change this behavior. it is typical to create a base DN (such as dc=datapower. LDAP Suffix Optional if LDAP authentication or authorization is used by this AAA policy. SAML Message Signing Algorithm Select the algorithm to sign SAML messages.dc=datapower. Set to off to change this behavior. the AAA policy generates log messages at the indicated level for every access allowed. SAML Signing Message Digest Algorithm Select the hash algorithm for SAML signing message. 58 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide .dc=com) and then create one entry under this base for each user. Log Allowed By default. Refer to “Defining Key objects” on page 16 for more information. the user name Alice is mapped to the DN cn=Alice. an LDAP suffix of dc=datapower. To make LDAP authentication more usable. LDAP-based authentication implementations require an X.dc=com) and a password. Set the LDAP suffix to the base name under which user entries are found. Log Rejected By default. select a crypto key used to sign SAML assertions. SAML Message Signing Certificate Optionally if SAML-based identity extraction. Log Rejected Level When Log Rejected set to on. change the default level. DoS Flooding-Attack Valve Specifies the number of times to perform the same XML processing per user request. SAML Artifact Mapping File This file contains a map of SAML artifact source identifiers to artifact retrieval endpoints. Enable Ping Identity compatibility when using SAML for authentication or authorization. LDAP Version Select the LDAP protocol version (2. To be sure log targets capture these AAA messages. At this time.0 metadata schema (xmlns:md="urn:oasis:names:tc:SAML:2.0 Metadata File This file contains information about the various SAML Authorities that might be used for SAML 2. SAML 2. the AAA Policy supports this property in the following cases: v Identity extraction when the method is Subject DN from Certificate in the Message’s signature v Authentication when the method is Validate the Signer Certificate for a Digitally Signed Message When used with the value of 1. the default version. the processing fails if the needed signature is not part of extracted identity. WS-Trust Encryption Recipient Certificate When generating a WS-Trust token for a secret key (such as a WS-SecureConversation token). the AAA Policy extracts the first signature and its first reference from the security header and ignores all other signatures or signing references. and click Upload to upload a file. it can be specified by the SAML artifact responder URL in the authentication phase. This property limits the number of times to perform the same XML processing per user request. select the key to encrypt the initial secret. During signature verification. the verification would fail. the more likely one or more log targets will catch the message.Note: Log targets capture messages at or above the level configured for the target. The higher the level. The file must conform to the SAML 2. However if the information was the second signing reference. Use a value in the range of 1 through 1000. message signing. or 3) used when accessing the authorization server.0:metadata"). If there is only one artifact retrieval URL. XML processing includes encryption. select a file. coordinate these levels. For example if dos-valve is 2 and the needed information to verify the signature was the third signing reference. This property is required only when artifacts will be retrieved from multiple endpoints and the source identifiers for these endpoints are encoded in the artifact itself (per the SAML specification). Ping Identity Compatibility Select whether to enable (on) or disable (off) Ping Identity compatibility. and signature validation.0 authentication and authorization. If the security header contains more signatures or a single signature contains more signing references. The default is 3. Referenced objects 59 . From the list. decryption. the verification would succeed. these signatures and signing references are ignored. Appendix A. for example. BinarySecurityToken element from WS-Security header The claimed identity of the requester is extracted from the WS-Security BinarySecurityToken element (using the token’s string value as the claimed identity) contained in a SOAP header. 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. there should be only one wsse:Security element having same actor/role. Use the Identity panel to specify the method or methods used by the AAA Policy to extract the identity claimed by the service requester.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. If selected. Click the Identity tab to display the AAA Policy Configuration (Identity) screen. specify the identifier. Use the check boxes to enable (on) or disable (off) one or more identification methods. The default is on. WS-SecureConversation Identifier The claimed identity of the requester is extracted from a WS-SecureConversation Identifier. and AAA should only process the wsse:Security header for the designated Actor/Role Identifier. 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. 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. we can enforce those attributes when AAA tries to use wsse:Security header. the WebGUI prompts for the following property: HTTP’s Basic Authentication Realm The name of the HTTP Basic Authentication Realm as described by RFC 2617. Continue with defining the identity extraction method. 60 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide . WS-Trust Base or Supporting Token The claimed identity of the requester is extracted from a WS-Trust Base or Supporting token. This setting takes effect for all AAA processing except post processing. WS-Sec Actor/Role Identifier When enforcing WS-Security Actor/Role. HTTP’s Authentication header The claimed identity of the requester is extracted from the HTTP Authorization header (name and password). HTTP Authentication: Basic and Digest Access Authentication. Name from SAML attribute assertion The claimed identity of the requester is extracted from a SAML assertion that contains a SAML attribute statement. Referenced objects 61 . If selected. 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 selected.Kerberos AP-REQ from SPNEGO token The claimed identity of the requester is extracted from a Kerberos AP-REQ contained in the SPNEGO token. SAML artifact The claimed identity of the requester is extracted from a SAML artifact. use the Subject DN extracted from the certificate associated with the signature as the claimed identity. If you require name spaces in the XPath expression. The name contained in the Subject element of the attribute statement is used as the claimed identity. if the signature is valid. If this is checked. Name from SAML authentication assertion The claimed identity of the requester is extracted from a SAML assertion that contains a SAML authentication statement. the Validation Credentials for Signing Certificate appears. LTPA Token The claimed identity of the requester is extracted from an LTPA (Lightweight Third Party Authentication) token value. The name contained in the Subject element of the authentication statement is used as the claimed identity. the WebGUI prompts for the following property: Validation Credentials for Signing Certificate Select the Validation Credentials List used to validate the presented certificate. The XPath expression is applied to the entire message. which are opaque Appendix A. LTPA tokens. Token extracted from the message The claimed identity of the requester is extracted using an XPath expression. Refer to “Defining Identification Credentials objects” on page 15 for more information. the Validation Credentials for Signing Certificate field is displayed. Subject DN from the certificate in the message’s signature The claimed identity of the requester is extracted from a certificate used to validate a digitally-signed message — verify the signature validity. Client IP address The client’s IP address is used for identity extraction. the WebGUI prompts for the following property: Cookie name Specify the cookie name. If selected. If this is checked. the XPath Expression field is displayed. If this is checked. the WebGUI prompts for the following property: XPath expression Provide the operative XPath expression. refer to “Namespace Mapping tab” on page 80 for procedural and configuration details. Token extracted as Cookie value The claimed identity of the requester is extracted from a Cookie value. the WebGUI prompts for the following properties: Host 62 Specify the IP address or domain name of the LDAP authentication server. Optionally. Use the Authenticate panel to designate the authentication method. an AAA Policy authenticates the claimed identity.signed and encrypted strings. Click Apply to commit AAA Policy properties. are carried via HTTP. If selected. Authenticate tab After extracting the claimed identity of the service requester. IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide . Bind to Specified LDAP Server (Default) The requester is authenticated by an LDAP server. select an authentication method. LTPA Key File Password and Confirm LTPA Key File Password Provides the cleartext password to the LTPA key file. specifically in the Set-Cookie response and Cookie request headers. Because the LTPA token must be decrypted before authentication. Custom template The claimed identity of the requester is extracted by a custom or proprietary identification resource (for example. Accept an LTPA token The requester is authenticated by an encrypted LTPA token. If selected. a style sheet). the WebGUI prompts for the following property values: LTPA Token Versions Specifies the LTPA formats supported for authentication purposes. Refer to Understanding LTPA for more information. If selected. 2. the WebGUI prompts for the following property: Custom URL Specify the local or remote URL of the identification resource. or all LTPA-based authentication will fail. From the Method list. Use the check boxes to specify the LTPA versions that are supported for authentication. Accept a SAML Assertion with a Valid Signature The requester is authenticated by a SAML assertion with a valid signature. Click the Authenticate tab to display the AAA Policy Configuration (Authenticate) screen. LTPA Key File Provide the name of the file that contains the cipher keys to be used for encryption and decryption. click Save Config to save the object to the startup configuration. Refer to Understanding LTPA for more information. 1. the following properties identify the needed cryptographic resources. Select at least one version. The authentication process can use internal or external resources. Port Specify the LDAP authentication server port number. In this case. the LDAP server returns the text in the specified LDAP attribute for the user in the UsernameToken. o=datapower. on Enables an LDAP search for the user’s group. LDAP Bind Password and Confirm LDAP Bind Password Specify and confirm the password for the LDAP bind operation. Refer to “Load Balancer Group” on page 101 for more information. authentication fails. 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. defaults to the canonical port number. LDAP queries will be load balanced in accordance with the settings in the group. LDAP Search Attribute Specify the name of the LDAP attribute that contains the cleartext password. Load balancing allows for failover. Retain the default value to use a non-SSL connection. If not supplied. This property is relevant when the Search for DN is off. off (Default) Disables an LDAP search for the user’s group. LDAP Prefix Optionally specify an LDAP Prefix name. This string is prepended to the identity extracted before submission to the LDAP server. LDAP Load Balancer Group Optionally select a Load Balancer Group. When specified. LDAP Suffix Optionally specify an LDAP Suffix name. For example. this property overrides the settings for the Host and Port properties. This suffix string is appended to the identity extracted before submission to the LDAP server. This property is relevant when the Search for DN is off. If you select a group. Referenced objects 63 . The login name of the user along with the LDAP prefix and the LDAP suffix will be used to construct the user’s DN. The login name of the user along with the LDAP Search Parameters will be used as part of an LDAP search to retrieve the user’s DN. SSL Proxy Profile Select an SSL Proxy Profile to provide a secure connection to remote authentication server.com. LDAP Bind DN Specify the Distinguished Name for the LDAP bind operation. Appendix A. The default is cn=. If the hashed value of the returned text does not match the value in the <Password> element. Search for DN Indicate whether to perform an LDAP search retrieve the DN of the user. The default is userPassword. Refer to “Defining an LDAP Search Parameters object” on page 100 for detail. The DataPower appliance sends an entropy element to the WS-Trust server as part of the security token request exchange. Require Client Entropy Indicates whether to require client entropy as key material in the WS-Trust request. v If off. When required. SSL Proxy Profile Select an SSL Proxy Profile to provide a secure connection to remote authentication server. The version selected affects the format of the messages sent to SAML authorities.0. SSL Proxy Profile Select an SSL Proxy Profile to provide a secure connection to remote authentication server. 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 displays the following field. Use the WS-Trust Encryption Certificate property to determine how to include the key material in the request.v If on. SAML Version Select the SAML version used for authentication. 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.0 are supported. Retain the default value to use a non-SSL connection. If selected. off (Default) Does not require client entropy. not for AAA authentication. 1. Versions 1. LDAP Search Parameters Select the LDAP Search Parameters from the list. the WebGUI prompts for the following properties: SAML Authentication Query Server Specify the URL of the SAML Authentication Query Server that can authenticate the requesting entity and supply a SAML Authentication Assertion. Retain the default value to use a non-SSL connection. The following properties are relevant for attaching WS-Policy.1 and 2. specify the size of the client entropy in bytes in the Client Entropy Size field. The size refers to the length of the 64 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide . on Requires client entropy. 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. specify the value for the AppliesTo header in the AppliesTo Header field. Require AppliesTo SOAP Header Indicates whether to generate a WS-Addressing AppliesTo header as part of the security token request exchange. Retain the default value to use a non-SSL connection.client entropy before Base64 encoding. SSL Proxy Profile Select an SSL Proxy Profile to provide a secure connection to remote authentication server. Require Server Entropy Indicates whether to require server entropy in the WS-Trust response. When required. off (Default) Does not generate a WS-Addressing AppliesTo header. the WebGUI prompts for the following properties: ClearTrust Server URL Provide a local or remote URL that locates the authentication resource. WS-Trust Encryption Certificate Optionally select a Crypto Certificate to encrypt WS-Trust elements in the request. Use an integer in the range of 8 through 128. When required. off (Default) Generates a WS-Trust RequestSecurityToken. The default is 32. on Requires server entropy. Contact Netegrity SiteMinder The requester is authenticated by a Netegrity server. Use an integer in the range of 8 through 128. the WS-Trust BinarySecret element contains the entropy material. off (Default) Does not require server entropy. If blank. he public key of the certificate encrypts the client entropy key material for the recipient. The default is 32. on Generates a WS-Trust RequestSecurityTokenCollection. the WebGUI prompts for the following properties: Appendix A. If selected. In this case. The WS-Trust server must return an entropy element to the DataPower appliance as part of the security token request exchange. Contact ClearTrust Server The requester is authenticated via a ClearTrust server. on Generates a WS-Addressing AppliesTo header. Referenced objects 65 . If selected. specify the minimum allowable size of the received entropy material in bytes in the Server Entropy Size field. use an SSL Proxy Profile to secure the message exchange with the WS-Trust server. Require RequestSecurityTokenCollection Indicates whether to generate a WS-Trust RequestSecurityToken or a WS-Trust RequestSecurityTokenCollection as part of the security token request exchange. The size refers to the length of the client entropy before Base64 encoding. The version selected affects the format of the messages sent to SAML authorities. Retrieve SAML Assertions Corresponding to a SAML Browser Artifact The requester is authenticated by a SAML artifact. Contact NSS for SAF Authentication The requester is authenticated by the SAF. Pass Identity Token to the Authorize Step The requester is not authenticated by this AAA policy. A Tivoli Access Manager object must exist and be in an enabled state for this method to succeed. Contact Tivoli® Access Manager The requester is authenticated by a Tivoli Access Manager. the WebGUI prompts for the following property: Custom URL Provide a local or remote URL that locates the authentication resource. a style sheet).0 are supported. 1. Refer to “IBM Tivoli Access Manager” on page 88 for more information. 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. the request is passed to the authorization server for disposition. SSL Proxy Profile Select an SSL Proxy Profile to provide a secure connection to remote authentication server. SAML Version Select the SAML version used for authentication. 66 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide .0. If selected. Custom Template The requester is authenticated by a custom/proprietary resource (for example. Retain the default value to use a non-SSL connection. SSL Proxy Profile Select an SSL Proxy Profile to provide a secure connection to remote authentication server. SAML 2 Issuer Specify a value that appears in the SAML <samlp:Issuer> element after the SAML Artifact has been authenticated. Netegrity Base URI Specify the appropriate URI string. Versions 1. Refer to “z/OS NSS Client” on page 144 for more information. 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. Port Specify the Netegrity authentication server port number. Retain the default value to use a non-SSL connection.Host Specify the IP address or domain name of the Netegrity authentication server.1 and 2. This element is included in the information delivered to the Authorize phase. If selected. If selected. To identify a local resource. The following inputs are displayed for all methods.xml. Use DataPower AAA Info File The requester is authenticated by an XML file. To examine a sample AAA Info file. If selected. the WebGUI prompts for the following property: SSL Client Validation Credentials Select the Validation Credentials List used to validate offered client certificates. This field is required. Use specified RADIUS Server The requester is authenticated by a RADIUS server. Refer to “Working with Validation Credentials objects” on page 21 for more information. If selected. open store:///authfile.Use an Established WS-SecureConversation Security Context The requester is authenticated by a WS-SecureConversation token contained in the request. the WebGUI prompts for the following properties: Kerberos principal name Provide the name part of the server identity. Referenced objects 67 . the WebGUI prompts for the following properties: AAA Info File URL Specify the location of the XML file used for authentication purposes. XPath Expression Use the specified XPath expression. If selected. Validate the SSL Certificate from the Connection Peer The requester is authenticated via its client SSL credentials. User certificate from BinarySecurityToken The requester is authenticated by a certificate that is included with a BinarySecurityToken. the WebGUI prompts for the following property: X. If selected. Validate the Signer Certificate for a Digitally Signed Message The signature requires validation. Refer to “Working with Validation Credentials objects” on page 21 for more information. Appendix A. 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.509 BinarySecurityToken Validation Credentials Select the Validation Credentials to validate the X. Kerberos keytab Select the Kerberos Keytab File object. use the form store:///authfile.509 certificate in the BinarySecurityToken. This value is the server name that is contained in the sname field of the unencrypted portion of the Kerberos ticket.xml. the WebGUI prompts for the following properties: Signature Validation Credentials Use a Validation Credentials List. Cache authentication results Select the caching strategy. To perform such credentials mapping. mapping an authenticated account name/password to an LDAP group. Click the MapCredentials tab to display the AAA Policy Configuration (Map Credentials) screen. authentication information is removed from the cache. the WebGUI prompts for the following property: Custom URL Provide a local or remote URL that locates the mapping resource. Otherwise. Credentials from Tivoli Federated Identity Manager The authentication credentials are mapped by Tivoli Federated Identity Manager (TFIM). Click Apply to commit AAA Policy properties. It might be necessary to map credentials presented by an authentication method to a format congruent with a different authorization method. 3. a style sheet). If selected. which you identify during policy definition. Disabled Disables caching of authentication data Maximum Compares the explicit TTL with the received TTL (if any). Otherwise. By default. select a credentials mapping method. 4. Cache Lifetime Specify the explicit TTL in seconds. If selected. Use the data-specific TTL if it is less than the explicit TTL. Optionally. use the explicit value. On authentication failure. specified by the Cache Lifetime property. This defaults to 3. Absolute (Default) Caches all authentication data with an explicit TTL (time-to-live). use the Map Credentials panel to designate the mapping method and resource. From the Method list. use the explicit value. None Authentication credentials are not mapped. Use the data-specific TTL if it is greater than the explicit TTL. If credentials mapping is necessary. Custom The authentication credentials are mapped by a custom/proprietary resource (for example. for example. Minimum Compares the explicit TTL specified by the Cache Lifetime property with the received TTL (if any). 1. Map Credentials tab After receiving authentication credentials. the WebGUI prompts for the following property: 68 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide . authentication information from remote resources is cached for a period of three seconds. 2. click Save Config to save the object to the startup configuration. an AAA Policy can optionally map these credentials. an AAA Policy uses custom XML or XPath resources. Open store://authfile. This URL has not been rewritten. click Save Config to save the object to the startup configuration. an AAA policy identifies the specific resource being requested by that client. To identify a local resource. 4. Optionally. AAA Info File The authentication credentials are mapped using an XML file as the mapping resource. 2. the WebGUI prompts for the following property: AAA Info File URL Specify the location of the XML file used for authentication purposes. the WebGUI prompts for the following property: XPath Expression Specify the operative XPath expression. The URL can be rewritten by a URL Rewrite Policy attached to the service or by another processing action before the AAA Policy. Credentials from WS-SecureConversation Token The authentication credentials are mapped via a WS-SecureConversation exchange. 3. use the form store:///authfile. If selected. URL sent by client The identity of the requested resource is extracted from the original URL sent by the client. 1. Use the Resource panel to designate the methods used to identify the resource requested by an authenticated client. Refer to “IBM Tivoli Federated Identity Manager” on page 90 for more information.xml to examine a sample AAA Info file.TFIM Configuration Select an existing TFIM object. Resource tab After authenticating a client. Apply XPath Expression The authentication credentials are mapped using an XPath expression as the mapping resource.xml. If selected. Use the check boxes to enable (on) or disable (off) one or more resource identification methods. Referenced objects 69 . Click the Resource tab to display the AAA Policy Configuration (Resource) screen. Click Apply to commit AAA Policy properties. URL sent to back end The identity of the requested resource is extracted from the (possibly rewritten) URL sent to the server. URI of toplevel element in the message The identity of the requested resource is extracted from the namespace of the top level application element Local name of request element The identity of the requested resource is extracted from the simple name of the top level application element Appendix A. Click Apply to commit AAA Policy properties.xml. 4. Click Apply to commit AAA Policy properties. From the Method list. 3. Click the Map Resource tab to display the AAA Policy Configuration (Map Resource) screen. 2. select a resource mapping method. the WebGUI prompts for the following property: AAA Info File URL Specify the location of the XML file used for authentication purposes. If selected. To identify a local resource.xml. 1. None Identified resources are not mapped. AAA Info File The identified resource is mapped using an XML file as the mapping resource. the WebGUI prompts for the following property: XPath Expression Specify the operative XPath expression. it might be necessary to map extracted resource identities to a form compatible with the authorization method. the WebGUI prompts for the following property: Custom URL Provide a local or remote URL that locates the mapping resource. If selected. click Save Config to save the object to the startup configuration. click Save Config to save the object to the startup configuration. use the Map Resource panel to designate the mapping method. 3. If selected. Optionally. 4. the WebGUI prompts for the following property: XPath Expression Specify the operative XPath expression.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. 70 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide . To examine a sample AAA info file. open store:///authfile. Apply XPath Expression The identified resource is mapped using an XPath expression as the mapping resource. If selected. Map Resource tab After identifying the requested resource. use the form store:///authfile. Custom The identified resource is mapped by a custom/proprietary resource (for example. Optionally. a style sheet). If resource identity mapping is necessary. an AAA Policy next authorizes the client. Retain the default value to use a non-SSL connection. If selected. Load balancing allows for failover when using LDAP for authorization. If selected. the WebGUI prompts for the following properties: Host Specify the IP address or domain name of the LDAP authentication server. LDAP Bind DN Specify the Distinguished Name for the LDAP Bind. The authorization process can use internal or external resources. defaults to the canonical port number. LDAP Load Balancer Group Optionally select a Load Balancer Group. 1. a style sheet). LDAP Bind Password and Confirm Bind Password Specify and confirm the password for the LDAP Bind. Use the Authorize panel to designate the authorization method. Contact ClearTrust Server The requester is authorized via a ClearTrust server. the WebGUI prompts for the following property: Custom URL Specify a local or remote URL that locates the authorization resource. Allow Any Authenticated Client Any authenticated used is authorized. Appendix A. Click Authorize to display the AAA Policy Configuration (Authorize) screen. From the Method list. SSL Proxy Profile Select an SSL Proxy Profile to provide a secure connection to remote authorization server. Group DN Specify the Distinguished Name of the LDAP group. If not specified. 2. that is. Referenced objects 71 . select an authentication method. Check for Membership in an LDAP Group The requester is authorized by an LDAP server. If selected. determines if the authenticated service requester is allowed access to the requested resource. the WebGUI prompts for the following properties: ClearTrust Server URL Specify a local or remote URL that locates the authorization resource. Custom Template The requester is authorized by a custom/proprietary resource (for example. If a group is selected.Authorize tab After authenticating a service requester and extracting the identity of the requested resource. Port Specify the LDAP authentication server port number. LDAP queries will be load balanced in accordance with the settings in the group. Netegrity Base URI Specify the appropriate URI string. SSL Proxy Profile Select an SSL Proxy Profile to provide a secure connection to remote authorization server. LDAP Search Scope Select the depth of the LDAP search.LDAP Group Attribute Specify a GroupAttribute string. Contact NSS for SAF Authorization The requester is authorized by the SAF. Port. Netegrity Operation Name Extension The Netegrity Base URI is combined with the Host. If selected. The String Representation of LDAP Search Filters. Retain the default value to use a non-SSL connection. 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. SSL Proxy Profile Select an SSL Proxy Profile to provide a secure connection to remote authorization server. The authorizing identity must be presented as the value that corresponds to the attribute. LDAP filter syntax is defined in RFC 2254. Contact Netegrity SiteMinder The requester is authorized by a Netegrity server. If selected. Port Specify the Netegrity authorization server port number. and Netegrity Operation Name Extension configuration items to form the URL for attempting Netegrity authentication. the WebGUI prompts for the following properties: 72 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide . the WebGUI prompts for the following properties: Host Specify the IP address or domain name of the Netegrity authorization server. Retain the default value to use a non-SSL connection. The URL is of the following form: http://Host:Port/NetegrityBaseURI/operationNetegrityOpNameExtension where NetegrityOpNameExtension is directly appended to the operation name. z/OS NSS Client Configuration Select the z/OS NSS Client object that specifies the details for connecting to the NSS server. 1.1 and 2. Refer to “z/OS NSS Client” on page 144 for more information. SAML Match Select the minimum authorization criteria. Versions 1. SAML Name Qualifier Optionally specify the value of the NameQualifier attribute of the NameIdentifier in the generated SAML query. the WebGUI prompts for the following properties: URL Specify the location of the SAML server. Appendix A. The default is r (Read). Some SAML implementations require this value to be present. If selected.0. 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. SAML Version Select the SAML protocol version to use when employing SAML for authorization. The version selected affects the format of the messages sent to SAML authorities.0 are supported. specify the operative XPath expression. Generate a SAML Attribute Query The requester is authorized by a SAML attribute query/response exchange between the DataPower appliance and a SAML server. Referenced objects 73 . 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. a (Alter) c (Control) r (Read) u (Update) Always Allow All messages are forwarded to the backend server. Default Action Select the default action to specify the access level to the resource. SAML Version Select the SAML protocol version to use when employing SAML for authorization. Some SAML implementations require this value to be present. specifies the operative XPath expression SAML Name Qualifier Optionally specify the value of the NameQualifier attribute of the NameIdentifier in the generated SAML query.0 are supported. 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. Versions 1. A TAM object must exist for this method to succeed. the WebGUI prompts for the following property: SAML Match Select the minimum authorization criteria. If selected. The version selected affects the format of the messages sent to SAML authorities.0. the WebGUI prompts for the following properties: URL Specify the location of the SAML server. Contact Tivoli Access Manager The requester is authorized by a Tivoli Access Manager (TAM). Retain the default value to use a non-SSL connection. 74 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide . 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. 1.1 and 2. Use SAML Attributes from Authentication The requester is authorized by the same SAML authentication or attribute statements used to authenticate the requester. Refer to “IBM Tivoli Access Manager” on page 88 for more information. 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. SAML Match Select the minimum authorization criteria.SSL Proxy Profile Select an SSL Proxy Profile to provide a secure connection to remote authorization server. the client is rejected. the client is authorized only if the AAA Policy. can understand and discharge the conditions. Any other XACML response results in the client’s rejection. acting as a PEP. can understand and discharge the conditions. if the permit response is accompanied by obligations. which might be configured and located on the DataPower appliance. the WebGUI prompts for the following properties: XACML Version Select the XACML version (1. acting as an XACML Policy Enforcement Point (PEP). Permit-biased PEP If the XACML response to the authorization request is deny. the client is authorized.0 or 2. if the permit response is accompanied by obligations. the client is rejected. Base PEP If the XACML response to the authorization request is permit. processes the PDP authorization response. acting as a PEP. If the XACML response to the authorization request is deny. if the deny response is accompanied by obligations. if the deny response is accompanied by Appendix A. specifies the operative XPath expression Use XACML Authorization Decision The requester is authorized by an XACML Policy Decision Point (PDP). the client is authorized. the client is rejected only if the AAA Policy. the default) used for communications between the PDP and this AAA Policy. the client is authorized only if the AAA Policy.0. can understand and discharge the conditions. Deny-biased PEP If the XACML response to the authorization request is permit. or which might reside on a remote network appliance. acting as a PEP.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. PEP Type Select how the AAA Policy. Referenced objects 75 . acting as an XACML PEP. If selected. Use On Box PDP Use this toggle to specify the location of the PDP. AAA XACML Binding Method Retain the default value. If selected. the SOAP Body of the content request is wrapped by the <xacml-samlp:XACMLAuthzDecisionQuery> SAML Profile element. the WebGUI displays the following property: Policy Decision Point Select the PDP to provide authorization services for the AAA Policy. This context request contacts the PDP for an XACML decision.0 Profile. the WebGUI displays the following property value: URL of External Policy Decision Point Specify the URL to which to send XACML-based authorization requests.0. on Before the PEP posts the context request to the external PDP with the HTTP POST method. Meaningful only when the XACML version is 2. off (Default) Does not require the use of the SAML2. can understand and discharge the conditions. PDP Requires SAML 2.0 property when the XACML request is wrapped by the <xacml-samlp:XACMLAuthzDecisionQuery> SAML Profile element. 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. off (Default) The PEP posts the context request to the external PDP with the HTTP POST method. SOAP Enveloping Use the toggle to determine whether the external PDP requires SOAP enveloping. off Specifies the use of a remote XACML PDP. on Forces the use of the SAML2. the client is rejected only if the AAA Policy. which is the only supported option.0 profile. Any other XACML response results in the client’s authorization. on (Default) Specifies use of a local PDP. If the custom binding style sheet generated SOAP enveloping.0 Use this toggle to force the use of the SAML2. acting as a PEP.obligations.0 profile. This property can be combined with the PDP Requires SAML 2. 76 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide . Refer to “XACML Policy Decision Point” on page 95 for more information. retain the default setting. If selected. Post Processing tab After authorizing the client. If selected. The following inputs appear for all methods. Otherwise. authorization information is removed from the cache. Referenced objects 77 . it could generate a SAML authentication assertion and place that assertion in the header of the message. Optionally. To example a sample AAA Info file.xml. 2. Click Apply to commit AAA Policy properties. click Save Config to save the object to the startup configuration. 3. Otherwise. open store:///authfile. Click the Post Processing tab to display the AAA Policy Configuration (Post Processing) screen. Use the data-specific TTL if it is greater than the explicit TTL. use the explicit value. authorization information from remote resources is cached for a period of three seconds. For example. the WebGUI prompts for the following property: AAA Info File URL Specify the location of the XML file used for authorization purposes.Obligation Fulfillment Custom Stylesheet Specify the custom style sheet to parse any obligation that accompany an authorization decision that is received from the PEP. the WebGUI prompts for the following property: Appendix A. an AAA Policy can perform postprocessing activities. Absolute (Default) Caches all authorization data with an explicit TTL (time-to-live). Use the data-specific TTL if it is less than the explicit TTL. Cache Lifetime Specify the explicit TTL in seconds.xml. Provide the following inputs: Run custom post processing stylesheet Select whether to enable (on) or disable (off) custom (style sheet-based) postprocessing. If selected. use the form store:///authfile. Defaults to 3. use the explicit value. AAA Info File The requester is authorized by an XML file. Use the Post Processing panel to specify postprocessing behavior. On authorization failure. 1. specified by the Cache Lifetime property Disabled Disables caching of authorization data Maximum Compares the explicit TTL with the received TTL (if any). 4. To identify a local resource. Cache authorization results Select the caching strategy. Minimum Compares the explicit TTL (specified by the Cache Lifetime property) with the received TTL (if any). By default. If selected. set to on to generate a WS-Trust token timestamp.0. The version selected affects the format of the messages sent to SAML authorities. Kerberos client password If obtaining a Kerberos ticket for the requesting client. XS. attesting to the authenticity of the requesting client. SAML Name Qualifier If generation of SAML authentication assertions is enabled.Custom URL If custom post processing is enabled. the WebGUI prompts for the following properties: Generate token timestamp If generation of WS-Trust tokens is enabled. Kerberos Client Keytab Provide the location of the Kerberos keytab. This token can serve as WS-SecureConversation token. in the appliance transmission to the target server. Generate SAML Authentication Assertion Select whether to enable (on) or disable (off) the generation of SAML authentication assertions. SAML Version If generation of SAML authentication assertions is enabled. If selected. Optionally specify a NameQualifier as defined by the SAML protocol version selected. the WebGUI prompts for the following properties: Kerberos client principal Provide the name part of the client’s identity (the client name contained in the cname field of the unencrypted portion of the Kerberos ticket).0 are supported. the WebGUI prompts for the following properties: Issuer for generated SAML assertions If generation of SAML authentication assertions is enabled. Specify the shared secret in the upper field and confirm the entry in the lower field. specify the client Kerberos password (the shared secret known only to the requesting client and the Kerberos Key Distribution Center). Versions 1. 1. If selected.1 and 2. select the SAML protocol version to use when employing SAML for authentication. Generate requested WS-Trust token Set to on to generate a WS-Trust token after authentication and authorization has taken place. Optionally specify the assertion originator or retain the default value. specify a local or remote URL that locates the style sheet. Kerberos server principal Provide the name part of the server’s identity (the server name contained in the cname field of the unencrypted portion of the Kerberos ticket). 78 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide . Include a WS-Security Kerberos AP-REQ token Select whether to enable (on) or disable (off) the inclusion of a WS-Security Kerberos AP-REQ token. Allow WS-Trust token renewal If generation of WS-Trust tokens is enabled. If selected.1. Domino LTPA Used in Lotus® environments WebSphere Version 1 LTPA Used in WebSphere environments WebSphere Version 2 LTPA (Default). Text The actual password for the user name. LTPA Key File Specify the name of the file that contains the cipher keys used for encryption and decryption.0 Single Logout.1. or derived password Digest The digest of the password as specified in Web Services Security UsernameToken Profile 1.0. the WebGUI prompts for the following properties: WS-Security UsernameToken Password Type Select the password type. Appendix A. Send SAML Logout Message (SAML 2.0 Include Password Select whether to enable (on) or disable (off) the inclusion of the password in the WS-Security Username Token. set to on to allow for the renewal of the WS-Trust token. the password hash. the default) the inclusion of a WS-Security UsernameToken in the server-bound message. the WebGUI prompts for the following properties: LTPA Token Version Select the token version/type. Refer to Understanding LTPA for more information. for z/OS. the WebGUI prompts for the following properties: SAML Logout Message Session Authority Specify the URL of the SAML authority to which to send the logout message. Generate an LTPA Token Add an LTPA Token to the HTTP headers transmitted to the server. SSL Proxy Profile Optionally select the SSL Profile to support a secure connection to the SAML authority. Used in WebSphere environments (introduced in WebSphere Application Server version 5. Add WS-Security UsernameToken Select whether to enable (on) or disable (off.2.1.0 only) Click on to enable SAML Version 2. LTPA Key File Password and Confirm LTPA Key File Password Provide and confirm the cleartext password to the LTPA key file. If selected. If selected. and version 5. for other platforms) LTPA Token Expiry Specify the LTPA token lifetime (the number of seconds from the cookie creation to its expiration). Referenced objects 79 . Request TFIM Token Mapping Select whether to enable or disable token mapping by IBM Tivoli Federated Identity Manager (TFIM). 4. click Save Config to save the object to the startup configuration. 6. the WebGUI prompts for the following properties: Kerberos Client Principal Specify the name part of the client’s identity (the client name contained in the cname field of the unencrypted portion of the Kerberos ticket). Click Apply to commit AAA Policy properties. 1. 5. Click Add to display the Namespace Mapping Property window. Kerberos Server Principal Specify the name part of the server identity (the server name contained in the cname field of the unencrypted portion of the Kerberos ticket). the WebGUI prompts for the following property: TFIM Configuration Select an existing TFIM object. Refer to Understanding SPNEGO for more information. 80 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide . Click Apply to commit AAA Policy properties. Click Save to return to the AAA Policy Configuration (Namespace Mapping). 4. Kerberos Client Keytab Specify the location of the Kerberos keytab. Click the Namespace Mapping tab to display the AAA Policy Configuration (Namespace Mapping). If enabled. Optionally. If selected.Generate a Kerberos SPNEGO Token Add an Kerberos SPNEGO token to be inserted into the WWW-Authenticate HTTP header sent to the target server. 3. URI Specify the namespace URI. click Save Config to save the object to the startup configuration. Namespace Mapping tab An AAA Policy can use XPath expressions as it processes client requests — specifically XPath expressions can be used while: v Identifying service requestors v Mapping authentication credentials v Identifying requested resources v Mapping requested resources v Authorizing an authenticated service requestor Use the Namespace Mapping panel to provide namespace mappings that might be required by XPath expressions. Provide the following inputs: Prefix Specify the namespace prefix. 2. Optionally. Refer to “IBM Tivoli Federated Identity Manager” on page 90 for more information. 3. This tool allows you to upload an XML document and build the expression by pointing at the desired node. 1. Referenced objects 81 . 6. can identify the server which authenticated the user. 1. Click Add to display the SAML Attributes Property window. Click Save to return to the AAA Policy Configuration (SAML Attributes). or specify various user-associated LDAP attributes. 3. 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. you can use the following procedure to add name-value pairs to the LTPA token. can optionally contain an extended attribute field. b. d. 2. Select the method to assign a value to this attribute from the LTPA User Attribute Type field. Appendix A. 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. LTPA Attributes tab The WebSphere Version 1 and Version 2 LTPA tokens. Optionally. but not the Domino® LTPA token. Click the LTPA User Attributes tab to display the LTPA User Attributes catalog. 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. 4.SAML Attributes tab Use the SAML Attributes panel to provide SAML attribute namespace data. If XPath is selected. Click Add to display the LTPA User Attributes Property window. Specify the attribute name in the LTPA User Attribute Name field. click XPath Tool. 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. for example. If the defined expression contains namespace elements. a. Local Name Specify the attribute name. you can click XPath Binding to provide namespace/prefix data. Attribute Value Specify the appropriate value. Click Apply to commit AAA Policy properties. 2. Click the SAML Attributes tab to display the AAA Policy Configuration (SAML Attributes). To assist in creating the XPath expression. Provide the following inputs: Namespace URI Specify the attribute namespace URI. If desired. Such pairs provide a means to transmit additional information about the cookie subject to applications which can decrypt the cookie. These attribute name mappings and attribute values can be used for authentication and authorization. consisting of an arbitrary list of name-value pairs. Such information. 5. click Save Config to save the object to the startup configuration. 2. 3. Specify the name of the mapped credential in the Credential Name field. Click Done to close the confirmation window. Transaction Priority tab Click the Transaction Priority tab to display the Transaction Priority catalog. To create new SAML attribute. 4. use the following procedure: Click SAML Attributes to display the SAML Attributes catalog. repeat the step 2 to add additional namespace mappings. Click Commit. Define the following properties: Namespace URI The URI for the namespace of the Local Name. 1. All of these fields are optional. a. define SAML attributes. 2. Local Name The local attribute name. This name can be used for matching. 3. 5. Click Add to display the Transaction Priority Property window. c. Defining SAML attributes To 1. Click Save to return to the catalog. depending on the specific context or the SAML Match Type selected. This commits all changes to the AAA Policy under construction or modification. 5. Click XPath Bindings to display the XPath Bindings catalog. Select whether to require authorization with the Require Authorization toggle. Click Add to display the Namespace Property window. Click Save to return to the XPath Bindings catalog. After defining all SAML attribute. 4. Specify the namespace URI in the URI field. use the following procedure: 1. 6. This value can be used for matching. 4. If necessary. Note: You might need to use the multistep probe to determine the string for the mapped credential. Specify the namespace prefix in the Prefix field.Refer to “Setting namespace mappings (XPath bindings)” for more information. The default is off. Select the priority of the transaction from the Transaction Priority list. 82 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide . 3. Attribute Value The attribute value. Setting namespace mappings (XPath bindings) If you need to provide namespace data for XPath expressions. b. Click Done to complete the namespace mapping. 6. The default is Normal. click Done. 2. Click Save to save the configuration. click Add. Repeat step 2 through step 4 to create as many SAML attributes as needed. 3.xsd file in the store: directory. If the defined expression contains namespace elements. 2. For assistance in creating the XPath expression. LTPA User Attribute Type Select the type of attribute. Provide the following inputs: LTPA User Attribute Name Specify the name of the attribute. Click Add to display the LTPA User Attributes window. use the following procedure: Click LTPA User Attributes to display the catalog. The explicit value of the attribute. This tool allows you to load an XML document and build the expression by selecting the desired node.Adding LTPA user attributes To 1. Using an AAA Info file AAA Info File An AAA Info file can be selected as the method for the following steps of an AAA policy: v Authenticate v Map Credentials v Map Resource v Authorize The AAA Info XML file has the following basic structure. click XPath Binding to provide namespace/prefix data. add name-value pairs to the LTPA token. The following is a reproduction of the AAAInfo. LTPA User Attribute Static Value Meaningful only when the type is Static. The XPath expression used to extract a value dynamically. LTPA User Attribute XPath Value Meaningful only when the type is XPath. Static (Default) Use the explicitly assigned value. XPath Use an XPath expression to set the value dynamically. click XPath Tool. <xsd:element name="Authenticate" type="tns:AuthenticateType" maxOccurs="unbounded"> </xsd:element> <xsd:element name="MapCredentials" type="tns:MapCredentialsType" maxOccurs="unbounded"> </xsd:element> <xsd:element name="MapResource" type="tns:MapResourceType" maxOccurs="unbounded"> Appendix A. 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. which mirrors the steps of an AAA Policy. If selected. Refer to “Setting namespace mappings (XPath bindings)” on page 82 for more information. Referenced objects 83 . it does not need to include an Authenticate. perhaps more meaningful to the authorization method.. Clicking either of these buttons launches the AAA Info File Editor. Input resources can be one or more of the following types: v Original (client) URL v v v v v URL sent to server (target URL) SOAP Operation Namespace (request URI) SOAP Operation Name (request operation) HTTP method Token extracted by XPath These resource inputs map to Resource Extraction methods used by the AAA Policy. the field that offers the ability to select an XML file has the + and . 84 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide .xsd file in the store: directory. Map Resource. In each case. The schema for an AAA Info file uses the AAAInfo. Note: The AAA Info file can be edited outside of the AAA Info File Editor and uploaded to the appliance.</xsd:element> <xsd:element name="Authorize" type="tns:AuthorizeType" maxOccurs="unbounded"> </xsd:element> Note: Any given XML File could be used for one or more of these operations. Usually. One or more XML files could be used for these operations. Authenticate element: The Authenticate element or elements contain the database of identities that can be authenticated by this file. MapResource element: The MapResource element takes in a resource string extracted from the message and maps it to another.. Only the part of the file that supports the desired operation needs to be completed. Identities can be identified by one or more of the following attributes: v User name v Password v IP address or host name v IP network v Distinguished name (DN) v Custom token Each identity is given a credential by this element. if the file is only used for Map Credentials. respectively. this element is used to map an identity extracted from a message to another identity more meaningful to the authorization method. This element can be fed directly from an Authenticate element contained in this file. MapCredentials element: The MapCredentials element takes in a credential string and maps it to another. For example. These buttons allow for the creation of a new XML file or the editing of an existing XML file. however. or Authorize section. buttons. The input resource name can be matched by a PCRE regular expression. The input can be matched by a PCRE regular expression. Refer to “AAA Info File editor” on page 85 for more information. Authorize element: The Authorize element takes in a Credential and a Resource and returns an access status (allow or deny). none are initially listed. including HTTP Basic Authentication. do not use this field. Passwords can be extracted from messages by HTTP Basic Authentication and WS-Security UserName. you cannot use the IP Network field. Click Next if this file will not be used for authentication. you cannot use the Host Name or IP Address field.z. v Use this field only when the identity extraction method is set to Client IP address.0 (or 0) is not allowed. When creating a new file. and Name from SAML headers. WS-Security UserName. The IP address takes dotted decimal form w. click Cancel to abandon all changes and close the file editor. Click Add to create new identities that this file can authenticate. The entry 0.y.0. Click Next or Back to move between pages. Both the Credential and the Resource can be matched by a PCRE regular expression. Credentials (authenticated identities): The authenticated identities page provides a list of identities that are authenticated by this file.y.x. v If this field is used. User name The user name extracted from the message. IP Network The IP network of the client that submitted the message.25/24). Appendix A. Password The password extracted from the message. all unauthenticated identities are denied access. launched by the WebGUI. Host Name or IP Address The host name or IP address of the client that submitted the message. Default credential (unauthenticated identity): The initial screen presents the opportunity to set the default credentials for unauthenticated identities. v Use this field only when the identity extraction method is set to Client IP address. If those AAA Policy identity extraction methods are not used. User names can be extracted from messages in a number of ways.2. AAA Info File editor The AAA Info File Editor. If left blank. A new window opens with a form for adding identities. v If this field is used. This is the credential assigned to identities for which no other credential can be found in the Authenticate section. This entry takes the form x.0. 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. Referenced objects 85 . steps through each of these sections in an AAA Info file and helps to configure them.z.a/b (for example 192.168. The AAA Policy identity extraction methods Subject DN from SSL certificate or Subject DN from SAML signature return this value. any input credential that does not match a map is converted to a blank credential for the purposes of authorization. It is possible to create one entry for user name Bob that also has a password of foo and another with no password entry. do not use this field. Distinguished Name The DN extracted from the message. If those methods are not used. The value should be meaningful either to the AAA Policy Map Credentials method or to the AAA Policy Authorize method. Bob will still authenticate. Resource mapping is used to map the resource identifier extracted from the message to something else. Map credentials: The Map Credentials page presents a list of all credential maps contained in the file. Custom token A custom token is extracted from the message. all methods will be executed. The AAA Policy identity extraction methods Token extracted from the message and Token extracted as cookie value return this value. authentication will fail. 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. Entering foo causes the AAA policy to match all input credentials that contain the string foo. When creating a new file. If those methods are not used for extraction. Should the extraction method only retrieve the user name and not the password. tests an extracted identity against all entries in the order in which they are listed. This field accepts PCRE expressions. do not use this field. This can be the same as the extracted identity or different. Create as many mapping entries as needed by clicking Add for each new entry. All of the fields that contain information must be matched for the authentication to succeed. Credential Name The credential to output in place of the input credential. however.If the Identity Extraction method used by the AAA Policy does not use either of these methods. This is the value to which the input credential is mapped. The AAA policy. Map resources: The Map Resource page presents a list of all resource mappings contained in the file. Click Submit to add the new map to the list of maps. Note: If this file is used for mapping credentials. Click Next to move to the next page if this file will not be used for mapping credentials. This is not a regular expression. Click Add to create a new credential map. If the AAA Policy uses more than one resource extraction method. Input Credential The credential input to the mapping. Credential Name The credential returned by the authentication. this list is empty. 86 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide . do not use this field. allowing a single expression to match more than one input credential. stopping after it finds a complete match. Original URL The URL sent by the client submitting the message. Credential The credential to match for authorization. Request URI The Namespace URI of the action or method requested in the body of the SOAP message. Authorized access to resources: The Authorize page presents a list of all authorization pairs contained in this file.Click Next if this file will not be used for resource identity mapping. if any) and an input resource (after mapping. 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. File Information: The file information page provides a means to name the file and add a comment if desired. Result of XPath Expression Any value that is extracted from the message by an XPath expression. HTTP Method Select the desired method. This is a PCRE expression. Appendix A. if any). Note: When this file is used for authorization. This field accepts PCRE expressions. Select any to allow any method. Any unmatched entries result in denied access. This is a PCRE expression. This is identified as the topmost element in the SOAP:Body element. Target URL The URL used to send the message to the back end server. Resource The resource string to which the input resource is mapped. This is a PCRE expression. after the firewall URL Rewrite Policy has executed. Authorization is based on an input credential (after mapping. Access is allowed only if a match is found and the Access for that match is allow. Referenced objects 87 . This field is required. Access Select allow or deny as the authorization result. click Next. This file is typically placed in the local: directory. Resource The resource to match for authorization. Click Add to create a new map. Request Operation The name of the operation requested in the body of the SOAP message. click Add. access is denied by default. If this file is not used for authorization. This field accepts PCRE expressions. To create an authorization entry. Tivoli Access Manager configuration Configuration consists of creating a TAM client configuration file and configuring a TAM object. the appliance supports only remote client operations. The following files are needed to create the TAM object or are created using the appliance: v The ASCII version of the configuration file (. you need to have the TAM configuration files on the appliance. In this case.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. the appliance does not support these directory servers.conf extension) v The obfuscated version of the configuration file (. Tivoli Access Manager security The TAM client supports LDAP along with the proprietary IBM protocol. Creating TAM configuration files Before configuring a TAM object. and the LDAP (directory) server. You can create TAM configuration files either on the appliance or using the native TAM configuration utilities.obf extension) using the same file name as the ASCII version v The TAM SSL key file (.conf. Note: Integration with TAM requires the presence of a license on the DataPower appliance. replica authorization servers. v Click Commit to save the file and close the window. An AAA Policy object can use TAM for both authentication and authorization. Only authenticated users can receive an authorization decision. The TAM configuration supports only one policy server and supports only LDAP directories. The AAA policy will not succeed with TAM without first configuring an instance of the TAM object with at least one authorization server replica. During object configuration. v Click Cancel to abandon all changes and close the window. IBM Tivoli Access Manager Integrating with IBM Tivoli Access Manager (TAM) allows a user to be authenticated using a simple user name and password. SSL keys and certificates must be in the proprietary IBM CMS database format and must be uploaded to the appliance. You do not need to create Key objects or Certificate objects. Authorization decisions are made for an authenticated user on a resource and an operation. The files can be placed in the encrypted cert: or sharedcert: flash directories.sth extension) 88 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide . the TAM configuration files must reside on the appliance. Although native TAM supports both local and remote clients. The configuration files specify the network and security configuration for the policy server. The configuration files identify the location of these files. Both the ASCII and obfuscated versions of the configuration files are needed.kdb extension) v The TAM SSL stash file (. a resource is passed as a string. v Click Back to move backward through the file to make any additional changes needed. Although the configuration files allow specifications for Microsoft® Active Directory and Lotus Domino. To create and configure a TAM object: 1. ensure that the file entry in the [configuration-database] stanza defines the location of the obfuscated version of the configuration file on the appliance. 4. Define the operational parameters. copies of the key file and the stash file are stored in the temporary: directory. you might need to modify them before creating the TAM object. When defined in the configuration file. If necessary. You can create authorization server replicas during the creation of the TAM object. Refer to the online help for details. Refer to the online help for details. Refer to the online help for details. Each TAM object requires at least one authorization server replica. The ASCII version and the obfuscated version of the TAM configuration files are stored in the local: directory. 1) Click Add to display the properties window. Appendix A. v The TAM object needs at least one authorization server replica. Click Add to display the configuration screen.Notes: v If you use the native TAM configuration utilities to create the configuration files. Define at least one authorization server replica. and stash files. v Ensure that the obfuscated version of the configuration file is on the workstation and is the same name as the ASCII version. Click the Authorization Server Replica tab. Define the operational properties. When using secure communication. you might need to make the following modifications: v Unless the LDAP key stash file is uploaded to the appliance. or you can define replica entries in the [manager] stanza. you can now create and configure a TAM object. Define a replica. configure additional replicas for failover purposes. If you set the Create File Copies to Download property to on. you might need to upload the SSL key file for the LDAP server (. Select Objects → Access → IBM Tivoli Access Manager to display the catalog. Creating configuration files on the appliance: To create a TAM configuration file: 1. v During the creation of TAM object. Modifying native TAM configuration files: When the configuration files are generated by the native TAM utilities. modify the TAM configuration file by defining the ssl-keyfile-pwd entry in the [ldap] stanza. ensure that this file is on the workstation. Select Administration → Miscellaneous → IBM Tivoli Access Manager Tools to display the action screen. The key file and the stash file that TAM uses are stored in the cert: directory. 2. A replica indicates the network location of a remote TAM authorization server. 4. Creating and configuring TAM objects After creating the TAM configuration. key. the replicas are not shown in the Authorization Server Replica catalog. 2) Define the operational parameters.kdb extension). 2. a. Follow the prompts. 3. Use this window to specify the operational parameters. If not the same name. Referenced objects 89 . b. Click Create Tivoli Access Manager Configuration. 3. For example. d. 2. The value determines the details for the namespace and WS-Trust messages. the provided input credentials must be able to be expressed in the request token format for the TFIM endpoint. 90 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide . Specify the name for the object in the Name field. a WS-Security Username token as the request token cannot be created when the available user credential is an X. Creating the TFIM object To create and configure a TFIM object. Use this screen to specify operational parameters. Refer to the online help for details. Select Administration → Miscellaneous → IBM Tivoli Access Manager Tools to display the action screen. Click Add to display the IBM Tivoli Federated Identity Manager configuration screen. 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. 5. 5. When integrating with TFIM. Specify a descriptive object-specific summary in the Comment field. Retain the default setting for the Admin State toggle. IBM Tivoli Federated Identity Manager DataPower appliances integrate with IBM Tivoli Federated Identity Manager (TFIM) through the exchange of WS-Trust SOAP messages. click disabled. a. To place the object in an inactive administrative state.3) Click Save. an authenticated identity can be mapped to the identity for authorization. 2. Follow the prompts. The default is 9080. To refresh certificates: 1. Click the Refresh Tivoli Access Manager Client Certificate tab. 6. Use the Objects → Access Settings → IBM Tivoli Federated Identity Manager menu path to display the IBM Tivoli Federated Identity Manager catalog. Specify the port number of the TFIM server in the Port field. Optionally. f. Define the operational properties. If necessary. c. Refreshing certificates Refreshing Tivoli Access Manager (TAM) certificates first refreshes the password of the keystore associated with the TAM object and then refreshes the client certificate in the keystore with the configured TAM server. repeat the previous step to create another replica. 3. e. Specify the host name or IP address of the TFIM server in the Server field. c. use the following procedure: 1. Click Refresh Tivoli Access Manager Client Certificate. During the Post Processing phase. b.509 certificate. Click Apply to save the object to the running configuration. an authorized identity can be mapped to the output AAA identity. 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. click Save Config to save the object to the startup configuration. Select the currently configured version of TFIM from the Compatibility Mode list. 4. 0. version 6.Note: Selecting Version 6.1 as the compatibility mode. requires the specification of a Custom Request. Custom Token Indicates a custom token.0.1 or Version 6. Custom Indicates a custom token. select TFIM 6. SAML 2.1.2. SAML 1. trust chains in the TFIM 6.0. the following formats are available: Custom Indicates a custom style sheet for generating the TFIM request. Username Token (Default) Indicates a WS-Security Username Token Type.1 compatibility mode is selected.2 server.0.2 messages with a TFIM 6.1. To use WS-Trust version 1. Referenced objects 91 .509 Token Indicates a WS-Security X.0 Indicates a SAML Assertion 1. version 6. If the 6. requires the specification of a Custom Request. Appendix A. SAML 1. g.2 Indicates Tivoli Federated Identity Manager.1. v If Version 6.1 Indicates a SAML Assertion 1.0. version 6. Kerberos Token Indicates a WS-Security Kerberos Token.2 will behave the same as TFIM 6. When selected. Version 6. X.2 server must use the Validate OASIS URI as the Request Type.0 Indicates Tivoli Federated Identity Manager. TFIM 6. Version 6.509 Token. Version 6. v If Version 6. The available formats depend on the selected value for Compatibility Mode.3 of the WS-Trust specification.2.0 Indicates a SAML Assertion 2. the following formats are available: Binary Security Token Indicates a WS-Security BinarySecurityToken. Select the format of the request token from the Request Token Format list.2 as the compatibility mode will cause the TFIM client/endpoint to generate WS-Trust messages using version 1.0 Indicates a SAML Assertion 1.1 Indicates a SAML Assertion 1.1 (Default) Indicates Tivoli Federated Identity Manager. When selected. In this case. SAML 1. Username Token (Default) Indicates a WS-Security Username Token Type.1. SAML 1. TFIM 6. When enabled. TFIM 6. The TFIM trust service uses this information to determine which trust chain to invoke.1 or TFIM 6. TFIM responses are schema-validated with the WS-Trust version that is defined by the compatibility mode. specify the scope for this security token in the Applies-To Address field. j. optionally specify the name of the Web services operation to use in the Operation field. off (Default) Responses are not schema-validated. For example. 3.2.33. TFIM 6.2. i. To determine the correct value.2. When Request Token Format is not Custom. in the TFIM WS-Security Management (WSSM) component. From the SSL Proxy Profile list. select an SSL Proxy Profile to manage secure communications with the peer. this information specifies the destination of the request. or TFIM 6. Optionally. For example: EchoService The TFIM trust service uses this information to determine which trust chain to invoke with finer granularity. Click Upload or Fetch to upload the custom style sheet file. To determine the correct value.2 and when Request Token Format is Custom.1 or TFIM 6. To determine the correct value. To determine the correct value. or TFIM 6.1.251:9080/EchoApplication/Services/EchoServiceUser In the TFIM service. a default value of NotSpecified is used. A port type is a group of Web services operations. a default value of NotSpecified is used. 4) When using TFIM 6.0.com:9080/EchoApplication/Services/EchoServiceUser http://9. consult your TFIM administrator. 2) When using TFIM 6. specify the services to which this token applies: http://tfim. on Responses are schema-validated.1.97. If a value is not specified. Click Apply to save the object to the running configuration.0. optionally specify the name of the Web services port type to use in the Port Type field. When using TFIM 6. For example: echo The TFIM trust service uses this information to determine which trust chain to invoke with finer granularity.0. specify the identity that issued the request in the Issuer field.h.ibm. Working with Kerberos objects A basic description of the Kerberos authentication protocol is helpful for understanding the support provided by the DataPower appliance. k. define the following properties: 1) When using TFIM 6. For example. If a value is not specified. 92 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide . select the location of the custom style sheet in the Custom Request field.1. 3) When using TFIM 6. 4. consult your TFIM administrator.2. 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. click Save Config to save the object to the startup configuration. Use the Schema Validate Response toggle to specify whether to schema-validate responses from the TFIM server. consult your TFIM administrator. consult your TFIM administrator. The custom style sheet file must be in the local: or store: directory. or TFIM 6. the KDC has the option of requiring pre-authentication before responding. The KDC response contains two items: v A randomly generated session key encrypted with Alice’s shared secret v A ticket for the FTP service The ticket contains: v v v v The idobj for Alice The idobj for the FTP service A ticket lifetime Another copy of the session key The ticket is encrypted with the shared secret of the FTP service principal. Kerberos is an idobj extraction. Referenced objects 93 . Consequently. Appendix A. or the KDC can immediately issue the ticket to Alice. 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. or both. 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. The ticket plus authenticator is called an AP-REQ message. When the FTP service receives the AP-REQ from Alice.The Kerberos authentication protocol uses a star topology. At this point. The Key Distribution Center (KDC) is at the center of the star. This shared secret takes the form of a password for human principals and a randomly generated keytab file for nonhuman principals. and not a malicious user replaying a previously issued ticket) that she sends along with her ticket to the FTP service. When a Kerberos client (for example. v Services must have a name and shared secret registered with the KDC. and they share a session key which can be used to secure the rest of their communications. v All Kerberos cryptographic operations are symmetric in nature. At this point. More accurately. v A client principal must request a separate ticket for each server with which it communicates. the FTP service). it decrypts the ticket and verifies the authenticator. v A service must have access to its shared secret to decrypt Kerberos tickets. services running on server computers are principals in the KDC database. and one for the FTP service). Points to remember when using Kerberos When using Kerberos. v In an AAA Policy. Each Kerberos principal (a human. there are two encrypted copies of the session key (one for Alice. keep the following points in mind: v Both clients and servers are principals in the KDC database. 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 Kerberos is not an authorization protocol. At this point the FTP server has authenticated Alice. authentication protocol. Alice) wants to communicate securely with a Kerberos server (for example. Alice must access KDC of her Kerberos realm and request a ticket for the FTP service. Admin State Retain the default setting. Kerberos realm name Specify the name of the Kerberos realm that is serviced by this KDC. Click Add to display the Kerberos KDC Server configuration screen. The default is 88. To place the object in an inactive administrative state. Kerberos Keytab File objects A Kerberos Keytab file contains the keys needed to decrypt the ticket presented by a client attempting to obtain services. Kerberos KDC Server Specify the host name or IP address of the KDC server. only a password was required. 4. 2. Such authentication is entirely transparent to the user. is based on a security infrastructure that is. Click Ping to verify connectivity. at its core. click disabled. There is exactly one KDC per Kerberos realm. when configured to use an Active Directory domain. As of Windows 2000. This has been changed to an encrypted key for added security. Previously. Kerberos KDC Server objects Use the following procedure to configure a Kerberos KDC Server: 1. specify the UDP timeout. Optionally. 3. Click Apply to save the object to the running configuration. Provide the following inputs: Name Specify the name of the object. click Save Config to save the object to the startup configuration. authentication in a Windows domain is handled by Kerberos. UDP Timeout When the Transport Layer protocol is UDP. Select Objects → Crypto → Kerberos KDC server to display the Kerberos KDC Server catalog. Use the following procedure to configure a Kerberos Keytab File: 94 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide . 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. Kerberos. 5. The Kerberos Keytab File object identifies the file that contains the keys needed to decrypt the ticket. Use TCP Select whether to use UDP or TCP as the Transport Layer protocol to access the KDC server. Refer to Understanding SPNEGO for implementation details. Comments Specify a descriptive object-specific summary.There is no restriction in Kerberos that specifies which clients can request tickets for a particular service. Note: Microsoft Windows. eXtensible Access Control Markup Language (XACML) Version 2. This list includes files that are stored in the encrypted and protected cert: directory of the appliance. b.0. Appendix A. If the file does not reside on the appliance. To place the object in an inactive administrative state. 2. is employed to render the final decision. Referenced objects 95 . XACML Policy Decision Point During the authorization phase of an AAA Policy. Admin State Retain the default setting. 3. click disabled. Comments Specify a descriptive object-specific summary. click disabled. 5. c. File Name Select the keytab file. Use the Evaluate Individual Policies Equally toggle to signal the presence of a comprehensive top-level XACML policy-set. a. The DataPower appliance supports the “mandatory to implement” and “optional” specifications that are listed in Section 10.1. which defines a procedure for arriving at an authorization decision given the individual results of evaluation by a set of policies. Click Add to display the Kerberos Keytab Configuration screen. Select Objects → Access → XACML Policy Decision Point to display the XACML Policy Decision Point catalog. Provide the following inputs: Name Specify the name of the object. on Indicates the presence of multiple XACML policy-sets. The AAA Policy acts as an XACML Policy Enforcement Point (PEP). you can select Use XACML Authorization Decision. 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. d. Use the following procedure to configure an XACML Policy Decision Point (PDP). a policy combining algorithm. click Save Config to save the object to the startup configuration. The PEP allows the XACML Policy Decision Point (PDP) to decide whether or not to authorize access. Use the Name field to specify the name of this XACML PDP. click Upload or Fetch to transfer the file. Specify a descriptive object-specific summary in the Comment field. Click Add to display the XACML Policy Decision Point Configuration screen.2. It is generated through the Kerberos system itself. 1. Click Apply to save the object to the running configuration. Note: This file is not generated on the DataPower appliance. 2005. dated February 1.8 of the OASIS Standard. 4. 2. Retain the default setting for the Admin State toggle. Select Objects → Crypto → Kerberos Keytab to display the Kerberos Keytab catalog. Optionally. To place the object in an inactive administrative state. In other words a single deny takes precedence over other policy evaluations. the policy combination evaluates immediately to deny. the policy combination evaluates immediately to permit. This property is meaningful only if the Evaluate Individual Policies Equally radio button is set to on. the policy combination evaluates to the result of evaluating that single policy. evaluation is immediately halted. Specify the policy combining algorithm used by this XACML PDP in the Dependent Policies Combining field. if the target (resource) evaluates to TRUE and the policy conditions evaluate unambiguously to permit or deny.0 standard defines the following policy combining algorithms: Deny Overrides The deny-overrides policy-combining algorithm evaluates each policy in the order that it appears in the XACML policy set. 96 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide . If all policies are determined to be NotApplicable. If all policies are determined to be NotApplicable. and the policy combination evaluates to the effect of that individual policy.e. g. Use the Dependent Policy Files field with the Add and Delete buttons to construct a list of dependent policy files. Permit Overrides The permit-overrides policy combining algorithm evaluates each policy in the order that it appears in the XACML policy set. If after evaluating all policies. Specify the location of the top-level XACML policy-set in the General Policy File field. unlike the other policy combining algorithms. no policy is considered applicable by virtue of its target (the requested resource). more than one policy is considered applicable by virtue of its target. the policy combination evaluates to NotApplicable. If any policy in the set evaluates to deny. f. 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. the policy combination evaluates to NotApplicable. For an individual policy. the policy combination evaluates to Indeterminate. The XACML Version 2. then the next policy in the order is evaluated. If after evaluating all policies. If the individual policy evaluates the target as FALSE or the policy conditions as NotApplicable. This property is meaningful only if the Evaluate Individual Policies Equally radio button is set to off. In other words a single permit takes precedence over other policy evaluations. only one single policy is considered applicable by virtue of its target. If after evaluating all policies. Only One Applicable The only-one-applicable 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. only-one-applicable must evaluate all policies to render a final evaluation. if no further policy exists in the order. the policy combination evaluates to NotApplicable. This policy employs Request Maps. All files in noted directories with a .400) that specifies the time. XACML policies are never cached. The default value of 0 specifies that the cache is never expired.xml or . use the WebGUI or CLI to specify a cache lifetime. regardless of any assigned TTL value v When the URL Refresh Policy is protocol-specified. 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. Specify an integer (in the range from 0 to 2. users can access the XML manager that is associated with the AAA policy with the clear xsl cache CLI command. Click Apply to save the object to the running configuration. or Error Policy. This command also clears the compiled XACML policies that are referenced by AAA polices that are supported by the XML manager. 4.678. to client requests that are based on a set of matching criteria. Use the XACML Policies Cache Lifetime field to specify the policy combining algorithm used by this XACML PDP. The Profiles selected then provide the detailed security configuration. Web Response Profile. Referenced objects 97 . Response Maps. in turn. use local or standard URLs to locate files. click Save Config to save the object to the startup configuration. Appendix A. Application Security Policy An Application Security Policy establishes the rules used to enforce security for a Web Application Firewall service. Optionally. i. Explicitly clear the cache Use the clear pdp cache CLI command to clear the cache. that compiled XACML policies are maintained in the PDP cache.xacml extension are considered as potentially available to the current XACML PDP. and Error Maps. respectively. Specify the TTL for the PDP During PDP configuration. h. in seconds. 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 greater of the URL Refresh Policy refresh interval or the TTL for the PDP controls cache refresh 3. Each of these maps. Use the XML Manager When the PDP is used by an AAA policy for authorization. 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. matches a Web Request Profile. v When TTL for the PDP is 0 (cache never expires). There are several ways for users to control the XACML PDP policy caches. the URL Refresh Policy controls cache refresh v When the URL Refresh Policy is no-cache.Policy sets can be local or remote to the appliance. Use a URL Refresh Policy Use a URL Refresh Policy whose conditions match the internal URL xacmlpolicy:///pdpName to perform periodic cache refreshes. Optionally. Comments Specify a descriptive object-specific summary. At least one Request Map entry is required. A catalog of all configured maps is displayed. click disabled. This is the name that appears in all Policy listings. Click the name of a Map to edit it. Refer to “Matching Rule” on page 106 for more information. At least one Response Map entry is required. To place the object in an inactive administrative state. Click Add to create a new Map. Click on the name of a Policy to edit it. Response Maps tab Response Maps select Web Request Profiles to execute on server responses based on a set of matching criteria. Request Maps tab Request Maps select Web Request Profiles to execute on client requests based on a set of matching criteria. Click the Request Maps tab to establish Web Request matching maps.Select Objects → Web Applications → Application Security Policy to display the Application Security Policy catalog. Click Add to create a new Policy. the corresponding Web Request Profile executes. Provide the following inputs: 98 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide . The new map then appears in the catalog list of maps. This catalog lists all Application Security Policy objects that are configured in the current domain. Click Save to save the map and close the window. Click Add to create a new Map. Request Profile Select a Web Request Profile. If the server response meets the matching criteria. Provide the following inputs: Matching Rule Select an existing Matching Rule. Click the Response Maps tab to establish Web Response matching maps. A catalog of all configured maps is displayed. Provide the following inputs: Name Specify a name for this Policy. If the client request meets the matching criteria. Refer to “Web Request Profile” on page 132 for more information. the corresponding Web Request Profile executes. Admin State Retain the default setting. Click the name of a Map to edit it. Matching Rule Select an existing Matching Rule. Refer to “Matching Rule” on page 106 for more information. Response Profile Select a Web Response Profile. Refer to “Web Response Profile” on page 139 for more information. Click Save to save the map and close the window. The new map then appears in the catalog list of maps. Error Maps tab Error Maps select a Processing Rule to execute on errors based on a set of matching criteria. If the error meets the matching criteria, the corresponding Processing Rule executes. To establish Error Policy matching maps, use the following procedure: 1. Click the Error Maps tab to display the Error Maps catalog. This catalog lists all configured maps. 2. Click the name of a Map to edit it. Click Add to create a new Map. 3. Provide the following inputs: Matching Rule Select an existing Matching Rule. Refer to “Matching Rule” on page 106 for more information. Processing Rule Select an existing Processing Rule. Refer to “Processing Rule” on page 111 for more information. 4. Click Save to save the map and close the window. The new map is in the Error Maps catalog. Click Cancel to abandon any changes. Count Monitor Although the configuration of the following objects all the configuration of count monitors, Web Application Firewall services do not support this type of monitor configuration. v AAA Policy v Error Policy Error Policy A Web Application Firewall service can employ an Error Policy to handle errors returned by the backend service. An Error Policy can take action on the error, changing the error response received by the requesting client. Select Objects → Web Applications → Error Policy to display the Error Policy catalog. This catalog lists all the Error Policy objects. Click on the name of an existing Policy to edit it. Click Add to create a new Policy. The Error Policy object configuration screen is displayed. Provide the following inputs: Appendix A. Referenced objects 99 Name Specify a name for this Error Policy object. This name will appear in the catalog listing of objects as well as in any list of Error Policy objects. Admin State Retain the default setting. To place the object in an inactive administrative state, click disabled. Comments Specify a descriptive object-specific summary. Mode Select a mode of operation. Redirect Redirects the client to the specified URL. The URL field appears when this mode is selected. Proxy The appliance fetches the specified URL and then return its contents to the client. The URL field appears when this mode is selected. Error-rule The appliance executes a selected Processing Rule and return the result to the client. The Error Rule field appears when this mode is selected. Standard The appliance passes the error to the Application Security Policy selected for the Web Application Firewall. If the Application Security Policy includes an Error Map that will match the error, then that action is taken. This mode is useful when you want to execute error handling rules for specific requests and want to enforce monitoring of all errors, even if no Error Map matches the request. URL Specify a fully qualified URL (http://host/...). This URL is used only for the Redirect or Proxy modes of operation. Error Rule Select a Processing Rule when the mode is set to Error-rule. This rule is executed against the error returned by the application server. Monitor Do not select a Count Monitor object. The Web Application Firewall service does not support this configuration. Defining an LDAP Search Parameters object The LDAP Search Parameters object serves as a container for the parameters that are used to perform an LDAP search operation. Authentication The parameters for an LDAP search to retrieve the DN of the user. Credentials mapping The parameters for an LDAP search to retrieve the group name (DN or attribute) based on the DN of the authenticated user. You need to add a prefix and optionally add a suffix to create the LDAP filter. The prefix and suffix are constructs of the LDAP filter expression, as defined in LDAP: String Representations of Search Filters. This filter is used to perform the LDAP search and return matching entries. 100 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide To create an LDAP Search Parameters object, use the following procedure: 1. Select Objects → Access Settings → LDAP Search Parameters to display the catalog. 2. Click Add to display the configuration screen. 3. Specify the name of the object in the Name field. 4. Retain the default setting for the Admin State toggle. To place the object in an inactive administrative state, click disabled. 5. Specify a descriptive object-specific summary in the Comment field. 6. Specify the base DN to begin the search in the LDAP Base DN field. This value identifies the entry level of the tree used by the LDAP Scope property. 7. Specify the name of the attribute to return for each entry that matches the search criteria in the LDAP Returned Attribute field. The default is the dn attribute. 8. Specify the prefix of the LDAP filter expression in the LDAP Filter Prefix field. If the prefix is mail= and the user name is
[email protected], the LDAP search filter would be
[email protected]. 9. Optionally specify the suffix of the LDAP filter expression in the LDAP Filter Suffix field. If the prefix is mail=, the suffix is )(c=US)), and the user name is
[email protected], the LDAP search filter would be (&(
[email protected])(c=US)). 10. Select the depth of the search from the LDAP Scope list: Base Searches the entry level of the tree only. One level Searches the entry level of the tree and any object that is one-level below the input. Subtree (Default) Search the entry level of the tree and all of its descendents. 11. Click Apply to save the object to the running configuration. 12. Optionally, click Save Config to save the object to the startup configuration. Load Balancer Group A Load Balancer Group is a server pool that can provide redundancy among a collection of servers. A Load Balancer Group can be used as the backend server for a DataPower service or can be used to provide LDAP or IMS™ Connect server failover protection. A request to connect to a Load Balancer Group results in the selection of a healthy server to receive an incoming client request. Each instance of a Load Balancer Group can support 512 members. Health of member servers The health of each member of the group is considered one of the following : v Healthy or up v Quarantined or softdown v Convalescent or down Appendix A. Referenced objects 101 the health state is up. 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. which is one of the following values: v up v down v softdown Refer to “Health of member servers” on page 101 for details. If the health check fails.Healthy By default. Providing basic configuration properties on the Main tab 2. When the dampening period elapses. Configuring Load Balancer Group objects The configuration of a Load Balancer Group consists of the following activities: 1. Quarantined During a normal HTTP transaction or the TCP ping. When quarantined. the server returns to the healthy state and becomes eligible to receive forwarded client requests. While deemed convalescent. the server is: v Removed from the server pool v Ineligible to receive forwarded client requests Setting the health state with a variable The health state for each server can be set with the service/lbhealth/ service variable. the health state is down. the server is deemed convalescent. all servers are considered healthy and are eligible to receive forwarded client requests. When deemed convalescent. While quarantined. The server is not considered to be healthy until it passes a health check. Optionally defining health check criteria on the Health tab 102 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide . the health state is softdown. This variable takes one of the following syntax statements: var://service/lbhealth/group/server/state var://service/lbhealth/group/server:port/state Where: group The name of the Load Balancer Group server The IP address or host name of the member port The port of the member state The state of the server. When healthy. Defining server members on the Members tab 3. a failure to connect to a server causes the server to be quarantined until a dampening period elapses. you can associate a periodic health check with a Load Balancer Group. use the Load Balancer Hash Header property to identify the header to read. Damp Time Specify the number of seconds that a server remains in an softdown state. Admin State Retain the default setting. this property is available only in the object view. Least Connections Maintains a record of active server connections and forward a new connection to the server with the least number of active connections.Providing basic configuration To 1. perform the following procedure: Select Objects → Network → Load Balancer Group to display the catalog. This property does not impact servers that are in the down state. click disabled. The following values are available: First Alive Uses the concept of a primary server and backup servers. Referenced objects 103 . Weighted Round Robin Maintains a weighted list of servers and forwards new connections in proportion to the weight (or preference) of each server. The same client is served by the same server. all connections are forwarded to this server. connections are forwarded to backup servers. Additionally. Do not Bypass Down State Select the connection-behavior when no member is up. This algorithm is used in applications that require the storage of server-side state information. Comments Specify a descriptive object-specific summary. and this property is on the Main tab. To place the object in an inactive administrative state. The default is 120. This property is available for Multi-Protocol Gateway and Web Service Proxy services only. start the configuration. Use a value in the range of 1 through 86400. Appendix A. When the primary server is healthy. The primary server is the first server in the members list. Hash Uses the IP address of the client or the value of an HTTP header as the basis for server selection. Click Add to display the configuration screen. Algorithm Select the algorithm to select the actual server. 3. When the primary server is quarantined or convalescent. 2. When using an HTTP header. such as cookies. Provide the following inputs: Name Specify the name for the Load Balancer Group. Round Robin (Default) Maintains a list of servers and forwards a new connection to the next server on the list. member servers are contacted on the DataPower service-defined port.domain. Weight If the algorithm is Weighted Round Robin only. 3. 4. off (Default) Does not attempt to contact other members. Each server that fails is set to the softdown state. The default is 0. Use a value in the range of 1 through 65000.com is a member of the Appsters Load Balancer Group. By default.” off Defining server members Use the following procedure to add members or assign weight to members. The default is 1. the order of members is not important. A receives 50% of requests. If appserver1. 104 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide . Masquerade as Group Name Select which name to present in the message header. Makes the next attempt when at least one members is in the up state.domain. However. Click Add to display the property window. Try Every Server Before Failing Select the retry-behavior for a failed attempt. B. (Default) Use the host name of the member. If you specify a nonzero value. the message header contains appserver1. explicitly identify the member-specific target port.on Does not forward the connection to any member. on Sends the requests to each server until one responds or all fail. respectively. Mapped Server Port Specify the member-specific target port or retain the default value (0) to use the DataPower service-defined port. and 40. The greater the value. Select the Members tab to display the catalog. the message header contains Appsters. that member server will always be contacted on this port. Provide the following inputs: Actual Host Specify the IP address or the domain-qualified host name of the member. 2. Because of the weighting. the more likely this server is to receive a connection request. For example there are three members (A. off (Default) Selects the first member in the down state and forwards the connection to this server. if you have services running on different ports for different member servers. B receives 30% of requests. If appserver1. 1. For all algorithms except First Alive. Continue with procedure that is provided in “Defining server members. on Uses the name of the Load Balancer Group. and C receives 20% of requests.domain. and C) that have the assigned weights of 100. Use a value in the range of 0 through 65535.com. specify the relative weight (preference). 60.com is a member of the Appsters Load Balancer Group. Health Port Specify the member-specific health port or retain the default value (0) to use the Load Balancer Group-defined port. Use a value in the range of 0 through 65535. The default is 0. A nonzero value overrides the value for the Remote Port property of the health check. This property is available during the configuration of the health check on the Health screen. 4. Click Save to return to the catalog. Assignment of all members to a Load Balancing Group completes the required configuration. v To associate a periodic health check with the new Load Balancer Group, refer to “Defining health checks.” v If you are completed with the configuration, click Apply to save the object to the running configuration and return to the object catalog. v Optionally, click Save Config to save the object to the startup configuration. Defining health checks A health check is essentially a scheduled rule that sends the same request to each server member. The successful completion of the health check requires that the server passes normal TCP and HTTP connection criteria. Optionally, the health check contains a filter to test the response from the server. If the filter accepts the response, the server is considered to be healthy; otherwise, it is considered to be convalescent. Use the following procedure to define the health check: 1. Click the Health tab to display the configuration screen. 2. Provide the following inputs: Enabled Controls whether to perform the periodic health check. URI on Enables the health check. off (Default) Disables the health check. When the check type is Standard, specify the non-server (file path) portion of the target URI. That is, specify the URI to receive the client request that is generated by the rule. The default is /. This URI is used with the specified remote port. Remote Port Specify the port on the target server to receive the query. The default is 80. You can override this value for one or more members of the Load Balancer Group with the Health Port property. This property is available during the configuration of member servers in the group. The response from the server is evaluated to determine the health status of each member server in the group. The request is sent to the target URI and remote port. Health Check Type Select the type of check to perform. Standard (Default) Select if the group does not consist of LDAP servers. Appendix A. Referenced objects 105 LDAP Select if the group consists of LDAP servers. IMS Connect Select if the group consists of IMS Connect servers. Send SOAP Request? When the check type is Standard, specify the HTTP method to access the target URI. on (Default) Click to access the target URI with an HTTP POST operation (by posting a SOAP message). off Click to access the target URI with an HTTP GET operation. SOAP Request Document When Send SOAP Request? is on, specify the SOAP message to send as a client request. The default is the healthcheck.xml file in the store: directory (store:///healthcheck.xml). Timeout Specify the number of seconds for the completion of the health check. Use a value in the range of 2 through 86400. The default is 10. If successful, the server is deemed healthy and is marked as up; otherwise, the server is deemed convalescent and is marked as down. Frequency Specify the number of seconds between health checks. Use a value in the range of 5 through 86400. The default is 180. XPath Expression When the check type is Standard, use with the XSL Health Check Filter property to specify the XPath expression that must be found in a valid server response. If necessary, click XPath Tool to define an XPath expression. XSL Health Check Filter When the check type is Standard, specify the style sheet to filter the server response. The default is the healthcheck.xsl file in the store: directory (store:///healthcheck.xsl). This style sheet uses the specified XPath Expression value as input and scans the server response for its presence. If found, the server is deemed healthy and is marked as up; otherwise, the server is deemed convalescent and is marked as down. SSL proxy profile Optionally, when the check type is Standard, select an SSL Proxy Profile to provide the resources for a secure connection. 3. Click Apply to save the object to the running configuration. 4. Optionally, click Save Config to save the object to the startup configuration. Matching Rule Matching Rule objects support the implementation of processing policies and XML manager-based schema validation rules. Both use a Matching Rule to determine if a candidate XML document is subject to a particular processing or validation action in a processing policy. A Matching Rule contains one or more match expressions. Match expressions are of the following types: 106 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide v Error code expressions define an error set that is subject to a specific error-rule. As error codes are written as hexadecimal integers, the error code expression matches one or more hexadecimal integers. v HTTP expressions work with a specified HTTP header to define a group of HTTP headers. An HTTP expression can define, for example, an HTTP header that contains a specific header field or an HTTP header that contains a defined value in a specific header field. v URL expressions define a group of URLs. For example, a URL expression could define all URLs or only URLs that contain a specific domain name. v XPath expressions define content in the XML document. For example, an XPath expression could define all attributes of a specific name. Note: Candidate documents are evaluated against all match expressions in the Matching Rule. A document matches the rule only if it conforms to all expressions in the rule. Documents that fail to match all expressions do not match the rule. To configure a Matching Rule, use the following procedure: 1. Select Objects → XML Processing → Matching Rule to display the catalog. 2. Click Add to display the configuration screen. 3. Specify the name of the object in the Name field. 4. Retain the default setting for the Admin State toggle. To place the object in an inactive administrative state, click disabled. 5. Specify a descriptive object-specific summary in the Comment field. 6. Use the Match with PCRE toggle to indicate whether match patterns use PCRE expression or shell-style expressions. on Uses PCRE expressions. off (Default) Uses shell style expressions. 7. Use the Boolean Or Combinations toggle to indicate whether to combine the match criteria with OR semantics or with AND semantics. on Uses OR semantics to evaluate the criteria. Only a single match condition needs to be true for the match to succeed. (Default) Uses AND semantics to evaluate the criteria. All match conditions must be true for the match to succeed. 8. Define matching rules on the Matching Rule tab off a. Click Add to display the Property window. b. Select the desired match type from the Matching Type list. Error Code Bases the match on an error code. This type is for use in the processing of error rules. Full URL Deprecated. Use URL. This legacy type creates a match that uses a shell-style match pattern against the full inbound URL. Host Deprecated. Use HTTP. This legacy type creates a match that uses a shell-style match pattern against the Host: header in HTTP 1.1 requests. HTTP Bases the match on HTTP header fields. Appendix A. Referenced objects 107 org. one of several actions is taken. d. If a match is found. v When URL. A Name-Value Profile filters names. The protocol provides for HTTP headers. identify the target error code in the Error Code field. 2) Specify the HTTP expression in the HTTP Value Match field. refer to http://www. a match is made. For a PCRE expression. Click Apply to save the object to the running configuration. again expressed as a match expression. c. URL-encoded query strings. XPath Bases the match on an XPath expression. ? The single character wildcard matches one occurrence of any single character. 3. [1-5] Matches 1. The expression is applied to the inbound document. For more information.=reject). A Name-Value Profile provides a means to implement this inspection and action configuration. the pair passes. Name-Value Profile Web applications communicate with clients using the various mechanisms of the HTTP protocol. the corresponding value is compared to a corresponding match expression. Optionally. The Name-Value Profile works by comparing each name in a name-value pair to all entries in a configured Validation List.* rather than * to match any number of any characters. Click Select to view a list of selectable error codes.URL Bases the match on the inbound URL after any URL rewrite. and for names that match a given expression. or 5 [xy] Matches x or y You can use any PCRE-compliant expression. Click Save. Wildcards are allowed. sets constraints on the corresponding values. 108 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide . Click XPath Tool for help creating this expression. Define the matching criteria: v When HTTP: 1) Specify the target HTTP header field in the HTTP Header Tag field. 4. it is necessary to inspect and take action on these names and values. You can use wildcards to define a match pattern as follows: * The string wildcard matches 0 or more occurrences of any character. 2. specify the XPath expression in the XPath Expression field. 10. click Save Config to save the object to the startup configuration. specify the URL match expression in the URL Match field. cookie values. To provide integrity and security for such an application. 9. use .pcre. v When XPath. 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. If a match is found. When the XPath expression evaluates to true. [] The delimiter pair to bracket a character or numeric range.=valueB&broken. v When Error Code. Repeat this step to define another matching rule. If no match is found. Max Name Length Specify an integer to determine the maximum size. The Name-Value Profile configuration page appears. in bytes. Referenced objects 109 . 3. Post body. Post body. No Match Policy Select an option to determine the action taken when a given name does not match a Name Matching expression in the configured Validation List (refer to “Validation List tab” on page 110). click the object name. No Match Map Value Specify an alphanumeric string. This name appears in all lists of available Name-Value Profiles. cookie set. To edit an existing object. of a name attribute used in this profile. only names that contain the substring token will be accepted. or Query String). To place the object in an inactive administrative state.=valueB &broken. in bytes. The No Match Map Value input appears when this option is selected. Error The Profile validation fails and an error is generated. The default is 512 bytes. Select Objects → Web Applications → Name-Value Profile to display the Name-Value Profile catalog.=reject. stripped from the string or replaced with a known value. or the entire string can be rejected (in which case. Maximum Count Specify an integer to determine the maximum number of name value pairs allowed in a single entity (header. given the URL-encoded string token=valueA&token1. click Add. the profile will fail to pass). 1. The name-value pair with a name of broken can optionally be passed through. of a value attribute used in this profile The default is 1024 bytes.For example. in bytes. of the aggregated names and values in a single entity. Provide the following inputs: Name Specify an alphanumeric name for this profile object. Total Size Specify an integer to determine the maximum size. Comments Specify a descriptive object-specific summary. The Value of any Name Value pair that Appendix A. This is the default. The catalog lists all available Name Value Pair objects. click disabled. Admin State Retain the default setting. Set The given Name token is replaced with a default value. Strip The Name-Value pair is removed from the entity (headers. 2. Pass-thru The given Name Value pair is passed through to the next step in processing. To create a new object. and those that are accepted must have a value that contains the string value. Max Value Length Specify an integer to determine the maximum size. Query String or cookie) and processing continues. unmatched values can also be checked for cross site scripting (XSS). the No Match Policy is executed. Use to validate any data that might get stored and displayed again later such as the contents of a comment form. 2. name values that do not match an entry in the Validation List are checked for Cross Site Scripting (sometimes called CSS or XSS) signatures. Query String. investigates escaped characters. 1. Click the Validation List tab to edit and create a Validation List. This is the default. Value Constraint The regular expression (PCRE style) that is applied to a value input to determine whether it is an expected input. the values that do not match the Value Constraint expression are checked for cross site scripting (sometimes called CSS or XSS) signatures. Click Add to create new entries. The value will be replaced with this constant value when the Failure Policy is Set. Provide the following inputs: Name Expression The regular expression that the submitted names are matched against. Check XSS When set to on. the Failure Policy is executed. Error The Profile validation fails and an error is generated. Pass-thru The given Name Value pair is passed through to the next step in processing. If no match is found. 3. In addition. No Match XSS Policy When set to on. These signatures are generally attempts to obfuscate the real meaning of the value if the value were displayed directly in a 110 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide . the value must also match against the corresponding value constraint to be passed through. Set The given Value is replaced with a default value. those characters with the high-bit set. If no match is found. When set to on. or cookie) and processing continues. When a match is found. 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 they match. These signatures are generally attempts to obfuscate the real meaning of the value if the value were displayed directly in a browser. The Map Value input appears when this option is selected. Post body. the Name Value Pair passes. Failure Policy Select an option to determine the action taken when a given value does not match the Value Constraint expression. Strip The Name Value pair is removed from the entity (headers. If a match is found. The default is off. and various forms of the term script which is often used to engage JavaScript™ on a browser without the user's knowledge. the corresponding value is compared to the corresponding Value Constraint in the Validation List. Map Value Specify an alphanumeric string.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. Rule Direction Select the rule type or direction. Admin State Retain the default setting. If the message contains attachments. investigates escaped characters. Select Objects → XML Processing → Processing Rule to display the catalog. 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 various forms of the term script. the attachments are contained in the one file. an error will result. 2. The created archive contains only one file. PKZIP The message will be decompressed using the pkzip algorithm. Provide the following inputs: Name Specify the name of this Processing Rule. Referenced objects 111 . Output Filter Select a compression algorithm to apply to the entire message payload after the last action of the rule executes. This is. If the message is not compressed using the selected algorithm. PKZIP The message will be decompressed using the pkzip algorithm. in effect. To place the object in an inactive administrative state. Appendix A. Use to validate any data that might get stored and displayed again later . Comments Specify a descriptive object-specific summary.such as the contents of a comment form. characters with the high-bit set. a filter. click disabled. reusable processing rules which can later be assigned to one or more processing policies. gzip The message will be decompressed using the gzip algorithm. 3.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. When set to on. The default is off. which is often used to engage JavaScript on a browser without the user's knowledge. gzip The message will be decompressed using the gzip algorithm.browser. 1. Processing Rule You can create global. Click Add to display the configuration screen. with the list of available processing actions. Rate Specify an integer to set the rate of acceptable traffic. Comments Specify a descriptive object-specific summary. To create a new object. per user. Enforcement Style Select the action taken when the rate limit is exceeded. Admin State Retain the default setting. The Rate Limiter object configuration page appears. Optionally. Notify Generate log message in the appropriate application domain. creating a low memory state. The default is 500. Log targets must subscribe to this event to capture message. A Rate Limiter object is used by a Web Request Profile. The ability to shape transactions is limited when concurrent connections are high. off (Default) Disables the processing of non-XML documents. Provide the following inputs: Name Specify an alphanumeric name for this object. 4. To edit an existing object. click Add. 5. To place the object in an inactive administrative state.Non-XML Processing Select whether to enable or disable the processing of non-XML documents. Select Objects → Web Applications → Rate Limiter to display the Rate Limiter catalog. Rate Limiter A Rate Limiter object establishes policies used to control the rate at which requests are received by a Web Application Firewall. 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. Actions Use the Add and Delete buttons. Unprocessed Select whether to determine whether the actions of the rule will take effect on the message. the Limiter can reject requests. Click Apply to save the object to the running configuration. click the name. to manage actions for this processing rule. post notification or shape. on Enables the processing of non-XML documents. transactions are rejected until rate drops. expressed in transactions per second. When the rate exceeds the limits set. or delay traffic to remain in the limits set. click disabled. Once too many messages are buffered. 112 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide . click Save Config to save the object to the startup configuration. This catalog lists all Rate Limiter objects. This duplicates the Request Type and Response Type properties of the services. click disabled. 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. The login cookie is only good for the amount of time specified by this property. When too many distinct counts are observed. Click on the name of an existing Policy to edit it. Session Management Policy A Session Management Policy controls and manages the following Web request attributes: v The URL of the pages that start. Auto Renew If this property is enabled (on). This parameter specifies how many distinct users to track before discarding. Comments Specify a descriptive object-specific summary. Start pages are pages that can be accessed without a session cookie. Referenced objects 113 . When this is set to off. Use an integer in the range of 1 through 864000. Address Independent Sessions Normally the session cookie contains the client IP address to prevent using the session on any other host. Provide the following inputs: Name Specify an alphanumeric name for this Policy. The login cookie can be renewed during activity depending on the value of the Auto Renew property. When this is set to on. Admin State Retain the default setting. Start Pages Select the matching rule that is used to identify start pages. or begin. Some environments might make this behavior undesirable. Enabling this property makes the session cookie address independent. The default is 3600. This catalog lists all Session Management Policy objects. Click Add to create a new object. If a security policy is Appendix A. the session lifetime is the total amount of time allowed before returning to the login sections. the Session Lifetime then measures idle time between uses. the users not seen in the longest time are discarded. The Session Management Policy configuration page appears. Set to 0 to disable this enforcement. Session Lifetime Specify an integer that determines the lifetime of a session.Distinct Users The count is organized by the identity most recently used. Concurrent Connections The number of simultaneous connections allowed per user. in seconds. The click of a mouse or submission of a form constitutes a use. the session lifetime is renewed on each use of the session. To place the object in an inactive administrative state. This name appears in all listings of available Policies. Refer to “Matching Rule” on page 106 for more information. URL Rewrite Policy You can design a URL Rewrite Policy that defines rules for the following rewrite and replacement operations: v Rewrite the entire URL or a portion of the URL v Replace a header value in the message v Rewrite the HTTP POST body in the message The rewrite rules in the URL Rewrite Policy are applied before document processing. Click Add to display the URL Rewrite Policy Configuration (Main) screen.enforced on the page. content-type Replaces the value of the Content-Type header based on a URL match. Click the URL Rewrite Rule tab to display the URL Rewrite Policy Rule Configuration (URL Rewrite Rule) screen. Response Applies to server responses only. Both Applies to both client requests and server responses. absolute-rewrite Rewrites the entire URL or a portion of the URL based on a URL match. URL Rewrite Direction Select the direction of the URL Rewrite Policy. Select Objects → XML Processing → URL Rewrite Policy to display the URL Rewrite Policy catalog. 114 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide . click disabled.” URL Rewrite Rule tab 1. Provide the following inputs: Name Specify the name of this URL Rewrite Policy. To place the object in an inactive administrative state. Request Applies to client requests only. 2. Continue with “URL Rewrite Rule tab. Click Add to display the URL Rewrite Policy Property window. 4. Direction is applied at the service level and has no effect on other policies. 3. Provide the following inputs: URL Rewrite Type Select the rule type. Therefore. these pages will then issue a session cookie. 2. Use the following method to create a URL Rewrite Policy: 1. the evaluation criteria in the Matching Rule is against the rewritten value. Admin State Retain the default setting. 3. – If the match pattern is (. b.*)\?(. Followed by a text subpattern. or HTTP POST body. For example *. Depending on the rule type. specify the complete replacement.* or * Matches any string. To retain the first text subpattern. h. and so forth. The backward slash (\) in the PCRE is a URL escape. c.pcre. . Followed by X or x. a candidate URL or specific HTTP header field is matched against the expression. g. Followed by xsl=.* matches any value. defines the expression to be matched against the contents of a specific HTTP header field. Input Replace Expression Specify a PCRE-style replacement that defines the rewritten URL. e. f. To replace the second text subpattern only. Match Expression Specify a PCRE (Perl-compatible regular expression) that defines the match condition that triggers the rewrite rule. Followed by a text subpattern that does not contain an ampersand (&) character. specify the evaluation replacement for any text subpattern or retain the original text subpattern. A text subpattern. specify $2. c.*) Matches a string of the following format: a. rewrite This rule type is deprecated. Followed by ?. defines the expression to be matched against the URL. The POST body contains the input values for a basic HTTP POST request.* or *. d.*)xsl=(. Followed by a text subpattern. specify $1xsl=ident. Followed by L or l. Appendix A. d. specify $1.*)xsl=(. content-type. PCRE documentation is available at http://www. post-body Rewrites the body of an HTTP POST request. A text subpattern. and post-body. v For absolute-rewrite. Followed by S or s. Followed by &.xsl?$3.org.*)\?(. – If the match pattern is . v For header-rewrite. (. HTTP header field. (.header-rewrite Replaces the value of an arbitrary header based on its value. Referenced objects 115 .*) Matches a string of the following format: a. to retain the second text subpattern. b. Followed by a text subpattern.*)&[Xx][Ss][Ll]=([^&]+)(. e. Followed by =. v For absolute-rewrite.*). defines the rewritten URL. If a rewritten URL begins with a host name or port that is different from the configured remote address, the host name or port portion of the rewritten URL is ignored. v For content-type, defines the replacement value for the Content-Type header. v For header-rewrite, defines the replacement value for the specified header. v For post-body, defines the rewritten body of the HTTP POST. For example: – If the match pattern is .* or *, specify the complete replacement. – If the match pattern is (.*)xsl=(.*)\?(.*), specify the evaluation replacement for any text subpattern or retain the original text subpattern. To retain the first text subpattern, specify $1; to retain the second text subpattern, specify $2, and so forth. To omit the second text subpattern only, specify $1$3. Stylesheet Replace Expression Specify a PCRE-style replacement that identifies the replacement style sheet. This option is available for absolute-rewrite or post-body only. v If the match pattern is .* or *, specify the complete replacement. v If the match pattern is (.*)xsl=(.*)\?(.*), specify the evaluation replacement for any text subpattern or retain the original text subpattern. To retain the first text subpattern, specify $1; to retain the second text subpattern, specify $2, and so forth. To retain the second text subpattern only and not use the third text subpattern, specify http://mantis:8000/$2. Input URL Unescape Select whether URL-encoded characters (for example, %2F) that occur in the rewritten URL are replaced with literal character equivalents. This option is available for absolute-rewrite or post-body only. on Enables the substitution of literal characters for URL-encoded characters. off (Default) Disables the substitution of literal characters for URL-encoded characters. Stylesheet URL Unescape Select whether URL-encoded characters (for example, %2F) that occur in the replacement URL are replaced with literal character equivalents. This option is available for absolute-rewrite or post-body only. on (Default) Enables the substitution of literal characters for URL-encoded characters. off Disables the substitution of literal characters for URL-encoded characters. Header Name Identifies the name of the header to have its value rewritten. The header name must be entered exactly as it is defined in the message. This option is for header-rewrite only. URL Normalization Select whether to enable normalization of URL strings. Normalizing a URL compresses "." and ".." and converts backward slashes (\) to forward slashes (/). 116 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide on (Default) Enables normalization. off Disables normalization. 4. Click Save to return to the URL Rewrite Policy Configuration (Main) screen. 5. Click Apply to save the object to the running configuration. 6. Optionally, click Save Config to save the object to the startup configuration. User Agent A User Agent is a client that initiates a request for a local service. An XML Manager uses a User Agent, for example, to retrieve resources from elsewhere on the network. The settings of a User Agent can affect messages that sent out by a specific DataPower service when its XML Manager employs a User Agent. Select Network → User Agent to display the User Agent catalog. Click Add to display the User Agent configuration (Main) screen. Provide the following inputs: Name Specify the User Agent name. Admin State Retain the default setting. To place the object in an inactive administrative state, click disabled. Comments Specify a descriptive object-specific summary. HTTP Request-Header Optionally, include the User Agent HTTP request-header field in client requests issued by this User Agent, and to specify the contents of the field. The field contains information about the user agent that sends the request. The HTTP specification does not require this field. By default, the appliance does not include the request-header field. Leave blank to suppress the inclusion of this field in client requests that the User Agent issues. Maximum Redirects Specify the maximum number of HTTP redirect messages that this User Agent can receive before the it declares the target URL as unreachable. Timeout Specify the amount of time, in seconds, that the connection can be idle before the User Agent times out and closes the connection. Use an integer in the range of 1 through 86400. The default is 300. Note: The default timeout for a connection failure is 10 seconds, which cannot be changed. The timeout applies when a specified server cannot be contacted. Click Apply to save the object to the running configuration and return to the object catalog. Optionally, click Save Config to save the object to the startup configuration. Appendix A. Referenced objects 117 Proxy Policy The User Agent will forward all requests that meet the URL Matching Expression to an HTTP server instead of to the host that is identified in the target URL. When there are multiple proxy policies, candidate URLs are evaluated against each proxy policy in the order in which it was created. Consequently, the sequence of proxy policies is important. 1. Click the Proxy Policy tab to display the User Agent configuration (Proxy Policy) screen. 2. Click Add to display the Proxy Policy Property window. 3. Provide the following inputs: URL Matching Expression Define the target URL sets associated with this Proxy Policy. Match patterns can contain the following wildcard syntax: * Indicates a string that matches 0 or more occurrences of any character. ? Indicates a single character that matches one occurrence of any single character. [] Indicates a delimited range of alphabetic or numeric characters. For example, [1-5] would match 1, 2, 3, 4, or 5, and [x-y] would match x or y. You can use any PCRE-compliant expression. For more information, refer to http://www.pcre.org. Skip Use the toggle to specify whether requests for an identified URL (that is, a member of the target URL set) are forwarded to the specified HTTP server. on Does not forward requests. off (Default) Forwards requests to the specified HTTP server. When selected, provide the following inputs. Remote Host Specify the host name or IP address of the HTTP server to which to forward requests. Remote Port Specify the port on the HTTP server to which to forward requests. 4. Click Save. 5. Click Apply to save the object to the running configuration. 6. Optionally, click Save Config to save the object to the startup configuration. SSL Proxy Profile Certain User Agent requests require a secure (SSL-enabled) connection. The resources required for SSL support are provided by an SSL Proxy Profile. Refer to “Defining SSL Proxy Profile objects” on page 19 for more information. To assign an instance of an SSL Proxy Profile object to the User Agent, use the following procedure: 1. Click the SSL Proxy Profile Policy tab. 2. Click Add. 118 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide or 5. the communication will use SSL employing the SSL Proxy Profile specified. 2. ? Indicates a single character that matches one occurrence of any single character. [] Indicates a delimited range of alphabetic or numeric characters. You can use any PCRE-compliant expression. You can use any PCRE-compliant expression. Password Specify the associated password. [] Indicates a delimited range of alphabetic or numeric characters. 5. or 5. For example. Match patterns can contain the following wildcard syntax: * Indicates a string that matches 0 or more occurrences of any character. ? Indicates a single character that matches one occurrence of any single character.pcre. In the URL Matching Expression field. The SSL Proxy Profile must be either a client or two-way profile. Click Add to display the Basic-Auth Policy Property window. an HTTP Authorization header will be added. and [x-y] would match x or y. 4. 2. 4. If the target URL matches this expression. Match patterns can contain the following wildcard syntax: * Indicates a string that matches 0 or more occurrences of any character. Click Save. refer to http://www. 4. select an instance of the SSL Proxy Profile object to support secure access to the HTTP Proxy Server. Referenced objects 119 . For example. 3. Provide the following inputs: URL Matching Expression Define the target URL(s) set associated with this policy. [1-5] would match 1. or it could be a subset. The URL set defined by this matching expression could be identical to the set defined by the HTTP Proxy Policy. define the target URL sets associated with this policy.3. If the target URL matches this expression. Click the Basic-Auth Policy tab to display the User Agent configuration (Basic-Auth Policy) screen. For more information. From the SSL Proxy Profile list. using the User Name and Password supplied. Appendix A. and [x-y] would match x or y. User name Specify the user name. Confirm Password Specify the associated password again.org. [1-5] would match 1. Basic HTTP Authentication Certain User Agent requests require basic HTTP authentication (user name and password). which lists all user name/password pairs. For more information. refer to http://www.org. 3.pcre. 4.1 Host: www. which lists all SOAP actions. [] Indicates a delimited range of alphabetic or numeric characters. In the following example. click Save Config to save the object to the startup configuration.org. Public Key Authentication Policy A User Agent can use public key authentication in its communications with remote resources. Match patterns can contain the following wildcard syntax: * Indicates a string that matches 0 or more occurrences of any character. Click the PubKey-Auth Policy tab to set the configuration values for this feature. Optionally. 3. click Save Config to save the object to the startup configuration. the corresponding header will be inserted in the request to the resource. Click Add to display the SOAP Action Property window. Soap Action Specify the SOAP action (a URI that identifies the intent of the SOAP HTTP request). or 5. [1-5] would match 1. Click the Soap-Action Policy tab to display the User Agent configuration (SOAP-Action Policy) screen. 2. Provide the following inputs: URL Matching Expression Define the target URL set that is associated with this policy. Optionally.info Content-Type: text/xml. charset="utf-8" Content-Length: <length of HTTP request> SOAPAction: GetCatalogList Click Save to complete specification of the header field contents and return to the User Agent configuration (Soap-Action Policy) screen. For example. the Soap Action is: GetCatalogList POST /webServices/soap/endpoint HTTP/1. SOAP Action Policy Certain User Agent requests require that the contents of the SOAPAction HTTP request header field be supplied.pcre. ? Indicates a single character that matches one occurrence of any single character. If the target URL matches this expression. which now lists the newly created SOAP action. and [x-y] would match x or y. 120 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide .Click Save to complete basic authentication and return to the User Agent configuration (Basic-Auth Policy) screen.somedomain. This feature is useful when the agent uses the SCP or SFTP protocol for communication. refer to http://www. which now lists the newly created user name-password pair. You can use any PCRE-compliant expression. For more information. com/images/* v scp://user[a-c]@10.23/inbound/* Private Key Select the desired private key.[0-4]. Provide the following inputs: URL Matching Expression Specify a URL Match expression in the URL Matching Expression field. Click Save to add this policy to the list.ssh/authorized_keys on the remote server. You can use any PCRE-compliant expression. [1-5] would match 1. Allow Compression Policy A User Agent can compress the payload of its communications with remote resources. or click Add to create a new policy. Appendix A.org. Provide the following inputs: URL Matching Expression Specify a URL Match expression in the URL Matching Expression field.pcre. or click Add to create a new policy. 2. This certificate must reside in $HOME/. This feature is useful when the payload is large. For example. 4. If the Crypto Key object needed is not presented in the list. For more information. Match patterns can contain the following wildcard syntax: * Indicates a string that matches 0 or more occurrences of any character.10. The Public Key Property window is displayed. or 5. [] Indicates a delimited range of alphabetic or numeric characters. click the + button to create the object. refer to http://www. Examples include the following: v https://server. Referenced objects 121 . The Private Key file must be uploaded to the local appliance to create the Crypto Key object. Click any existing policy to edit the policy. Click the Allow-Compression Policy tab to set the configuration values needed for this feature. Match patterns can contain the following wildcard syntax: * Indicates a string that matches 0 or more occurrences of any character. ? Indicates a single character that matches one occurrence of any single character. The Allow Compression Property window is displayed.com/transactions/* v sftp://
[email protected] any existing policy to edit the policy. 3. The remote server must also possess the appropriate certificate. and [x-y] would match x or y.domain. Provide the following inputs: 122 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide . or click Add to create a new policy. Click the Restrict to HTTP 1. 4. Restrict to HTTP/1. [] Indicates a delimited range of alphabetic or numeric characters. For example. You can use any PCRE-compliant expression. [1-5] would match 1.0 Policy The User Agent can restrict HTTP communications to the HTTP 1. or click Add to create a new policy.0 Policy Property window is displayed. Allow Compression Use the toggle to enable (on) or disable (off) compression. For example. For more information. 2.pcre. [1-5] would match 1. Click Save to add this policy to the list. refer to http://www. refer to http://www. [] Indicates a delimited range of alphabetic or numeric characters. 3.pcre. 4. Click any existing policy to edit the policy. Note: A Multi-Protocol Gateway can also inject HTTP headers. The Inject Header Property window is displayed.0 Use the toggle to enable (on) or disable (off) HTTP protocol restriction. Click Save to add this policy to the list.? Indicates a single character that matches one occurrence of any single character. You can use any PCRE-compliant expression. Match patterns can contain the following wildcard syntax: * Indicates a string that matches 0 or more occurrences of any character. The Restrict to HTTP 1. Use this Policy to control this behavior. and [x-y] would match x or y.org. 3. The User Agent operates on the communication after the gateway. and [x-y] would match x or y.0 specification. or 5. ? Indicates a single character that matches one occurrence of any single character. Inject Header Policy The User Agent can inject an HTTP Header and corresponding value into the communication with the remote server. Restrict to HTTP 1. Provide the following inputs: URL Matching Expression Specify a URL Match expression in the URL Matching Expression field.0 Policy tab. 2. if so desired.org. Click the Inject Header Policy tab. For more information. Click any existing policy to edit the policy. or 5. ? Indicates a single character that matches one occurrence of any single character. Match patterns can contain the following wildcard syntax: * Indicates a string that matches 0 or more occurrences of any character. unlike all other HTTP 1. ? Indicates a single character that matches one occurrence of any single character. For example. the backend server must be RFC 2616 compatible.1 protocol. However.URL Matching Expression Specify a URL Match expression in the URL Matching Expression field. Click any existing policy to edit the policy. To stream full documents towards the backend server. Provide the following inputs: URL Matching Expression Specify a URL Match expression in the URL Matching Expression field. many applications will fail to understand Chunked encoding. and [x-y] would match x or y. Header Value Specify the corresponding value string for the injected header. Referenced objects 123 . [] Indicates a delimited range of alphabetic or numeric characters. Click Save to add this policy to the list. While all servers will understand how to interpret Content-Length. Note: A Multi-Protocol Gateway can also control Chunked Uploads. Click the Chunked Uploads Policy tab. Header Name Specify the name of the HTTP Header to inject. For this reason. However doing so interferes with the ability of the appliance to fully stream.1 features that can be negotiated down at runtime if necessary. or 5. this property should be enabled. Chunked Uploads Policy The User Agent can use HTTP 1. Appendix A. the body of the document can be delimited by either Content-Length or chunked encoding.pcre. This is useful for streaming large documents. [1-5] would match 1. or click Add to create a new policy.org. because this feature cannot be renegotiated at run time. 3. You can use any PCRE-compliant expression. 4. refer to http://www. For more information.1 Chunked content encoding. 2. Match patterns can contain the following wildcard syntax: * Indicates a string that matches 0 or more occurrences of any character. Content-Length is the standard method. The Chunked Uploads Property window is displayed. When the appliance employs the HTTP 1. The User Agent operates on the communication after the Multi-Protocol Gateway. You can use any PCRE-compliant expression. refer to http://www. 2. You can use any PCRE-compliant expression. [1-5] would match 1. Enable/Disable HTTP 1. ? Indicates a single character that matches one occurrence of any single character. For example. The FTP server will open all data connections to the FTP client. and [x-y] would match x or y. Click Save to add this policy to the list. For more information. but do not fail if the server does not support PASV. 3. this mode is incompatible with firewalls.1 Chunked Request Bodies Use the toggle to enable (on) or disable (off) chunked encoding.[] Indicates a delimited range of alphabetic or numeric characters. 4.org. Click the FTP Client Policies tab to display the User Agent configuration (FTP Client Policies) screen. Match patterns can contain the following wildcard syntax: * Indicates a string that matches 0 or more occurrences of any character. or 5. refer to http://www. Passive Mode Select how the use of FTP passive mode to control the direction in which FTP data connections are made.pcre. These controls can be further overridden by query parameters in the URL that is used to initiate the file transfer. FTP Client Policies The User Agent can associate a set of FTP URLs with a specified policy that controls the default values of many FTP client options for outgoing FTP connections. 2. [1-5] would match 1. Click any existing policy to edit or click Add to create a new policy to display the FTP Client Policies Property window. Provide the following inputs: URL Matching Expression Specify a shell-style expression that defines a URL set. 124 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide . and [x-y] would match x or y. 4. Request Passive Mode Use the FTP PASV command to request that the FTP client be allowed to open all data connections to the FTP server. For more information. Passive Mode Not Requested Do not use the FTP PASV command to allow the client to open FTP data connections.org. For example. [] Indicates a delimited range of alphabetic or numeric characters. or 5. Often.pcre. 3. fail. Use the FTP PROT C command if command channel is encrypted or has been encrypted. and fail if the server does not support PASV. Request Data Encryption Request encryption of FTP data connections using the FTP PROT P command. Require TLS Authentication Use the FTP AUTH TLS command to encrypt the command connection. Request Stop Encryption Use the FTP CCC command to request the end of encryption of the command channel using TLS. this behavior is the only option when a NAT is in use. even if the command channel is encrypted. All setting are compatible with NAT. No Authentication Requested (Default) Do not use the FTP AUTH command to allow encrypt the command connection. Require Data Encryption Request encryption of FTP data connections using the FTP PROT P Appendix A. Leave Encrypted (Default) Leave the FTP command connection encrypted after (optional) authentication of the USER and PASS commands. This setting is not compatible with NAT and many firewalls. The command connection remains secure. Encryption must be stopped for compatibility with NAT (Network Address Translation) and other firewall applications. Encrypt Command Connection Select how to control the use of TLS to secure the FTP command connection. The user name and password will be passed in the clear. if supported by the server. Stop Command Encryption After Authentication Select how to control the cessation of FTP command channel encryption after user authentication. Although this behavior might be a security risk. Do not fail if the server does not support data encryption. If not available. This setting is required for compatibility with NAT and many firewall. Request TLS Authentication Use the FTP AUTH TLS command to encrypt the command connection. Require Stop Encryption Use the FTP CCC command to request the end of encryption of the command channel using TLS. if available.Require Passive Mode (Default) Use the FTP PASV command to request that the FTP client be allowed to open all data connections to the FTP server. Some servers do not support CCC. Encrypt File Transfers Select how to control the encryption of file transfers. Referenced objects 125 . This setting requires that the command change is encrypted or has been encrypted. If not supported. fail. Unencrypted Data (Default) Do not encrypt FTP data connections. Size Check Select whether to perform a size check after a transfer. Some XML files.) character that begins the suffix). Quoted Commands Select an FTP Quoted Command to send to the FTP server before each STOU. STOR. Disabled Do not perform this check. Image (Binary) Data (Default) Transfer files in image mode. This setting uses the FTP TYPE I command. or RETR command. When enabled and the URL end in a slash. Write Unique Filename if Trailing Slash Select whether the FTP server creates unique file names. use the STOU command to request that the server generates a unique file name in the target directory. This setting requires that the command change is encrypted or has been encrypted. Before enabling. ensure that the FTP server support the STOU command. This setting uses the STOR command to initial the transfer. This setting allows for the standardizations of end-of-line conventions between different operating systems. This setting uses the FTP TYPE A command. the STOU command is used instead of the STOR command.command. Fail if the server does not support data encryption. In most cases. which transfers data as binary 8-bit bytes. instead of having the FTP client choose a unique name. Optional (Default) If the FTP SIZE command is available. must be transferred in image mode. Data Type Select the default data type of file transfers. Request Unique File Name When Trailing Slash (Default) If the supplied file name ends in a slash (before the question mark (?) character that initiates the query parameter. This setting increases the overhead at both ends of the transfer. the transfer generally fails. the default value of binary is appropriate. Use Supplied File name Always uses the supplied file name to generate the target file name that is requested on the server. This behavior allows multiple systems to write files to the same directory without any risk of duplicate file names that overwrite each other. because there is only a directory specification (no file name). such as ones that are signed. If the URL ends in a slash. The SIZE command compares the 126 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide . Some FTP servers provide the STOU command. or the semicolon (. This setting is more efficient and has less overhead at both ends of the transfer. ASCII Data Transfer files in ASCII mode. The STOU command causes the FTP server to choose a unique file name to write to in the current directory. The transfer fails if the FTP server does not support the STOU command. use it to check the size of the file after transfer. Comments Specify a descriptive object-specific summary.returned value to the number of bytes that were transferred. 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). click Add. The Web Application Firewall Configuration (Main) screen is displayed. Referenced objects 127 . Admin State Retain the default setting. such as SQL Injection v Cookie handling. The Web Application Firewall offers: v Destination service proxy v SSL termination v Authentication and authorization service v Rate limiting v Session start and timeout enforcement v URL-encoded name-value input processing v HTTP protocol filtering v Threat protection. Web Application Firewall A Web Applications Firewall provides security. proxy. click the name of the firewall in the catalog. ticket sales. The catalog lists all Web Application Firewall objects that are configured in the current domain. specify the name of the Load Balancer Group. click disabled. To place the object in an inactive administrative state. Remote Host Specify the host name or IP address of the backend server. To use a load balancer. If the appliance should employ an SSL connection to the backend server. the transfer is marked as failing. If not equal. threat mediation and content processing services for a Web-based application (such as enrollment. 2. To create a new Web Application Firewall service. The name must be unique throughout the appliance. 3. configure an SSL Proxy Profile that in turn uses a Crypto Profile configured for client (or forward) connections. Select Objects → Services → Web Application Firewall to display the Web Application Firewall catalog. or a trading system). To edit an existing Web Application Firewall. SSL Proxy Profile Select an existing SSL Proxy Profile to assign the SSL Proxy Profile to Appendix A. benefits management. Provide the following inputs: Name Specify a unique name for this object. Remote Port Specify the TCP port number of the backend server. including sign and encrypt v Error handling v XML and non-XML content processing 1. Click Save to add this policy to the list. select an Application Security Policy. Error Policy Select an existing Error Policy to assign that policy to this firewall. the Error Policy established by the Application Security Policy overrides this selection. XML Manager Select an existing XML Manager to assign that manager to this firewall. More than one firewall can use the same XML Manager. use an SSL Proxy Profile that uses a Crypto Profile configured for two-way SSL. The default XML Manager is used if you do not create one. Refer to “Defining SSL Proxy Profile objects” on page 19 for more information. v To implement SSL communication with both requesting clients and the backend server. or both will use SSL in accordance with the configured Crypto Profile. Security Policy To establish the security policy to be enforced by this firewall. in turn. Refer to “Error Policy” on page 99 for more information.this handler. no request-side security policies are enforced. The User Agent settings. Optionally. This policy is the default policy that handles responses sent to the client. an XML Manager can employ a User Agent. use an SSL Proxy Profile that uses a Crypto Profile configured as a Server (reverse) profile. communication with clients. the rules in this policy handle the violation. When selected. set the SSL check box for at least one source address. User Agent settings override settings on the XML Manager. To override (disable) the defined request or response security policy that is defined by the selected Application Security Policy. Refer to “XML Manager” on page 142 for more information. Under Source Addresses. Because an Application Security Policy can also establish an Error Policy. v To implement SSL communication with requesting clients. If any part of the Application Security Policy is violated. You can enable the streaming of XML operations by configuring the XML Manager to use a Streaming Compile Option Policy. can affect the behavior of the gateway when communicating with backend servers or with clients when returning responses. 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. the backend server. Request Security If disabled (off). 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. All 128 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide . Refer to “Application Security Policy” on page 97 for more information. click off for these fields on this configuration screen. This property overrides the response security policy that is defined in the selected Application Security Policy. Buffer Messages Buffers submitted messages until all processing is verified as complete. After verification. the URI is rewritten to make the URI RFC-compliant. in seconds. Stream Messages Begins to send the message to the backend before all processing is complete. the default). 2. that a front-side client-connection can be idle before being abandoned in a transaction. Select this option when the selected XML Manager has streaming enabled or when streaming of attachments is enabled. Proxy Settings tab To modify the default proxy settings: 1. Click the Proxy Settings tab. Optionally. characters that are escaped that do not need to be are unescaped. Provide the following inputs: Normalize URI When this property is enabled (on. Stream Output to Front Select the desired streaming behavior. This makes checking for attack sequences more reliable. Certain characters will be escaped. Click Apply to save the object to the running configuration. no response-side security policies are enforced. Referenced objects 129 . This behavior potentially increases processing speed. in seconds. This property overrides the request security policy that is defined in the selected Application Security Policy. All responses are allowed through. Stream Output to Back Select the desired streaming behavior.requests are allowed through. After verification. additionally. Stream Messages Begins to send the message to the requesting client all processing is complete. Select this option when the selected XML Manager has streaming enabled or when streaming of attachments is enabled. forward the message to the appropriate requesting client. forward the message to the appropriate backend. 4. that a backside client-connection can be idle before being abandoned in a transaction. Response Security If disabled (off). click Save Config to save the object to the startup configuration. Front Side Timeout Specify the amount of time. Buffer Messages Buffers submitted messages until all processing is verified as complete. 5. This behavior potentially increases processing speed. Back Side Timeout Specify the amount of time. Appendix A. The backend server must also support HTTP 1. Web servers that issue redirects might want to disable this feature. Optionally. HTTP Response Version Select the HTTP version (HTTP 1. 130 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide . Refer to “URL Rewrite Policy” on page 114 for more information. Use HTTP 1. HTTP Options tab To modify the default HTTP options: 1. Header and URL Rewrite Policy Optionally assign a URL Rewrite Policy.0 or HTTP 1. separate from the URL.1. to replace a header value in the message.0 requests will always be replied to with 1. 3.1. the default) the firewall tries to resolve the redirects.1 protocol. Incoming HTTP 1. the default) to use on client responses. click Save Config to save the object to the startup configuration. Provide the following inputs: HTTP Version to Server Select the HTTP version (HTTP 1. Click Apply to save the object to the running configuration. Click the HTTP Options tab. 2. 4. This policy defines rules to rewrite the entire URL or a portion of the URL. such as chunked uploads. in seconds (in the range 0 through 86400. The rewrite rules are applied before document processing. Allow Chunked Uploads Enable (on) or disable (off. HTTP response code 302. When disabled (off) the backside server receives a request that reflects the information as it arrived at the DataPower appliance. Rewrite Host Names When Gatewaying Some protocols have distinct name-based elements. HTTP uses the Host header for this purposes.0 or HTTP 1. to demultiplex.1 to support chunked responses. require the selection of 1. with a default of 180). with a default of 180). Follow Redirects Some protocols generate redirects as part of the protocol.1. Front Persistent Timeout Specify the maximum amount of time. that a gateway maintains an idle persistent TCP connection on the front side. in seconds (in the range 0 through 86400. the evaluation criteria in the Matching Rule is against the rewritten value. Certain HTTP 1. the default) the ability to send Content-Type Chunked Encoded documents to the backend server.1 for the connection to be established and maintained using the HTTP 1. that a gateway maintains an idle persistent TCP connection on the backside. or to rewrite the HTTP POST body in the message.Back Persistent Timeout Specify the maximum amount of time. If this property is enabled (on. for example. the default) to use on the server-side connection. Therefore.0 compatible responses regardless of this setting. When enabled (on. the default) the backside server receives a request that reflects the final route.1 features. Web servers often depend on the Host header for the value of their redirect. the default value. Refer to “User Agent” on page 117 for more information. enable this property. Click Apply to save the object to the running configuration. the Crypto Profile of the selected SSL Proxy Profile handles these requests. HTTP Client IP Label Retain X-Client-IP. 4. Optionally. Port Number Specify the TCP port on which the service listens.0.0. 4. All other HTTP 1. Source Addresses tab Source addresses determine the IP addresses and TCP ports to assign to the service. or provide another value (for example. click Save Config to save the object to the startup configuration. Click Apply to save the object to the running configuration. the body of the document can be delimited by either Content-Length or chunked encoding. Click Add. Optionally. Content-Length is the standard method. The default is 3000. When enabled. Referenced objects 131 . this property can be enabled at the User Agent on a per-URL basis. This value indicates that the service is active on all addresses. 3. Appendix A. 2. Alternatively. 7. To stream full documents toward the backend server. use the following procedure: Click the Source Addresses tab to display the Source Addresses catalog. This feature cannot be renegotiated at run time. host name. v Select the check box to enable. To 1. add a source address.1 protocol. X-Forwarded-For). When enabled. Repeat steps 2 through 4 to define additional source addresses.0. The default is 0. Provide the following inputs: Local IP Address Specify the IP address. SSL Indicates whether the service acts as an SSL server for requesting clients. Click Save. click Save Config to save the object to the startup configuration.1 features can be negotiated at run time. Retaining the default value interferes with the ability of the appliance to stream full documents. or host alias on which the service listens. Use an integer in the range of 1 through 65535. v Ensure that the check box is not selected to disable. While all servers can interpret Content-Length. For this reason. At least one source address must be configured.When the appliance uses the HTTP 1. 6. many applications fail to understand Chunked Encoded documents. 3. Remote clients connect to these addresses. 5. the backend server must be RFC 2616 compatible. the satisfaction style helps determine how the results of those profiles are combined. guarantee acceptance of the transaction. authorization and audit v Rate limit traffic v Filter access by IP address v Establish error handling v Manage sessions v Filter HTTP methods v Filter HTTP header. Click Add to create a new Web Request Profile. 132 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide . URL-encoded HTTP POST. and filter cookies v Provide service threat protection. The admission style. This name appears in the catalog listing and in all lists of available Web Request Profiles. the client’s request (the transaction request) is immediately forwarded to the backend service. encrypt or sign. Mode Select the satisfaction style. A Web Request Profile can do any or all of the following: v Allow or deny SSL communications v Perform authentication. Click the name of an existing object to edit it. To place the object in an inactive administrative state. such as filtering SQL injection attacks Select Objects → Web Applications → Web Request Profile to display the Web Request Profile catalog. any other matching profiles will be run and the whole transaction only passes if no failure is found. click disabled. a passed profile of the prerequisite satisfaction style does not. This catalog lists all Web Request Profile objects. The request is not necessarily forwarded to the backend service. any other profile that matches the request can now run.Web Request Profile A Web Request Profile establishes the security policy to apply to requests that originate from clients. however. A failed profile always results in the failure of the transaction. Each transaction could match more than a single request profile on the same transaction. the request is passed to the backend service. No other matching profile is run. However. and HTTP Query String values v Manage XML traffic v Allow or disallow. Provide the following inputs: Name Specify a name for this object. Admission If a request passes the criteria defined in this profile. on its own. If this happens. Comments Specify a descriptive object-specific summary. if there are no other matching profile and the request passes this profile. Admin State Retain the default setting. The Web Request Profile configuration screen is displayed. on the other hand. Prerequisite If a request passes the criteria defined in this profile. passes the transaction as soon as the profile is declared passing. In those circumstances. 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. A Rate Limit Policy restricts identities (as determined by AAA or the client IP address if AAA has not been selected) to a specific number of transactions per second or a specific number of concurrent transaction connections. To limit connections from a given IP address (after a count of requests from that address results in an error) hits a certain level. If the Web Application Firewall is not configured as an SSL server and the client attempts to use SSL. the connection is refused before this policy executes. Deny Do not allow SSL communications to the appliance. Only those requests that successfully pass the AAA policy selected will be forwarded to the backend service. This Access Control List will be used to allow or deny access to this service based on the IP address of the client. Allow Allow SSL communications to the appliance. Leave the default selection (none) to enforce no authentication and authorization policy on requests. use an Error Policy (refer to “Error Policy” on page 99).Most profiles will be admission style. Refer to “Rate Limiter” on page 112 for more information. Refer to “AAA Policy” on page 57 for more information. Retain the default value of (none) to not enforce rate limiting. Referenced objects 133 . is met. When this option is selected. Access Control List Select an Access Control List. established in the Application Security Policy. This profile will only run when the corresponding match rule. The connection might employ SSL. When attached to a service. or multipart/form-data MIME types will be automatically provided to the AAA processing policy. The connection will not succeed unless the Web Application Firewall is configured as an SSL Server and the client requests SSL communications. application/www-url-encoded. Profile tab Click the Profile tab. Provide the following inputs: Allow SSL Select a profile policy regarding SSL communications. An Error Policy allows for error count monitoring. Require Require SSL communications links to the appliance. an SSL connection request will be refused even when Web Application Firewall is configured to accept SSL connections from clients. an Access Control List denies all access by Appendix A. Any input to this transaction as XML. Rate Limiting Select a Rate Limit Policy to enforce rate limiting on Web requests. AAA Policy Select an AAA Policy to establish AAA filtering on Web requests. Any request that does not employ one of the checked methods will be rejected by the Profile. A Session Policy establishes the URLs that are acceptable starting points (start pages) for a Web application session. The Error Policy selected will also override any Error Policy selected at the Web Application Firewall object level. Retain the default value of (none) to not enforce no Error Policy. Error Policy Select an Error Policy. This Error Policy will run when any client request violates this Web Request Profile. are processed. a Session Policy limits the duration of any session. Provide the following inputs: Methods Use the check boxes to establish accepted HTTP methods. v Requests without a body are not subject to this constraint. Retain the default value of (none) to not enforce access control.default. Refer to “Error Policy” on page 99 for more information. all content types are allowed. for example). No processing (Default) No processing performed. v Requests without a content type are assumed to have their content-type header set to an empty string. such as text/xml. first grant access to all addresses (allow 0. or send a copy of request content to a third location).0. if encountered. If you do not define any content type. To deny access to only selected addresses. Session Policy Select a Session Policy. Versions Use the check boxes to establish accepted HTTP versions. Retain the default value of (none) to not enforce session management. Processing tab It is possible to perform actions on Web requests (such as transform XML content. Methods & Versions tab Click the Methods & Versions tab to control the HTTP methods and versions accepted by this Profile. 134 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide . Click the Processing tab to access these configuration options.0) and then create deny entries for the desired hosts. Use a PCRE to define the allowed content types. Refer to “Session Management Policy” on page 113 for more information. In addition. Any request that does not employ one of the checked versions will be rejected by the Profile. Content-Type List Specify which content-type headers to allow on the request. Provide the following inputs: XML Processing Select how requests containing an XML MIME type in the HTTP header Content-type: field (text/xml.0. The Rule can perform such actions as authenticate and authorize. The XML Transformation Rule specified then runs on the request and the result is used as the request content. This rule can alter the content of the request. Refer to “Processing Rule” on page 111 for more information. thus providing both content control and threat protection. or send a copy of the request content to a third destination. The XML Transformation Rule specified then runs on the request and the result is used as the request content. This provides a means to control the name-value pairs passed to the backend server. are processed. The Rule can perform such actions as authenticate and authorize. Referenced objects 135 .Well Formed XML The appliance parses the request to validate that the request is well-formed XML. repackage with additional information retrieved from elsewhere or send a copy of the request content to a third destination. This is done using the inputs available on the Name Value tab. convert to XML. for example). Non-XML Processing Rule Select a Processing Rule for requests when they do not contain an XML MIME type and the XML processing policy is set to Side Effect or Binary. This rule cannot alter the content of the request (cannot access the INPUT and OUTPUT multistep processing contexts). Non-XML Processing Select how requests that do not contain an XML MIME type in the HTTP header Content-Type field (www-url-encoded. XML Transformation Rule Select a Processing Rule for requests when they contain an XML MIME type and the XML processing policy is set to Well Formed XML or Well Formed SOAP. No processing (Default) No processing performed. Well Formed SOAP The appliance parses the request to validate that the request adheres to the SOAP specifications. The request payload is submitted as an non-parsed binary object. Name Value tab The profile can filter the names and corresponding values of HTTP headers. Each HTTP header name-value pair will be Appendix A. Binary Rule The appliance executes the Non-XML Processing Rule specified. Refer to “Processing Rule” on page 111 for more information. Provide the following inputs: Header Name-Value Profile Select a Name-Value Profile. The result of this rule is then used as the request payload for further processing. URL-encoded HTTP Post body content or HTTP Query strings. Side-Effect Rule The appliance executes the Non-XML Processing Rule specified. These values can also be mapped to alternate values. When this option is selected. URL-Encoded Body Name-Value Profile Select a Name-Value Profile. Refer to “Name-Value Profile” on page 108 for more information. and Cookie Content Name-Value Profile inputs appear. Refer to “Name-Value Profile” on page 108 for more information. When selected. Requests with no cookies will be rejected by this profile. Deny Cookies are not allowed. the Query String Name-Value Profile input is displayed. When this option is selected. Click the Cookie tab to access these configuration properties. any header is allowed. any element is allowed. Cookie tab A Web Request Profile can manage cookies. the appliance encrypts outbound cookies sent by the backend application. Require Cookies must be present in the request. the Profile can sign or encrypt cookies. Sign/Encrypt Cookies Select how to enable signing or encrypting of cookie content. the Sign/Encrypt Cookies. Requests that contain query strings are rejected by this profile. Query String Name-Value Profile Select a Name-Value Profile. Refer to “Name-Value Profile” on page 108 for more information. When selected. When the client returns the cookie on a subsequent request. Requests without query strings are rejected by this profile. the Query String Name-Value Profile input is displayed. Cookies can be allowed. When cookies are not denied. Allow Cookies are allowed. Allow Query String Select an option to determine how to handle HTTP Query Strings. as well as enforce filters on the name-value pairs contained in the cookie. Each element in the HTTP POST body will be subjected to the rules set forth in the selected Profile. Requests containing cookies will be rejected by this profile. Require Query strings must be present in the request. and Cookie Content Name-Value Profile inputs appear. If no profile is specified. the Sign/Encrypt Cookies. Provide the following inputs: Allow Cookies Select how cookies are handled by this profile. Each query string name-value pair in the HTTP request is subject to the rules in the selected profile. If no profile is specified. Encrypt When this option is selected. If no profile is specified.subjected to the rules set forth in the selected Profile. Deny Query strings are not allowed. denied or required. any query string pair is allowed. Allow Query strings are allowed. the appliance decrypts the 136 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide . boundary= -----------------------------1943549852707912569510983863 Content-Length: 1289 -----------------------------1943549852707912569510983863 Content-Disposition: form-data. name="hdrx25" Appendix A. the appliance signs outbound cookies sent by the backend application. U.image/png. If no profile is specified. The Secret Key and IP Address-specific Cookie inputs appear when this option is selected.0 Host: patriot User-Agent: Mozilla/5. Click the Multipart Form tab to access these configuration options.q=0.5 Accept-Encoding: gzip.*/*.7 Content-Type: multipart/form-data.0 (X11.en. q=0.xml HTTP/1. rv:1. Each name-value pair in the cookie will be subjected to the rules set forth in the selected Profile.0.0 -v speed=4 x86-basic-1. When the client returns the cookie on a subsequent request. Referenced objects 137 . Secret Key Signing or Encrypting cookies requires a secret password phrase for the cryptographic operation. (none) (Default) Cookies are neither signed nor encrypted. then each appliance can verify or decrypt a cookie generated by another appliance without the need to maintain any state information. any query string pair is allowed.rot13 Accept-Charset: ISO-8859-1.utf-8.7. If this key is the same on multiple appliances. POST 116. Here is an example of a multipart/form submission.12) Gecko/20051010 Firefox/1. Linux i686.0.application/xml. the appliance verifies and removes the signature before passing it back to the server.text/html. name="upfile".4-20030911.cookie before passing it back to the server. filename="NOTES" Content-Type: application/octet-stream /home/mcm/iso>sudo cdrecord dev=ATAPI:0. Disabling this property makes the generated cookies address independent.q=0.7 (Ubuntu package 1.application/xhtml+xml.q=0. IP Address-specific Cookies Normally the signed or encrypted cookie contains the client IP address and this prevents the client from using this cookie from any other host.7. Refer to “Name-Value Profile” on page 108 for more information. Cookie Content Name-Value Profile Select a Name-Value Profile. The Secret Key and IP Address-specific Cookie inputs appear when this option is selected.9.8. Some environments make this behavior undesirable.text/plain.5 Accept-Language: en-us.iso -----------------------------1943549852707912569510983863 Content-Disposition: form-data.*. name="hdrx21" PRE1776 -----------------------------1943549852707912569510983863 Content-Disposition: form-data.1. This is the default.q=0.7) Accept: text/xml.deflate.q=0. Sign When this option is selected. en-US. Multipart Form tab This Web Request Profile can impose limits on multipart/form submissions. This defaults to 5000000. Provide the following inputs: Minimum Size Specify an integer to determine the minimum request body size in bytes if the HTTP method provides a body. This defaults to 5000000. in characters. and multipart/form-data requests through the standard SQL Injection filter. Filter Unicode Reject (on) or allow (off) requests if Unicode is detected in the URI. Filter Dot Dot Reject (on) or allow (off) requests containing . per part. Filter . Defaults to 1024. Maximum Size Specify an integer to determine the maximum request body size in bytes if the HTTP method provides a body. Threat Protection tab Click the Threat Protection tab to access the configuration options that provide basic threat protection services. Restrict Sub-Content Types Use the toggle to restrict types (on) or to allow all types (off). If enabled. in URI after URI normalization has been performed. SQL Injection Filter Set to on to cause the appliance to pass data parameters from the query string. Defaults to on. Defaults to on. this setting forces the individual form-data content types to be matched against the general list of request acceptable content-type expressions provided on the Main configuration panel for this Web Request Profile. limiting the size of requests. in bytes.. of all parts combined. Maximum URI Length Specify an integer to determine the maximum URI length. 138 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide . This defaults to 4. such as filtering for SQL Injection attacks. Max Aggregate Size of All Parts Specify an integer to determine the maximum size. The default is 128000000. The defaults is 0. Max Size Per Part Specify an integer to determine the maximum size.Post2000 -----------------------------1943549852707912569510983863 Provide the following inputs: Max Number of Parts Specify an integer to determine the maximum number of parts allowed in the request. Defaults to on. in bytes.exe Reject (on) or allow (off) requests containing exe in URI after URI normalization has been performed. or filtering potentially dangerous content based on URI. application/www-urlencoded requests. Truncate If the request contains URI fragments. If this happens. Reject If the request contains URI fragments. Referenced objects 139 . Click Add to create a new Web Response Profile. Admission If a response passes the criteria defined in this profile. A Web Response Profile can do any or all of the following: v Establish error handling v Filter HTTP methods v Filter HTTP header values v Manage XML traffic v Provide service threat protection by managing response sizes Select Objects → Web Applications → Web Response Profile to display the Web Response Profile catalog. Provide the following inputs: Name Specify a name for this object. This catalog lists all Web Response Profile objects.Fragmented URI Policy A URI fragment is the portion of a URI after the hash (#) symbol. click disabled. the server response (the transaction response) is immediately forwarded to the client. Each transaction could match more than a single response profile on the same transaction. Click the name of an existing object to edit it. the request will be rejected by this profile. if there are no other matching profile and the response passes this profile. The response is not necessarily forwarded to the backend service. Mode Select the satisfaction style. This name appears in the catalog listing and in all lists of available Web Response Profiles. the satisfaction style helps determine how Appendix A. Admin State Retain the default setting. Allow URI fragments are allowed. To place the object in an inactive administrative state. No other matching profile is run. However. any other profile that matches the response can now run. the fragments will be removed from the request. Comments Specify a descriptive object-specific summary. the response is passed to the backend service. Web Response Profile A Web Response Profile establishes the security policy applied to responses returned from application servers. The Web Response Profile configuration screen is displayed. Select an option to determine a policy for handling URI fragments. Prerequisite If a response passes the criteria defined in this profile. v Responses without a body are not subject to this constraint. Any response version that does not employ one of the checked versions will be rejected by the Profile. Provide the following inputs: Error Policy Select an Error Policy. v Responses without a content type are assumed to have their content-type header set to an empty string. A failed profile always results in the failure of the transaction. If you do not define any content type.the results of those profiles are combined. all content types are allowed. In those circumstances. The admission style. Click the Processing tab to access these configuration options. guarantee acceptance of the transaction. Codes & Versions tab Click the Codes & Versions tab to control the HTTP methods and versions accepted by this Profile. 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. Most profiles will be admission style. a passed profile of the prerequisite satisfaction style does not. Profile tab Click the Profile tab. Any response codes that do not employ one of the checked methods will be rejected by the Profile. passes the transaction as soon as the profile is declared passing. or send a copy of response content to a third location). Content-Type List Specify which content-type headers to allow on the response. Provide the following inputs: Response Codes Use the check boxes to establish accepted HTTP methods. This Error Policy will run when any client response violates this Web response Profile. however. on the other hand. 140 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide . Leave the default (none) selected to enforce no Error Policy. Use a PCRE to define the allowed content types. Refer to “Error Policy” on page 99 for more information. any other matching profiles will be run and the whole transaction only passes if no failure is found. on its own. such as text/xml. if encountered. Response Versions Use the check boxes to establish accepted HTTP versions. The Error Policy selected will also override any Error Policy selected at the Web Application Firewall object level. Processing tab It is possible to perform actions on Web responses (such as transform XML content. Binary Rule The appliance executes the Non-XML Processing Rule specified. or send a copy of the response content to a third destination. Well Formed SOAP The appliance parses the response to validate that the response adheres to the SOAP specifications. Appendix A. 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. convert to XML. The result of this rule is then used as the response payload for further processing. Referenced objects 141 . are processed.Provide the following inputs: XML Processing Select how responses containing an XML MIME type in the HTTP header Content-Type field (text/xml. This is done using the inputs available on the Name Value tab. for example). are processed. XML Transformation Rule Select a Processing Rule. for example). Well Formed XML The appliance parses the response to validate that the response is well-formed XML. 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. Name Value tab The Profile can filter the names and corresponding values of HTTP headers. No processing (Default) No processing performed. The XML Transformation Rule specified then runs on the response and the result is used as the response content. The Rule can perform such actions as authenticate and authorize. No processing (Default) No processing performed. Side-Effect Rule The appliance executes the Non-XML Processing Rule specified. repackage with additional information retrieved from elsewhere or send a copy of the response content to a third destination. Non-XML Processing Rule Select a Processing Rule. The Rule can perform such actions as authenticate and authorize. The XML Transformation Rule specified then runs on the response and the result is used as the response content. This rule can alter the content of the response. This rule cannot alter the content of the response (cannot access the INPUT and OUTPUT multistep processing contexts). Refer to “Processing Rule” on page 111 for more information. The response payload is submitted as an non-parsed binary object. These values can also be mapped to alternate values. Non-XML Processing Select how responses that do not contain an XML MIME type in the HTTP header Content-Type field (www-url-encoded. Refer to “Processing Rule” on page 111 for more information. you must map these extensions to their DataPower equivalent. 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. An XML Manager also provides the following capabilities: v Basic network configuration. XML Manager The firmware creates a default XML Manager object in the default domain and in each application. The most common example is the node-set() extension function. v Enable schema validation by defining schema-validation rules. Threat Protection tab Click the Threat Protection tab to access the configuration options that provide basic threat protection services. The default instance in each domain can be edited like any other instance of an XML Manager object. such as load balancing and accessing remote servers. This ability removes the need to alter or rewrite a style sheet for use by the appliance. and other document resources on behalf of one or more services. the appliance can 142 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide . any header is allowed. Each HTTP header name-value pair will be subjected to the rules set forth in the selected Profile. the priority. This policy allows an administrator to determine how to cache documents. v Set manager-associated limits on the parsing of XML documents. The policy defines the time-to-live. These rules apply to all documents that match predefined criteria. An XML Manager object can automatically map custom style sheet extension functions to DataPower extension functions. By default. This defaults to 0.Provide the following inputs: Header Name-Value Profile Select a Name-Value Profile. These limitations provide for increased security and stability to protect against DoS attacks or runaway data. XML Manager objects obtain documents via HTTP. or Salon nodeset XSLT extension functions. by limiting the size of responses. and the type. v Enable the caching of documents that this XML Manager object obtains. An XML Manager object obtains and manages XML documents. Maximum Size Specify an integer to determine the maximum response body size in bytes if the HTTP method provides a body. If no profile is specified. The number of documents in the cache depends on the availability of allocated memory. It is possible to map any extension function to a DataPower extension function. v Define extension function mapping. Alternatively. style sheets. v Define the caching policy for documents. If a service uses style sheets that reference the Microsoft node-set. Parser limits defined by the XML Manager object that is associated with a service can be overridden by service-specific settings. the appliance imposes limits on various characteristics of XML documents. Oracle node-set. This defaults to 128000000. The default instance in each domain operates independently of each other. Refer to “Name-Value Profile” on page 108 for more information. define the documents to store in the document cache. Flushing the document cache The appliances maintains a cache of documents. The remaining properties modify default values or implement enhanced behavior. On the Extension Functions tab. Referenced objects 143 . Certain applications might require the running of a scheduled processing rule. 10. Otherwise. define the caching of documents that are obtained via HTTP. 5. Click Apply to save the object to the running configuration.validate documents with a validate action in a processing rule. To flush the cache. 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. define rules to enforce validation of all documents that match the defined criteria. On the Scheduled Processing Policy Rule tab. On the Main tab. For information about the configuration properties. This function is available from the following screens: Appendix A. click Flush Stylesheet Cache. On the Document Cache tab. the XML Manger object continues to use the previous compiled style sheets until they are recompiled. On the Schema Validation Rules tab. Policy-based schema validation is the preferred strategy. define scheduled processing rules. To flush the cache. On the XML Parser Limits tab. Do not mix and match schema validation strategies. 11. define the limits to impose when parsing XML documents. 6. 2. To configure an XML Manager: 1. Select Objects → XML Processing → XML Manager to display the catalog. define the basic configuration. 4. click Flush Document Cache. 8. Note: After a change to a Compile Options Policy object. refer to the online help. 3. Click Add to display the configuration screen. define the maps for custom extension functions to DataPower extension functions. click Save Config to save the object to the startup configuration. 9. Optionally. On the Document Cache Policy tab. v Schedule processing rules. 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. 7. flush the stylesheet cache. the connection will fail. but if more than one client with the same tuple try to connect. refer to the section on preparing to provide network security services in the z/OS Communications Server: IP Configuration Guide. The z/OS NSS Client object specifies the authentication information required to allow the DataPower appliance to function as an NSS client. the following actions occur: v DataPower requests a secure connection to the z/OS Communications Server v RACF performs authentication of users v RACF performs authorization to resources v RACF logs authorized and unauthorized attempts to access RACF-protected resources v z/OS Communications Server NSS protocol provides return codes and reason codes for connectivity requests To support this functionality. For further information. The z/OS NSS Client object specifies the following properties: v Remote Address v Remote Port v v v v v SSL Proxy Profile Client ID System Name User Name Password Based on these properties and the request type. Only one physical connection per Remote Address. v Configure SSL for the TCP connection between the client and server. If the connection is not established or the provided parameters are not valid. and Client ID is allowed. For further information. the object operational state is down and shows one of the following event codes: v Invalid registration parameters v TCP connection retry (interval is 1 minute) v TCP connection in progress v Communication failed 144 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide . refer to the section on configuring the NSS server in the z/OS Communications Server: IP Configuration Guide. v Authorize the client userid to SAF profiles representing security services and resources. Remote Port. the NSS server must be configured to support the NSS client.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. See the following z/OS Communications Server documentation for these configuration steps: v Enable the XMLAppliance discipline support. refer to the section on network security services server in the z/OS Communications Server: IP Configuration Reference. For further information. Additional z/OS NSS Client objects might be configured. 13. click Add. Reenter the password in the Confirm Password field. Specify a descriptive object-specific summary in the Comment field.wss?rs=852&uid=swg21329236 for z/OS Communications Server: IP Diagnosis Guide updates. Select OBJECTS → z/OS Configurations → z/OS NSS Client to display the catalog. Optionally. 11. 3. 8. Click Apply to save the object to the running configuration. Referenced objects 145 . 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. Specify the port on which the NSS server listens in the Remote Port field. Appendix A. 14. 7. use the following procedure: 1. 15. 6. Specify the system name to identify the NSS client to the NSS server in the System Name field.com/support/docview.ibm. Specify the password to use to authenticate with the SAF in the Password field. 4. Specify the IP address or hostname of the NSS server in the Remote Address field. Specify the user name to use to authenticate with the SAF in the User Name field. Creating the z/OS NSS Client To configure a z/OS NSS client. 10. Retain the default setting for the Admin State toggle. To display the configuration screen. 12. 5.v Cannot connect to host For additional information on logged NSS protocol return codes and reason codes. click disabled. refer to http://www. Select an SSL Proxy Profile in the SSL Proxy field to provide a secure connection to the remote authentication server. Specify the client ID to be used for registration with the NSS server in the Client ID field. Specify the name of the object in the Name field. 2. click Save Config to save the object to the startup configuration. To place the object in an inactive administrative state. 9. 146 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide . A multistep transaction can include both a request component and a response component. For a complete list of the available extension variables. except PIPE. 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. 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. refer to “Extension variables” on page 156. In other words. The local context cannot be accessed by any object outside of the scope of the multistep transaction. 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. © Copyright IBM Corp. var://context/context/variable Addresses a variable called variable in a context called context. This action creates a variable in a specified context and assigns it a value. the service cannot read and use the variable. There are the following distinct variable types. The local context cannot be accessed by any object outside of the scope of the multistep transaction. To use a variable. Working with variables Variables can be used in most context. The majority of service variables are read-only and cannot be set. In other words. 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. 2002. A multistep transaction can include both a request component and a response component. A named context variables can be user-defined or based on an extension variable. Note: Creating variables in a named context is the recommended approach.Appendix B. the service cannot read and use the variable. you must create it with the Set Variable action. A local context variables can be user-defined or based on an extension variable. For a complete list of the available extension variables. 2009 147 . refer to “Extension variables” on page 156. 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. refer to “Service variables. Note: Refer to “List of available variables” on page 159 for the list of variables that you can define for document processing. System variables persist beyond the multistep scope and can be read by other objects in the system. Service variables Service variables enable the setting and retrieval of pieces of state that usually reflect the state of the current transaction.For a complete list of the available service variables. If the content of a variable needs to be read or set outside the scope of the multistep process. use a system variable. Table 2. 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. refer to “System variables” on page 158. Names and permissions for general service variables that are available to only Multi-Protocol Gateway and Web Service Proxy services 148 Variable name Permission var://service/mpgw/backend-timeout Read-write IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide . 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. Table 2 lists the names and permission for these variables.” var://system/variable Addresses a global variable that is available in all contexts. Table 1. For a complete list of the available global system variables. Table 1 lists the names and permission for these variables. General variables are available to all services. 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. Use this variable as a custom redirect implementation. var://service/reply-to-qm Read and write the value in the ReplyToQMgr (Reply to Queue Manager) MQ header. Use an integer in the range of 1 through 86400. not as the point of the service. Table 3. When write. Working with variables 149 . Appendix B. unusual messages might be written to the event log. indicates that the service skips backside processing. shows the input message value. changes the dynamic routing. changes the dynamic routing.Table 2. Configuration services service variables This section contains information about variables for configuration services in alphabetic order by permission category. Table 3 lists the names and permission for these variables. Because the service is not aware of the processing flow. When read. 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. gets or sets the backend timeout. Read-write variables var://service/max-call-depth Gets or sets the maximum call depth for each transaction. When read. This variable controls how many levels of called rules can be layered before an error is thrown. var://service/reply-to-q Read and write the value in the ReplyToQ (Reply to Queue) MQ header. When write. Setting this variable overrides the default timeout. 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. Read-write variables var://service/mpgw/backend-timeout For Multi-Protocol Gateway and Web Service Proxy services only. The default is 128. in seconds. shows the input message value. Set this variable to 1 to prevent backside processing. Table 5 lists the names and permission for these variables. var://service/mqmd-reply-to-q Sets the output MQ message descriptor. Legacy MQ-specific service variables This section contains information about MQ-specific variables in alphabetic order by permission category. Table 4. 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. 150 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide .ReplyToQMgr value for an MQ Host or MQ Proxy service. MQ-specific variables are available to only the legacy MQ Host and MQ Proxy services. Table 4 lists the names and permission for these variables. 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.Load balancer service variables This section contains information about load balancer variables in alphabetic order by permission category. var://service/mqmd-reply-to-qm Sets the output MQ message descriptor.ReplyToQ value for an MQ Host or MQ Proxy service. Table 5. 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. Multistep variables This section contains information about system variables in alphabetic order by permission category. shows the input message value. Table 6. Multistep variables usually impact the behavior of specific actions in the context of a processing rule. Appendix B. Working with variables 151 . var://service/message-identifier Read and write the MQ value in the Message Identifier header for MQ Host and MQ Proxy services. Use a setvar action before a log action to change the version of SOAP to use when logging this message. When read. 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. 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. changes the dynamic routing. var://service/persistence Read and write the MQ value in the Persistence for MQ Host and MQ Proxy services. When write. Table 6 lists the names and permission for these variables. var://service/priority Read and write the MQ value in the Priority header for MQ Host and MQ Proxy services. When write. shows the input message value. changes the dynamic routing. 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. var://service/report Read and write the MQ value in the Report header for MQ Host and MQ Proxy services.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. When read. var://service/message-type Read and write the MQ value in the Message Type header for MQ Host and MQ Proxy services. the DataPower service 152 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide .2. Table 7. no notification is sent. Read-write variables var://service/soap-oneway-mep Gets or sets the SOAP one-way Message Exchange Pattern (MEP) notification.1. When using WSA and one-way MEPs. 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 true. the service layer will time out waiting for a response. v When false. var://service/transaction-name Sets the name for asynchronous transactions. 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. notifies the service layer that this transaction is performing a one-way MEP operation.Supports the following values: soap11 Uses SOAP 1. Table 7 lists the names and permission for these variables. 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-timeout Sets the timeout for asynchronous transactions. soap12 (Default) Uses SOAP 1. When a DataPower service is configured for WSA-to-WSA and it receives a WSA annotated message without the wsa:MessageId. assumes that this is a one-way MEP and notifies the service layer by setting this value of this variable to true. Setting this variable overwrites the error response that is sent to the client in an error condition. var://service/error-ignore Gets or sets a flag that controls how the Front Side Handler processes error condition. If any error happens and the variable is set. var://service/error-message Gets or sets the generic error message that is sent to the client. on the TIBCO EMS and WebSphere JMS Front Side Handler use this variable. The default value is 0. This variable is not needed for Web Service Proxy services. as one-way MEPs are identified by reviewing the specifics of the port operation. Read-write variables var://service/error-code Gets or sets the assigned error code from the Result Code table. var://service/error-protocol-response Sets the protocol-specific response for an error. Table 8. Names and permissions for variables that are available for error handling Variable name Permission var://service/error-code Read-write var://service/error-ignore Read-write var://service/error-message Read-write var://service/error-protocol-reason-phrase Write-only var://service/error-protocol-response Write-only var://service/error-subcode Read-write var://service/strict-error-mode Read-write Write-only variables var://service/error-protocol-reason-phrase Sets the protocol-specific reason phrase for an error. To set the error message that is written to the log file. This variable overwrites the reason phrase in the response to provide a short description that an be understood by people. Currently. Error handling transaction variables This section contains information about error handling variables in alphabetic order by permission category. The content of the message is produced by an error rule. use the var://service/formatted-error-message variable. Working with variables 153 . This variable contains the error condition that stopped multistep processing. it does not run any error handling action and produces a regular response. This variable overwrites the protocol-specific response code in an error condition. Table 8 lists the names and permission for these variables. 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. Appendix B. If the value is set and greater than zero. Table 10. Setting the var://service/set-request-header/FOO variable to the value BAR would set the request header FOO to BAR. 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. the sub-code is a more specific result code. 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. Often. This variable can help to disambiguate the reason for which the error rule was invoked. Sometimes. var://service/set-response-header/ Sets the protocol response header. Table 9 lists the names and permission for these variables. Table 10 lists the names and permission for these variables. an invocation of the dp:reject extension element stops multistep processing. the sub-code is the same as the value of the var://service/error-code variable. var://service/set-request-header/ Sets the protocol request header. Persistent connection transaction variables This section contains information about persistent connection variables in alphabetic order by permission category. var://service/strict-error-mode Gets or sets the strict error mode. 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. This variable directly correlates to the dp:set-request-header() extension function. This variable controls the error mode for multistep processing. Names and permissions for variables that are available for persistent connections 154 Variable name Permission var://service/connection/note Read-write IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide . v If the value is not set. var://service/append-response-header/ Appends to the protocol response header. v If the value is set. Table 9.var://service/error-subcode Gets or sets the error sub-code. the service generates an error. use the var://service/URI variable. These extension element. Multi-Protocol Gateway. URL-based transaction variables This section contains information about URL-based transaction variables in alphabetic order by permission category. Use this variable before using the var://service/routing-url variable. Table 11. – The URI is stripped. var://service/routing-url-sslprofile Sets the SSL proxy profile for the routing URL (dynamic route). – The URI is absolute and cannot be controlled with the Propagate URI toggle (WebGUI) or propagate-uri command. Table 11 lists the names and permission for these variables. The var://service/routing-url variable is an addition to the dp:set-target and dp:xset-target extension elements. To specify the URI. Working with variables 155 . These extension elements do not allow the specification of a protocol. If any other protocol.Read-write variables var://service/connection/note Gets or sets the annotation for the current connection. 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. Use this variable when the ssl property for the DataPower service is not sufficient for the route to be selected. and Web Service Proxy services. The value could be an identifier that could be used to maintain the state based on an existing protocol session. if provided. Routing transaction variables This section contains information about routing variables in alphabetic order by permission category. as shown in the following excerpt: <dp:set-variable name="'var://service/routing-url'" value="'http://10. 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.36. This variable allows the user to annotate the current protocol session.10. Appendix B.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. Table 12 on page 156 lists the names and permission for these variables. overrides the value of the target server that is specified in this variable. sets the routing URL. Table 13 lists the names and permission for these variables. Table 14 lists the names and permission for these variables. particularly fetch. Extension variables usually impact the behavior of specific actions. Table 13. var://service/wsm/wsdl-warning Sets the WSDL warning. Names and permissions for extension variables 156 Variable name Permission var://local/_extension/allow-compression Write-only var://local/_extension/donot-follow-redirect Write-only var://local/_extension/header/ Write-only var://local/_extension/http-10-only Write-only var://local/_extension/prevent-persistent-connection Write-only var://local/_extension/sslprofile Write only IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide . Extension variables This section contains information about system variables in alphabetic order by permission category. results. Names and permissions for variables that are available for URL-based transactions Variable name Permission var://service/URI Read-write Read-write variables var://service/URI Gets or sets the request URI of the transaction. Web Services Management transaction variables This section contains information about Web Services Management (WSM) variables in alphabetic order by permission category. Table 14. and results-async actions.Table 12. Read-write variables var://service/wsa/timeout Gets or sets the timeout value for the WS-Addressing asynchronous reply. 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/wsa/genpattern Gets or sets the pattern for the WS-Addressing asynchronous reply. bar. var://local/_extension/header/ Appends the specified header field to the protocol connection.asp tmpvar3" var://local/_extension/http-10-only Restricts HTTP to version 1. 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. this means the content-encoding and accept-encoding headers. var://local/_extension/prevent-persistent-connection Disables HTTP persistent connection. Set this variable to allow compression of outgoing results content and negotiate the returned document to be compressed if the underlying protocol supports it.Write-only variables var://local/_extension/allow-compression Enables compression of HTTP requests.com/foome. 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. For instance: results tmpvar2 https://foo. Set the value in seconds. 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. Persistent connections are supported by default.asp tmpvar3 var://local/_extension/timeout Sets the request timeout on an input context to override any previously set timeout parameter. For HTTP. By default.1 on the related context of a results action or fetch action. where appropriate. perhaps based on AAA. redirects are followed.bar. Working with variables 157 . var://local/_extension/donot-follow-redirect Disables HTTP redirects.bar.com/foome. it could be set up as follows to dynamically resolve the value of *sslprofiletouse: setvar tmpvar2 var://local/_extension/sslprofile var://context/notepad/sslprofiletouse results tmpvar2 https://foo.bar. Set this variable to prevent the use of HTTP/1.com/foome. Appendix B. Set this variable to prevent persistent connections of the outgoing a results action call or fetch action call that is associated with this context.asp If the profile needed to be determined programmatically.asp tmpvar3 would normally use the SSL Proxy Profile that is associated with any user-agent configuration for the URL https://foo. var://local/_extension/sslprofile Sets the SSL proxy profile for the request.0.com/foome. Table 15. Table 15 lists the names and permission for these variables. 158 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide .System variables This section contains information about system variables in alphabetic order by permission category. var://system/tasktemplates/debug Gets or sets the debugging level for task templates. 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). 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. headers append-response-header var://service/append-response-header Transaction. MQ genpattern var://service/wsa/genpattern Transaction. configuration correlation-identifier var://service/correlation-identifier Service. MQ mq-ccsi var://service/mq-ccsi Service. error handling error-protocol-reason-phrase var://service/error-protocol-reason-phrase Transaction. 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 backend-timeout var://service/mpgw/backend-timeout Service. Table 16. MQ mqmd-reply-to-qm var://service/mqmd-reply-to-qm Service. WSM header var://local/_extension/header Extension http-10-only var://local/_extension/http-10-only Extension lbhealth var://service/lbhealth Service. error handling error-message var://service/error-message Transaction. error handling error-protocol-response var://service/error-protocol-response Transaction. error handling error-subcode var://service/error-subcode Transaction. load balancer max-call-depth var://service/max-call-depth Service. configuration message-identifier var://service/message-identifier Service. MQ mqmd-reply-to-q var://service/mqmd-reply-to-q Service. MQ note var://service/connection/note Transaction. general config-param var://service/config-param Service. Working with variables 159 . persistent connection Appendix B. error handling expiry var://service/expiry Service. MQ message-type var://service/message-type Service. error handling error-ignore var://service/error-ignore Transaction.List of available variables Table 16 lists the variables that you can define for document processing. MQ format var://service/format Service. asynchronous transaction-timeout var://service/transaction-timeout Transaction. routing routing-url-sslprofile var://service/routing-url-sslprofile Transaction. asynchronous URI var://service/URI Transaction. MQ routing-url var://service/routing-url Transaction. error handling timeout var://service/wsa/timeout Transaction. multistep sslprofile var://local/_extension/sslprofile Extension strict-error-mode var://service/strict-error-mode Transaction.Table 16. asynchronous transaction-name var://service/transaction-name Transaction. WSM wsdl-warning var://service/wsm/wsdl-warning Transaction. WSM 160 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide . asynchronous soapversion var://service/log/soapversion 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. WSM transaction-key var://service/transaction-key Transaction. routing set-request-header var://service/set-request-header Transaction. general soap-fault-response var://service/soap-fault-response Service. general soap-oneway-mep var://service/soap-oneway-mep Transaction. MQ report var://service/report Service. headers skip-backside var://service/mpgw/skip-backside Service. URL wsdl-error var://service/wsm/wsdl-error Transaction. headers set-response-header var://service/set-response-header Transaction. All available variables (continued) Short variable name Full variable name Category persistence var://service/persistence Service. From the Category list.ibm. © Copyright IBM Corp. Click the GO icon to display the list of most recent updates. 7. you want it resolved quickly. To determine what fixes are available for your IBM product. You can search the available knowledge bases to determine whether the resolution to your problem was already encountered and is already documented. 5.Appendix C. you can use the search facility to find all references across the documentation set. From the Search Support (this product) area of the product-specific support page. You can use the search function of Adobe® Acrobat to query information. 3. select WebSphere.com/support 2. Documentation The IBM WebSphere DataPower documentation library provides extensive documentation in Portable Document Format (PDF). From the Sub-Category list. 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. 4. check the product support site by performing the following steps: 1. select WebSphere DataPower SOA Appliances. Click the link for the firmware and documentation download that is specific to your WebSphere DataPower product. Follow the instructions in the technote to download the fix. 2002. Go to the IBM Support site at the following Web address: http://www. 2009 161 . Getting help and technical assistance This section describes the following options for obtaining support for IBM products: v “Searching knowledge bases” v “Getting a fix” v “Contacting IBM Support” on page 162 Searching knowledge bases If you encounter a problem. use the Search Support feature from the product-specific support page. IBM Support If you cannot find an answer in the documentation. 6. Select Support & Downloads → Download to open the Support & downloads page. If you download and store the documents in a single location. Click Information to include to access that technote that lists the information that is required to report a problem. Following the instructions. From this page. use the following procedure: a. Whenever possible. Submit the problem in one of the following ways: Online From the IBM Support Web site (http://www. c. gather background information. 162 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide .ibm.S. c. and Canada. Scroll down to the Additional support links section of the page. 2. Locate the Assistance area of the product support page. click Contacts. refer to the Software Support Handbook. To contact IBM Support with a problem. the following criteria must be met: v Your company has an active maintenance contract. By phone For the phone number to call in your country.com/support). IBM Support provides a workaround that you can implement until the APAR is resolved and a fix is delivered. click the Software Support Handbook link. you can obtain a PDF copy of the handbook. Access the IBM Software Support Web page at the following Web address: http://www.Contacting IBM Support IBM Support provides assistance with product defects. refer to “Contacts” in the Software Support Handbook. Gather diagnostic information. From the Software Support Handbook Web site. If the problem you should submit is for a software defect or for missing or inaccurate documentation. and determine the severity of the problem. Under Support tools. The APAR describes the problem in detail. Access the product support at the following Web address: http://www. 3.ibm. select Support & Downloads → Open a service request.com/software/support b. In the U. a. Before contacting IBM Support. Bookmark this page for future reference. v You are authorized to submit problems. For help. Define the problem.com/software/integration/datapower/support b.ibm. d. call 1–800–IBM-SERV (1–800–426–7378) and select option 2 for software. use the following procedure: 1. To access the online version of this handbook. IBM Support creates an authorized program analysis report (APAR). or service may be used.Notices and trademarks This information was developed for products and services offered in the U. CICS. © Copyright IBM Corp. IBM may make improvements or changes in the product(s) or the program(s) described in this publication at any time without notice. therefore. Tivoli. the Adobe logo.S. program. and the PostScript logo are either registered trademarks or trademarks of Adobe Systems Incorporated in the United States. in the United States and other countries. DataPower. Microsoft and Windows are trademarks of Microsoft Corporation in the United States. these changes will be incorporated in new editions of the publication. PostScript. or both. Inc. EITHER EXPRESS OR IMPLIED. Any reference to an IBM product. 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. 2009 163 .A. program. it is the user’s responsibility to evaluate and verify the operation of any non-IBM product. The furnishing of this document does not grant you any license to these patents. IMS. and z/OS are registered trademarks of the International Business Machines Corporation in the United States or other countries. BUT NOT LIMITED TO. in writing.A. 2002. NY 10504-1785 U. Changes are periodically made to the information herein. the IBM logo. However. You can send license inquiries. DB2. Adobe. or features discussed in this document in other countries. Some states do not allow disclaimer of express or implied warranties in certain transactions. or service is not intended to state or imply that only that IBM product. to: IBM Director of Licensing IBM Corporation North Castle Drive Armonk. IBM may not offer the products. THE IMPLIED WARRANTIES OF NON-INFRINGEMENT.S. or service. developerWorks. Redbooks. or service that does not infringe any IBM intellectual property right may be used instead. RACF. INCLUDING. this statement may not apply to you. MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. other countries. IBM may have patents or pending patent applications covering subject matter described in this document. and/or other countries. services. Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems. program. Trademarks IBM. Any functionally equivalent product. Consult your local IBM representative for information about the products and services currently available in your area. WebSphere. program. This information could include technical inaccuracies or typographical errors. Other company. product. and service names may be trademarks or service marks of others. 164 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide . Index Special characters ... button list of referenced object 3 referenced object 2 .java.policy file 37 [configuration-database] stanza, file entry 89 [ldap] stanza, ssl-keyfile-pwd entry 89 [manager] stanza, replica entry 89 + button list of referenced object 3 referenced object 2 A AAA authentication search parameters 100 search parameters 100 TFIM 90 AAA Info File Authenticate element 84 Authorize element 85 editor authenticated identities 85 authorized access to resources confirmation 88 credentials 85 default credential 85 file information 87 map credentials 86 map resources 86 overview 85 unauthenticated identity 85 MapCredentials element 84 MapResource element 84 overview 83 AAA Policy AAA Info File Authenticate element 84 Authorize element 85 MapCredentials element 84 MapResource element 84 overview 83 file editor authenticated identities 85 authorized access to resources confirmation 88 credentials 85 default credential 85 file information 87 map credentials 86 map resources 86 overview 85 unauthenticated identity 85 LTPA, adding user attributes 83 namespace mappings XPath bindings 82 object pages Authenticate 62 © Copyright IBM Corp. 2002, 2009 87 87 AAA Policy (continued) object pages (continued) Authorize 71 Identity 60 LTPA Attributes 81 Main 57 Map Credentials 68 Map Resource 70 Namespace Mapping 80 Post Processing 77 Resource 69 SAML Attributes 81 Transaction Priority 82 SAML attributes defining 82 z/OS NSS Client 144 AAAInfo.xsd file 83 accepted configuration deployment policy 54 Add button list of referenced object 3 admin account exporting configuration data 43 Administration menu 1 administrative states, objects 6 AP-REQ message, Kerberos 92 appliance configuration backing up 43, 44 comparing 52 configuration checkpoints 48 copying files 47 objects 47 exporting 43 select objects and files 45 importing configuration 50 managing configuration changes 52 moving files 47 objects 47 reading change report 53 reverting changes 53 undoing changes 53 appliance-wide log location 33 application domains backing up configuration 44 Application Security Policy configuring 30 object pages Error Maps 31, 99 General 30 Main 97 Request Maps 30, 98 Response Maps 31, 98 Apply button 4 asynchronous transaction variables service/transaction-timeout 152 asynchronous transactions variables listing 152 service/transaction-key 152 asynchronous transactions variables (continued) service/transaction-name 152 asynchronous variables service/soap-oneway-mep 152 audit log location 33 viewing 33 audit: directory 33 Authenticate element, AAA Info File 84 authentication LDAP 100 search parameters 100 Authorize element, AAA Info File 85 auto-config.cfg file 4 B backend-timeout variable 149 bold typeface ix builder deployment policy 55 buttons ... 2 + 2 Apply 4 Cancel 4 Delete 5 Edit 3 Logout 1 Save Config 1, 4 Undo 5 View 3 C CA Unicenter Manager 142 caches flushing document cache 143 stylesheet cache 143 Cancel button 4 cert: directory 33 certificate files location 33 Certificate objects export packages 43 certificates DER 9 exporting 11 generating 10 importing 12 PEM 9 PKCS #12 9 PKCS #8 9 security location, shared 34 location, Web browsers supported formats 9 uploading 37 34 165 checkpoint configuration files location 33 chkpoints: directory 33 clear pdp cache CLI 97 clear xsl cache CLI 97 Clone link 6 commands clear pdp cache 97 clear xsl cache 97 web-mgmt 1 config: directory 33 configuration managing appliance configuration 41 configuration checkpoints defining number to allow 48 deleting 50 listing 49 loading 50 overwriting 49 rolling back 50 saving 49 configuration data applying 4 backing up WebGUI 43, 44 backing up application domains 44 comparing WebGUI 52 configuration checkpoints 48 copying files 47 objects 47 different release level 43 exchanging 43 exporting location of files 33 select objects and files 45 WebGUI 43 files not included 43 importing WebGUI 43, 50 managing changes 52 moving files 47 objects 47 objects not included 43 reading change report 53 reading changes 53 saving 4 undoing changes 53 configuration files exported, location 33 location 33 TAM ASCII 88 creating 89 modifying 89 obfuscated 88 configuration service variables listing 149 service/config-param/ 149 service/max-call-depth 149 configuration states, objects 6 Control Panel File Management 35 count monitors configuring 99 166 credentials identification configuring 15 creating 15 credentials mapping LDAP 100 search parameters 100 Crypto Certificate configuring 13 creating 13 object pages 13 Crypto Firewall Credentials object pages 14 Crypto Identification Credentials object pages 15 Crypto Key configuring 16 creating 16 object pages 16 Crypto Profile configuring 17 creating 17 object pages 17 Crypto Shared Secret Key configuring 18 creating 18 object pages 18 Crypto Tools exporting certificates 11 exporting keys 11 generating certificates 10 generating keys 10 importing certificates 12 importing keys 12 Crypto Validation Credentials object pages 21 customer support contacting 162 obtaining fixes 161 searching knowledge bases 161 D dashboard 1 default log location 33 Delete button 5 list of referenced object 3 deployment policy accepted configuration 54 creating 54 filtered configuration 54 modified configuration 54 using the builder 55 Deployment Policy object pages 54 deployment policy builder creating matching statements DER certificate format 9 key format 9 directories audit: 33 available 33 cert: 33 chkpoints: 33 config: 33 55 directories (continued) displaying contents 35 dpcert: 33 export: 33 hiding contents 35 image: 33 local: 33 logstore: 33 logtemp: 33 managing 33 pubcert: 34 refreshing contents 36 sharedcert: 34 store: 34 tasktemplates: 35 temporary: 35 disabled administrative state 6 documentation conventions, typefaces Domain list 1 down operation state 6 dpcert: directory 33 E Edit button 3 enabled administrative state 6 error handling variables listing 153 service/error-code 153 service/error-ignore 153 service/error-message 153 service/error-protocol-reasonphrase 153 service/error-protocol-response 153 service/error-subcode 153 service/strict-error-mode 154 Error Policy object pages 99 Export link 5 export packages admin account 43 files not included 43 objects not included 43 permission 43 export: directory 33 Extensible Access Control Markup Language See XACML PDP extension functions node-set() 142 extension variables listing 156 local/_extension/allowcompression 157 local/_extension/donot-followredirect 157 local/_extension/header/ 157 local/_extension/http-10-only 157 local/_extension/prevent-persistentconnection 157 local/_extension/sslprofile 157 local/_extension/timeout 157 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide ix F file entry, [configuration-database] stanza 89 File Management utility, launching 35 file system See directories files .java.policy 37 AAAInfo.xsd 83 auto-config.cfg 4 certificates location 33 checkpoint configurations location 33 configurations location 33 copying 38 remote URL 38 deleting 40 editing during configuration 4 File Management utility 40 exported, location 33 fetching 38 healthcheck.xml 106 healthcheck.xsl 106 managing 33 moving 39 not in export packages firmware files 43 log files 43 private keys location 33 renaming 39 TAM ASCII configuration 88 creating configuration 89 modifying configuration 89 obfuscated configuration 88 SSL key 88 SSL stash 88 uploading JKS 37 remote 38 workstation 36 viewing during configuration 4 File Management utility 40 filtered configuration deployment policy 54 Firewall Credentials configuring 14 creating 14 firmware files between release levels 43 export packages 43 firmware images location 33 fixes, obtaining 161 flash drive See directories G general variables listing 148 general variables (continued) service/soap-fault-response 148 H health check filter 106 SOAP request 106 healthcheck.xml file 106 healthcheck.xsl file 106 I IBM Tivoli Access Manager See TAM IBM Tivoli Federated Identity Manager See TFIM Identification Credentials configuring 15 creating 15 image: directory 33 Import Package creating 42 Include Configuration File creating 41 object pages 41 installation images See firmware images intellectual property 163 italics typeface ix J J2RE (j2re1.4.2) 37 j2re1.4.2 (J2RE) 37 j2sdk1.4.2 (SDK) 37 Java Crypto Extension See SunJCE Java Crypto Extension Key Store See JCEKS Java Key Store See JKS java.security package 37 JCE See SunJCE JCEKS 37 JKS crypto extension 37 granting permissions 37 java.security package 37 keytool utility 37 managing 37 required software 37 uploading certificates 37 working with 37 K KDC, Kerberos 92 Kerberos AP-REQ message 92 configuring KDC server KDC 92 keytab 92 principal 92 94 Kerberos KDC server configuring 94 creating 94 object pages 94 Kerberos keytab configuring 94 definition 92 Kerberos Keytab File object pages 94 Key Distribution Center See KDC Key objects export packages 43 key-certificate pairs creating 9 keys DER 9 exporting 11 generating 10 importing 12 PEM 9 PKCS #12 9 PKCS #7 9 supported formats 9 knowledge bases searching 161 L LDAP authentication search parameters 100 credentials mapping search parameters 100 search parameters 100 licensing sending inquiries 163 links Clone 6 Export 5 Show Probe 7 View Logs 5 View Status 6 load balancer group creating 101 server state 101 Load Balancer Group adding members 104 assigning weight 104 configuring, basic 103 health convalescent (down) 102 healthy (up) 102 quarantined (softdown) 102 health checks enabling 105 overriding port 104 health of members 101 object pages Health 105 Main 103 Members 104 service/lbhealth/ variable 102 load balancer service variables listing 150 service/lbhealth/ 150 local: directory 33 Index 167 AAA Policy 83 M MapCredentials element. AAA Info File 84 Matching Rule object pages 106 matching statements deployment policy builder 55 deployment policy. manual 56 message catalogs 34 message monitors count monitors 99 modified configuration deployment policy 54 Modified configuration state 6 monitors count monitors configuring 99 message monitors count monitors 99 monospaced typeface ix MQ Host variables listing 150 service/correlation-identifier 151 service/expiry 151 service/format 151 service/message-identifier 151 service/message-type 151 service/mq-ccsi 150 service/mqmd-reply-to-q 150 service/mqmd-reply-to-qm 150 service/persistence 151 service/priority 151 service/reply-to-q 151 168 MQ Host variables (continued) service/reply-to-qm 151 service/report 151 MQ Proxy variables listing 150 service/correlation-identifier 151 service/expiry 151 service/format 151 service/message-identifier 151 service/message-type 151 service/mq-ccsi 150 service/mqmd-reply-to-q 150 service/mqmd-reply-to-qm 150 service/persistence 151 service/priority 151 service/reply-to-q 151 service/reply-to-qm 151 service/report 151 Multi-Protocol Gateway service variables backend-timeout 149 service/reply-to-q 149 service/reply-to-qm 149 skip-backside 149 multistep variables log/soapversion 151 N Name-Value Profile object pages Main 108 Validation List 110 namespace mappings. AAA Policy navigation Administration menu 1 Network menu 1 Objects menu 1 Services menu 1 Status menu 1 Network menu 1 New configuration state 6 node-set() extension function 142 notices 163 O object pages AAA Policy Authenticate 62 Authorize 71 Identity 60 LTPA Attributes 81 Main 57 Map Credentials 68 Map Resource 70 Namespace Mapping 80 Post Processing 77 Resource 69 SAML Attributes 81 Transaction Priority 82 Application Security Policy Error Maps 31. 98 82 object pages (continued) Application Security Policy (continued) Response Maps 31. 99 General 30 Main 97 Request Maps 30.local/_extension/allow-compression variable 157 local/_extension/donot-follow-redirect variable 157 local/_extension/header/ variable 157 local/_extension/http-10-only variable 157 local/_extension/prevent-persistentconnection variable 157 local/_extension/sslprofile variable 157 local/_extension/timeout variable 157 log files export packages 43 log/soapversion variable 151 Logout button 1 logs appliance-wide location 33 audit location 33 viewing 33 default location 33 viewing from catalog 5 viewing from configuration screen 5 viewing object-specific logs 5 logstore: directory 33 logtemp: directory 33 LTPA adding user attributes. 98 Crypto Certificate 13 Crypto Firewall Credentials 14 Crypto Identification Credentials 15 Crypto Key 16 Crypto Profile 17 Crypto Shared Secret Key 18 Crypto Validation Credentials 21 Deployment Policy 54 Error Policy 99 Include Configuration File 41 Kerberos KDC server 94 Kerberos Keytab File 94 Load Balancer Group Health 105 Main 103 Members 104 Matching Rule 106 Name-Value Profile Main 108 Validation List 110 Processing Rule 111 Rate Limiter 112 Session Management Policy 113 SSL Proxy Profile 19 TAM 89 TFIM 90 URL Rewrite Policy Main 114 URL Rewrite Rule 114 User Agent Allow-Compression Policy 121 Basic-Auth Policy 119 Chunked Uploads Policy 123 FTP Client Policies 124 Inject Header Policy 122 Main 117 Proxy Policy 118 Pubkey-Auth Policy 120 Restrict to HTTP 1. AAA Info File 84 MapResource element.0 Policy 122 Soap-Action Policy 120 SSL Proxy Profile 118 Web Application Firewall General 27 HTTP Options 130 Main 127 Proxy Settings 129 Source Addresses 131 Timeout/Protocol 29 Web Request Profile Cookies 136 Main 132 Methods & Versions 134 Multipart Form 137 Name Value 135 Processing 134 Profile 133 Threat Protection 138 Web Response Profile Codes & Versions 140 Main 139 Name Value 141 Processing 140 Profile 140 Threat Protection 142 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide . 150 service/max-call-depth variable 149 service/message-identifier variable 151 service/message-type variable 151 service/mq-ccsi variable 150 service/mqmd-reply-to-q variable 150 service/mqmd-reply-to-qm variable 150 service/persistence variable 151 service/priority variable 151 service/reply-to-q variable 149. lists (continued) deleting 3 modifying 3 selecting 3 replica entry. proxy.4. creating 19 server proxy.2) 37 search parameters..xml 106 SSL client proxy. [manager] stanza 89 S SAML attributes defining. objects 6 P patents 163 PEM certificate format 9 key format 9 persistent connections variables listing 154 service/connection/note 155 PKCS #12 certificate format 9 key format 9 PKCS #7 certificate format 9 PKCS #8 key format 9 Policy Decision Point See XACML PDP principal. AAA Policy 82 Save Config button 1.. Kerberos 92 private key files location 33 private keys uploading 37 Processing Rule object pages 111 pubcert: directory 34 R Rate Limiter object pages 112 referenced objects .. 151 service/reply-to-qm variable 149. lists .xsl 106 location 34 subdirectories creating 35 deleting 36 SunJCE JCEKS 37 support See customer support system variables listing 158 system/map/debug 158 system/tasktemplates/debug 158 system/map/debug variable 158 system/tasktemplates/debug variable 158 T TAM ASCII configuration file 88 authorization server replicas 89 configuration. button 3 + button 3 Add button 3 adding 3 creating 3 Delete button 3 referenced objects. creating 20 SSL authentication 17 SSL Proxy Profile creating client proxy 19 forward proxy 19 reverse proxy 19 server proxy 19 two-way proxy 20 object pages 19 ssl-keyfile-pwd entry. [ldap] stanza 89 Status menu 1 store: directory 34 style sheets flushing the cache 143 healthcheck.. creating 19 forward proxy. LDAP 100 security certificates shared location 34 Web browsers location 34 server pool See load balancer group server state load balancer group 101 service variables listing 148 types 148 service/append-request-header/ variable 154 service/append-response-header/ variable 154 service/config-param/ variable 149 service/connection/note variable 155 service/correlation-identifier variable 151 service/error-code variable 153 service/error-ignore variable 153 service/error-message variable 153 service/error-protocol-reason-phrase variable 153 service/error-protocol-response variable 153 service/error-subcode variable 153 service/expiry variable 151 service/format variable 151 service/lbhealth/ variable 102. button 2 + button 2 creating 2 modifying 2 selecting 2 referenced objects.. creating 19 reverse..object pages (continued) XACML PDP 95 XML Manager 142 objects administrative state 6 configuration state 6 not in export packages Certificate 43 Key 43 User 43 operational state 6 referenced . 4 Saved configuration state 6 scenarios Web Application Firewall benefits management site 26 college enrollment form 25 trading site 26 schemas location 34 SDK (j2sdk1. general 88 configuring TAM objects 89 creating configuration files 89 Index 169 . creating 19 two-way proxy. 151 service/report variable 151 service/routing-url variable 155 service/routing-url-sslprofile variable 155 service/set-request-header/ variable 154 service/set-response-header/ variable 154 service/soap-fault-response variable 148 service/soap-oneway-mep variable 152 service/strict-error-mode variable 154 service/transaction-key variable 152 service/transaction-name variable 152 service/transaction-timeout variable 152 service/URI variable 156 service/wsa/genpattern variable 156 service/wsa/timeout variable 156 service/wsm/wsdl-error variable 156 service/wsm/wsdl-warning variable 156 Services menu 1 Session Management Policy object pages 113 sharedcert: directory 34 Show Probe link 7 skip-backside variable 149 SOAP request healthcheck. button 2 + button 2 creating 2 modifying 2 selecting 2 status 6 TFIM 90 Objects menu 1 operational states. 150 MQ Host listing 150 service/correlation-identifier 151 service/expiry 151 service/format 151 service/message-identifier 151 service/message-type 151 service/mq-ccsi 150 service/mqmd-reply-to-q 150 service/mqmd-reply-to-qm 150 service/persistence 151 service/priority 151 service/reply-to-q 151 service/reply-to-qm 151 service/report 151 MQ Proxy listing 150 service/correlation-identifier 151 variables (continued) MQ Proxy (continued) service/expiry 151 service/format 151 service/message-identifier 151 service/message-type 151 service/mq-ccsi 150 service/mqmd-reply-to-q 150 service/mqmd-reply-to-qm 150 service/persistence 151 service/priority 151 service/reply-to-q 151 service/reply-to-qm 151 service/report 151 Multi-Protocol Gateway backend-timeout 149 service/reply-to-q 149 service/reply-to-qm 149 skip-backside 149 multistep log/soapversion 151 persistent connections listing 154 service/connection/note 155 service listing 148 type 148 system listing 158 system/map/debug 158 system/tasktemplates/debug 158 transaction listing 152 type 152 transaction headers listing 154 service/append-request-header/ 154 service/append-response-header/ 154 service/set-request-header/ 154 service/set-response-header/ 154 transaction routing listing 155 service/routing-url 155 service/routing-url-sslprofile 155 transaction URL listing 155 service/URI 156 types 147 using 147 Web Service Proxy backend-timeout 149 service/reply-to-q 149 service/reply-to-qm 149 skip-backside 149 WSM listing 156 service/wsa/genpattern 156 service/wsa/timeout 156 service/wsm/wsdl-error 156 service/wsm/wsdl-warning 156 View button 3 View Logs link 5 View Status link 6 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide .0 Policy 122 Soap-Action Policy 120 SSL Proxy Profile 118 User objects export packages 43 utilities keytool 37 170 V Validation Credentials creating non expiring. non-passwordprotected certificates 21 select certificates 21 types of lists 21 variables asynchronous service/soap-oneway-mep 152 asynchronous transactions listing 152 service/transaction-key 152 service/transaction-name 152 service/transaction-timeout 152 configuration service listing 149 service/config-param/ 149 service/max-call-depth 149 error handling listing 153 service/error-code 153 service/error-ignore 153 service/error-message 153 service/error-protocol-reasonphrase 153 service/error-protocolresponse 153 service/error-subcode 153 service/strict-error-mode 154 extension listing 156 local/_extension/allowcompression 157 local/_extension/donot-followredirect 157 local/_extension/header/ 157 local/_extension/http-10-only 157 local/_extension/preventpersistent-connection 157 local/_extension/sslprofile 157 local/_extension/timeout 157 general listing 148 service/soap-fault-response 148 list.TAM (continued) creating TAM objects 89 licensing 88 modifying configuration files 89 obfuscated configuration file 88 object pages 89 refreshing certificates 90 security 88 SSL key file 88 SSL stash file 88 tasktemplates: directory 35 temporary: directory 35 TFIM AAA 90 object 90 object pages 90 TFIM endpoint WS-Trust messages 90 Tivoli Access Manager See TAM trademarks 163 transaction headers variables listing 154 service/append-request-header/ 154 service/append-response-header/ 154 service/set-request-header/ 154 service/set-response-header/ 154 transaction routing variables listing 155 service/routing-url 155 service/routing-url-sslprofile 155 transaction URL variables listing 155 service/URI 156 transaction variables listing 152 types 152 typeface conventions ix U Undo button 5 up operational state 6 URL Rewrite Policy object pages Main 114 URL Rewrite Rule 114 User Agent object pages Allow-Compression Policy 121 Basic-Auth Policy 119 Chunked Uploads Policy 123 FTP Client Policies 124 Inject Header Policy 122 Main 117 Proxy Policy 118 Pubkey-Auth Policy 120 Restrict to HTTP 1. all available 159 load balancer service listing 150 service/lbhealth/ 102. flushing 143 modifying 142 object pages 142 XPath bindings AAA Policy 82 Z z/OS NSS Client creating 145 overview 144 Index 171 .W Web Application Firewall configuring 27 object pages General 27 HTTP Options 130 Main 127 Proxy Settings 129 Source Addresses 131 Timeout/Protocol 29 scenarios benefits management site 26 college enrollment form 25 trading site 26 Web Management Interface 1 Web Request Profile object pages Cookies 136 Main 132 Methods & Versions 134 Multipart Form 137 Name Value 135 Processing 134 Profile 133 Threat Protection 138 Web Response Profile object pages Codes & Versions 140 Main 139 Name Value 141 Processing 140 Profile 140 Threat Protection 142 Web Service Proxy service variables backend-timeout 149 service/reply-to-q 149 service/reply-to-qm 149 skip-backside 149 web-mgmt command 1 WebGUI accessing 1 Administration menu 1 applying configuration changes 4 canceling changes 4 cloning services 6 common tasks 4 dashboard 1 deleting objects 5 Domain list 1 exporting objects 5 logging in 1 Logout button 1 Network menu 1 Objects menu 1 resetting configuration 5 reverting changes 5 Save Config button 1 saving configuration changes 4 Services menu 1 Status menu 1 viewing object status 6 viewing object-specific logs 5 viewing probe data 7 Welcome screen 1 Welcome screen 1 workstation uploading files 36 WS-Security Management See WSSM WS-Trust messages TFIM endpoint 90 WSM variables listing 156 service/wsa/genpattern 156 service/wsa/timeout 156 service/wsm/wsdl-error 156 service/wsm/wsdl-warning 156 X XACML PDP configuring 95 object pages 95 XML Manager caches flushing the document cache 143 flushing the stylesheet cache 143 configuring 142 document cache. 172 IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide . . Printed in USA .