Amweb41 Admin

IBM Tivoli Access Manager

WebSEAL Administrator’s GuideVersion 4.1

SC32-1134-01

��

NoteBefore using this information and the product it supports, read the information in Appendix D, “Notices”, on page 341.

Fifth Edition (August 2003)

This edition replaces GC32-0684-01

© Copyright International Business Machines Corporation 1999, 2002. All rights reserved.US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contractwith IBM Corp.

Contents

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiWho should read this book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiWhat this book contains . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiPublications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xii

Release information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiiiBase information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiiiWebSEAL information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiiiWeb security information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiiiDeveloper references . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xivTechnical supplements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xivRelated publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xivAccessing publications online . . . . . . . . . . . . . . . . . . . . . . . . . . . . xviOrdering publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii

Accessibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xviiContacting software support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xviiConventions used in this book . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii

Typeface conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xviiOperating system differences . . . . . . . . . . . . . . . . . . . . . . . . . . . . xviii

Chapter 1. IBM Tivoli Access Manager WebSEAL overview . . . . . . . . . . . . . . 1Introducing IBM Tivoli Access Manager and WebSEAL . . . . . . . . . . . . . . . . . . . . . 1Understanding the Tivoli Access Manager security model . . . . . . . . . . . . . . . . . . . . 2

The protected object space . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3Defining and applying ACL and POP policies . . . . . . . . . . . . . . . . . . . . . . . 4Policy administration: The Web Portal Manager . . . . . . . . . . . . . . . . . . . . . . 6

Protecting the Web space with WebSEAL . . . . . . . . . . . . . . . . . . . . . . . . . . 6Planning and implementing the security policy . . . . . . . . . . . . . . . . . . . . . . . . 8

Identifying content types and levels of protection . . . . . . . . . . . . . . . . . . . . . . 8Understanding WebSEAL authentication . . . . . . . . . . . . . . . . . . . . . . . . . . 9

The goals of authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10Authenticated and unauthenticated access to resources . . . . . . . . . . . . . . . . . . . . 10The WebSEAL session/credentials cache structure . . . . . . . . . . . . . . . . . . . . . 11

Understanding WebSEAL junctions . . . . . . . . . . . . . . . . . . . . . . . . . . . 12WebSEAL junctions and Web site scalability . . . . . . . . . . . . . . . . . . . . . . . 14

Chapter 2. Basic server configuration . . . . . . . . . . . . . . . . . . . . . . 19General server information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

Root directory of the WebSEAL installation . . . . . . . . . . . . . . . . . . . . . . . . 19Starting and stopping WebSEAL . . . . . . . . . . . . . . . . . . . . . . . . . . . 20WebSEAL represented in the protected object space . . . . . . . . . . . . . . . . . . . . . 20WebSEAL returns HTTP/1.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20WebSEAL log file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

Using the WebSEAL configuration file . . . . . . . . . . . . . . . . . . . . . . . . . . 21The webseald.conf configuration file . . . . . . . . . . . . . . . . . . . . . . . . . . 21WebSEAL server root directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

Configuring communication parameters . . . . . . . . . . . . . . . . . . . . . . . . . . 23Configuring WebSEAL for HTTP requests . . . . . . . . . . . . . . . . . . . . . . . . 23Configuring WebSEAL for HTTPS requests . . . . . . . . . . . . . . . . . . . . . . . . 24Restricting connections from specific SSL versions . . . . . . . . . . . . . . . . . . . . . 24Timeout parameters for HTTP/HTTPS communication . . . . . . . . . . . . . . . . . . . . 24Additional WebSEAL server timeout parameters . . . . . . . . . . . . . . . . . . . . . . 25

Managing the Web space . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26Root directory of the Web document tree . . . . . . . . . . . . . . . . . . . . . . . . 26Configuring directory indexing . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27Windows: File naming for CGI programs . . . . . . . . . . . . . . . . . . . . . . . . 28

© Copyright IBM Corp. 1999, 2002 iii

Executable UNIX files on the WebSEAL server host system . . . . . . . . . . . . . . . . . . 28Configuring Web document caching . . . . . . . . . . . . . . . . . . . . . . . . . . 29Specifying document MIME types for URL filtering . . . . . . . . . . . . . . . . . . . . . 31

Managing custom HTTP error message pages . . . . . . . . . . . . . . . . . . . . . . . . 31Macro support for HTTP error message pages . . . . . . . . . . . . . . . . . . . . . . . 33

Managing custom account management pages. . . . . . . . . . . . . . . . . . . . . . . . 34Custom page parameters and values . . . . . . . . . . . . . . . . . . . . . . . . . . 34Custom HTML page descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . 35Macro support for account management pages . . . . . . . . . . . . . . . . . . . . . . 35

Multi-locale support for Web services. . . . . . . . . . . . . . . . . . . . . . . . . . . 36Managing client-side and server-side certificates . . . . . . . . . . . . . . . . . . . . . . . 38

GSKit key database file types . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38Configuring key database parameters. . . . . . . . . . . . . . . . . . . . . . . . . . 39Using the iKeyman certificate management utility . . . . . . . . . . . . . . . . . . . . . 40Configuring CRL checking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41Configuring the CRL cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

Configuring default HTTP logging . . . . . . . . . . . . . . . . . . . . . . . . . . . 42Enabling and disabling HTTP logging . . . . . . . . . . . . . . . . . . . . . . . . . 43Specifying the timestamp type . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43Specifying log file rollover thresholds. . . . . . . . . . . . . . . . . . . . . . . . . . 43Specifying the frequency for flushing log file buffers . . . . . . . . . . . . . . . . . . . . 43HTTP common log format (for request.log) . . . . . . . . . . . . . . . . . . . . . . . . 44Displaying the request.log file . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44Displaying the agent.log file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44Displaying referer.log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

Configuring HTTP logging using event logging . . . . . . . . . . . . . . . . . . . . . . . 45Logging WebSEAL serviceability messages . . . . . . . . . . . . . . . . . . . . . . . . . 46WebSEAL audit trail files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

Configuring audit trail files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47HTTP audit records. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50Authentication audit records. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

Chapter 3. Advanced server configuration . . . . . . . . . . . . . . . . . . . . 53Configuring a default quality of protection level . . . . . . . . . . . . . . . . . . . . . . . 53

Configuring QOP for individual hosts and networks . . . . . . . . . . . . . . . . . . . . 54Configuring authorization database updates and polling . . . . . . . . . . . . . . . . . . . . 55

Configuring update notification listening . . . . . . . . . . . . . . . . . . . . . . . . 55Configuring authorization database polling. . . . . . . . . . . . . . . . . . . . . . . . 55

Managing worker thread allocation . . . . . . . . . . . . . . . . . . . . . . . . . . . 56Configuring WebSEAL worker threads . . . . . . . . . . . . . . . . . . . . . . . . . 56Allocating worker threads for junctions (junction fairness) . . . . . . . . . . . . . . . . . . . 56

Replicating front-end WebSEAL servers . . . . . . . . . . . . . . . . . . . . . . . . . . 58Configuring multiple WebSEAL server instances . . . . . . . . . . . . . . . . . . . . . . . 59

Configuration overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59Configuring multiple WebSEAL instances on UNIX . . . . . . . . . . . . . . . . . . . . . 60Configuring multiple WebSEAL instances on Windows . . . . . . . . . . . . . . . . . . . . 65Unconfiguring multiple WebSEAL instances . . . . . . . . . . . . . . . . . . . . . . . 69Server start, stop, restart, and status commands . . . . . . . . . . . . . . . . . . . . . . 70

Configuring switch user . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72Overview of the switch user function. . . . . . . . . . . . . . . . . . . . . . . . . . 72Configuration procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74Using switch user . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79Additional switch user features . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80Developing a custom CDAS for switch user . . . . . . . . . . . . . . . . . . . . . . . 81

Configuring WebSEAL server-side request caching . . . . . . . . . . . . . . . . . . . . . . 83Background . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83Server-side caching process flow . . . . . . . . . . . . . . . . . . . . . . . . . . . 83Configuring server-side caching parameters . . . . . . . . . . . . . . . . . . . . . . . 84Notes and limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85

Handling UTF-8 encoded characters . . . . . . . . . . . . . . . . . . . . . . . . . . . 85Preventing vulnerability caused by cross-site scripting . . . . . . . . . . . . . . . . . . . . . 87

iv IBM Tivoli Access Manager: WebSEAL Administrator’s Guide

Background . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87Configuring URL string filtering . . . . . . . . . . . . . . . . . . . . . . . . . . . 87

Suppressing server identity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88Configuring cryptographic hardware for encryption and key storage . . . . . . . . . . . . . . . . 88

Conditions and prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90Configuring WebSEAL for cryptographic hardware over BHAPI . . . . . . . . . . . . . . . . . 90Configuring WebSEAL for cryptographic hardware over PKCS#11 . . . . . . . . . . . . . . . . 90

Problem determination tools for WebSEAL . . . . . . . . . . . . . . . . . . . . . . . . . 93

Chapter 4. WebSEAL security policy . . . . . . . . . . . . . . . . . . . . . . . 95WebSEAL-specific ACL policies. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95

/WebSEAL/<host>. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95/WebSEAL/<host>/<file> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95WebSEAL ACL permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95Default /WebSEAL ACL policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96Valid characters for ACL names . . . . . . . . . . . . . . . . . . . . . . . . . . . 96

Three strikes login policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96Account lock policy with load-balanced WebSEAL servers . . . . . . . . . . . . . . . . . . . 97Command syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98

Password strength policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98Password strength policy set by the pdadmin utility. . . . . . . . . . . . . . . . . . . . . 99Command syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99Valid and invalid password examples . . . . . . . . . . . . . . . . . . . . . . . . . 100Specific user and global settings . . . . . . . . . . . . . . . . . . . . . . . . . . . 100

Authentication strength POP policy (step-up). . . . . . . . . . . . . . . . . . . . . . . . 101Configuring levels for step-up authentication. . . . . . . . . . . . . . . . . . . . . . . 101Enabling step-up authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . 102Step-up login form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103Step-up authentication algorithm . . . . . . . . . . . . . . . . . . . . . . . . . . . 104Step-up authentication notes and limitations . . . . . . . . . . . . . . . . . . . . . . . 104Distinguishing step-up from multi-factor authentication . . . . . . . . . . . . . . . . . . . 105

Network-based authentication POP policy . . . . . . . . . . . . . . . . . . . . . . . . . 105Configuring authentication levels. . . . . . . . . . . . . . . . . . . . . . . . . . . 106Specifying IP addresses and ranges . . . . . . . . . . . . . . . . . . . . . . . . . . 106Disabling step-up authentication by IP address . . . . . . . . . . . . . . . . . . . . . . 107Network-based authentication algorithm . . . . . . . . . . . . . . . . . . . . . . . . 107Network-based authentication notes and limitations . . . . . . . . . . . . . . . . . . . . 107

Quality of protection POP policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108Handling unauthenticated users (HTTP / HTTPS) . . . . . . . . . . . . . . . . . . . . . . 108

Processing a request from an anonymous client . . . . . . . . . . . . . . . . . . . . . . 108Forcing user login . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108Applications of unauthenticated HTTPS . . . . . . . . . . . . . . . . . . . . . . . . 109Controlling unauthenticated users with ACL/POP policies . . . . . . . . . . . . . . . . . . 109

Chapter 5. WebSEAL authentication. . . . . . . . . . . . . . . . . . . . . . . 111Understanding the authentication process . . . . . . . . . . . . . . . . . . . . . . . . . 111

Supported session data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112Supported authentication methods . . . . . . . . . . . . . . . . . . . . . . . . . . 112

Managing session state . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113Session state overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113GSKit and WebSEAL session cache overview . . . . . . . . . . . . . . . . . . . . . . . 113Configuring the GSKit SSL session ID cache . . . . . . . . . . . . . . . . . . . . . . . 114Configuring the WebSEAL session/credentials cache . . . . . . . . . . . . . . . . . . . . 114Maintaining state with session cookies . . . . . . . . . . . . . . . . . . . . . . . . . 115Determining valid session ID data types . . . . . . . . . . . . . . . . . . . . . . . . 118Configuring failover cookies . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118

Authentication configuration overview . . . . . . . . . . . . . . . . . . . . . . . . . . 122Local authentication parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . 122External custom CDAS authentication parameters . . . . . . . . . . . . . . . . . . . . . 122Default configuration for WebSEAL authentication . . . . . . . . . . . . . . . . . . . . . 123

Contents v

Configuring multiple authentication methods . . . . . . . . . . . . . . . . . . . . . . 123Prompting for login . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123Logout and change password commands . . . . . . . . . . . . . . . . . . . . . . . . 124Post password change processing. . . . . . . . . . . . . . . . . . . . . . . . . . . 125

Configuring Basic Authentication. . . . . . . . . . . . . . . . . . . . . . . . . . . . 125Enabling and disabling Basic Authentication . . . . . . . . . . . . . . . . . . . . . . . 125Setting the realm name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125Configuring the Basic Authentication mechanism . . . . . . . . . . . . . . . . . . . . . 126Configuration conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126

Configuring forms authentication. . . . . . . . . . . . . . . . . . . . . . . . . . . . 126Enabling and disabling forms authentication . . . . . . . . . . . . . . . . . . . . . . . 126Configuring the forms authentication mechanism . . . . . . . . . . . . . . . . . . . . . 127Configuration conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127Customizing HTML response forms . . . . . . . . . . . . . . . . . . . . . . . . . . 127

Configuring client-side certificate authentication. . . . . . . . . . . . . . . . . . . . . . . 127Background: Mutual authentication using certificates . . . . . . . . . . . . . . . . . . . . 127The WebSEAL test certificate . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129Enabling and disabling certificate authentication . . . . . . . . . . . . . . . . . . . . . 129Configuring the certificate authentication mechanism . . . . . . . . . . . . . . . . . . . . 130

Configuring HTTP header authentication . . . . . . . . . . . . . . . . . . . . . . . . . 130Enabling and disabling HTTP header authentication . . . . . . . . . . . . . . . . . . . . 131Specifying header types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131Configuring the HTTP header authentication mechanism . . . . . . . . . . . . . . . . . . . 131Configuration conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132

Configuring IP address authentication . . . . . . . . . . . . . . . . . . . . . . . . . . 132Enabling and disabling IP address authentication . . . . . . . . . . . . . . . . . . . . . 132Configuring the IP address authentication mechanism . . . . . . . . . . . . . . . . . . . . 132

Configuring token authentication. . . . . . . . . . . . . . . . . . . . . . . . . . . . 132Enabling and disabling token authentication . . . . . . . . . . . . . . . . . . . . . . . 132Configuring the token authentication mechanism . . . . . . . . . . . . . . . . . . . . . 133Configuring WebSEAL to use the SecurID client library . . . . . . . . . . . . . . . . . . . 133

Supporting multiplexing proxy agents . . . . . . . . . . . . . . . . . . . . . . . . . . 134Valid session data types and authentication methods . . . . . . . . . . . . . . . . . . . . 135Authentication process flow for MPA and multiple clients . . . . . . . . . . . . . . . . . . 136Enabling and disabling MPA authentication . . . . . . . . . . . . . . . . . . . . . . . 137Create a user account for the MPA . . . . . . . . . . . . . . . . . . . . . . . . . . 137Add the MPA account to the webseal-mpa-servers group. . . . . . . . . . . . . . . . . . . 137MPA authentication limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . 137

Configuring reauthentication based on security policy . . . . . . . . . . . . . . . . . . . . . 137Conditions affecting POP reauthentication . . . . . . . . . . . . . . . . . . . . . . . . 137Creating and applying the reauthentication POP . . . . . . . . . . . . . . . . . . . . . 138Configuring session cache entry lifetime reset and extension . . . . . . . . . . . . . . . . . 138Customizing login forms for reauthentication. . . . . . . . . . . . . . . . . . . . . . . 140

Configuring reauthentication based on session inactivity policy . . . . . . . . . . . . . . . . . 140Conditions affecting inactivity reauthentication . . . . . . . . . . . . . . . . . . . . . . 140Enabling inactivity reauthentication . . . . . . . . . . . . . . . . . . . . . . . . . . 141Resetting and extending the session cache entry lifetime value . . . . . . . . . . . . . . . . . 142Customizing login forms for reauthentication. . . . . . . . . . . . . . . . . . . . . . . 143

Configuring automatic redirection to a login home page . . . . . . . . . . . . . . . . . . . . 144Automatic redirection process flow . . . . . . . . . . . . . . . . . . . . . . . . . . 144Conditions affecting automatic redirection . . . . . . . . . . . . . . . . . . . . . . . . 144Configuring the custom URL . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145Enabling and disabling automatic redirection. . . . . . . . . . . . . . . . . . . . . . . 145

Chapter 6. Cross-domain single sign-on solutions . . . . . . . . . . . . . . . . 147Understanding CDSSO authentication . . . . . . . . . . . . . . . . . . . . . . . . . . 147

Customizing single sign-on authentication. . . . . . . . . . . . . . . . . . . . . . . . 147CDSSO features and requirements . . . . . . . . . . . . . . . . . . . . . . . . . . 148Authentication process flow for CDSSO with CDMF . . . . . . . . . . . . . . . . . . . . 148

Configuring CDSSO authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . 149CDSSO configuration summary . . . . . . . . . . . . . . . . . . . . . . . . . . . 149

vi IBM Tivoli Access Manager: WebSEAL Administrator’s Guide

Enabling and disabling CDSSO authentication . . . . . . . . . . . . . . . . . . . . . . 150Configuring the single sign-on authentication mechanism . . . . . . . . . . . . . . . . . . 150Encrypting the authentication token data . . . . . . . . . . . . . . . . . . . . . . . . 151Configuring the token time stamp . . . . . . . . . . . . . . . . . . . . . . . . . . 152Configuring the token label name . . . . . . . . . . . . . . . . . . . . . . . . . . 152Creating the CDSSO HTML link . . . . . . . . . . . . . . . . . . . . . . . . . . . 153Protecting the authentication token . . . . . . . . . . . . . . . . . . . . . . . . . . 153Enabling compatibility with previous releases . . . . . . . . . . . . . . . . . . . . . . 153

Understanding e-community single sign-on . . . . . . . . . . . . . . . . . . . . . . . . 154e-community features and requirements . . . . . . . . . . . . . . . . . . . . . . . . 155e-community process flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156Understanding the e-community cookie . . . . . . . . . . . . . . . . . . . . . . . . 160Understanding the ″vouch for″ request and reply . . . . . . . . . . . . . . . . . . . . . 160Understanding the “vouch for” token . . . . . . . . . . . . . . . . . . . . . . . . . 161

Configuring e-community single sign-on . . . . . . . . . . . . . . . . . . . . . . . . . 161E-community configuration summary . . . . . . . . . . . . . . . . . . . . . . . . . 161Enabling and disabling e-community authentication . . . . . . . . . . . . . . . . . . . . 162Specifying an e-community name . . . . . . . . . . . . . . . . . . . . . . . . . . 163Configuring the single sign-on authentication mechanism . . . . . . . . . . . . . . . . . . 163Encrypting the ″vouch for″ token. . . . . . . . . . . . . . . . . . . . . . . . . . . 164Configuring the ″vouch for″ token label name . . . . . . . . . . . . . . . . . . . . . . 165Specifying the master authentication server (MAS) . . . . . . . . . . . . . . . . . . . . . 165Specifying the ″vouch for″ URL . . . . . . . . . . . . . . . . . . . . . . . . . . . 166Configure token and ec-cookie lifetime values . . . . . . . . . . . . . . . . . . . . . . 166Enabling compatibility with previous releases . . . . . . . . . . . . . . . . . . . . . . 167

Chapter 7. WebSEAL junctions . . . . . . . . . . . . . . . . . . . . . . . . . 169WebSEAL junctions overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169

Junction database location and format . . . . . . . . . . . . . . . . . . . . . . . . . 169Applying coarse-grained access control: summary . . . . . . . . . . . . . . . . . . . . . 170Applying fine-grained access control: summary . . . . . . . . . . . . . . . . . . . . . . 170Guidelines for creating WebSEAL junctions . . . . . . . . . . . . . . . . . . . . . . . 170Additional references for WebSEAL junctions. . . . . . . . . . . . . . . . . . . . . . . 171

Using pdadmin to create junctions . . . . . . . . . . . . . . . . . . . . . . . . . . . 171Configuring a basic WebSEAL junction . . . . . . . . . . . . . . . . . . . . . . . . . . 172

Creating TCP type junctions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172Creating SSL type junctions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173Adding back-end servers to a junction . . . . . . . . . . . . . . . . . . . . . . . . . 174

Mutually authenticated SSL junctions . . . . . . . . . . . . . . . . . . . . . . . . . . 174WebSEAL validates back-end server certificate . . . . . . . . . . . . . . . . . . . . . . 175Distinguished name (DN) matching . . . . . . . . . . . . . . . . . . . . . . . . . . 175WebSEAL authenticates with client certificate. . . . . . . . . . . . . . . . . . . . . . . 175WebSEAL authenticates with BA header . . . . . . . . . . . . . . . . . . . . . . . . 176Handling client identity information across junctions . . . . . . . . . . . . . . . . . . . . 176

Creating TCP and SSL proxy junctions . . . . . . . . . . . . . . . . . . . . . . . . . . 177WebSEAL-to-WebSEAL junctions over SSL . . . . . . . . . . . . . . . . . . . . . . . . 178Modifying URLs to back-end resources . . . . . . . . . . . . . . . . . . . . . . . . . . 178

Understanding path types used in URLs . . . . . . . . . . . . . . . . . . . . . . . . 179Filtering URLs in responses . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180Processing URLs in requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183Handling cookies from servers across multiple -j junctions . . . . . . . . . . . . . . . . . . 185

Additional junction options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186Forcing a new junction (–f) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187Supplying client identity in HTTP headers (–c) . . . . . . . . . . . . . . . . . . . . . . 187Supplying client IP addresses in HTTP headers (–r) . . . . . . . . . . . . . . . . . . . . 189Limiting the size of WebSEAL-generated HTTP headers . . . . . . . . . . . . . . . . . . . 189Passing session cookies to junctioned portal servers (–k) . . . . . . . . . . . . . . . . . . . 190Supporting case-insensitive URLs (–i) . . . . . . . . . . . . . . . . . . . . . . . . . 190Stateful junction support (–s, –u) . . . . . . . . . . . . . . . . . . . . . . . . . . . 191Specifying back-end server UUIDs for stateful junctions (–u) . . . . . . . . . . . . . . . . . 191Junctioning to Windows file systems (–w) . . . . . . . . . . . . . . . . . . . . . . . . 194

Contents vii

Technical notes for using WebSEAL junctions. . . . . . . . . . . . . . . . . . . . . . . . 195Mounting multiple servers at the same junction . . . . . . . . . . . . . . . . . . . . . . 195Exceptions to enforcing permissions across junctions . . . . . . . . . . . . . . . . . . . . 195Certificate authentication across junctions . . . . . . . . . . . . . . . . . . . . . . . . 195Handling domain cookies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196

Using query_contents with third-party servers . . . . . . . . . . . . . . . . . . . . . . . 196Installing query_contents components . . . . . . . . . . . . . . . . . . . . . . . . . 196Installing query_contents on third-party UNIX servers . . . . . . . . . . . . . . . . . . . 197Installing query_contents on third-party Win32 servers . . . . . . . . . . . . . . . . . . . 197Customizing query_contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199Securing query_contents. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200

Chapter 8. Single sign-on solutions across junctions . . . . . . . . . . . . . . . 201Configuring BA headers for single sign-on solutions . . . . . . . . . . . . . . . . . . . . . 201

Single sign-on (SSO) concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201Supplying client identity in BA headers . . . . . . . . . . . . . . . . . . . . . . . . 202Supplying client identity and generic password . . . . . . . . . . . . . . . . . . . . . . 202Forwarding original client BA header information . . . . . . . . . . . . . . . . . . . . . 203Removing client BA header information . . . . . . . . . . . . . . . . . . . . . . . . 204Supplying user names and passwords from GSO . . . . . . . . . . . . . . . . . . . . . 205

Using global sign-on (GSO). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205Mapping the authentication information . . . . . . . . . . . . . . . . . . . . . . . . 206Configuring a GSO-enabled WebSEAL junction . . . . . . . . . . . . . . . . . . . . . . 207Configuring the GSO cache. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208

Configuring single sign-on to IBM WebSphere (LTPA) . . . . . . . . . . . . . . . . . . . . . 208Configuring an LTPA junction . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209Configuring the LTPA cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209Technical notes for LTPA single sign-on. . . . . . . . . . . . . . . . . . . . . . . . . 210

Configuring single sign-on forms authentication. . . . . . . . . . . . . . . . . . . . . . . 210Background and goals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210Forms single sign-on process flow . . . . . . . . . . . . . . . . . . . . . . . . . . 211Requirements for application support . . . . . . . . . . . . . . . . . . . . . . . . . 212Creating the configuration file for forms single sign-on . . . . . . . . . . . . . . . . . . . 213Enabling forms single sign-on . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216Example configuration file for IBM HelpNow . . . . . . . . . . . . . . . . . . . . . . 216

Chapter 9. Application integration . . . . . . . . . . . . . . . . . . . . . . . 219Supporting CGI programming. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219

Windows: Supporting WIN32 environment variables . . . . . . . . . . . . . . . . . . . . 220Supporting back-end server-side applications. . . . . . . . . . . . . . . . . . . . . . . . 221Junction ″best practices″ for application integration. . . . . . . . . . . . . . . . . . . . . . 221

Supplying complete HOST header information with -v . . . . . . . . . . . . . . . . . . . 221Supporting standard absolute URL filtering . . . . . . . . . . . . . . . . . . . . . . . 222

Building a custom personalization service . . . . . . . . . . . . . . . . . . . . . . . . . 223Configuring WebSEAL for a personalization service . . . . . . . . . . . . . . . . . . . . 223Personalization service example . . . . . . . . . . . . . . . . . . . . . . . . . . . 224

Enabling dynamic business entitlements (tag/value) . . . . . . . . . . . . . . . . . . . . . 224Creating business entitlements from LDAP data . . . . . . . . . . . . . . . . . . . . . . 224Inserting credential data into the HTTP header . . . . . . . . . . . . . . . . . . . . . . 226

Maintaining session state between client and back-end applications . . . . . . . . . . . . . . . . 228Background to user session management . . . . . . . . . . . . . . . . . . . . . . . . 228Enabling user session id management . . . . . . . . . . . . . . . . . . . . . . . . . 228Inserting credential data into the HTTP header . . . . . . . . . . . . . . . . . . . . . . 229Terminating user sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230

Providing access control to dynamic URLs . . . . . . . . . . . . . . . . . . . . . . . . 231Dynamic URL components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231Mapping ACL and POP objects to dynamic URLs . . . . . . . . . . . . . . . . . . . . . 232Updating WebSEAL for dynamic URLs . . . . . . . . . . . . . . . . . . . . . . . . . 233Resolving dynamic URLs in the object space . . . . . . . . . . . . . . . . . . . . . . . 234Configuring limitations on POST requests . . . . . . . . . . . . . . . . . . . . . . . . 234

viii IBM Tivoli Access Manager: WebSEAL Administrator’s Guide

Summary and technical notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236Dynamic URL example: The Travel Kingdom. . . . . . . . . . . . . . . . . . . . . . . . 237

The application. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237The interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237The security policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238Secure clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238Access control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238Conclusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239

Appendix A. WebSEAL configuration file reference . . . . . . . . . . . . . . . . 241Guidelines for configuring stanzas . . . . . . . . . . . . . . . . . . . . . . . . . . . 241

General guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241Default values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242Defined strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242File names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243Integers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243Boolean values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244

Change configuration settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244Stanza organization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245Server configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247User registry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252

LDAP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252Active Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258IBM Lotus Domino . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261

Secure Socket Layer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271

Authentication mechanisms . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272Authentication libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276Reauthentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280Authentication failover . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281Cross-domain single sign on . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283e-community single sign-on . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284Quality of protection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287

Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289Content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291

Content management. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292Account management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293Automatic redirect. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296Local CGI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297Icons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299Content caching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301Content MIME types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302Content encodings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303

Junctions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304Junction management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305Document filtering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309Event handler filtering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310Scheme filtering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311MIME types and header filtering . . . . . . . . . . . . . . . . . . . . . . . . . . . 312Script filtering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313Global Sign-On cache. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315Lightweight Third Party Authentication cache . . . . . . . . . . . . . . . . . . . . . . 317

Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319Auditing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322Policy database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325Entitlements services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327Policy server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328

Appendix B. WebSEAL junction reference . . . . . . . . . . . . . . . . . . . . 329

Contents ix

Using pdadmin to create junctions . . . . . . . . . . . . . . . . . . . . . . . . . . . 329The junction commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330Create a new junction for an initial server . . . . . . . . . . . . . . . . . . . . . . . . . 331Add a server to an existing junction . . . . . . . . . . . . . . . . . . . . . . . . . . . 333

Appendix C. Using the pdbackup utility for WebSEAL . . . . . . . . . . . . . . . 335Functionality . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335

Backing up data: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335Restoring data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336

Syntax. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337

UNIX examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337Windows examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338Contents of amwebbackup.lst . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338Additional backup data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340

Appendix D. Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341Trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345

x IBM Tivoli Access Manager: WebSEAL Administrator’s Guide

Preface

Welcome to the IBM® Tivoli® Access Manager WebSEAL Administrator’s Guide.

IBM Tivoli Access Manager WebSEAL is the resource security manager forWeb-based resources in a Tivoli Access Manager secure domain. WebSEAL is ahigh performance, multi-threaded Web server that applies fine-grained securitypolicy to the protected Web object space. WebSEAL can provide single sign-onsolutions and incorporate back-end Web application server resources into itssecurity policy.

This administration guide provides a comprehensive set of procedures andreference information for managing the resources of your secure Web domain. Thisguide also provides you with valuable background and concept information for thewide range of WebSEAL functionality.

IBM® Tivoli® Access Manager (Tivoli Access Manager) is the base software that isrequired to run applications in the IBM Tivoli Access Manager product suite. Itenables the integration of IBM Tivoli Access Manager applications that provide awide range of authorization and management solutions. Sold as an integratedsolution, these products provide an access control management solution thatcentralizes network and application security policy for e-business applications.

Note: IBM Tivoli Access Manager is the new name of the previously releasedsoftware entitled Tivoli SecureWay® Policy Director. Also, for users familiarwith the Tivoli SecureWay Policy Director software and documentation, themanagement server is now referred to as the policy server.

Who should read this bookThis guide is for system administrators responsible for configuring andmaintaining an Tivoli Access Manager WebSEAL environment.

Readers should be familiar with the following:v PC and UNIX® operating systemsv Database architecture and conceptsv Security managementv Internet protocols, including HTTP, TCP/IP, File Transfer Protocol (FTP), and

Telnetv Lightweight Directory Access Protocol (LDAP) and directory servicesv A supported user registryv Authentication and authorization

If you are enabling Secure Sockets Layer (SSL) communication, you also should befamiliar with SSL protocol, key exchange (public and private), digital signatures,cryptographic algorithms, and certificate authorities.

What this book containsv Chapter 1: IBM Tivoli Access Manager WebSEAL overview

© Copyright IBM Corp. 1999, 2002 xi

This chapter introduces you to important WebSEAL concepts and functionalitysuch as: organizing and protecting your object space, authentication, credentialsacquisition, and WebSEAL junctions.

v Chapter 2: Basic server configuration

This chapter is a technical reference for general WebSEAL configuration tasks,including: using the WebSEAL configuration file, managing the Web space,managing certificates, and configuring logging.

v Chapter 3: Advanced server configuration

This chapter is a technical reference for advanced WebSEAL configuration tasks,including: configuring multiple WebSEAL instances, configuring switch userfunctionality, managing worker thread allocation, and configuring authorizationdatabase updates and polling.

v Chapter 4: WebSEAL security policy

This chapter provides detailed technical procedures for customizing securitypolicy on WebSEAL, including: ACL and POP policies, quality of protection,step-up authentication policy, network-based authentication policy, three-strikeslogin policy, and password strength policy.

v Chapter 5: WebSEAL authentication

This chapter provides detailed technical procedures for setting up WebSEAL tomanage a variety of authentication methods, including: user name andpassword, client-side certificates, SecurID token passcode, special HTTP headerdata, and reauthentication functionality.

v Chapter 6: Cross domain single sign-on solutions

This chapter discusses cross domain sign-on solutions for the external side of aWebSEAL proxy configuration—between the client and the WebSEAL server.

v Chapter 7: WebSEAL junctions

This chapter is a complete technical reference for setting up and using WebSEALjunctions.

v Chapter 8: Single sign-on solutions across junctions

This chapter discusses single sign-on solutions for the internal side of aWebSEAL proxy configuration—between the WebSEAL server and the back-endjunctioned application server.

v Chapter 9: Application integration

This chapter explores a variety of WebSEAL capabilities for integratingthird-party application functionality.

v Appendix A: WebSEAL configuration file reference

v Appendix B: WebSEAL junction reference

v Appendix C: Using the pdbackup utility for WebSEAL

v Appendix D: Notices

PublicationsThe Tivoli Access Manager library is organized into the following categories:v “Release information” on page xiiiv “Base information” on page xiiiv “WebSEAL information” on page xiiiv “Web security information” on page xiiiv “Developer references” on page xivv “Technical supplements” on page xiv

xii IBM Tivoli Access Manager: WebSEAL Administrator’s Guide

Release informationv IBM Tivoli Access Manager Read Me First Card

GI11-4198-00 (am41_readme.pdf)Provides information for installing and getting started using Tivoli AccessManager.

v IBM Tivoli Access Manager Release NotesSC32-1130-00 (am41_relnotes.pdf)Provides late-breaking information, such as software limitations, workarounds,and documentation updates.

Base informationv IBM Tivoli Access Manager Base Installation Guide

SC32-1131-01 (am41_install.pdf)Explains how to install, configure, and upgrade Tivoli Access Manager software,including the Web Portal Manager interface.

v IBM Tivoli Access Manager Base Administrator’s GuideSC32-1132-01 (am41_admin.pdf)Describes the concepts and procedures for using Tivoli Access Manager services.Provides instructions for performing tasks from the Web Portal Managerinterface and by using the pdadmin command.

WebSEAL informationv IBM Tivoli Access Manager WebSEAL Installation Guide

SC32-1133-01 (amweb41_install.pdf)Provides installation, configuration, and removal instructions for the WebSEALserver and the WebSEAL application development kit.

v IBM Tivoli Access Manager WebSEAL Administrator’s GuideSC32-1134-01 (amweb41_admin.pdf)Provides background material, administrative procedures, and technicalreference information for using WebSEAL to manage the resources of yoursecure Web domain.

Web security informationv IBM Tivoli Access Manager for WebSphere Application Server User’s Guide

SC32-1136-01 (amwas41_user.pdf)Provides installation, removal, and administration instructions for Tivoli AccessManager for IBM WebSphere® Application Server.

v IBM Tivoli Access Manager for WebLogic Server User’s GuideSC32-1137-01 (amwls41_user.pdf)Provides installation, removal, and administration instructions for Tivoli AccessManager for BEA WebLogic Server.

v IBM Tivoli Access Manager Plug-in for Edge Server User’s GuideSC32-1138-01 (amedge41_user.pdf)Describes how to install, configure, and administer the plug-in for IBMWebSphere Edge Server application.

v IBM Tivoli Access Manager Plug-in for Web Servers User’s GuideSC32-1139-01 (amws41_user.pdf)Provides installation instructions, administration procedures, and technicalreference information for securing your Web domain using the plug-in for Webservers.

Preface xiii

Developer referencesv IBM Tivoli Access Manager Authorization C API Developer’s Reference

SC32-1140-01 (am41_authC_devref.pdf)Provides reference material that describes how to use the Tivoli Access Managerauthorization C API and the Access Manager service plug-in interface to addTivoli Access Manager security to applications.

v IBM Tivoli Access Manager Authorization Java Classes Developer’s ReferenceSC32-1141-01 (am41_authJ_devref.pdf)Provides reference information for using the Java™ language implementation ofthe authorization API to enable an application to use Tivoli Access Managersecurity.

v IBM Tivoli Access Manager Administration C API Developer’s ReferenceSC32-1142-01 (am41_adminC_devref.pdf)Provides reference information about using the administration API to enable anapplication to perform Tivoli Access Manager administration tasks. Thisdocument describes the C implementation of the administration API.

v IBM Tivoli Access Manager Administration Java Classes Developer’s ReferenceSC32-1143-01 (am41_adminJ_devref.pdf)Provides reference information for using the Java language implementation ofthe administration API to enable an application to perform Tivoli AccessManager administration tasks.

v IBM Tivoli Access Manager WebSEAL Developer’s ReferenceSC32-1135-01 (amweb41_devref.pdf)Provides administration and programming information for the Cross-domainAuthentication Service (CDAS), the Cross-domain Mapping Framework (CDMF),and the Password Strength Module.

Technical supplementsv IBM Tivoli Access Manager Command Reference

GC32-1107-01 (am41_cmdref.pdf)Provides information about the command line utilities and scripts provided withTivoli Access Manager.

v IBM Tivoli Access Manager Error Message ReferenceSC32-1144-01 (am41_error_ref.pdf)Provides explanations and recommended actions for the messages produced byTivoli Access Manager.

v IBM Tivoli Access Manager Problem Determination GuideGC32-1106-01 (am41_pdg.pdf)Provides problem determination information for Tivoli Access Manager.

v IBM Tivoli Access Manager Performance Tuning GuideSC32-1145-01 (am41_perftune.pdf)Provides performance tuning information for an environment consisting of TivoliAccess Manager with the IBM Directory server defined as the user registry.

Related publicationsThis section lists publications related to the Tivoli Access Manager library.

The Tivoli Software Library provides a variety of Tivoli publications such as whitepapers, datasheets, demonstrations, redbooks, and announcement letters. The Tivoli

xiv IBM Tivoli Access Manager: WebSEAL Administrator’s Guide

Software Library is available on the Web at:http://www.ibm.com/software/tivoli/library/

The Tivoli Software Glossary includes definitions for many of the technical termsrelated to Tivoli software. The Tivoli Software Glossary is available, in English only,from the Glossary link on the left side of the Tivoli Software Library Web pagehttp://www.ibm.com/software/tivoli/library/

IBM Global Security ToolkitTivoli Access Manager provides data encryption through the use of the IBM GlobalSecurity Toolkit (GSKit). GSKit is included on the IBM Tivoli Access Manager BaseCD for your particular platform.

The GSKit package installs the iKeyman key management utility, gsk5ikm, whichenables you to create key databases, public-private key pairs, and certificaterequests. The following document is available on the Tivoli Information CenterWeb site in the same section as the IBM Tivoli Access Manager productdocumentation:v Secure Sockets Layer Introduction and iKeyman User’s Guide

(gskikm5c.pdf)Provides information for network or system security administrators who plan toenable SSL communication in their Tivoli Access Manager environment.

IBM DB2 Universal DatabaseIBM DB2® Universal Database™ is required when installing IBM Directory Server,z/OS™, and OS/390® LDAP servers. DB2 is provided on the product CDs for thefollowing operating system platforms:v IBM AIX®

v Microsoft™ Windows™

v Sun Solaris Operating Environment

DB2 information is available at:

http://www.ibm.com/software/data/db2/

IBM Directory ServerIBM Directory Server, Version 4.1, is included on the IBM Tivoli Access ManagerBase CD for all platforms except Linux for zSeries™. You can obtain the IBMDirectory Server software for Linux for S/390 at:

http://www.ibm.com/software/network/directory/server/download/

If you plan to use IBM Directory Server as your user registry, see the informationprovided at:

http://www.ibm.com/software/network/directory/library/

IBM WebSphere Application ServerIBM WebSphere Application Server, Advanced Single Server Edition 4.0.3, isincluded on the Web Portal Manager CDs and installed with the Web PortalManager interface. For information about IBM WebSphere Application Server, see:

http://www.ibm.com/software/webservers/appserv/infocenter.html

Preface xv

http://www.ibm.com/software/tivoli/library/


http://www.ibm.com/software/data/db2/

http://www.ibm.com/software/network/directory/server/download/

http://www.ibm.com/software/network/directory/library/

http://www.ibm.com/software/webservers/appserv/infocenter.html

IBM Tivoli Access Manager for Business IntegrationIBM Tivoli Access Manager for Business Integration, available as a separatelyorderable product, provides a security solution for IBM MQSeries®, Version 5.2,and IBM WebSphere® MQ for Version 5.3 messages. IBM Tivoli Access Manager forBusiness Integration allows WebSphere MQSeries applications to send data withprivacy and integrity by using keys associated with sending and receivingapplications. Like WebSEAL and IBM Tivoli Access Manager for OperatingSystems, IBM Tivoli Access Manager for Business Integration, is one of theresource managers that use the authorization services of IBM Tivoli AccessManager for e-business.

The following documents associated with IBM Tivoli Access Manager for BusinessIntegration Version 4.1 are available on the Tivoli Information Center Web site:v IBM Tivoli Access Manager for Business Integration Administrator’s Guide

(SC23-4831-00)v IBM Tivoli Access Manager for Business Integration Release Notes (GI11-0957-00)v IBM Tivoli Access Manager for Business Integration Read Me First (GI11-0958-00)

IBM Tivoli Access Manager for Operating SystemsIBM Tivoli Access Manager for Operating Systems, available as a separatelyorderable product, provides a layer of authorization policy enforcement on UNIXsystems in addition to that provided by the native operating system. IBM TivoliAccess Manager for Operating Systems, like WebSEAL and IBM Tivoli AccessManager for Business Integration, is one of the resource managers that use theauthorization services of IBM Tivoli Access Manager for e-business.

The following documents associated with IBM Tivoli Access Manager forOperating Systems Version 4.1 are available on the Tivoli Information Center Website:v IBM Tivoli Access Manager for Operating Systems Installation Guide (SC23-4829-00)v IBM Tivoli Access Manager for Operating Systems Administration Guide

(SC23-4827-00)v IBM Tivoli Access Manager for Operating Systems Problem Determination Guide

(SC23-4828-00)v IBM Tivoli Access Manager for Operating Systems Release Notes (GI11-0951-00)v IBM Tivoli Access Manager for Operating Systems Read Me First (GI11-0949-00)

Accessing publications onlineThe publications for this product are available online in Portable Document Format(PDF) or Hypertext Markup Language (HTML) format, or both in the TivoliSoftware Library: http://www.ibm.com/software/tivoli/library

To locate product publications in the library, click the Product manuals link on theleft side of the Library page. Then, locate and click the name of the product on theTivoli Software Information Center page.

Product publications include release notes, installation guides, user’s guides,administrator’s guides, and developer’s references.

Note: To ensure proper printing of PDF publications, select the Fit to page checkbox in the Adobe Acrobat Print window (which is available when you clickFile →Print).

xvi IBM Tivoli Access Manager: WebSEAL Administrator’s Guide


Ordering publicationsYou can order many IBM Tivoli publications online at:http://www.elink.ibmlink.ibm.com/public/applications/publications/cgibin/pbi.cgi

You can also order by telephone:v In the United States: 800-879-2755v In Canada: 800-426-4968v In other countries, for a list of telephone numbers, see

http://www.ibm.com/software/tivoli/order-lit/

AccessibilityAccessibility features help a user who has a physical disability, such as restrictedmobility or limited vision, to use software products successfully. With this product,you can use assistive technologies to hear and navigate the interface. You also canuse the keyboard instead of the mouse to operate all features of the graphical userinterface.

Contacting software supportBefore contacting IBM Tivoli Software support with a problem, refer to the IBMTivoli Software support Web site at:http://www.ibm.com/software/sysmgmt/products/support/

If you need additional help, contact software support by using the methodsdescribed in the IBM Software Support Guide at the following Web site:http://techsupport.services.ibm.com/guides/handbook.html

The guide provides the following information:v Registration and eligibility requirements for receiving supportv Telephone numbers and e-mail addresses, depending on the country in which

you are locatedv A list of information you should gather before contacting customer support

Conventions used in this bookThis reference uses several conventions for special terms and actions and foroperating system-dependent commands and paths.

Typeface conventionsThe following typeface conventions are used in this reference:

Bold Lowercase commands or mixed case commands that are difficult todistinguish from surrounding text, keywords, parameters, options, namesof Java classes, and objects are in bold.

Italic Variables, titles of publications, and special words or phrases that areemphasized are in italic.

MonospaceCode examples, command lines, screen output, file and directory namesthat are difficult to distinguish from surrounding text, system messages,text that the user must type, and values for arguments or commandoptions are in monospace.

Preface xvii

http://www.elink.ibmlink.ibm.com/public/applications/publications/cgibin/pbi.cgi

http://www.elink.ibmlink.ibm.com/public/applications/publications/cgibin/pbi.cgi

http://www.ibm.com/software/tivoli/order-lit/

http://www.ibm.com/software/sysmgmt/products/support/

http://techsupport.services.ibm.com/guides/handbook.html

Operating system differencesThis book uses the UNIX convention for specifying environment variables and fordirectory notation. When using the Windows command line, replace $variable with%variable% for environment variables and replace each forward slash (/) with abackslash (\) in directory paths. If you are using the bash shell on a Windowssystem, you can use the UNIX conventions.

xviii IBM Tivoli Access Manager: WebSEAL Administrator’s Guide

Chapter 1. IBM Tivoli Access Manager WebSEAL overview

IBM®Tivoli®Access Manager for e-business (Tivoli Access Manager) is a robust andsecure centralized policy management solution for e-business and distributedapplications. IBM Tivoli Access Manager WebSEAL is a high performance,multi-threaded Web server that applies fine-grained security policy to the TivoliAccess Manager protected Web object space. WebSEAL can provide single sign-onsolutions and incorporate back-end Web application server resources into itssecurity policy.

This overview chapter introduces you to the main capabilities of the WebSEALserver.

Topic Index:v “Introducing IBM Tivoli Access Manager and WebSEAL” on page 1v “Understanding the Tivoli Access Manager security model” on page 2v “Protecting the Web space with WebSEAL” on page 6v “Planning and implementing the security policy” on page 8v “Understanding WebSEAL authentication” on page 9v “Understanding WebSEAL junctions” on page 12

Introducing IBM Tivoli Access Manager and WebSEALIBM Tivoli Access Manager:

IBM Tivoli Access Manager is a complete authorization and network securitypolicy management solution that provides unsurpassed end-to-end protection ofresources over geographically dispersed intranets and extranets.

In addition to its state-of-the-art security policy management feature, Tivoli AccessManager provides authentication, authorization, data security, and centralizedresource management capabilities. You use Tivoli Access Manager in conjunctionwith standard Internet-based applications to build highly secure and well-managedintranets.

At its core, Tivoli Access Manager provides:v Authentication framework

Tivoli Access Manager provides a wide range of built-in authenticators andsupports external authenticators.

v Authorization frameworkThe Tivoli Access Manager authorization service, accessed through the TivoliAccess Manager authorization API, provides permit and deny decisions onrequests for protected resources located in the secure domain.

With Tivoli Access Manager, businesses can securely manage access to privateinternal network-based resources while leveraging the public Internet’s broadconnectivity and ease of use. Tivoli Access Manager, in combination with acorporate firewall system, can fully protect the Enterprise intranet fromunauthorized access and intrusion.

© Copyright IBM Corp. 1999, 2002 1

IBM Tivoli Access Manager WebSEAL:

IBM Tivoli Access Manager WebSEAL is the resource manager responsible formanaging and protecting Web-based information and resources.

WebSEAL is a high performance, multi-threaded Web server that appliesfine-grained security policy to the Tivoli Access Manager protected Web objectspace. WebSEAL can provide single sign-on solutions and incorporate back-endWeb application server resources into its security policy.

WebSEAL normally acts as a reverse Web proxy by receiving HTTP/HTTPSrequests from a Web browser and delivering content from its own Web server orfrom junctioned back-end Web application servers. Requests passing throughWebSEAL are evaluated by the Tivoli Access Manager authorization service todetermine whether the user is authorized to access the requested resource.

WebSEAL provides the following features:v Supports multiple authentication methods

Both built-in and plug-in architectures allow flexibility in supporting a variety ofauthentication mechanisms.

v Accepts HTTP and HTTPS requestsv Integrates and protects back-end server resources through WebSEAL junction

technologyv Manages fine-grained access control for the local and back-end server Web space

Supported resources include URLs, URL-based regular expressions, CGIprograms, HTML files, Java servlets, and Java class files.

v Performs as a reverse Web proxyWebSEAL appears as a Web server to clients and appears as a Web browser tothe junctioned back-end servers it is protecting.

v Provides single sign-on capabilities

Understanding the Tivoli Access Manager security modelThe security policy for a Tivoli Access Manager secure domain is maintained andgoverned by two key security structures:v User registry

Client WebSEAL

� Supports multiple authentication methods� Integrates Access Manager authorization service� Manages fine-grain control of Web resources� Handles variety of resource types� Incorporates and secures back-end server resources� Unifies protected Web resource space� Provides single sign-on solutions

authentication Webapplication

server

/

Secured Webobject space

WebSEAL junction

Figure 1. Protecting the Web space with WebSEAL

2 IBM Tivoli Access Manager: WebSEAL Administrator’s Guide

The user registry (such as LDAP, Lotus Domino, or Microsoft Active Directory)contains all users and groups who are allowed to participate in the Tivoli AccessManager secure domain.

v Master authorization (policy) database

The authorization database contains a representation of all resources in thedomain (the protected object space). The security administrator can dictate anylevel of security by applying rules, known as access control list (ACL) policiesand protected object policies (POP), to those resources requiring protection

The process of authentication proves the identity of a user to WebSEAL. A user canparticipate in the secure domain as authenticated or unauthenticated. Only userswith an entry in the user registry can become authenticated users. Using ACLs andPOPs, the security administrator can make certain public resources available tounauthenticated users. Other resources can be made available only to certainauthenticated users.

When a user successfully authenticates to WebSEAL, a set of identificationinformation—known as a credential—is created for that user. The credentialcontains the user identity, any group memberships, and any special (″extended″)security attributes.

The Tivoli Access Manager authorization service enforces security policies bycomparing a user’s authentication credentials with the policy permissions assignedto the requested resource. The resulting recommendation is passed to the resourcemanager (for example, WebSEAL), which completes the response to the originalrequest. The user credential is essential for full participation in the secure domain.

The protected object spaceThe protected object space is a hierarchical portrayal of resources belonging to aTivoli Access Manager secure domain. The virtual objects that appear in thehierarchical object space represent the actual physical network resources.v System resource – the actual physical file or application.v Protected object – the logical representation of an actual system resource used

by the authorization service, the Web Portal Manager, and other Tivoli AccessManager management utilities.

Policy templates can be attached to objects in the object space to provide protectionof the resource. The authorization service makes authorization decisions basedthese templates.

The following object space categories are used by Tivoli Access Manager:v Web objects

Web objects represent any resource that can be addressed by an HTTP URL. Thisincludes static Web pages and dynamic URLs that are converted to databasequeries or some other type of application. The WebSEAL server is responsiblefor protecting Web objects.

v Tivoli Access Manager management objects

Management objects represent the management activities that can be performedthrough the Web Portal Manager. The objects represent the tasks necessary todefine users and set security policy. Tivoli Access Manager supports delegationof management activities and can restrict an administrator’s ability to setsecurity policy to a subset of the object space.

v User-defined objects

Chapter 1. IBM Tivoli Access Manager WebSEAL overview 3

User-defined objects represent customer-defined tasks or network resourcesprotected by applications that access the authorization service through the TivoliAccess Manager authorization API.

Defining and applying ACL and POP policiesSecurity administrators protect Tivoli Access Manager system resources by definingrules, known as ACL and POP policies, and applying these policies to the objectrepresentations of those resources in the protected object space.

The Tivoli Access Manager authorization service performs authorization decisionsbased on the policies applied to these objects. When a requested operation on aprotected object is permitted, the application responsible for the resourceimplements this operation.

One policy can dictate the protection parameters of many objects. Any change tothe rule will affect all objects to which the template is attached.

The access control list (ACL)An access control list policy, or ACL policy, is the set of rules (permissions) thatspecifies the conditions necessary to perform certain operations on that resource.ACL policy definitions are important components of the security policy establishedfor the secure domain. ACL policies, like all policies, are used to stamp anorganization’s security requirements onto the resources represented in theprotected object space.

An ACL policy specifically controls:1. What operations can be performed on the resource2. Who can perform these operations

An ACL policy is made up of one or more entries that include user and groupdesignations and their specific permissions or rights. An ACL can also containrules that apply to unauthenticated users.

ManagementObjects

WebObjects

User-DefinedObjects

Figure 2. Tivoli Access Manager protected object space


Protected object policies (POP)ACL policies provide the authorization service with information to make a ″yes″ or″no″ answer on a request to access a protected object and perform some operationon that object.

POP policies contain additional conditions on the request that are passed back toTivoli Access Manager Base and the resource manager (such as WebSEAL) alongwith the ″yes″ ACL policy decision from the authorization service. It is theresponsibility of Tivoli Access Manager and the resource manager to enforce thePOP conditions.

The following tables list the available attributes for a POP:

Enforced by Tivoli Access Manager Base

POP Attribute Description

Name Name of the policy. This becomes the <pop-name> in thepdadmin pop commands.

Description Descriptive text for the policy. This appears in the popshow command.

Warning Mode Provides administrators a means to test ACL and POPpolicies.

Audit Level Specifies type of auditing: all, none, successful access,denied access, errors.

Time-of-Day Access Day and time restrictions for successful access to theprotected object.

Enforced by Resource Manager (such as WebSEAL)

POP Attribute Description

Quality of Protection Specifies degree of data protection: none, integrity,privacy.

IP Endpoint AuthenticationMethod Policy

Specifies authentication requirements for access frommembers of external networks.

Document Cache Control Specify caching instructions for the handling of specificdocuments.

user peter ---------T---rx

group engineering ---------T---rx

user michael ---------T---rx

unauthenticated ---------------

ACL

(containing multiple

entries)

Figure 3. ACL policy


Explicit and inherited policyPolicy can be explicitly applied or inherited. The Tivoli Access Manager protectedobject space supports inheritance of ACL and POP policy attributes. This is animportant consideration for the security administrator who manages the objectspace. The administrator needs to apply explicit policies only at points in thehierarchy where the rules must change.

Policy administration: The Web Portal ManagerThe Web Portal Manager is a Web-based graphical application used to managesecurity policy in a Tivoli Access Manager secure domain. The pdadmin commandline utility provides the same administration capabilities as the Web PortalManager, plus some commands not supported by the Web Portal Manager.

From the Web Portal Manager (or pdadmin), you can manage the user registry, themaster authorization policy database, and the Tivoli Access Manager servers. Youcan also add and delete users/groups and apply ACL and POP policies to networkobjects.

Protecting the Web space with WebSEALWhen WebSEAL enforces security in a secure domain, each client must provideproof of its identity. In turn, Tivoli Access Manager security policy determineswhether that client is permitted to perform an operation on a requested resource.Because access to every Web resource in a secure domain is controlled byWebSEAL, WebSEAL’s demands for authentication and authorization can providecomprehensive network security.

In security systems, authorization is distinct from authentication. Authorizationdetermines whether an authenticated client has the right to perform an operationon a specific resource in a secure domain. Authentication can validate the identityof a client, but says nothing about the client’s right to perform operations on aprotected resource.

In the Tivoli Access Manager authorization model, authorization policy isimplemented independently of the mechanism used for user authentication. Userscan authenticate their identity using either public/private key, secret key, orcustomer-defined mechanisms.

ManagementObjects

WebObjects

User-DefinedObjects

Explicit RuleInherited

Rule

Figure 4. Explicit and inherited policies


Part of the authentication process involves the creation of a credential thatdescribes the identity of the client. Authorization decisions made by anauthorization service are based on user credentials.

The resources in a secure domain receive a level of protection as dictated by thesecurity policy for the domain. The security policy defines the legitimateparticipants of the secure domain and the degree of protection surrounding eachresource requiring protection.

The authorization process consists of the following basic components:v A resource manager is responsible for implementing the requested operation

when authorization is granted. WebSEAL is a resource manager.A component of the resource manager is a policy enforcer that directs therequest to the authorization service for processing.

Note: Traditional applications bundle the policy enforcer and resource managerinto one process. Examples of this structure include WebSEAL andthird-party applications.

v An authorization service performs the decision-making action on the request.

The following diagram illustrates the complete authorization process:

1. An authenticated client request for a resource is directed to the resourcemanager and intercepted by the policy enforcer process.The resource manager can be WebSEAL (for HTTP, HTTPS access) or athird-party application.

2. The policy enforcer process uses the Tivoli Access Manager authorization APIto call the authorization service for an authorization decision.

3. The authorization service performs an authorization check on the resource,represented as an object in the protected object space. Base POP policies arechecked first. Next the ACL policy attached to the object is checked against theclient’s credentials. Then, POP policies enforced by the resource manager arechecked.

client

authorizationservice

Secure Domain

authorizationpolicy

protected objectspace

2. Request forauthorization

(authAPI)

5. Authorizedoperation

1. Request

6. Response

3. Authorizationcheck

4. Authorizationdecision(authAPI)

resources

/

resourcemanager

policyenforcer

Figure 5. The Tivoli Access Manager authorization process


4. The decision to accept or deny the request is returned as a recommendation tothe resource manager (through the policy enforcer).

5. If the request is finally approved, the resource manager passes the request on tothe application responsible for the resource.

6. The client receives the results of the requested operation.

Planning and implementing the security policyA corporate security policy identifies:v The Web resources requiring protectionv The level of protection

Tivoli Access Manager uses a virtual representation of these Web resources, calledthe protected object space. The protected object space contains objects thatrepresent actual physical resources in your network.

You implement security policy by applying the appropriate security mechanisms tothe objects requiring protection.

Security mechanisms include:v Access control list (ACL) policies

ACL policies identify user types that can be considered for access and specifythe operations permitted on the object.

v Protected object policies (POP)A POP specifies additional conditions governing the access to the protectedobject, such as privacy, integrity, auditing, and time-of-day access.

v Extended attributesExtended attributes are additional values placed on an object, ACL, or POP thatcan be read and interpreted by third-party applications (such as an externalauthorization service).

The core component of Tivoli Access Manager is the Tivoli Access Managerauthorization service—which permits or denies access to protected objects(resources) based on the user’s credentials and the access controls placed on theobjects.

To successfully implement the security policy, you must logically organize thedifferent content types (as described in “Identifying content types and levels ofprotection” on page 8) and apply the appropriate ACL and POP policies. Accesscontrol management can be very complex and is made much easier by carefulcategorization of the content types.

Identifying content types and levels of protectionAs the security administrator of your Web space, you must correctly identify thetypes of content available to a variety of user types. Some content must be highlyprotected and available only to specific users; other content is for general publicview. Each security scenario demands different protection requirements and theassociated WebSEAL configuration.

It is your responsibility to:v Know your Web contentv Identify the types of users requiring access to this content


v Understand the strengths and weaknesses of the available WebSEALconfiguration options for securing this content

Protection of Web content falls into three broad categories:1. Public content – access requires no protection

v Unauthenticated clients access using HTTPv Unauthenticated credential used for access control to resourcesv Basic WebSEAL configuration requirements

2. Public content – access requires privacy (encryption)v Unauthenticated clients access using HTTPSv Encryption required to protect sensitive data required by application server

(such as credit card numbers and user account information)v Unauthenticated credential used for access control to resourcesv WebSEAL configuration needs to stipulate privacy

3. Private content – access requires authenticationv Authenticated clients access using HTTP or HTTPSv Administrator determines the need for encryptionv Authenticated credential used for access control to resources; clients must

have account defined in user registryv WebSEAL configuration is complex and all options must be considered

carefully to determine impact of security policy

Understanding WebSEAL authenticationAuthentication is the method of identifying an individual process or entityattempting to login to a secure domain. When both server and client requireauthentication, the exchange is known as mutual authentication.

WebSEAL can enforce a high degree of security in a secure domain by requiringeach client to provide proof of its identity.

The following conditions apply to WebSEAL authentication:v WebSEAL supports a standard set of authentication methods.

You can customize WebSEAL to support other authentication methods.v The WebSEAL server process is independent of the authentication method.v WebSEAL requires a client identity. From this identity, WebSEAL builds an

authenticated (or unauthenticated) credential that can be used by the TivoliAccess Manager authorization service to permit or deny access to resources.

Client WebSEAL

Who are you?

Who are you?

Figure 6. Mutual authentication


This flexible approach to authentication allows security policy to be based onbusiness requirements and not physical network topology.

The goals of authenticationAlthough WebSEAL is independent of the authentication process, WebSEALrequires the results of authentication—the client identity. The authenticationprocess results in the following actions:1. The authentication method results in a client identity

Client authentication is successful only if the user has an account defined in theTivoli Access Manager user registry or is processed successfully by aCross-domain Authentication Service (CDAS). Otherwise the user is designatedas unauthenticated.Method-specific identity information, such as passwords, tokens, andcertificates, represent physical identity properties of the user. This informationcan be used to establish a secure session with the server.

2. WebSEAL uses the identity to acquire credentials for that clientWebSEAL matches the client identity with a registered Tivoli Access Manageruser. WebSEAL then builds the credentials appropriate to this user. This isknown as credentials acquisition.The credential represents a user’s privileges in the secure domain, describes theuser in a specific context, and is valid only for the lifetime of that session.Credential data includes the user name, any group memberships, and anyspecial ″extended″ security attributes.If a user is not a member of the user registry (″anonymous″), WebSEAL buildsan unauthenticated credential for that user. Remember that an ACL can containspecial rules governing unauthenticated users.These credentials are available to the authorization service that permits ordenies access to requested objects in the WebSEAL protected object space.

Credentials can be used by any Tivoli Access Manager service that requiresinformation about the client. Credentials allow Tivoli Access Manager to securelyperform a multitude of services such as authorization, auditing, and delegation.

Tivoli Access Manager distinguishes the authentication of the user from theacquisition of credentials. A user’s identity is always constant. However,credentials—which define the groups or roles in which a user participates—arevariable. Context-specific credentials can change over time. For example, when aperson is promoted, credentials must reflect the new responsibility level.

See Chapter 5, “WebSEAL authentication”, on page 111 for further informationabout support for specific authentication methods.

Authenticated and unauthenticated access to resourcesIn a Tivoli Access Manager secure domain environment, the identity of a user isproven to WebSEAL through the process of authentication. In general, a user canparticipate in the secure domain as authenticated or unauthenticated.

In either case, the Tivoli Access Manager authorization service requires a usercredential to make authorization decisions on requests for resources in the securedomain. WebSEAL handles authenticated user credentials differently fromunauthenticated user credentials.


The credential for an unauthenticated user is simply a generic passport that allowsthe user to participate in the secure domain and access resources that are availableto unauthenticated users.

The credential for an authenticated user is a unique passport that describes aspecific user who belongs to the Tivoli Access Manager user registry (or isprocessed successfully by a CDAS). The authenticated user credential contains theuser identity, any group memberships, and any special (″extended″) securityattributes.

The process flow for authenticated users:v A user makes a request for a resource protected by WebSEAL. The protection on

the resource requires that the user be authenticated. WebSEAL prompts the userto log in.

v Successful authentication can occur only if the user is a member of the TivoliAccess Manager user registry or is handled by a CDAS operation.

v A WebSEAL session ID is created for the user.v A credential for this user is built from information contained in the registry

about this user (such as group memberships).v The session ID and credential, plus other data, is stored as an entry in the

WebSEAL session/credentials cache.v As WebSEAL processes this request (and future requests during this session), it

keeps the credential information available.v Whenever an authorization check is required, the Tivoli Access Manager

authorization service uses the credential information during the decision-makingprocess.

v When the user logs off, the cache entry for that user is removed and the sessionis terminated.

The process flow for unauthenticated users:v A user makes a request for a resource protected by WebSEAL. The protection on

the resource does not require that the user be authenticated. WebSEAL does notprompt the user to log in.

v WebSEAL builds an unauthenticated credential for the user.v No entry is created in the WebSEAL session/credentials cache.v The user can access resources that contain the correct permissions for the

unauthenticated type category of user.v If the user requires access to a resource not available to unauthenticated users,

WebSEAL prompts the user to log in.v A successful log in changes the user’s status to authenticated.v If log in is unsuccessful, a 403 ″Forbidden″ message is returned. The user can

still continue to access other resources that are available to unauthenticatedusers.

The WebSEAL session/credentials cache structureThe WebSEAL session cache is also known as the WebSEAL credentials cache. Thecache can be represented as an internal table where WebSEAL stores informationabout all sessions established by authenticated users.


Each user session is represented by an entry in the cache table.

Each cache entry contains the following types of information:v Session ID

The session ID is a unique identifier that is sent with each request made by thatuser. The session ID identifies the specific cache entry for that user.

v Cache data

The most important data stored in the cache entry is the user credential. Thecredential is required whenever the user requests protected resources. Theauthorization service uses the credential information to permit or deny access tothe resource.WebSEAL can mark, or ″flag″, a cache entry to support certain functionality. Forexample, when session inactivity reauthentication is enabled, a cache entry is″flagged″ when the session inactivity value has expired.

v Time-stamps

The creation time-stamp for the cache entry becomes the reference point for thesession lifetime value. The ″last active″ time-stamp for the cache entry becomesthe reference point for the session inactivity timer.

The user credential contains:v User namev Group membershipsv Extended attributes

Extended attributes allow you to store customized data in the user credential.An example of a credential extended attribute is the tagvalue_user_session_idattribute. The value of this attribute can be inserted in an HTTP header to allowa back-end junctioned server to maintain session state with the user.

Understanding WebSEAL junctionsTivoli Access Manager provides authentication, authorization, and managementservices for a network. In a Web-based network, these services are best providedby one or more front-end WebSEAL servers that integrate and protect Webresources and applications located on back-end Web servers.

WebSEAL Session / Credentials Cache

Session ID Cache Data Time-stamps

1234- user credential- internal flags- internal data

- creation time- last active timecache

entry

Figure 7. WebSEAL session/credentials cache


The connection between a WebSEAL server and a back-end Web application serveris known as a WebSEAL junction. A WebSEAL junction is a TCP/IP connectionbetween a front-end WebSEAL server and a back-end server.

The back-end server can be another WebSEAL server or, more commonly, athird-party Web application server. The back-end server Web space is ″connected″to the WebSEAL server at a specially designated junction (mount) point in theWebSEAL Web space.

A junction allows WebSEAL to provide protective services on behalf of theback-end server. WebSEAL can perform authentication and authorization checks onall requests before passing those requests on to the back-end server. If the back-endserver requires fine-grained access control on its objects, you must performadditional configuration steps to describe the third-party Web space to the TivoliAccess Manager security service (see “Using query_contents with third-partyservers” on page 196).

Junctions provide a scalable, secure environment that allows load balancing, highavailability, and state management capabilities—all performed transparently toclients. As an administrator, you can benefit from this centralized management ofthe Web space.

WebSEAL junctions provide the added value of logically combining the Web spaceof a back-end server with the Web space of the WebSEAL server. Junctions betweencooperating servers result in a single, unified, distributed Web space that isseamless and transparent to users.

The client never needs to know the physical location of a Web resource. WebSEALtranslates logical URL addresses into the physical addresses that a back-end serverexpects. Web objects can be moved from server to server without affecting the waythe client accesses those objects.

A unified Web space simplifies the management of all resources for the systemadministrator. Additional administrative benefits include scalability, load balancing,and high availability.

ClientWeb

applicationserver

junction

TCP or SSL

WebSEAL/

/mnt

Secure Domain

Figure 8. Junctions connect WebSEAL with back-end servers


Most commercial Web servers do not have the ability to define a logical Web objectspace. Instead, their access control is connected to the physical file and directorystructure. WebSEAL junctions can transparently define an object space that reflectsorganizational structure rather than the physical machine and directory structurecommonly encountered on standard Web servers.

WebSEAL junctions also allow you to create single sign-on solutions. A singlesign-on configuration allows a user to access a resource, regardless of theresource’s location, using only one initial login. Any further login requirementsfrom back-end servers are handled transparently to the user.

WebSEAL junctions are an important tool for making your Web site scalable.Junctions allow you to respond to increasing demands on a Web site by attachingadditional servers.

WebSEAL junctions and Web site scalabilityWebSEAL junctions are used to create a scalable Web site. As the demands on theWeb site grow, more servers can easily be added to expand the capabilities of thesite.

Additional servers can be added for the following reasons:v To extend the site with additional contentv To duplicate existing content for load balancing, fail-over capability, and high

availability

/

WebSEAL Web space

Combined Web space:WebSEAL plus junctioned server

/junction-point

Figure 9. WebSEAL junction results in a unified Web space


Replicated front-end WebSEAL serversJunction support for back-end servers starts with at least one front-end WebSEALserver. Replicated front-end WebSEAL servers provide the site with load balancingduring periods of heavy demand. The load balancing mechanism is handled by amechanism such as IBM Network Dispatcher or Cisco Local Director.

Front-end replication also provides the site with fail-over capability—if a serverfails for some reason, the remaining replica servers will continue to provide accessto the site. Successful load balancing and fail-over capability results in highavailability for users of the site.

When you replicate front-end WebSEAL servers, each server must contain an exactcopy of the Web space and the junction database.

Account information for authentication resides in a user registry that isindependent of the front-end servers.

Supporting back-end serversWeb site content can be served by the WebSEAL server itself, back-end servers, ora combination of both. WebSEAL junction support for back-end servers allows youto scale the Web site through additional content and resources.

Each unique back-end server must be junctioned to a separate junction (mount)point. As the demand for additional content grows, more servers can be addedthrough junctions. This scenario provides a solution for networks that have a largeexisting investment in third-party Web servers.

SSL Client SSL Client

WebSEAL ServerPrimary

Internet

WebSEAL ServerReplica

Load-Balancingmechanism

Figure 10. Replicated front-end WebSEAL servers


The following diagram illustrates how junctions provide a unified, logical objectspace. This Web space is transparent to the user and allows for centralizedmanagement.

Replicated back-end servers are junctioned to the same junction point, as discussedin the next section.

Replicated back-end serversTo extend scalability features to a back-end server configuration, you can replicatethe back-end servers. As is the case with replicated front-end servers, replicatedback-end servers must contain Web spaces that are mirror images of each other.

SSL Client


Internet


Third-party Server/engineering

SSL Client

Third-party Server/sales

Load-balancingmechanism

Figure 11. Junctioning back-end servers

Web Object Space

/Engineering Junction Sales Junction

Figure 12. Unified Web space


WebSEAL load balances across the replicated servers using a ″least-busy″scheduling algorithm. This algorithm directs each new request to the server withthe fewest connections already in progress.

WebSEAL also correctly fails-over when a server is down and starts re-using thatserver after it has been restarted.

If the back-end application requires its state to be maintained over several pages,stateful junctions can be used to ensure that each session returns to the sameback-end server.

SSL Client


Internet


SSL Client

ReplicatedEngineering Servers

ReplicatedSales Servers

ReplicatedFront-endServers


Figure 13. Replicated back-end servers


Chapter 2. Basic server configuration

This chapter contains information that describes a basic set of administration andconfiguration tasks you can perform to customize the WebSEAL server for yournetwork. See also Chapter 3, “Advanced server configuration”, on page 53.

Topic Index:v “General server information” on page 19v “Using the WebSEAL configuration file” on page 21v “Configuring communication parameters” on page 23v “Managing the Web space” on page 26v “Managing custom HTTP error message pages” on page 31v “Managing custom account management pages” on page 34v “Multi-locale support for Web services” on page 36v “Managing client-side and server-side certificates” on page 38v “Configuring default HTTP logging” on page 42v “Configuring HTTP logging using event logging” on page 45v “Logging WebSEAL serviceability messages” on page 46

General server informationThe following sections provide general information about the WebSEAL server:v “Root directory of the WebSEAL installation” on page 19v “Starting and stopping WebSEAL” on page 20v “WebSEAL represented in the protected object space” on page 20v “WebSEAL returns HTTP/1.1” on page 20v “WebSEAL log file” on page 21

Root directory of the WebSEAL installationWebSEAL program files are installed in the following root directory:

UNIX:/opt/pdweb/

Windows:C:\Program Files\Tivoli\PDWeb\

You can configure this path on a Tivoli Access Manager for Windows installation.You cannot configure this path on UNIX installations of Tivoli Access Manager.

This guide uses the <install-path> variable to represent this root directory.

On UNIX installations, the following separate directory contains expandable files,such as audit and log files:/var/pdweb/


Starting and stopping WebSEALYou can start and stop the WebSEAL server process using the pdweb command onUNIX and using the Services Control Panel on Windows.

UNIX:pdweb {start|stop|restart|status}

The pdweb command is located in the following directory:/usr/bin/

For example, to stop the WebSEAL server and then restart the server, use:# /usr/bin/pdweb restart

Windows:

Identify the WebSEAL server process in the Services Control Panel and use theappropriate control buttons.

WebSEAL represented in the protected object spaceThe server-name parameter in the webseald.conf configuration file specifies thepoint in the Tivoli Access Manager protected object space that represents thisWebSEAL server instance.

For a single WebSEAL server installation, this value is automatically set using thehost name of the machine where this WebSEAL server is being installed.

For example, if the machine (host) name is sales1, the parameter value is set as:[server]server-name = sales1

The representation of this WebSEAL server instance in the Tivoli Access Managerprotected object space would appear as:/WebSEAL/sales1

See also: “Replicating front-end WebSEAL servers” on page 58.

For multiple instances of WebSEAL on the same machine, this value is set by the –ioption to the PDWeb_config (UNIX) or ivweb_setup (Windows) script used tocreate the multiple WebSEAL server instances.

See also: “Configuring multiple WebSEAL server instances” on page 59.

WebSEAL returns HTTP/1.1HTTP/1.0 requests are sent to junctioned back-end servers only if those serversreturn a status of 400 (Bad Request), return a status of 504 (HTTP version notsupported), of if the client browser specifies HTTP/1.0 in the request.

Otherwise, if the back-end server accepts HTTP/1.1, WebSEAL sends HTTP/1.1requests.

However, even when WebSEAL sends an HTTP/1.0 request to a junctionedback-end server (and the back-end server returns an HTTP/1.0 response),WebSEAL always returns an HTTP/1.1 response to the client browser.


WebSEAL log fileThe WebSEAL log file records serviceability messages such as server warning anderror messages. The name and location of the log file is defined by the server-logparameter in the [logging] stanza of the webseald.conf configuration file:

UNIX:[logging]server-log = /var/pdweb/log/msg_webseald.log

Windows:[logging]server-log = C:/Program Files/Tivoli/PDWeb/log/msg_webseald.log

See also “Logging WebSEAL serviceability messages” on page 46.

Using the WebSEAL configuration fileThe following sections provide information about the WebSEAL configuration file(webseald.conf):v “The webseald.conf configuration file” on page 21v “WebSEAL server root directory” on page 23

The webseald.conf configuration fileYou can customize the operation of WebSEAL by configuring the parameterslocated in the webseald.conf configuration file. The file is located in the followingdirectory:

UNIX:/opt/pdweb/etc/

Windows:C:\Program Files\Tivoli\PDWeb\etc\

Tivoli Access Manager configuration files are ASCII text-based and can be editedusing a common text editor. The configuration files contain parameter entries inthe following format:parameter = value

The initial installation of Tivoli Access Manager sets default values for mostparameters. Some parameters are static and never change; others can be modifiedto customize server functionality and performance.

Each file contains sections, or stanzas, containing one or more parameters for aparticular configuration category. The stanza headings appear within brackets:[stanza-name]

For example, the [junction] stanza in webseald.conf defines the configurationsettings affecting WebSEAL junctions. The [authentication-mechanisms] stanzadefines the authentication mechanisms supported by WebSEAL, along withassociated shared library files.

Chapter 2. Basic server configuration 21

Configuration files contain comments that explain the use of each parameter. The″#″ character is used to designate a line as a comment. All comment lines beginwith the ″#″ character. Therefore, the ″#″ character is not a valid character for usein parameter values.

Note: Anytime you make a change to the webseald.conf file, you must manuallyrestart WebSEAL so that the new changes are recognized. See “Starting andstopping WebSEAL” on page 20.

The following table summarizes the sections and stanzas contained in thewebseald.conf configuration file:

Sections Stanzas

WEBSEAL GENERAL [server]

LDAP [ldap]

ACTIVE DIRECTORY [uraf-ad]

DOMINO [uraf-domino]

SSL [ssl]

JUNCTION [junction][filter-url][filter-events][filter-schemes][filter-content-types][filter-request-headers][script-filtering][gso-cache][ltpa-cache]

AUTHENTICATION [ba][forms][token][certificate][http-headers][auth-headers][ipaddr][authentication-levels][mpa][cdsso][cdsso-peers][failover][failover-attributes][e-community-sso][e-community-domain-keys][reauthentication][authentication-mechanisms][ssl-qop][ssl-qop-mgmt-hosts][ssl-qop-mgmt-networks][ssl-qop-mgmt-default]

SESSION [session]


Sections Stanzas

CONTENT [content][acnt-mgt][enable-redirects][cgi][cgi-types][cgi-environment-variable][content-index-icons][icons][content-cache][content-mime-types][content-encodings]

LOGGING [logging]

AUTHORIZATION API [aznapi-configuration][aznapi-entitlement-services]

POLICY DIRECTOR [policy-director][manager]

See Appendix A, “WebSEAL configuration file reference”, on page 241.

WebSEAL server root directoryThe server-root parameter in the webseald.conf configuration file defines the rootlocation of the WebSEAL server for other parameters in this file. All relative pathnames expressed in the webseald.conf configuration file are relative to this rootdirectory.

UNIX:[server]server-root = /opt/pdweb/www

Windows:[server]server-root = C:\Program Files\Tivoli\PDWeb\www

Note: Under normal conditions, you should not change this pathname.

Configuring communication parametersThe following sections describe general information about the WebSEAL server:v “Configuring WebSEAL for HTTP requests” on page 23v “Configuring WebSEAL for HTTPS requests” on page 24v “Restricting connections from specific SSL versions” on page 24v “Timeout parameters for HTTP/HTTPS communication” on page 24v “Additional WebSEAL server timeout parameters” on page 25

Configuring WebSEAL for HTTP requestsWebSEAL typically handles many HTTP requests from unauthenticated users. Forexample, it is common to allow anonymous users read-only access to selecteddocuments on the public section of your Web site.

Parameters for handling HTTP requests over TCP are located in the [server] stanzaof the webseald.conf configuration file.


Enabling/disabling HTTP accessEnable or disable HTTP access during WebSEAL configuration:http = {yes|no}

IBM HTTP Server, WebSphere Application Server (which installs as IBM HTTPServer), and WebSEAL all use port 80 as the default port. If you install WebSEALon the same system as IBM HTTP Server, ensure that you change the default portto one of these servers. Edit the httpd.conf configuration file or the webseald.confconfiguration file.

Setting the HTTP access port valueThe default port for HTTP access is 80:http-port = 80

To change to port 8080, for example, set:http-port = 8080

Configuring WebSEAL for HTTPS requestsParameters for handling HTTP requests over SSL (HTTPS) are located in the[server] stanza of the webseald.conf configuration file.

Enabling/disabling HTTPS accessEnable or disable HTTPS access during WebSEAL configuration:https = {yes|no}

Setting the HTTPS access port valueThe default port for HTTPS access is 443:https-port = 443

To change to port 4343, for example, set:https-port = 4343

Restricting connections from specific SSL versionsYou can independently enable and disable connectivity for SSL (Secure SocketsLayer) version 2, SSL version 3, and TLS (Transport Layer Security) version 1. Theparameters that control connections for specific SSL and TLS versions are locatedin the [ssl] stanza of the webseald.conf configuration file. By default, all SSL andTLS versions are enabled.[ssl]disable-ssl-v2 = { yes | no }disable-ssl-v3 = { yes | no }disable-tls-v1 = { yes | no }

Timeout parameters for HTTP/HTTPS communicationWebSEAL uses the IBM Global Security Kit (GSKit) implementation of SSL. WhenWebSEAL receives a request from an HTTPS client, GSKit SSL establishes the initialhandshake and maintains session state.

WebSEAL supports the following timeout parameters for HTTP and HTTPScommunication. These parameters are located in the [server] stanza of thewebseald.conf configuration file.v client-connect-timeout


After the initial handshake has occurred, this parameter dictates how longWebSEAL holds the connection open for the initial HTTP or HTTPS request. Thedefault is 120 seconds.[server]client-connect-timeout = 120

v persistent-con-timeout

After the first HTTP request and server response, this parameter controlsmaximum number of seconds WebSEAL holds an HTTP persistent connectionopen before it is shutdown. The default value is 5 seconds.[server]persistent-con-timeout = 5

Additional WebSEAL server timeout parametersThe following additional timeout parameters are set in the webseald.confconfiguration file:

Parameter DescriptionDefault Value

(seconds)

[junction]http-timeout

The timeout value for sending toand reading from a back-end serverover a TCP junction.

120

[junction]https-timeout

The timeout value for sending toand reading from a back-end serverover an SSL junction.

120

[cgi]cgi-timeout

The timeout value for sending toand reading from a local CGIprocess.

120

[junction]ping-time

WebSEAL performs a periodicbackground ping of each junctionedserver to determine whether it isrunning. WebSEAL will not try moreoften than once every 300 seconds(or whatever value is set).

300

Connect

Client WebSEAL

SSL Handshake

HTTP Request

Response

HTTP Request

GSKit controlled

client-connect-timeout

persistent-con-timeout

Figure 14. Timeout parameters for HTTP and HTTPS communication


Managing the Web spaceThe following sections describe tasks required to manage the Web space:v “Root directory of the Web document tree” on page 26v “Configuring directory indexing” on page 27v “Windows: File naming for CGI programs” on page 28v “Configuring Web document caching” on page 29v “Specifying document MIME types for URL filtering” on page 31

Root directory of the Web document treeThe Web document tree location is the absolute path to the root of the documenttree for document resources made available by WebSEAL. This path name isrepresented by the doc-root parameter in the [content] stanza of the webseald.confconfiguration file. The default location is initially established during the installationof WebSEAL:

UNIX:[content]doc-root = /opt/pdweb/www/docs

Windows:[content]doc-root = C:\Program Files\Tivoli\PDWeb\www\docs

This value is used only once—the first time WebSEAL is started after installation.The value is then stored in the junction database. Future modification of this valuein webseald.conf has no impact.

How to change the document root after installation:

After installation, you must use the pdadmin utility to change the document rootdirectory location value. The following example (machine, or host, name iswebsealA) illustrates this procedure:1. Login to pdadmin:

# pdadminpdadmin> loginEnter User ID: sec_masterEnter Password:pdadmin>

2. Use the server task list command to display all current junction points:pdadmin> server task webseald-websealA list/

3. Use the server task show command to display details of the junction:pdadmin> server task webseald-websealA show /Junction point: /Type: LocalJunction hard limit: 0 - using global valueJunction soft limit: 0 - using global valueActive worker threads: 0Root Directory: /opt/pdweb/www/docs

4. Create a new local junction to replace the current junction point (the -f optionis required to force a new junction that overwrites an existing junction):pdadmin> server task webseald-websealA create -t local -f -d /tmp/docs /Created junction at /


5. List the new junction point:pdadmin> server task webseald-websealA list/

6. Display the details of this junction:pdadmin> server task webseald-websealA show /Junction point: /Type: LocalJunction hard limit: 0 - using global valueJunction soft limit: 0 - using global valueActive worker threads: 0Root Directory: /tmp/docs

Configuring directory indexingYou can specify the name of the default file returned by WebSEAL when the URLexpression of a request ends with a directory name. If this default file exists,WebSEAL returns the file to the client. If the file does not exist, WebSEALdynamically generates a directory index and returns the list to the client.

The parameter for configuring the directory index file is located in the [content]stanza of the webseald.conf configuration file.

The default value for the index file is:[content]directory-index = index.html

You can change this filename if your site uses a different convention. For example:[content]directory-index = homepage.html

WebSEAL dynamically generates a directory index if the directory in the requestdoes not contain the index file defined by the directory-index parameter. Thegenerated index contains a list of the directory contents, with links to each entry inthe directory. The index is generated only if the client requesting access to thedirectory has the ″list″ (l) permission on the ACL for that directory.

You can configure the specific graphical icons used by WebSEAL for each file typelisted in a generated index. The [content-index-icons] stanza of the webseald.confconfiguration file contains a list of the document MIME types and the associated.gif files that are displayed:[content-index-icons]image/*= /icons/image2.gifvideo/* = /icons/movie.gifaudio/* = /icons/sound2.giftext/html = /icons/generic.giftext/* = /icons/text.gifapplication/x-tar = /icons/tar.gifapplication/* = /icons/binary.gif

Note: The keys (left-hand side) of these stanza entries specify a MIME type, or acollection of MIME types. The asterisk (*) character is a wildcard only forthe MIME-type directory specified. For more information on configuringMIME types, see Appendix A, “WebSEAL configuration file reference”, onpage 241

You can configure this list to specify other icons for each MIME type. Icons canalso be located remotely. For example:application/* = http://www.acme.com/icons/binary.gif


You can also configure these additional icon values:v Icon used to represent sub-directories:

[icons]diricon = /icons/folder2.gif

v Icon used to represent the parent directory:[icons]backicon = /icons/back.gif

v Icon used to represent unknown file types:[icons]unknownicon = /icons/unknown.gif

Note: The supplied icons are in GIF format, but this format is not required. .

Windows: File naming for CGI programsParameters contained in the [cgi-types] stanza of the webseald.conf configurationfile allow you to specify the Windows file extension types that are recognized andexecuted as CGI programs.

The UNIX operating system has no file name extension requirements. Fileextension types must be defined, however, for Windows operating systems. The[cgi-types] stanza lists all valid extension types and maps each extension (whennecessary) to an appropriate CGI program.[cgi-types]<extension> = <cgi-program:>

By default only those files with extensions matching those listed in the stanza willbe executed as CGI programs. If a CGI program has an extension that is notcontained in this list, the program will not be executed.

Files with the .exe extensions are run as programs by Windows default andrequire no mapping.

Note: Anytime you want to install a .exe file on Windows for download, however,you must rename the extension or install the file as part of an archive (suchas .zip).

You must supply the appropriate interpreter programs for extensions that representinterpreted script files. Examples of these types of extensions include: shell scripts(.sh and .ksh), Perl scripts (.pl), and Tcl scripts (.tcl) files.

The following example illustrates a typical [cgi-types] stanza configuration:[cgi-types]bat = cmdcmd = cmdpl = perlsh = shtcl = tclsh76

Executable UNIX files on the WebSEAL server host systemWebSEAL supports the creation of local junctions. These junctions exist on thesame host system as the WebSEAL server.

When accessing a local junction on a UNIX system, WebSEAL interprets files asCGI scripts if the files are given the UNIX execute permission. For example, if an


HTML page located on the local WebSEAL junction is given execute permission,WebSEAL interprets the file as an executable, and will not display it.

To ensure that local files are displayed correctly, remove execute permission fromall non-CGI files that are accessed through the local junction.

Configuring Web document cachingClients can often experience extended network access time and file downloadingtime due to poor Web document retrieval performance. Poor performance canoccur because the WebSEAL server is waiting for documents retrieved fromjunctioned back-end servers or even slow local storage.

Web document caching gives you the flexibility of serving documents locally fromWebSEAL rather than from a back-end server across a junction. The Web documentcaching feature allows you to store commonly accessed Web document types in theWebSEAL server’s memory. Clients can experience much faster response tofollow-up requests for documents that have been cached in the WebSEAL server.

Cached documents can include static text documents and graphic images.Dynamically generated documents, such as database query results, cannot becached.

Caching is performed on the basis of MIME type. When you configure WebSEALfor Web document caching, you identify the following three parameters:v Document MIME typev Type of storage mediumv Size of storage medium

You define Web document caching in the [content-cache] stanza of thewebseald.conf configuration file. The following syntax applies:<mime-type> = <cache-type>:<cache-size>

Parameter Description

mime-type Represents any valid MIME type conveyed in an HTTP″Content-Type:″ response header. This value may contain a asterisk ( *). A value of */* represents a default object cache that will hold anyobject that does not correspond to an explicitly configured cache.Note that the asterisk here is a wildcard only for a MIME-typedirectory, and its contents. This is not a wildcard for regularexpression matching.

cache-type Specifies the type of storage medium to use for the cache. This releaseof Tivoli Access Manager supports only ″memory″ caches.

cache-size Specifies the maximum size (in kilobytes) to which the given cachecan grow before objects are removed according to a ″Least RecentlyUsed″ algorithm.

Example:text/html = memory:2000image/* = memory:5000*/* = memory:1000

Conditions affecting Web document cachingThe Web document caching mechanism observes the following conditions:v Caching occurs only when a cache is defined in webseald.conf.


v By default, no caches are defined at installation.v If you do not specify a default cache, documents that do not match any explicit

cache are not cached.v Authorization is still performed on all requests for cached information.v The caching mechanism does not cache responses to requests containing query

strings.v The caching mechanism does not cache responses to requests over junctions

configured with the –c and –C options.

Flushing all cachesYou can use the pdadmin utility to flush all configured caches. The utility does notallow you to flush individual caches.

You must login to the secure domain as the Tivoli Access Manager administratorsec_master before you can use pdadmin.

To flush all Web document caches, enter the following command:

UNIX:# pdadmin server task webseald-<machine-name> cache flush all

Windows:MSDOS> pdadmin server task webseald-<machine-name> cache flush all

Controlling caching for specific documentsYou can control caching for specific documents by attaching a special ProtectedObject Policy (POP) to those objects. This POP must contain an extended attributecalled document-cache-control.

The document-cache-control extended attribute recognizes the following twovalues:

Value Description

no-cache The no-cache value instructs WebSEAL not to cache this document.Remember that all children of the object with the POP also inherit thePOP conditions.

public The public value allows WebSEAL to cache the document by ignoringthe fact that the junction was created with a –c or –C option. Inaddition, this value also allows caching of this document when therequest is sent with an authorization header (such as BasicAuthentication). This condition also includes a request whereWebSEAL inserts BA information on behalf of the client (such as withGSO or –b supply junctions). Normally, proxy servers do not cache theresponse documents to requests that include authorization headers.

Use the pdadmin pop create, pdadmin pop modify, and pdadmin pop attachcommands. The following example illustrates creating a POP called ″doc-cache″with the document-cache-control extended attribute and attaching it to an object(budget.html):pdadmin> pop create doc-cachepdadmin> pop modify doc-cache set attribute document-cache-control no-cachepdadmin> pop attach /WebSEAL/hostA/junction/budget.html doc-cache

The budget.html document is never cached by WebSEAL. Each request for thisdocument must be made directly to the back-end server where it is located.


Details about the pdadmin command line utility can be found in the IBM TivoliAccess Manager Base Administrator’s Guide.

Specifying document MIME types for URL filteringTo ensure proper performance of links across WebSEAL junctions, WebSEAL canapply specific URL filtering rules to document responses from back-end junctionedservers. You must first specify the document MIME types that WebSEAL canrecognize.

The type parameter in the [filter-content-types] stanza of the webseald.confconfiguration file specifies a MIME type value. WebSEAL is configured by defaultto recognize documents of two MIME types:[filter-content-types]type = text/htmltype = text/vnd.wap.wml

WebSEAL can apply the following URL filtering functionality to all configureddocument types:v URL scheme filtering

WebSEAL filters only URLs using schemes defined in the [filter-schemes] stanzaof webseald.conf

v URL attribute filteringSee “Standard URL filtering rules for WebSEAL” on page 180.

v Script filtering for absolute URLsSee “Modifying absolute URLs with script filtering” on page 181.

Managing custom HTTP error message pagesSometimes the WebSEAL server attempts to service a request and fails. There canbe many causes of this failure. For example:v A file does not existv Permission settings forbid accessv CGI programs cannot be executed because of incorrect UNIX file permissions or

something similar

When a failure to service a request occurs, the server returns an error message tothe browser, such as ″403 Forbidden″, in an HTML error page. There are severalerror messages available; each message is stored in a separate HTML file.

These files are stored in the following directory:

UNIX:<install-path>/www/lib/errors/<locale-dir>

Windows:<install-path>\www\lib\errors\<locale-dir>

The errors directory contains a number of locale subdirectories containinglocalized versions of the error message files.

For example, the directory path for US/English messages is:

UNIX:


<install-path>/www/lib/errors/en_US

Windows:<install-path>\www\lib\errors\en_US

See “Multi-locale support for Web services” on page 36 for further information onmulti-locale support.

The messages in this directory are in HTML format so that they appear correctly ina browser. You can edit these HTML pages to customize their contents. The namesof the files are the hexadecimal values of the internal error codes that are returnedwhen the operations fail. These file names should not be changed.

The following table contains a list of the file names and contents for some of themore common error messages:

Filename Title DescriptionHTTP Error

Code

132120c8.html Authentication Failed Credentials could not be retrieved for the clientcertificate used. Possible reasons include:

v the user supplied an incorrect certificate

v the certificate has been revoked

v the user’s credentials are missing from theauthentication database

38ad52fa.html Non-Empty Directory The requested operation requires the removal of anon-empty directory. This is an illegal operation.

38cf013d.html Request Caching Failed The request-max-cache or request-body-max-readvalues have been exceeded.

38cf0259.html Could Not Sign User On The resource requested requires the WebSEALserver to sign user on to another Web server.However, a problem occurred while WebSEAL wasattempting to retrieve the information.

38cf025a.html User Has No Single Sign-onInformation

WebSEAL could not locate the GSO user for therequested resource.

38cf025b.html No Single Sign-on Target forUser

WebSEAL could not locate the GSO target for therequested resource.

38cf025c.html Multiple Sign-on Targets forUser

Multiple GSO targets are defined for the requestedresource. This is a mis-configuration.

38cf025d.html Login Required The resource requested is protected by ajunctioned back-end Web server, requiringWebSEAL to sign user on to that Web server. Inorder to do this, user must first log into WebSEAL.

38cf025e.html Could Not Sign User On The resource requested requires WebSEAL to signuser on to another Web server. However, thesign-on information for the user account isincorrect.

38cf025f.html Unexpected AuthenticationChallenge

WebSEAL received an unexpected authenticationchallenge from a junctioned back-end Web server.

38cf0421.html Moved Temporarily The requested resource has been temporarilymoved. This usually occurs if there has been amishandled redirect.

302

38cf0424.html Bad Request WebSEAL received an invalid HTTP request. 400


Filename Title DescriptionHTTP Error

Code

38cf0425.html Login Required The resource you have requested is secured byWebSEAL, and in order to access it, you must firstlogin.

38cf0427.html Forbidden User does not have permissions to accessrequested resource.

403

38cf0428.html Not Found Requested resource cannot be located. 404

38cf0432.html Service Unavailable A service required by WebSEAL to completerequest is currently not available.

503

38cf0437.html Server Suspended The WebSEAL server has been temporarilysuspended by the System Administrator. Norequests will be handled until the server isreturned to service by the Administrator.

38cf0439.html Session Information Lost The browser/server interaction was a statefulsession with a junctioned back-end server that isno longer responding. WebSEAL requires a servicelocated on this server to complete your request.

38cf0442.html Service Unavailable The service required by WebSEAL is located on ajunctioned back-end server where SSL mutualauthentication has failed.

38cf07aa.html CGI Program Failed A CGI program failed to execute properly.

default.html Server Error WebSEAL could not complete your request due toan unexpected error.

500

deletesuccess.html Success Client-initiated DELETE request completedsuccessfully.

200

putsuccess.html Success Client-initiated PUT operation completedsuccessfully.

200

relocated.html Temporarily Moved The requested resource has temporarily moved. 302

websealerror.html 400 WebSEAL Server Error WebSEAL server internal error. 400

Macro support for HTTP error message pagesThe following macros are available for use in customizing the HTML error pageslisted in the previous section. Macros dynamically substitute appropriateinformation that is available.

Macro Description

%ERROR_CODE% The numeric value of the error code.

%ERROR_TEXT% The text associated with an error code in the message catalog.

%METHOD% The HTTP method requested by the client.

%URL% The URL requested by the client.

%HOSTNAME% Fully qualified host name.

%HTTP_BASE% Base HTTP URL of the server ″http://<host>:<tcpport>/″.

%HTTPS_BASE% Base HTTPS URL of the server, ″https://<host>:<sslport>/″.

%REFERER% The value of the referer header from the request, or″Unknown″, if none.

%BACK_URL% The value of the referer header from the request, or ″/″ if none.


Macro Description

%BACK_NAME% The value ″BACK″ if a referer header is present in the request,or ″HOME″ if none.

Managing custom account management pagesTivoli Access Manager includes sample account management HTML pages that canbe customized to contain site-specific messages or perform site-specific actions.Most forms are appropriate for Forms, token, and BA authentication over HTTP orHTTPS.

The file locations for these forms are defined by the mgt-pages-root parameter inthe [acnt-mgt] stanza of the webseald.conf configuration file.mgt-pages-root = lib/html/<lang-dir>

The actual directory used is based on localization. The default United StatesEnglish directory is:lib/html/C

The Japanese locale files are in:lib/html/JP

See “Multi-locale support for Web services” on page 36 for further information onmulti-locale support.

Custom page parameters and valuesThe following special HTML page parameters and values are located in the[acnt-mgt] stanza of the webseald.conf configuration file. Some pages are usedonly by the Forms login method of providing identity information.

Parameter Page Usage

login = login.html Forms login

login-success = login_success.html Forms login

logout = logout.html Forms login

account-locked = acct_locked.html Any method

passwd-expired = passwd_exp.html Any method

passwd-change = passwd.html Any method

passwd-change-success = passwd_rep.html Any method

passwd-change-failure = passwd.html Any method

help = help.html Any method

token-login = tokenlogin.html Token login

next-token = nexttoken.html Token login

stepup-login = stepuplogin.html Step-up authentication

switch-user = switchuser.html Any method

cert-failure = certfailure.html Certificate login


Custom HTML page descriptions

Form Description

login.html Standard request form for username and password

login_success.html Page displayed after successful login.

logout.html Page displayed after successful logout.

acct_locked.html Page displayed if user authentication failed due to a lockedaccount.

passwd_exp.html Page displayed if user authentication failed due to anexpired password.

passwd.html Change password form. Also displayed if passwordchange request failed.

passwd_rep.html Page displayed if password change request was successful.

help.html Page containing links to valid administration pages.

tokenlogin.html Token login form.

nexttoken.html Next token form.

stepuplogin.html Step-up authentication login form.

switchuser.html Switch user management form.

certfailure.html Page displayed if client fails to authenticate with acertificate when accept-client-certs = required.

Macro support for account management pagesThe following macros are available for use in customizing the HTML pages listedin the previous section. These macro strings can be placed in the template files.Macros dynamically substitute appropriate information that is available.

Macro Description

%USERNAME% The name of the logged in user.

(See also “Customizing login forms for reauthentication” onpage 140.)

%ERROR% The hard-coded error message returned from Tivoli AccessManager.

%METHOD% The HTTP method requested by the client.

%URL% The URL requested by the client.

%HOSTNAME% Fully qualified host name.

%HTTP_BASE% Base HTTP URL of the server ″http://<host>:<tcpport>/″.

%HTTPS_BASE% Base HTTPS URL of the server, ″https://<host>:<sslport>/″.

%REFERER% The value of the referer header from the request, or″Unknown″, if none.

%BACK_URL% The value of the referer header from the request, or ″/″ ifnone.

%BACK_NAME% The value ″BACK″ if a referer header is present in therequest, or ″HOME″ if none.


Multi-locale support for Web servicesTivoli Access Manager WebSEAL provides multi-locale support for Web services.Standard WebSEAL server responses to client browsers, such as error messages,custom HTML login and logout pages, and serviceability messages, can bedelivered in the client’s preferred language.

WebSEAL supports multi-locale capabilities by using the values contained in theaccept-language HTTP header to determine the correct language forserver-generated messages and HTML pages. Translated information is availablefor the following server resources:v HTTP error messages

<install-path>/www/lib/errors/<locale-directory>

v Custom account management pages<install-path>/www/lib/html/<locale-directory>

v Serviceability messages

Browsers adopt a standard set of language values. Basic language values arerepresented by two characters, indicating the language. Location-specific values areexpressed in a two part format, indicating the language and the country where thisversion of the language is used. Examples include:v es (Spanish)v de (German)v en (English)v it (Italian)v en-US (English/United States)v en-GR (English/United Kingdom)v es-ES (Spanish/Spain)v es-MX (Spanish/Mexico)v pt-BR (Portuguese/Brazil)

The accept-language header can include more than one language. Each additionallanguage is separated by a comma. For example:accept-language: es-mx,es,en

The order in which the values appear in the header determine the hierarchy ofimportance. WebSEAL checks the first listed value for an existing installedlanguage pack. If no language pack for this language is installed, WebSEAL checksthe next language in the list for its associated language pack.

Note: The accept-language header can use a ″q=x.x″ parameter to express apreference level for a language. This parameter is not recognized byWebSEAL. The listed order of languages in the header determines the orderof priority for WebSEAL.

Several language packs for WebSEAL server messages are available for installation.Each language pack installation creates a locale-specific sub-directory within thepath for each message storage location. For example, a Spanish language packcreates the following sub-directory for the server error message storage location:<install-path>/www/lib/errors/es


The following table lists the languages supported by WebSEAL, with the associatedsub-directory name:

Language System Directory

English (default) C

Czech cs

German de

Spanish es

French fr

Hungarian hu

Italian it

Japanese ja

Korean ko

Polish pl

Portuguese, Brazil pt_BR

Russian ru

Chinese, China zh_CN

Chinese, Taiwan zh_TW

The following example process flow illustrates how WebSEAL evaluates theaccept-language header:1. The accept-language header contains pt-br as the first value in the list.2. The pt-br language is converted to pt_BR, representing the WebSEAL language

sub-directory for this language.3. If this sub-directory does not exist for the required message (for example, no

language pack is installed for this language), WebSEAL checks for a ptdirectory.

4. If no pt directory exists, WebSEAL attempts to find message sub-directories forthe next language listed in the header.

5. If there are no installed language packs for all messages listed in the header,WebSEAL defaults to the language environment which WebSEAL is running in,as determined by the LC_ALL or LANG environment variables set on theoperating system.

Conditions affecting multi-locale support on WebSEAL:

v Multi-locale support is enabled at all times on the WebSEAL server.v Installation of specific language packs determines what languages are supported.v WebSEAL always returns the UTF-8 character set to the user, regardless of what

the accept-charset HTTP header value requests.v If WebSEAL accesses a locale directory for a translated message, and the

directory is empty (for example, the contents were removed by theadministrator), a server error page is returned.


Managing client-side and server-side certificatesThis section describes the administration and configuration tasks required to set upWebSEAL to handle client-side and server-side digital certificates used forauthentication over SSL.

WebSEAL requires certificates for the following situations:v WebSEAL identifies itself to SSL clients with its server-side certificatev WebSEAL identifies itself to a junctioned back-end server (configured for mutual

authentication) with a client-side certificatev WebSEAL refers to its database of Certificate Authority (CA) root certificates to

validate clients accessing with client-side certificatesv WebSEAL refers to its database of Certificate Authority (CA) root certificates to

validate junctioned back-end servers configured for mutual authentication

WebSEAL uses the IBM Global Security Kit (GSKit) implementation of SSL toconfigure and administer digital certificates. GSKit provides the iKeyman utility toset up and manage the certificate key database that contains one or moreWebSEAL server/client certificates and the CA root certificates.

WebSEAL includes the following components at installation to support SSLauthentication using digital certificates:v A default key database (pdsrv.kdb)v A default key database stash file (pdsrv.sth) and password (″pdsrv″)v Several common CA root certificatesv A self-signed test certificate that WebSEAL can use to identify itself to SSL

clientsIt is recommended that you apply for a commonly recognized certificate from aknown Certificate Authority to replace this test certificate.

Configuration for WebSEAL certificate handling includes:v “Configuring key database parameters” on page 39v “Using the iKeyman certificate management utility” on page 40v “Configuring CRL checking” on page 41

GSKit key database file typesThe IBM Key Management tool (iKeyman) uses several file types that aresummarized in the following table.

A CMS key database consists of a file with the extension .kdb and possibly two ormore other files. The .kdb file is created when you create a new key database. Akey record in a .kdb file can be either a certificate or a certificate with itsencrypted private key information.

The .rdb and .crl files are created when you create a new certificate request.The .rdb file is required throughout the CA certificate request process.

File Type Description

.kdb The ″key database″ file. Stores personal certificates, personal certificate requests, and signercertificates. For example, the default WebSEAL key database file is pdsrv.kdb.

.sth The ″stash″ file. Stores an obfuscated version of the key database password. The stem name of thisfile is the same as the associated .kdb file. Also stores private keys, if there are any.


File Type Description

.rdb The ″request″ database file. Automatically created when you create a .kdb key database file. Thestem name of this file is the same as the associated .kdb file. This file contains certificate requeststhat are outstanding and have not yet been received back from the CA. When a certificate isreturned from the CA, the .rdb file is searched for the matching certificate request (based on thepublic key). If a match is found, the certificate is received and the corresponding certificate requestis deleted from the .rdb file. If a match is not found, the attempt to receive the certificate isrejected. Included in the certificate request is the common name, organization, street address, andother information that was specified at the time of the request, as well as the public and privatekey associated with the request.

.crl The ″certificate revocation list″ file. This file normally contains the list of certificates that have beenrevoked for one reason or another. However, iKeyman does not provide any support for certificaterevocation lists, so it is empty.

.arm An ASCII encoded binary file. A .arm file contains a base-64 encoded ASCII representation of acertificate, including its public key, but not its private key. The original binary certificate data istransformed into an ASCII representation. When a user receives a certificate in a .arm file, iKeymandecodes the ASCII representation and places the binary representation into the appropriate .kdbfile. Similarly, when a user extracts a certificate from a .kdb file, iKeyman converts the data frombinary to ASCII and places it in a .arm file. Note: Any file extension is acceptable to use (other than.arm), as long as the file itself is a Base64 encoded file.

.der The ″Distinguished Encoding Rules″ file. A .der file contains a binary representation of a certificate,including its public key, but not its private key. It is very similar to a .arm file, except that therepresentation is binary, not ASCII.

.p12 The ″PKCS 12″ file, where PKCS stands for ″Public-Key Cryptography Standards″. A .p12 filecontains a binary representation of a certificate, including both its public and private keys. A .p12file may also include more than one certificate; for example, a certificate chain. Because a .p12 filecontains a private key, it is password protected.

Configuring key database parametersWebSEAL Key Database File:

At installation, WebSEAL provides a default certificate key database. Thewebseal-cert-keyfile parameter, located in the [ssl] stanza of the webseald.confconfiguration file, identifies the name and location of this file:[ssl]webseal-cert-keyfile = /var/pdweb/www/certs/pdsrv.kdb

You can use the iKeyman utility to create a new key database. However, you mustenter the name and location of this new key file in the webseal-cert-keyfileparameter so that WebSEAL can find and use the certificates contained in thatdatabase.

Key Database File Password:

At installation, WebSEAL also provides a default stash file that contains thepassword for the pdsrv.kdb key file. The webseal-cert-keyfile-stash parameterinforms WebSEAL of the location of the stash file:webseal-cert-keyfile-stash = /var/pdweb/www/certs/pdsrv.sth

The default password encrypted in this stash file is ″pdsrv″. You can also express apassword as plain text in the webseal-cert-keyfile-pwd parameter. For example:webseal-cert-keyfile-pwd = pdsrv


At installation, WebSEAL uses the stash file to obtain the key file password. Thewebseal-cert-keyfile-pwd is commented out. By using the stash file you can avoiddisplaying the password as text in the webseald.conf configuration file.

Note: Uncomment the specific password parameter you want to use. If bothpassword and stash file are specified, the password value is used.

WebSEAL Test Certificate:

At installation, WebSEAL provides a non-secure self-signed test certificate. The testcertificate, acting as a server-side certificate, allows WebSEAL to identify itself toSSL clients.

To better control how this test certificate is used, the certificate is not installed as adefault certificate. Instead, the webseal-cert-keyfile-label parameter designates thecertificate as the active server-side certificate and overrides any other certificatedesignated as ″default″ in the keyfile database.webseal-cert-keyfile-label = WebSEAL-Test-Only

Note: WebSEAL uses GSKit certificate handling functionality. GSKit allows butdoes not require that a certificate in keyfile databases be designated thedefault certificate. For more information on certificate handling, see theGSKit document: Secure Socket Layer and iKeyman User’s Guide.

Although this test certificate allows WebSEAL to respond to an SSL-enabledbrowser request, it cannot be verified by the browser (which does not contain anappropriate root CA certificate). Because the private key for this default certificateis contained in every WebSEAL distribution, this certificate offers no true securecommunication.

You must use the iKeyman utility to generate a certificate request that can be sentto a Certificate Authority (CA). Use iKeyman to install and label the returnedserver certificate.

If you use different certificates for other scenarios (such as –K junctions), you canuse the iKeyman utility to create, install, and label these certificates. The keyfilelabel must not contain spaces.

WebSEAL (which by default runs as user ivmgr) must have read (r) permission onthese key database files.

Parameters for Inter-Tivoli Access Manager Server SSL Communication:

The [ssl] stanza of the webseald.conf configuration file contains four additionalparameters used to configure the keyfile used by WebSEAL for internal SSLcommunication with other Tivoli Access Manager servers. You should only modifythese parameters through the pdconfig configuration script.[ssl]ssl-keyfile =ssl-keyfile-pwd =ssl-keyfile-stash =ssl-keyfile-label =

Using the iKeyman certificate management utilityThe iKeyman utility is a tool provided with GSKit that you can use to managedigital certificates used by WebSEAL. Use iKeyman to:


v Create one or more key databasesv Change key database passwordsv Create new WebSEAL certificatesv Set a new default WebSEAL certificatev Create a self-signed certificate for testingv Request and receive CA root certificatesv Add certificates to and delete certificates from the databasev Copy certificates from one database to another

Refer to the Secure Sockets Layer Introduction and iKeyman User’s Guide for detailedinformation on using the iKeyman utility.

Configuring CRL checkingThe Certificate Revocation List (CRL) is a method of preventing the validation ofunwanted certificates. The CRL contains the identities of certificates that aredeemed untrustworthy. The GSKit implementation of SSL used by WebSEALsupports CRL checking. GSKit allows WebSEAL to perform CRL checking onclient-side certificates and certificates from SSL junctions.

WebSEAL must know the location of this list in order to perform CRL checking.Parameters for the location of the LDAP server that can be referenced for CRLchecking during client-side certificate authentication are found in the [ssl] stanza ofthe webseald.conf configuration file:[ssl]#crl-ldap-server = <server-name>#crl-ldap-server-port = <port-id>#crl-ldap-user = <webseal-admin-name>#crl-ldap-user-password = <admin-password>

Parameters for the location of the LDAP server that can be referenced for CRLchecking during authentication across SSL junctions are found in the [junction]stanza of the webseald.conf configuration file:[junction]#crl-ldap-server = <server-name>#crl-ldap-server-port = <port-id>#crl-ldap-user = <webseal-admin-name>#crl-ldap-user-password = <admin-password>

By default, CRL checking is disabled (parameters are commented out). To enableCRL checking during certificate authentication, uncomment each parameter andenter the appropriate values.

A null value for the crl-ldap-user indicates that the SSL authentication mechanismshould bind to the LDAP server as an anonymous user.

Note: For information on GSKit support of Certificate Revocation Lists, see SecureSockets Layer Introduction and iKeyman User’s Guide.

Configuring the CRL cacheGSKit allows WebSEAL to perform CRL checking on client-side certificates andcertificates from SSL junctions. To improve CRL checking performance, you cancache the CRL from a particular Certificate Authority (CA). Subsequent CRL checksare made against this cached version of the list.


The settings for the two webseald.conf configuration file parameters discussed inthis section are passed directly to the GSKit utility. For further information aboutGSKit functionality, refer to the GSKit documentation.

Setting the maximum number of cache entriesThe gsk-crl-cache-size parameter specifies the maximum number of entries in theGSKit CRL cache. Each entry represents an entire CRL for a particular CertificateAuthority. The default setting is ″0″. A value greater than ″0″ is required to activatethe cache. When gsk-crl-cache-size and gsk-crl-cache-entry-lifetime are both set to″0″ (default), CRL caching is disabled.[ssl]gsk-crl-cache-size = 0

Setting the GSKit cache lifetime timeout valueThe gsk-crl-cache-entry-lifetime parameter specifies the lifetime timeout value forall entries in the GSKit CRL cache. The value is expressed in seconds and can havea range of 0-86400 seconds. When gsk-crl-cache-size and gsk-crl-cache-entry-lifetime are both set to ″0″ (default), CRL caching is disabled.[ssl]gsk-crl-cache-size = 0

Configuring default HTTP loggingWebSEAL maintains three conventional HTTP log files that record activity ratherthan messages:v request.log

v agent.log

v referer.log

By default, these log files are located under the following directory:

UNIX:/var/pdweb/www/log/

Windows:C:\Program Files\Tivoli\PDWeb\www\log\

Parameters for configuring standard HTTP logging are located in the [logging]stanza of the webseald.conf configuration file.

The following table illustrates the relationship between the HTTP log files and theconfiguration file parameters:

Log FilesLocation

ParameterEnable/Disable Parameter

( = yes or no)

request.log requests-file requests

referer.log referers-file referers

agent.log agents-file agents

For example, the entry for the default location of the request.log file appears asfollows:

UNIX:requests-file = /var/pdweb/www/log/request.log


Windows:requests-file = \Program Files\Tivoli\PDWeb\www\log\request.log

Enabling and disabling HTTP loggingBy default, all HTTP logging is enabled:[logging]requests = yesreferers = yesagents = yes

Each log can be enabled or disabled independently from the others. If anyparameter is set to ″no″, logging is disabled for that file.

After it is enabled as described above, default WebSEAL HTTP logging is actuallyhandled by the Tivoli Access Manager event logging mechanism, as described in“Configuring HTTP logging using event logging” on page 45.

Specifying the timestamp typeYou can choose to have the timestamps in each log recorded in Greenwich MeanTime (GMT) instead of the local time zone. By default, the local time zone is used:[logging]gmt-time = no

To use GMT timestamps, set:gmt-time = yes

Specifying log file rollover thresholdsThe max-size parameter specifies the maximum size to which each of the HTTPlog files may grow and has the following default value (in bytes):[logging]max-size = 2000000

When a log file reaches the specified value — known as its rollover threshold —the existing file is backed up to a file of the same name with an appended currentdate and timestamp. A new log file is then started.

The various possible max-size values are interpreted as follows:v If the max-size value is less than zero (< 0), then a new log file is created with

each invocation of the logging process and every 24 hours from that instance.v If the max-size value is equal to zero (= 0), then no rollovers are performed and

the log file grows indefinitely. If a log file already exists, new data is appendedto it.

v If the max-size value is greater than zero (> 0), then a rollover is performedwhen a log file reaches the configured threshold value. If a log file already existsat startup, new data is appended to it.

Specifying the frequency for flushing log file buffersLog files are written to buffered data streams. If you are monitoring the log files inreal time, you might want to alter the frequency with which the server forces aflush of the log file buffers.

By default, log files are flushed every 20 seconds:


[logging]flush-time = 20

If you specify a negative value, a flush will be forced after every record is written.

HTTP common log format (for request.log)Every response (success or failure) sent back by the Tivoli Access Manager serveris recorded with a one-line entry in the request.log file using following HTTPCommon Log Format:host - authuser [date] request status bytes

where:

host Specifies the IP address of the requesting machine.

authuser This field contains the identity information of the user. The value″unauth″ is used for an unauthenticated user.

date Specifies the date and time of the request.

request Specifies the first line of the request as it came from the client.

status Specifies the HTTP status code sent back to the requestingmachine.

bytes Specifies the number of bytes sent back to the requesting machine.This value—either the unfiltered content size or a zero size—isconfigured with the log-filtered-pages parameter.

Displaying the request.log fileThe request.log records standard logging of HTTP requests, such as informationon URLs that have been requested and information on the client (for example, IPaddress) that made the request.

The following example shows a sample version of a request.log file:130.15.1.90 - - [26/Jan/2002:17:23:33 -0800] "GET /~am/a_html/ HTTP/1.0" 403 77130.15.1.90 - - [26/Jan/2002:17:23:47 -0800] "GET /icons HTTP/1.0" 302 93130.15.1.90 - - [26/Jan/2002:17:23:59 -0800] "GET /icons/ HTTP/1.0" 403 77130.15.1.90 - - [26/Jan/2002:17:24:04 -0800] "GET /~am/a_html/ HTTP/1.0" 403 77130.15.1.90 - - [26/Jan/2002:17:24:11 -0800] "GET /~am/ HTTP/1.0" 403 77

Displaying the agent.log fileThe agent.log file records the contents of the User_Agent: header in the HTTPrequest. This log reveals information about the client browser, such as architectureor version number, for each request.

The following example shows a sample version of a agent.log file:Mozilla/4.01 [en] (WinNT; U)Mozilla/4.01 [en] (WinNT; U)Mozilla/4.01 [en] (WinNT; U)Mozilla/4.01 [en] (WinNT; U)

Displaying referer.logThe referer.log records the Referer: header of the HTTP request. For eachrequest, the log records the document that contained the link to the requesteddocument.

The log uses the following format:


referer -> object

This information is useful for tracking external links to documents in your Webspace. The log reveals that the source indicated by referer contains a link to a pageobject. This log allows you to track stale links and to find out who is creating linksto your documents.

The following example shows a sample version of a referer.log file:http://manuel/maybam/index.html -> /pics/tivoli_logo.gifhttp://manuel/maybam/pddl/index.html -> /pics/tivoli_logo.gifhttp://manuel/maybam/ -> /pddl/index.htmlhttp://manuel/maybam/ -> /pddl/index.htmlhttp://manuel/maybam/pddl/index.html -> /pics/tivoli_logo.gifhttp://manuel/maybam/ -> /pddl/index.html

Configuring HTTP logging using event loggingWebSEAL HTTP logging can be configured in the [aznapi-configuration] stanza ofthe webseald.conf configuration file. Use the logcfg event logging parameter todefine one or more log agents (loggers) that gather a specific category of loginformation from the event pool and direct this information to a destination:[aznapi-configuration]logcfg = <category>:{stdout|stderr|file|pipe|remote} [[<param>[=<value>]][,<param>[=<value>]]...]

Refer to the ″Using event logging″ section of the IBM Tivoli Access Manager BaseAdministrator’s Guide for complete event logging configuration details.

The values for category that are appropriate for HTTP logging include:v http

All HTTP logging informationv http.clf

HTTP request information in common log formatv http.ref

HTTP Referer header informationv http.agent

HTTP User_Agent header informationv http.cof

The NCSA combined format captures HTTP request information (with timestamp) and appends the quoted referer and agent strings to the standardcommon log format.

The following log agent configurations are enabled when the default WebSEALHTTP logging parameters are enabled (see “Configuring default HTTP logging” onpage 42). Note that the log agent configurations accept the values of therequests-file, referers-file, agents-file, flush-time, and max-size parameters fromthe webseald.conf [logging] stanza:

request.log (common log format):logcfg = http.clf:file path=<requests-file>,flush=<flush-time>, \rollover=<max-size>,log=clf,buffer_size=8192,queue_size=48

referer.log:


logcfg = http.ref:file path=<referers-file>,flush=<flush-time>, \rollover=<max-size>,log=ref,buffer_size=8192,queue_size=48

agent.log (common log format):logcfg = http.agent:file path=<agents-file>,flush=<flush-time>, \rollover=<max-size>,log=agent,buffer_size=8192,queue_size=48

Because default HTTP logging is configured in a different stanza ([logging]) thanevent logging configuration ([aznapi-configuration]), it is possible to have twoduplicate entries for each event appear in a log file when both logging mechanismsare enabled.

The event logging mechanism provides you with much more flexibility ingathering HTTP log information and in customizing its output.

Logging WebSEAL serviceability messagesTivoli Access Manager WebSEAL serviceability messages are controlled by theTivoli Access Manager WebSEAL routing file. The routing file is located in thefollowing directory:

UNIX:/opt/pdweb/etc/

Windows:C:\Program Files\Tivoli\PDWeb\etc\

The routing file is an ASCII file that contains additional documentation in theform of comment lines. Entries in this configuration file determine the types ofserviceability messages that are logged. Enable any entry by removing thecomment character (#). The routing file includes the following default entries:

UNIX:FATAL:STDERR:-ERROR:STDERR:-WARNING:STDERR:-#NOTICE:FILE.10.100:/opt/pdweb/log/notice.log#NOTICE_VERBOSE:FILE.10.100:/opt/pdweb/log/notice.log

Windows:FATAL:STDERR:-ERROR:STDERR:-WARNING:STDERR:-#NOTICE:FILE.10.100:%PDWEBDIR%/log/notice.log#NOTICE_VERBOSE:FILE.10.100:%PDWEBDIR%/log/notice.log

Note: On a Windows system, the special environment variable PDWEBDIR is setat run time to the WebSEAL installation directory.

By default, when WebSEAL runs in the foreground, all messages are sent to thescreen (STDERR).

By default, when WebSEAL runs in the background, messages are redirected fromSTDERR and sent to the WebSEAL server log file as defined in the [logging] stanzaof the webseald.conf configuration file:


ServerConfigurationFile Log File Location

WebSEALServer(webseald)

webseald.conf UNIX:[logging]server-log=/var/pdweb/log/msg_webseald.logWindows:[logging]server-log=C:\Program Files\Tivoli\PDWeb\log\msg_webseald.log

To enable verbose.log, uncomment the NOTICE_VERBOSE line.

The FILE syntax for the NOTICE message controls log roll over and file recycling:FILE.<max-files>.<max-records>

The max-file value specifies the number of files that are used.

The max-records value specifies the maximum number of entries per file.

In the default example above, FILE.10.100 means there are 10 files created, eachwith a maximum of 100 entries. The files are named:notice.log.1notice.log.2...notice.log.10

The messages ″wrap around″ to the first file after the last file has reached its limitor when the server is stopped and restarted. When a log file is reused, the existingrecords are written over (erased).

WebSEAL audit trail filesAuditing is defined as the collection of data about system activities that affect thesecure operation of the Tivoli Access Manager authorization process. Each TivoliAccess Manager server (such as WebSEAL) can capture audit events whenever anysecurity-related auditable activity occurs.

Audit events are saved as audit records that document the specific activity of thatserver. Each audited activity is referred to as an audit event. A collection of auditevent records stored in a file is referred to as an audit trail.

Configuring audit trail filesTivoli Access Manager provides two methods to enable and configure auditing.Both methods involve specifying values for keys in the [aznapi-configuration]stanza of the webseald.conf configuration file. The two methods are:v Configuration of event logging

Event logging is configured by supplying a series of values to the logcfg key.Use of this method is recommended because it configures Tivoli Access Managerevent logging. Event logging provides a structured hierarchy for gathering allmessages for auditing and other serviceability purposes. The event loggingfeature also supports the use of alternate destinations for logging output, such asconsoles (stdout), pipes, and remote servers.

v Configuration of legacy auditing


Legacy auditing is configured by supplying a value for each the following keys:[aznapi-configuration]logauditauditlogauditcfglogsizelogflush

Use of this method is comparable to the event logging method, when directingoutput to a file. Note, however, that the event logging method providesadditional control over buffer size and event queues. Also, legacy auditing doesnot support output to consoles, pipes, or remote servers.

When configuring auditing for an event type, choose either event logging or legacyauditing.

Configuration tasksThe following configuration tasks are required for each WebSEAL audit trail file:1. Enable auditing

Enable the creation of audit records.2. Specify type of audit event.

Supported types of audit events for WebSEAL:v Authorizationv Credential acquisition authenticationv HTTP requests

3. Specify audit file locationLocation on the filesystem for the audit records.

4. Specify audit file sizeMaximum size of an audit trail file. When the maximum size is reached, the fileis backed up and a new file is started.

5. Specify file flush intervalFrequency with which the server flushes audit trail buffers to the file.

The following configuration tasks are optional for each WebSEAL audit trail file:v Specify maximum event queue

Maximum number of events to queue in memory.v Specify event queue high water mark

Number of events in queue which trigger a flush from memory to file.v Specify maximum buffer size

Maximum size, in bytes, of event buffer in memory to be built from individualevents.

v Specify file modeBinary or text. Text mode is available for Windows platform only.

The optional configuration tasks are supported by Tivoli Access Manager eventlogging but not by legacy auditing. For more information on these tasks, see IBMTivoli Access Manager Base Administrator’s Guide.

Example configurationThe syntax for using logcfg to configure an audit trail file is:


logcfg =category:file path=file_pathname, flush_interval=seconds,\rollover_size=number, log_id=logid, queue_size=number, hi_water=number,\buffer_size=number, mode={text|binary}

Supported values for category are:

Table 1. Audit event categories

Audit event type Category setting

Credentials acquisition authentication audit.authn

Authorization audit.azn

HTTP logging information http

HTTP request information in common logformat

http.clf

HTTP Referer header information http.ref

HTTP User Agent header information http.agent

The NCSA combined format captures HTTPrequest information (with time stamp) andappends the quoted referer and agent stringsto the standard common log format.

http.cof

For example, the following logcfg entry creates a WebSEAL audit trail file thatcollects authentication events:logcfg = audit.authn:file path=/var/pdweb/log/audit.log,flush_interval=20, \rollover_size=2000000

Note: The above example is entered as one continuous line in webseald.conf.

In this example, auditing is enabled when Tivoli Access Manager reads the logcfgentry from webseald.conf at startup time. The required configuration settings areprovided by the following parameters:

Table 2. Example values for required configuration settings

Parameter Required setting

audit.authn:file Type of audit event

path=/var/pdweb/log/audit.log Audit file location

rollover_size=2000000 Audit file size

flush_interval=20 File flush interval

In this example, none of the optional configuration settings are specified. When theoptional settings are not specified, Tivoli Access Manager uses default values foreach setting:

Table 3. Default values for optional configuration settings

Parameter Optional setting

queue_size=number Maximum event queue. The default value is0. This value means that no maximum sizeis imposed.

hi_water=number Event queue high water mark. The defaultvalue is two-thirds of the queue_size. Whenqueue_size is 0, the default is 100.


Table 3. Default values for optional configuration settings (continued)

buffer_size=number Maximum buffer size. Default size is 0,which disables buffering.

mode={text|binary} File mode. The default mode is binary. Textmode is supported on Windows only.

The logcfg entries are placed in webseald.conf, under the [aznapi-configuration]stanza. Create a separate logcfg entry for each type of audit event.

Legacy auditing

To use legacy auditing to accomplish the configuration tasks for the authenticationauditing example above, the comparable configuration file entries would be:[aznapi-configuration]logaudit = yesauditcfg = authnauditlog = /var/pdweb/log/audit.loglogsize = 2000000logflush = 20

Legacy auditing does not support the optional configuration settings.

See also:

v “Configuring HTTP logging using event logging” on page 45v The auditing section of the WebSEAL configuration file reference: “Auditing” on

page 322.v The logging and auditing chapter of the IBM Tivoli Access Manager Base

Administrator’s Guide.

HTTP audit recordsHTTP logging captures the same information as the standard HTTP log files(request.log, referer.log, and agent.log).

The following is a sample HTTP access audit record:<event rev="1.1"><date>2002-11-14-23:04:26.931+00:00I-----</date><outcome status="412668954">1</outcome><originator blade="webseald"><component>http</component><action>2</action><location>146.84.251.70</location></originator><accessor name="user not specified"><principal auth="IV_DCE_V3.0">cell_admin</principal></accessor><target resource="5">object>/pics/pd30.gif</object></target><data></data></event>

See also see “Configuring HTTP logging using event logging” on page 45

Authentication audit recordsAuthentication of a principal is performed during credential acquisition. Auditrecords can be captured by Tivoli Access Manager to record the success or failureof such authentication attempts.


You can configure auditing of authentication attempts by adding “authn” to theaudit configuration list in the [aznapi-configuration] stanza of the server’sconfiguration file:[aznapi-configuration]auditcfg = authn

The following is a sample authentication event logged from WebSEAL for anunauthenticated user.<event rev="1.1"><date>2001-11-14-23:04:26.630+00:00I-----</date><outcome status="0">0</outcome><originator blade="webseald"><component rev="1.2">authn</component><action>0</action><location>phaedrus</location></originator><accessor name=""><principal auth="invalid"></principal></accessor><target resource="7"><object></object></target><data></data></event>

The following is a sample authentication event logged from WebSEAL for anauthenticated user.<event rev="1.1"><date>2001-11-14-15:56:06.551+00:00I-----</date><outcome status="0">0</outcome><originator blade="webseald"><component rev="1.2">authn</component><action>0</action><location>phaedrus</location></originator><accessor name=""><principal auth="IV_LDAP_V3.0" domain="Default">testuser2</principal></accessor><target resource="7"><object></object></target><data></data></event>

The following is a sample authentication failure (due to expired password) eventlogged from WebSEAL.<event rev="1.1"><date>2001-11-14-16:23:00.294+00:00I-----</date><outcome status="320938188">0</outcome><originator blade="webseald"><component rev="1.2">authn</component><action>0</action><location>phaedrus</location></originator><accessor name=""><principal auth="IV_LDAP_V3.0" domain="Default">testuser2</principal></accessor><target resource="7"><object></object></target><data></data></event>

The following is a sample authentication failure event due to too many invalidlogin attempts (three strikes policy) logged from WebSEAL.<event rev="1.1"><date>2001-11-14-19:06:00.294+00:00I-----</date><outcome status="320938290">0</outcome>


<originator blade="webseald"><component rev="1.2">authn</component><action>0</action><location>phaedrus</location></originator><accessor name=""><principal auth="IV_LDAP_V3.0" domain="Default">testuser2</principal></accessor><target resource="7"><object></object></target><data></data></event>

The following is a sample successful change password event logged fromWebSEAL.<event rev="1.1"><date>2001-11-14-16:25:54.543+00:00I-----</date><outcome status="0">0</outcome><originator blade="webseald"><component rev="1.2">authn</component><action>0</action><location>phaedrus</location></originator><accessor name=""><principal auth="passwd-ldap" domain="Default">testuser2</principal></accessor><target resource="7"><object></object></target><data></data></event>

Table 4 lists the authentication error codes and their <data> element structures thatare returned when an authentication attempt fails:

Table 4. Authentication errors

Error type Error code (in hex) Error code (indecimal)

XML generated

Password failure 132120c8 320938184 <data>Passwordfailure: user</data>

Account lock-out 13212132 320938290 <data>Accountlock-out: user</data>

General failure All others All others <data><username>user</username></data>

To determine the reason for an audited event such as an account lock-out (due, forexample, to a three strikes policy), obtain the error code as shown in the tableabove. The error code is contained in the audit output in the <outcome status> tag:<outcome status>"13212132">0</outcome>

Invoke the pdadmin errtext command for the error code to receive a reason for theoutcome. For example:> pdadmin errtext 13212132This account has been temporarily locked out due to too manyfailed login attempts

Error codes for Tivoli Access Manager are described in the IBM Tivoli AccessManager Error Message Reference.


Chapter 3. Advanced server configuration

This chapter contains information that describes advanced administration andconfiguration tasks you can perform to customize the WebSEAL server for yournetwork. See also Chapter 2, “Basic server configuration”, on page 19.

Topic Index:v “Configuring a default quality of protection level” on page 53v “Configuring authorization database updates and polling” on page 55v “Managing worker thread allocation” on page 56v “Replicating front-end WebSEAL servers” on page 58v “Configuring multiple WebSEAL server instances” on page 59v “Configuring switch user” on page 72v “Configuring WebSEAL server-side request caching” on page 83v “Handling UTF-8 encoded characters” on page 85v “Preventing vulnerability caused by cross-site scripting” on page 87v “Suppressing server identity” on page 88v “Configuring cryptographic hardware for encryption and key storage” on page

88v “Problem determination tools for WebSEAL” on page 93

Configuring a default quality of protection levelYou can control the default level of encryption required for access to WebSEALover SSL (HTTPS) by configuring the quality of protection (QOP). Default qualityof protection management is controlled using parameters in the ″SSL QUALITY OFPROTECTION MANAGEMENT″ section of the webseald.conf configuration file:v Enable and disable QOP management with the ssl-qop-mgmt parameterv Specify allowed encryption levels in the [ssl-qop-mgmt-default] stanza1. Enable quality of protection management:

[ssl-qop]ssl-qop-mgmt = yes

2. Specify the default encryption level for HTTPS access:[ssl-qop-mgmt-default]# default = ALL | NONE | <cipher-level># ALL (enables all ciphers)# NONE (disables all ciphers and uses an MD5 MAC check sum)# DES-56# DES-168# RC2-40# RC2-128# RC4-40# RC4-128default = ALL

Note that you can also specify a selected group of ciphers:[ssl-qop-mgmt-default]default = RC4-128default = RC2-128default = DES-168


Tivoli Access Manager uses GSKit 5. The Cipher specifications supported byGSKIT5 when used in SSLv2/TLS in internet security are:CipherSuite SSL_RSA_WITH_NUL_MD5CipherSuite SSL_RSA_WITH_NUL_SHACipherSuite SSL_RSA_EXPORT_WITH_RC4_40_MD5CipherSuite SSL_RSA_EXPORT_WITH_RC2_CBC_40_MD5CipherSuite SSL_RSA_WITH_DES_CBC_SHACipherSuite SSL_RSA_WITH_RC4_128_MD5CipherSuite SSL_RSA_WITH_RC4_128_SHACipherSuite SSL_RSA_WITH_3DES_EDE_CBC_SHACipherSuite TLS_RSA_EXPORT1024_WITH_DES_CBC_SHACipherSuite TLS_RSA_EXPORT1024_WITH_RSA_56_SHA

These TLS cipher specifications are also used with SSLV3.

Configuring QOP for individual hosts and networksThe ssl-qop-mgmt = yes parameter also enables any settings that appear in the[ssl-qop-mgmt-hosts] and [ssl-qop-mgmt-networks] stanzas. These stanzas allowquality of protection management by specific host/network/netmask IP address.

The [ssl-qop-mgmt-default] stanza lists the ciphers used for all IP addresses notmatched in the [ssl-qop-mgmt-hosts] and [ssl-qop-mgmt-networks] stanzas.

Example configuration syntax for hosts:[ssl-qop-mgmt-hosts]# <host-ip> = ALL | NONE | <cipher-level># ALL (enables all ciphers)# NONE (disables all ciphers and uses an MD5 MAC check sum)# DES-40# DES-56# DES-168# RC2-40# RC2-128# RC4-40# RC4-128xxx.xxx.xxx.xxx = ALLyyy.yyy.yyy.yyy = RC2-128

Example configuration syntax for network/netmask:[ssl-qop-mgmt-networks]# <network/netmask> = ALL | NONE | <cipher-level># ALL (enables all ciphers)# NONE (disables all ciphers and uses an MD5 MAC check sum)# DES-40# DES-56# DES-168# RC2-40# RC2-128# RC4-40# RC4-128xxx.xxx.xxx.xxx/255.255.255.0 = RC4-128yyy.yyy.yyy.yyy/255.255.0.0 = DES-56

The [ssl-qop-mgmt-hosts] and [ssl-qop-mgmt-networks] stanzas are provided forbackward compatibility only. It is recommended that you not use them for TivoliAccess Manager configuration.


Configuring authorization database updates and pollingThe Tivoli Access Manager policy server (pdmgrd) manages the masterauthorization policy database and maintains location information about otherTivoli Access Manager servers in the secure domain. A Tivoli Access Manageradministrator can make security policy changes to the secure domain at any time.The policy server makes the necessary adjustments to the master authorizationdatabase whenever security policy changes are implemented.

When the policy server makes a change to the master authorization database, itcan send out notification of this change to all replica databases in the securedomain that support individual policy enforcers (such as WebSEAL). The policyenforcers must then request an actual database update from the masterauthorization database.

WebSEAL, as a resource manager and policy enforcer, has three options to obtaininformation about authorization database changes:v Listen for update notifications from the policy server (configurable and enabled

by default).v Check (poll) the master authorization database at regular intervals (configurable

and disabled by default).v Enable both listening and polling.

The [aznapi-configuration] stanza of the webseald.conf configuration file containsparameters for configuring update notification listening and database polling.

The path to WebSEAL’s local replica authorization policy database is defined bythe db-file parameter:[aznapi-configuration]db-file = /var/pdweb/db/webseald.db

Configuring update notification listeningThe listen-flags parameter, found in the [aznapi-configuration] stanza, enablesand disables update notification listening by WebSEAL. By default, listening isenabled. To disable listening, enter ″disable″.[aznapi-configuration]listen-flags = enable

The ssl-listening-port parameter, found in the [ssl] stanza, configures the SSL portfor the listener:[ssl]ssl-listening-port = 7234

Configuring authorization database pollingYou can configure WebSEAL to regularly poll the master authorization database forupdate information. The cache-refresh-interval parameter can be set to ″default″,″disable″, or a specific time interval in seconds. The ″default″ setting is equal to600 seconds. By default, polling is disabled.[aznapi-configuration]cache-refresh-interval = disable

Chapter 3. Advanced server configuration 55

Managing worker thread allocationv “Configuring WebSEAL worker threads” on page 56v “Allocating worker threads for junctions (junction fairness)” on page 56

Configuring WebSEAL worker threadsThe number of configured worker threads specifies the number of concurrentincoming requests that can be serviced by a server. Other connections that arrivewhen all worker threads are busy will be buffered until a worker thread isavailable.

You can set the number of threads available to service incoming connections toWebSEAL. Configuring the number of worker threads should be done carefullydue to possible performance impacts.

This configuration parameter does not impose an upper boundary on the numberof simultaneous connections. This parameter simply specifies the number ofthreads made available to service a potentially unlimited work queue.

Choosing the optimal number of worker threads depends on understanding thequantity and type of traffic on your network. In all cases, you must only enter avalue that is less than the worker threads limit imposed by the operating system.

By increasing the number of threads, you are, in general, decreasing the averagetime it takes to finish the requests. However, increasing the number of threadsimpacts other factors that could have an adverse effect on server performance.

WebSEAL maintains a single, generic worker list and worker threads pool forhandling requests from clients using TCP or SSL. This enhanced mechanismenables WebSEAL to consume fewer system resources while handling significantlygreater load.

You can configure the worker thread pool size by setting the worker-threadsparameter in the [server] stanza portion of the webseald.conf configuration file.[server]worker-threads = 50

Note: Change this parameter only to troubleshoot a performance problem. Thevalue selected must remain within the worker threads limits set by theoperating system. See the IBM Tivoli Access Manager Performance TuningGuide.

Allocating worker threads for junctions (junction fairness)You can configure the allocation of WebSEAL worker threads used to processrequests across multiple junctions on a global or per-junction basis. Theconfiguration mechanism maintains a ″fair″ distribution of worker threads acrossall junctions and prevents depletion of the worker thread pool by any one junction.

BackgroundWebSEAL draws from its pool of worker threads to process multiple requests. Thenumber of worker threads available to WebSEAL is specified by theworker-threads parameter in the webseald.conf configuration file.


You can adjust the worker-threads value to best serve your particular WebSEALimplementation. When no worker threads are available to handle incomingrequests, users experience a WebSEAL server that is not responding.

Worker threads are used to handle incoming requests to applications residing onmultiple junctioned back-end servers. However, the worker thread pool can bequickly drained if a particular back-end application is unusually slow whenresponding to and processing a high volume of requests. A depletion of the workerthread pool by this one application renders WebSEAL incapable of responding torequests for services on the remaining junctioned application servers.

You can configure global or per-junction limits on the number of worker threadsused to service applications on multiple junctions. These limits allow ″fairness″ toprevail for all junctions and prevents any one application from claiming more thanits share of worker threads.

Global allocation of worker threads for junctionsTwo parameters located in the [junction] stanza of the webseald.conf configurationfile control the global allocation of worker threads across all junctions for aparticular WebSEAL server. The values used for these parameters are expressed aspercentages within the range of 0 to 100. The default of 100 (%) indicates there isno limit.v worker-thread-soft-limit

This parameter is set to send a warning before the ″hard″ limit is reached. Whenthe worker-thread-soft-limit is exceeded, warning messages are sent (every 30seconds) to the WebSEAL error log file.For example, when worker-threads=50, a setting of 60 (%) causes warningmessages to be issued when the junction consumes more than 30 workerthreads. All requests above 30 worker threads are still processed, until the ″hard″limit is reached.

v worker-thread-hard-limit

This parameter determines the cut-off point for servicing requests across ajunction. When the worker-thread-hard-limit is exceeded, error messages aresent (every 30 seconds) to the WebSEAL error log file. In addition, the user issent a 503 ″Service Unavailable″ message.For example, when worker-threads=50, a setting of 80 (%) causes error messagesto be issued when the junction tries to consume more than 40 worker threads.All requests representing greater than 40 worker threads on the junction arereturned with a 503 ″Service Unavailable″ message.

These global settings apply equally to all configured junctions. When configuringthese two parameters, it is logical to set the ″soft″ limit to a lower value than the″hard″ limit.

For performance considerations, see the IBM Tivoli Access Manager PerformanceTuning Guide.

Per-junction allocation of worker threads for junctionsAlternatively, you can limit worker thread consumption on a per-junction basis.The following options to the pdadmin server task create command allow you tospecify hard and soft worker thread limits on a specific junction:v –l <percent-value>


This option sets a value (percent) on the junction that defines the soft limit forconsumption of worker threads. As in the global soft limit setting, this optioncauses warning messages to be issued when the junction consumes more workerthreads than allowed by the setting.

v –L <percent-value>This option sets a value (percent) on the junction that defines the hard limit forconsumption of worker threads. As in the global hard limit setting, this optioncauses warning messages to be issued when the junction tries to consume moreworker threads than allowed by the setting. In addition, the user is sent a 503″Service Unavailable″ message.

For example:pdadmin> server task webseald-<server-name> create -t tcp -h <host-name> \-l 60 -L 80 <jct-point>

Per-junction settings always override the global settings in webseald.conf.Inappropriate settings on a specific junction could adversely affect the policyestablished by the global settings.

Troubleshooting notesv You can use the pdadmin server task show command to view the number of

active worker threads on a specific junction:pdadmin> server task webseald-<server-name> show /<jct-point>

This information might be useful when you want to determine the location of ajunction that is absorbing more than its share of worker thread resources.

v If you specify a soft limit value that is greater than the hard limit value on aspecific junction, the junction will not be created.

v You must specify both soft and hard limit values (both –l and –L options) on aspecific junction.

Replicating front-end WebSEAL servers

Note: The following information replaces the former pdadmin server modifybaseurl command, used in previous versions of Tivoli Access Manager.

In a heavy load environment, it is advantageous to replicate front-end WebSEALservers to provide better load-balancing and fail-over capability. When youreplicate front-end WebSEAL servers, each server must contain an exact copy of theWeb space, the junction database, and the dynurl database.

This version of Tivoli Access Manager supports a manual configuration procedureto replicate front-end WebSEAL servers. The pdadmin command is no longer usedfor this task.

In the following example, ″WS1″ is the host name of the primary WebSEAL server.″WS2″ is the host name for the replica WebSEAL server.1. Install and configure WebSEAL on both WS1 and WS2 servers.2. Using the pdadmin command, create a new object to be the root of the

authorization space for both WebSEAL servers. For example:pdadmin> object create /WebSEAL/newroot

3. Stop WebSEAL on WS1.


4. On WS1, change the value of the server-name parameter in the webseald.confconfiguration file from ″WS1″ to ″newroot″:[server]server-name = newroot

5. Restart WebSEAL on WS1.6. Repeat Steps 3-5 for WS2.

The WS1 and WS2 servers now use the object /WebSEAL/newroot as the base forauthorization evaluations. Either the WS1 or the WS2 server can respond to objectlist and object show commands for objects residing below /WebSEAL/newroot.

Use the following procedure when unconfiguring either WS1 or WS2:1. Stop the WebSEAL server.2. Change the server-name parameter back to its original value. For example, for

WS1:[server]server-name = WS1

3. Proceed with normal unconfiguration procedures.

Conditions:v Unified object space management: Although a single object hierarchy is visible to

the administrator, all replicated WebSEAL servers are affected by administrationcommands applied to that object hierarchy and all servers are able to respond tothese commands.

v Unified authorization evaluation: Both WS1 and WS2 use /WebSEAL/newroot asthe base for authorization evaluations.

v Unified configuration: For front-end WebSEAL replication to function correctly,the Web space, junction database, and dynurl database configuration must beidentical on each server.

Configuring multiple WebSEAL server instancesTivoli Access Manager provides the capability for configuring multiple WebSEALserver instances on a single machine.

Configuration overviewFor configuration purposes, an instance of a WebSEAL server is defined by aunique network interface (IP address) and port number combination.

Multiple WebSEAL instances can be configured using one of the following methodsto create unique network interface:port combinations:v Use a single network interface (IP address) and assign WebSEAL instances to

unique HTTP/HTTPS listening portsv Assign WebSEAL instances to unique network interfaces (physical network

interface cards or logical network aliases) and use common HTTP/HTTPSlistening ports

Note: In both scenarios, the inter-server port value—for communications betweenthe WebSEAL instances and the policy server—must be unique for allWebSEAL instances.

Each configured WebSEAL instance has a unique name, a unique internal portnumber (for inter-Tivoli Access Manager server communication), a unique


directory location, and a unique configuration file. Multiple configuration files aremade unique by the server instance name, prepended with webseald-. Forexample:/opt/pdweb/etc/webseald-<instance-name>.conf

For both UNIX and Windows platforms, you use the pdconfig utility to configureand unconfigure multiple WebSEAL instances.

Note: The pdconfig utility is also used to create the initial WebSEAL instance.

Notes and Conditionsv If you want to use secure SSL communication between a WebSEAL instance and

the LDAP registry server, you must use the GSKit iKeyman utility to create andstore an SSL key file for this purpose. If the initial WebSEAL server is set up touse secure SSL communication with LDAP, multiple instances can use the samekey file.

v The newly created instance-specific configuration file is automatically configuredfor SSL communication between the new WebSEAL instance and internal Accessmanager servers (such as the policy server).

v The newly created instance-specific configuration file is also automaticallyconfigured to use the server certificate of the initial WebSEAL server toauthenticate to client browsers.

v The instructions that follow assume that your machine is configured with aninitial WebSEAL server and a single network card (with IP address).

v The inter-Tivoli Access Manager port value—for communications between the aWebSEAL instance and other Tivoli Access Manager servers (such as the policyserver)—must be unique for all WebSEAL instances.

v Values for the inter-Tivoli Access Manager server port must be greater than 1023.Values less than or equal to 1023 are reserved.

v The maximum number of allowed WebSEAL instances is governed by systemconfiguration limitations, such as available RAM and disk space. If any systemresource is exceeded, configuration error and startup failure messages appear.

Configuring multiple WebSEAL instances on UNIXAssumptions:v Initial WebSEAL server has been configured

Configuring multiple instances on unique HTTP/HTTPS ports:

In this scenario, new WebSEAL instances are made unique through differentHTTP/HTTPS listening port designations on a common network interface.1. Assumption: Windows is configured with an initial WebSEAL server

(pdconfig) and physical network card/IP address (for this example: 1.2.3.4).2. Start the pdconfig utility:

# pdconfig

The Access Manager for e-business Setup Menu appears.Access Manager for e-business Setup Menu

1. Configure Package2. Unconfigure Package


3. Display Configuration Statusx. Exit

Please select the menu item [x]:

3. Type ″1″ to select Configure Package and press Enter.The Access Manager for e-business Configuration Menu appears.Access Manager for e-business Configuration Menu

1. Access Manager WebSEAL Configurationx. Return to Access Manager for e-business Setup Menu


4. Type ″1″ to select Access Manager WebSEAL Configuration and press Enter.The Access Manager WebSEAL for e-business Setup Menu appears.Access Manager WebSEAL for e-business Setup Menu

1. Add Instance2. Unconfigure3. Display Configuration Statusx. Exit


5. Type ″1″ to select Add Instance and press Enter.The Configuring WebSEAL Instance script starts.

6. Type the instance name (for example, webseal1) and press Enter.Enter WebSEAL Instance Name: webseal1

The length of this name is limited to 20 characters.7. Type the Access Manager Listener Port and press Enter.

By default, the initial WebSEAL server listens on port=7234 for inter-AccessManager server communication. This port number is automaticallyincremented with each new instance. Therefore, the default port numberappearing for the first WebSEAL instance is 7235.Accept the default listener port value listed, or enter a different (but unique)value.Enter Access Manager Listener Port [7235]:

8. Type ″n″ (no) for Use Logical Network Interface and press Enter.Use logical network interface (y/n) [No] n

9. Type the administrator (sec_master) password and press Enter.Enter the password for the Access Manager Administrator:

10. Type ″y″ (yes) or ″n″ (no) to enable SSL communication between the AccessManager server and the LDAP server.Do you want to enable SSL communication between theAccess Manager server and the LDAP server (y/n) [Yes]?

Go to step 11 if you want secure SSL communication between the WebSEALinstance and the LDAP server.

Go to step 12 if you do not want secure SSL communication between theWebSEAL instance and the LDAP server.

11. Type ″y″ (yes) only if you want secure SSL communication between theWebSEAL instance and the LDAP server. Type the following information(press Enter for each entry):


Enter the location of the LDAP SSL Client Key File:Enter the SSL Client Certificate Label (if required):Enter the LDAP SSL Client Key File Password:Enter the LDAP Server SSL Port Number:

12. Type ″n″ (no) if you do not want secure SSL communication between theWebSEAL instance and the LDAP server. Press Enter.

13. The check Web Server configuration menu appears. Select the appropriatemenu options to enable or disable HTTP and HTTPS communication, changethe default port values (if required), and change the doc root location.If the initial WebSEAL server uses port 80 for HTTP access, the portdesignation is automatically incremented to 81 for the first instance.If the initial WebSEAL server uses port 443 for HTTPS access, the portdesignation is automatically incremented to 444 for the first instance.Please check Web Server configuration:

1. Enable TCP HTTP? Yes2. HTTP Port 813. Enable HTTPS? Yes4. HTTPS Port 4445. Web document root directory /opt/pdweb/www-webseal1/docs

a. Accept configuration and continue with configuration

x. Exit configuration

Select item to change: a

14. After all configuration changes have been made, type ″a″ to accept theconfiguration values and press Enter.The configuration continues.

15. The WebSEAL instance is created (this takes a few moments).* Configuring the Web Server

Configuration of application "webseal1-webseald" is in progress. This mighttake several minutes.SSL configuration has completed successfully for the application.

* Starting server

Access Manager WebSEAL Version 4.1.0 (Build 020730)

Copyright (C) IBM Corporation 1994-2002. All Rights Reserved.

webseal1 instance has been successfully configured.

Press Enter to continue ...

16. Press Enter. You are returned to the Access Manager WebSEAL for e-businessSetup Menu.Access Manager WebSEAL for e-business Setup Menu



17. Type ″3″ to display the status of the WebSEAL servers. Press Enter.Access Manager WebSEAL Configuration Status

Instance Configured Running


------------------------------------------webseald yes yeswebseald-webseal1 yes yes


18. Press Enter to return to the Access Manager WebSEAL for e-business SetupMenu.You can configure another instance or exit the pdconfig utility.

Configuring multiple instances on unique logical network interfaces:

In this scenario, new WebSEAL instances are made unique through differentnetwork interfaces on common HTTP/HTTPS listening port designations.1. Assumption: Windows is configured with an initial WebSEAL server and a

single network card/IP address.2. By default, the initial WebSEAL server listens for requests on HTTP/HTTPS

ports *:80 and *:443 (that is, across all available interfaces). Before you canconfigure and run additional WebSEAL server instances, you must assign theinitial WebSEAL server a specific IP address for a specific network interface.Additional WebSEAL servers cannot start if the initial WebSEAL serverreserves all available interfaces by listening on *:80 and *:443.

3. Edit the webseald.conf configuration file and specify an appropriate IPaddress for the initial WebSEAL server by adding the network-interfaceparameter to the [server] stanza. The value of network-interface must be theIP address of the default network interface. For example:[server]network-interface = 1.2.3.4

4. Restart the WebSEAL server.# /usr/bin/pdweb restart webseald

Now the initial WebSEAL server is only listening on port 80 (HTTP) and port443 (HTTPS) via the 1.2.3.4 interface.

5. Start the pdconfig utility:# pdconfig


1. Configure Package2. Unconfigure Package3. Display Configuration Statusx. Exit


6. Type ″1″ to select Configure package and press Enter.The Access Manager for e-business Configuration Menu appears.Access Manager for e-business Configuration Menu

1. Access Manager WebSEAL Configurationx. Return to Access Manager for e-business Setup Menu


7. Type ″1″ to select Access Manager for WebSEAL Configuration and pressEnter.The Access Manager WebSEAL for e-business Setup Menu appears.


Access Manager WebSEAL for e-business Setup Menu



8. Type ″1″ to select Add Instance and press Enter.The Configuring WebSEAL Instance script starts.

9. Type the instance name (for example, webseal2) and press Enter.Enter WebSEAL Instance Name: webseal2

The length of this name is limited to 20 characters.10. Type the Access Manager Listener Port and press Enter.

By default, the initial WebSEAL server listens on port=7234 for inter-AccessManager server communication. This port number is automaticallyincremented with each new instance. Therefore, the default port numberappearing for the first WebSEAL instance is 7235.Accept the default listener port value listed, or enter a different (but unique)value.Enter Access Manager Listener Port [7235]:

11. Type ″y″ (yes) for Use Logical Network Interface and press Enter.Use logical network interface (y/n) [No] y

12. Type the logical network interface and press Enter. (Your networkadministrator must provide this IP address.)Enter logical network interface: 1.2.3.5

13. Type the administrator (sec_master) password and press Enter.Enter the password for the Access Manager Administrator:

14. Type ″y″ (yes) or ″n″ (no) to enable SSL communication between the AccessManager server and the LDAP server.Do you want to enable SSL communication between theAccess Manager server and the LDAP server (y/n) [Yes]?

Go to step 15 if you want secure SSL communication between the WebSEALinstance and the LDAP server.

Go to step 16 if you do not want secure SSL communication between theWebSEAL instance and the LDAP server.

15. Type ″y″ (yes) only if you want secure SSL communication between theWebSEAL instance and the LDAP server. Type the following information(press Enter for each entry):Enter the location of the LDAP SSL Client Key File:Enter the SSL Client Certificate Label (if required):Enter the LDAP SSL Client Key File Password:Enter the LDAP Server SSL Port Number:

16. Type ″n″ (no) if you do not want secure SSL communication between theWebSEAL instance and the LDAP server. Press Enter.

17. The check Web Server configuration menu appears. Select the appropriatemenu options to enable or disable HTTP and HTTPS communication, changethe default port values (if required), and change the doc root location.The port designations are automatically set for 80 (HTTP) and 443 (HTTPS).


Please check Web Server configuration:

1. Enable TCP HTTP? Yes2. HTTP Port 803. Enable HTTPS? Yes4. HTTPS Port 4435. Web document root directory /opt/pdweb/www-webseal2/docs

a. Accept configuration and continue with configuration

x. Exit configuration

Select item to change: a

18. After any configuration changes, Type ″a″ to accept the configuration valuesand press Enter.The configuration continues.

19. The WebSEAL instance is created (this takes a few moments).* Configuring the Web Server

Configuration of application "webseal2-webseald" is in progress. This mighttake several minutes.SSL configuration has completed successfully for the application.

* Starting server

Access Manager WebSEAL Version 4.1.0 (Build 020730)

Copyright (C) IBM Corporation 1994-2002. All Rights Reserved.

webseal2 instance has been successfully configured.


20. Press Enter. You are returned to the Access Manager WebSEAL for e-businessSetup Menu.Access Manager WebSEAL for e-business Setup Menu



21. Type ″3″ to display the status of the WebSEAL servers. Press Enter.Access Manager WebSEAL Configuration Status

Instance Configured Running------------------------------------------webseald yes yeswebseald-webseal2 yes yes


22. Press Enter to return to the Access Manager WebSEAL for e-business SetupMenu.You can configure another instance or exit the pdconfig utility.

Configuring multiple WebSEAL instances on WindowsAssumptions:v Initial WebSEAL server has been configured


v Procedures described are appropriate for a Windows NT or Windows 2000platform

Configuring multiple instances on unique HTTP/HTTPS ports:

In this scenario, new WebSEAL instances are made unique through differentHTTP/HTTPS listening port designations on a common network interface.1. Assumption: Windows is configured with an initial WebSEAL server

(pdconfig) and physical network card/IP address (for this example: 1.2.3.4).2. Start the pdconfig utility:

MSDOS> pdconfig

The Access Manager for e-business Configuration dialogue box appears.

Note that the Access Manager WebSEAL component appears in the listwindow.

3. Highlight Access Manager WebSEAL in the list box, and click Configure.The Access Manager WebSEAL for e-business Configuration dialogue boxappears.An entry representing the initial default WebSEAL server appears in the listwindow.

4. Click Add Instance.The WebSEAL Instance Name dialogue box appears.

5. Enter the instance name (for example, webseal1) and click OK.The length of this name is limited to 20 characters.The Access Manager Listener Port dialogue box appears.

6. Accept the default listener port value that appears in the entry field, or enter adifferent (but unique) value.By default, the initial WebSEAL server listens on port=7234 for inter-AccessManager server communication. This port number is automaticallyincremented with each new instance. Therefore, the default port numberappearing for the first WebSEAL instance is 7235.

7. Click OK.The Configure Instance with Logical Network Interface dialogue box appears.

8. Select ″No″ for Use Logical Network Interface, and click OK.9. You must enter an administrator password (sec_master) once per pdconfig

session. If you have not previously entered this password for this pdconfigsession, the Access Manager Administrator Password dialogue box appears.Otherwise, the SSL Communication with the LDAP Server dialogue boxappears.If required, enter the password for sec_master and click OK.

10. The SSL Communication with the LDAP Server dialogue box appears.Go to step 11 if you want secure SSL communication between the WebSEALinstance and the LDAP server.Go to step 12 if you do not want secure SSL communication between theWebSEAL instance and the LDAP server.

11. Check ″yes″ only if you want secure SSL communication between theWebSEAL instance and the LDAP server.a. Enter LDAP client SSL information:

v Port number for SSL listening


v Key database file full path locationv Certificate labelv Password for the key database file

b. Click OK.c. The HTTP Properties dialogue box appears. Go to Step 13.

12. Check ″no″ if you do not want secure SSL communication between theWebSEAL instance and the LDAP server. Click OK.The HTTP Properties dialogue box appears. Continue with Step 13.

13. From the HTTP Properties dialogue box, enable HTTP and / or HTTPS accessby checking the appropriate check box.

14. Specify the appropriate port numbers.If the initial WebSEAL server uses port 80 for HTTP access, the portdesignation is automatically incremented to 81 for the first instance.If the initial WebSEAL server uses port 443 for HTTPS access, the portdesignation is automatically incremented to 444 for the first instance.

15. Click OK.The WebSEAL instance is created (this takes a few moments).The new WebSEAL instance is listed in the list box of the Access ManagerWebSEAL for e-business Configuration dialogue box.

Configuring multiple instances on unique logical network interfaces:

In this scenario, new WebSEAL instances are made unique through differentnetwork interfaces on common HTTP/HTTPS listening port designations.1. Assumption: Windows is configured with an initial WebSEAL server and a

single network card/IP address.2. By default, the initial WebSEAL server listens for requests on HTTP/HTTPS

ports *:80 and *:443 (that is, across all available interfaces). Before you canconfigure and run additional WebSEAL server instances, you must assign theinitial WebSEAL server a specific IP address for a specific network interface.Additional WebSEAL servers cannot start if the initial WebSEAL serverreserves all available interfaces by listening on *:80 and *:443.

3. Edit the webseald.conf configuration file and specify an appropriate IPaddress for the initial WebSEAL server by adding the network-interfaceparameter to the [server] stanza. The value of network-interface must be theIP address of the default network interface. For example:[server]network-interface = 1.2.3.4

4. Restart the WebSEAL server from the Services Control Panel.Now the initial WebSEAL server is only listening on port 80 (HTTP) and port443 (HTTPS) via the 1.2.3.4 interface.

5. Start the pdconfig utility:MSDOS> pdconfig



6. Highlight Access Manager WebSEAL in the list box, and click Configure.The Access Manager WebSEAL for e-business Configuration dialogue boxappears.


An entry representing the initial default WebSEAL server appears in the listwindow.

7. Click Add Instance.The WebSEAL Instance Name dialogue box appears.

8. Enter the instance name (for example, webseal2) and click OK.The length of this name is limited to 20 characters.The Access Manager Listener Port dialogue box appears.

9. Accept the default listener port value that appears in the entry field, or enter adifferent (but unique) value.By default, the initial WebSEAL server listens on port=7234 for inter-AccessManager server communication. This port number is automaticallyincremented with each new instance. Therefore, the default port numberappearing for the first WebSEAL instance is 7235.The Configure Instance with Logical Network Interface dialogue box appears.

10. Select ″Yes″ for Use Logical Network Interface.11. Specify the logical network interface IP address. (Your network administrator

must provide this IP address.) Click OK.12. You must enter an administrator password (sec_master) once per pdconfig

session. If you have not previously entered this password for this pdconfigsession, the Access Manager Administrator Password dialogue box appears.Otherwise, the SSL Communication with the LDAP Server dialogue boxappears.If required, enter the password for sec_master and click OK.

13. The SSL Communication with the LDAP Server dialogue box appears.Go to step 14 if you want secure SSL communication between the WebSEALinstance and the LDAP server.Go to step 15 if you do not want secure SSL communication between theWebSEAL instance and the LDAP server.

14. Check ″yes″ only if you want secure SSL communication between theWebSEAL instance and the LDAP server.a. Enter LDAP client SSL information:

v Port number for SSL listeningv Key database file full path locationv Certificate labelv Password for the key database file

b. Click OK.c. The HTTP Properties dialogue box appears. Go to Step 16.

15. Check ″no″ if you do not want secure SSL communication between theWebSEAL instance and the LDAP server. Click OK.The HTTP Properties dialogue box appears. Continue with Step 16.

16. The HTTP Properties dialogue box indicates that port 80 is set for HTTPaccess and port 443 is set for HTTPS access.

17. Accept the default port values, or enter different port values if required. ClickOK.The WebSEAL instance is created (this takes a few moments).The new WebSEAL instance is listed in the list box of the Access ManagerWebSEAL for e-business Configuration dialogue box.


Unconfiguring multiple WebSEAL instancesYou cannot unconfigure the initial WebSEAL server until all server instances areunconfigured first. An error message appears if you attempt to unconfigure theinitial WebSEAL server before removing all instances, and you are returned to theconfiguration menu.

UNIX:

1. Start the pdconfig utility:# pdconfig


1. Configure Package2. Unconfigure Package3. Display Configuration Statusx. Exit


2. Type ″2″ to select Unconfigure Package and press Enter.The Access Manager for e-business Unconfiguration Menu appears.Access Manager for e-business Unconfiguration Menu

1. Access Manager WebSEAL Unconfiguration2. Access Manager Policy Server Unconfiguration3. Access Manager Runtime Unconfigurationx. Return to Access Manager for e-business Setup Menu


3. Type ″1″ to select Access Manager WebSEAL UnconfigurationThe Access Manager WebSEAL for e-business Setup Menu appears.Access Manager WebSEAL for e-business Setup Menu



4. Type ″2″ to select Unconfigure and press Enter.The Access Manager WebSEAL for e-business Unconfiguration Menu appears.Access Manager WebSEAL for e-business Unconfiguration Menu---------------------------------------------------------

1. webseald-web12. webseald-web23. websealdx. Exit


5. Type the menu number for the WebSEAL instance you want to unconfigure(remove). Press Enter.Please select the menu item [x]: 2

6. Enter the administrator (sec_master) password and press Enter.The WebSEAL instance is unconfigured and removed (this takes a fewmoments).


Unconfiguring WebSEAL InstanceEnter the password for the Access Manager Administrator:* Cleaning up log files

Stopping the: webseald-webseal2* Unconfiguring server

Unconfiguration of application "webseal2-webseald" is in progress. This mighttake several minutes.SSL unconfiguration for application "webseal2-webseald" has completedsuccessfully.webseal2 instance has been successfully unconfigured.


7. Press Enter to return to the Access Manager WebSEAL for e-businessUnconfiguration Menu.You can unconfigure another WebSEAL instance or continue to press Enteruntil you completely exit from the pdconfig utility.

Windows:

1. Start the pdconfig utility:MSDOS> pdconfig



2. Highlight Access Manager WebSEAL in the list box, and click Unconfigure.The Access Manager WebSEAL for e-business Configuration dialogue boxappears.Entries representing the initial WebSEAL server and all configured WebSEALinstances appear in the list window.

3. In the list box, highlight the WebSEAL instance you want to unconfigure andremove. Click Unconfigure.

4. You must enter an administrator password (sec_master) once per pdconfigsession. If you have not previously entered this password for this pdconfigsession, the Access Manager Administrator Password dialogue box appears.Otherwise, the WebSEAL instance is unconfigured.If required, enter the password for sec_master and click OK.

5. The WebSEAL instance is unconfigured and removed (this takes a fewmoments).The WebSEAL instance no longer appears in the list box of the Access ManagerWebSEAL for e-business Configuration dialogue box.

Server start, stop, restart, and status commandsUNIX:

The pdweb utility provides start, stop, restart, and status capabilities for the initialWebSEAL server and any multiple server instances. You can also apply a commandto a specific server instance.pdweb {start|stop|restart|status} [<instance-name>]

Examples:

Start the initial WebSEAL server and all configured server instances:


# /usr/bin/pdweb start

Start a specific server instance only:# /usr/bin/pdweb start webseal3

Restart the initial WebSEAL server and all configured server instances:# /usr/bin/pdweb restart

Stop the initial WebSEAL server and all configured server instances:# /usr/bin/pdweb stop

Stop a specific server instance only:# /usr/bin/pdweb stop webseal3

Show status of all configured servers:# /opt/PolicyDirector/bin/pd_start statusAccess Manager ServersServer Enabled Running------------------------------------------pdmgrd yes yespdacld yes yeswebseald yes yeswebseald-webseal2 yes yeswebseald-webseal3 yes yes

Windows:

The Windows Services Control Panel provides server start, stop, and statusinformation.

Alternatively, the net command provides start and stop capabilities for the initialWebSEAL server and any multiple server instances.net {start|stop} <instance-name>

Examples:

Start the initial WebSEAL server and all configured server instances (you mustrepeat the command for each instance):MSDOS> net start websealdMSDOS> net start webseal2MSDOS> net start webseal3

Stop the initial WebSEAL server and all configured server instances (you mustrepeat the command for each instance):MSDOS> net stop websealdMSDOS> net stop webseal2MSDOS> net stop webseal3

Show status of all configured servers:Start > Settings > Control Panel > Services


Configuring switch userThe WebSEAL switch user function allows administrators to assume the identity ofa user who is a member of the Tivoli Access Manager secure domain. The ability toassume a user’s identity can help an administrator in a Help Desk environment totroubleshoot and diagnose problems. Switch user can also be used to test a user’saccess to resources and to perform application integration testing.

Read this entire section to ensure that you understand the switch user functionbefore configuring and using it. This section contains the following topics:v “Overview of the switch user function”v “Configuration procedure” on page 74v “Using switch user” on page 79v “Developing a custom CDAS for switch user” on page 81

Overview of the switch user functionThe switch user implementation is similar to the su command in UNIXenvironments. In the WebSEAL environment, the administrator acquires the user’scredentials and interacts with resources and back-end applications with the exactsame abilities as the actual user. The administrator uses a special HTML form tosupply switch user information. WebSEAL processes the form and activates aspecial authentication mechanism that returns the specified user’s credentialwithout the requirement of knowing the user’s password.

The following sequence describes the switch user process flow:1. An administrator authenticates to WebSEAL. WebSEAL establishes a session

for the administrator, and creates an entry for the administrator in theWebSEAL session cache.The session cache entry contains a cache data structure. This data structurestores the administrator’s credential. During the switch user process flow, thecache data will be manipulated.For more information on WebSEAL session caches, see “The WebSEALsession/credentials cache structure” on page 11.

2. The administrator connects to a pre-configured switch user HTML form, andcompletes the form. On the form, the administrator specifies:v The name of the user identity that the administrator needs to assume.v A destination URL.v An authentication method.

This action results in a POST request being sent to /pkmssu.form.

The WebSEAL administrator can optionally modify the contents of the switchuser HTML form before making it available for use by other administrators. See“Part 3: Configuring the switch user HTML form” on page 77. Theadministrator can also optionally extend the capabilities of the form. See “Part4: Designing additional input forms” on page 79.

3. WebSEAL determines whether to grant the switch user request by performingthe following checks:a. WebSEAL examines the membership of the Tivoli Access Manager

su-admins group to determine if the administrator has permission to invokethe switch user function.


Administrators requesting use of switch user authentication must bemembers of the su-admins group. Membership in this group must beconfigured before switch user can be used. For more information, see “Part1: Configuring user access” on page 74.

b. WebSEAL examines the membership of the Tivoli Access Managersu-admins, securitygroup and su-excluded groups to ensure the useridentity supplied in the switch user form is not a member of one of thesegroups.User identities that belong to any of these groups cannot be accessed by theswitch user function. The WebSEAL administrator must configurememberships in these groups before administrators use the switch userfunction. For configuration instructions and more information on thesegroups, see “Part 1: Configuring user access” on page 74

4. When access to the switch user function has been granted, WebSEAL calls theappropriate switch user shared library to perform the special switch userauthentication.WebSEAL supports a number of different authentication mechanisms. Eachauthentication mechanism has a corresponding switch user authenticationmechanism. WebSEAL provides shared libraries that contains the special switchuser mechanisms. Before switch user authentication can be used, the WebSEALadministrator must configure WebSEAL to use the necessary shared libraries.For more information, see “Part 2: Configuring switch user authenticationmechanisms” on page 75.

Note: Switch user authentication can also be performed by a custom switchuser CDAS library. For more information, see “Developing a customCDAS for switch user” on page 81.

5. When authentication of the designated user succeeds, the switch userauthentication mechanism returns a valid credential for the user — withoutrequiring the user password for input.

6. WebSEAL manipulates the contents of the appropriate entry in the WebSEALsession cache by:a. Placing the user’s credential into a new cache data structure.b. Removing the administrator’s WebSEAL session cache data and storing it in

a separate location.c. Inserting the user cache data, including the user’s credential, in place of the

administrator’s cache data.7. WebSEAL sends a redirect to the browser for the destination URL supplied in

the switch user form.The request is processed normally, using the user’s credential, and the URL isaccessed.

8. The administrator can continue to make other requests. All authorizationdecisions for these requests are based on the credential of the user.When using switch user functionality, administrators might need to establishand manage sessions with additional applications. These sessions need to beestablished using the identity of the new user. To enable this, the new usercredential also contains a new User Session ID. This User Session ID is used,for example, when troubleshooting the user’s ability to access and useadditional Web resources.For more information on WebSEAL session caches, see “Enabling user sessionid management” on page 228 and “The WebSEAL session/credentials cachestructure” on page 11.


9. The administrator ends the switch user session using the standard Tivoli AccessManager /pkmslogout utility. Upon successful log out:a. The user’s cache data is deleted.b. The administrator’s original cache data (and credential) is restored.c. The administrator is returned to the original page from which the switch

user form was requested.

The authorization service uses the original credential of the administrator forall subsequent requests.

Configuration procedureThe WebSEAL administrator must complete several configuration steps beforeadministrators can use the switch user functionality. To configure switch user,complete the instructions in each of the following sections:1. “Part 1: Configuring user access”2. “Part 2: Configuring switch user authentication mechanisms” on page 753. “Part 3: Configuring the switch user HTML form” on page 77

This part is optional.4. “Part 4: Designing additional input forms” on page 79

This part is optional.5. “Part 5: Stopping and restarting WebSEAL” on page 79

Part 1: Configuring user accessDuring WebSEAL installation, the WebSEAL configuration process automaticallycreates several groups for use by the switch user functionality. The WebSEALadministrator controls switch user capability by adding users to the groups.

To configure user access, complete the following steps:1. Add users to the su-admins group.

To use switch user function, a user must be a member of a specialadministrative group called su-admins. This group is automatically created bydefault during installation of a WebSEAL server. There are no users in thisgroup by default. The WebSEAL administrator must manually add users to thisgroup. Typically, only administrative users are added to this group.Users who have been granted membership in su-admins can switch user tomost other user identities, but cannot switch to the identity of any other userthat is also a member of the su-admins group . Thus, once an administrator isgranted switch user privileges by being added to su-admins, theadministrator’s account is protected from access by any other user that gainsswitch user privileges.

2. Add users to the su-excluded groupThis group contains the names of users whose identities should not be accessedthrough the switch user capability. During WebSEAL installation, the WebSEALconfiguration process automatically creates this group. There are no users inthis group by default. WebSEAL administrator typically add to this group thenames of users who are not members of the administrative group su-admins,but for whom switch user access should still be blocked

When switch user is used, WebSEAL also checks the memberships of the TivoliAccess Manager group called securitygroup. This group contains the name of theTivoli Access Manager administrative user sec_master, plus a number of WebSEALprocesses that must be excluded from access through switch user capability.


This group is automatically created by default during installation of a WebSEALserver. The following identities are automatically added to this group duringinstallation:v sec_master — the Tivoli Access Manager administratorv acld – the Tivoli Access Manager authorization server daemonv webseald — the WebSEAL daemon

WebSEAL administrators should not add any users to the securitygroup group. Tocontrol user access to switch user, use either su-admins or su-excluded.

Part 2: Configuring switch user authentication mechanismsTivoli Access Manager supplies a single, built-in, switch user library thatimplements the switch user authentication mechanism. The switch user librarydiffers from the standard authentication libraries. The library specifies anauthentication mechanism that takes a supplied user identity and returns a validcredential for that user without requiring the user password for input.

The built-in switch user shared library provided with Tivoli Access Manager iscalled libsuauthn (on UNIX systems) and suauthn (on Windows systems). Theplatform-specific shared library file names are:

Solaris Operating Environment (Solaris) libsuauthn.so

AIX libsuauthn.a

HP-UX libsuauthn.sl

Windows suauthn.dll

The built-in library supports the following authentication mechanisms:v su-passwordv su-token-cardv su-certificatev su-http-requestv su-cdsso

The authentication mechanisms are specified in the [authentication-mechanisms]stanza of the webseald.conf configuration file. There is a separate entry for eachsupported authentication mechanism.

By default, all of the switch user authentication mechanisms are disabled in theconfiguration file. For example:[authentication-mechanisms]#su-password = <su-password-library>#su-token-card = <su-token-card-library>#su-certificate = <su-certificate-library>#su-http-request = <su-http-request-library>#su-cdsso = <su-cdsso-library>

The configuration steps for enabling authentication consist primarily of editing theappropriate configuration file name=value entries. However, when the WebSEALdeployment supports more than one authentication mechanism, and theadministrator wants to use switch user functions for more than one type ofsupported mechanism, an additional step is required. In this case, additional copiesof the default switch user shared library must be made.


The following instructions are separated into two parts. The first part describeshow to configure a single switch user authentication mechanism. The second partdescribes how to configure multiple switch user authentication mechanisms. Usethe instructions that are appropriate for your deployment.

Configuring a single switch user authentication mechanism

To enable a single switch user authentication mechanism, complete the followingsteps:1. Edit the appropriate entry in webseald.conf. Remove the comment character (#)

at the start of the line.2. Enter the name of the switch user authentication library.

For example, on a Solaris system, prior to the configuration of switch user,webseald.conf for a WebSEAL server that was configured to support onlypassword authentication would contain the entries:[authentication-mechanisms]passwd-ldap = /opt/PolicyDirector/lib/libldapauthn.so.....#su-password = <su-password-library>#su-token-card = <su-token-card-library>#su-certificate = <su-certificate-library>#su-http-request = <su-http-request-library>#su-cdsso = <su-cdsso-library>

The switch user library specified by the su-password entry corresponds to theauthentication library specified by passwd-ldap. The entry shown below in boldfont shows the modified entry:[authentication-mechanisms]passwd-ldap = /opt/PolicyDirector/lib/libldapauthn.so.....su-password = /opt/PolicyDirector/lib/libsuauthn.so#su-token-card = <su-token-card-library>#su-certificate = <su-certificate-library>#su-http-request = <su-http-request-library>#su-cdsso = <su-cdsso-library>

Configuring multiple switch user authentication mechanisms

The default switch user shared library, libsuauthn (UNIX) or suauthn (Windows)supports multiple authentication mechanisms. In the configuration file, however,each entry for a configured switch user authentication library must be uniquelynamed, even though the same shared library is used for multiple authenticationmethods.

In the following example, for a Solaris platform, an existing environment has twoauthentication methods enabled:v Forms authentication using the built-in libldapauthn libraryv Certificate authentication using the built-in libsslauthn library

The configuration file entries are:[authentication-mechanisms]passwd-ldap = /opt/PolicyDirector/lib/libldapauthn.socert-ssl = /opt/PolicyDirector/lib/libsslauthn.so

To enable switch user authentication mechanisms for both of these authenticationmethods, complete the following steps:


1. Make a copy of the switch user shared library for each authenticationmechanism. The administrator can choose any name for each copy, as long aseach copy is uniquely named.For example, to support switch user for both forms authentication andcertificate authentication:# cp libsuauthn.so libsuformauthn.so# cp libsuauthn.so libsucert.so

2. Edit the appropriate entries in webseald.conf. Remove the comment character(#) at the start of the entry for each supported switch user authenticationmechanism.

3. For each uncommented entry, enter the name of the uniquely-named copy ofthe switch user authentication library.The updated configuration file entries for the example above are:[authentication-mechanisms]passwd-ldap = /opt/PolicyDirector/lib/libldapauthn.socert-ssl = /opt/PolicyDirector/lib/libsslauthn.sosu-password = /opt/PolicyDirector/lib/libsuformauthn.sosu-certificate = /opt/PolicyDirector/lib/libsucert.so

The environment is now expanded to support switch user functionality for bothauthentication methods.

Note: If your environment includes a custom CDAS authentication mechanism,you must provide the same functionality. See “Developing a custom CDASfor switch user” on page 81.

Part 3: Configuring the switch user HTML formThis part is optional.

WebSEAL provides a default HTML form that the administrator accesses in orderto use the switch user function. The default form can be used withoutmodification. Optionally, the form can be edited for customized appearance andfunctionality.

The default form is named switchuser.html. The name of this file can be modified.

Form contents and location

The form contains requests for:v User name

The name of the user whose credentials the administrator wants to access.v Destination URL

This page appears after a successful switch user operation.v Authentication method

The authentication method parameters specify which authentication mechanismWebSEAL uses to build the user credential.

Each of these entries is required. WebSEAL verifies that all required data is presentin the submitted form. If data is missing, the form is returned to the administratorwith a descriptive message. When all required data is present, WebSEAL submitsdata from the switch user form data to the /pkmssu.form action URL.


Note: Only members of the su-admins group can invoke the form. An ACL is notrequired on this file. WebSEAL performs an internally hard-coded groupmembership check. WebSEAL returns a 404 ″Not Found″ error when thegroup membership check fails.

The full path name for the switch user form is defined in webseald.conf. This pathname can be modified.

The values for three parameters are combined to build the full pathname:v The server-root parameter located in the [server] stanza specifies the root of

the server hierarchy.v The mgt-pages-root parameter in the [acnt-mgt] stanza specifies the localization

sub-directory.v The switch-user parameter in the [acnt-mgt] stanza specifies the name of the

switch user file.

For example, on a UNIX system, the webseald.conf entries would be:[server]server-root = /opt/pdweb/www....[acnt-mgt]mgt-pages-root = lib/html/<LANG>switch-user = switchuser.html

The value of the LANG directory is specific to the locale. You can determine thefull path to the switch user form by combining the values. For example, on aUNIX system, with a U.S. English locale where the LANG directory is called ″C″,the full path would be:/opt/pdweb/www/lib/html/C/switchuser.html

The default value of server-root on Windows is:C:\Program Files\Tivoli\PDWeb\www

The full path on Windows would be:C:\Program Files\Tivoli\PDWeb\www\lib\html\C\switchuser.html

How to customize the HTML form

To customize the switch user form, open the form for editing, and complete thefollowing steps:1. Specify the location and contents of the destination URL.

You can configure this as hidden input containing an appropriate home page ora successful switch user confirmation page.

2. Specify the authentication methodsYou can configure this field as hidden input. Valid values for the authenticationmethod include:su-basu-formssu-certificatesu-token-cardsu-http-requestsu-cdsso

The methods in the list above map directly to authentication mechanismsspecified in the webseald.conf configuration file. Note, however, that the su-ba


and su-forms methods both map to the su-password authenticationmechanism. Both basic authentication (ba) and forms authentication (forms) usethe su-password authentication library. Note that a WebSEAL deployment cansupport basic authentication without supporting forms authentication. Thusseparate configuration values are maintained for each authentication type(su-ba and su-forms).

Part 4: Designing additional input formsThis part is optional.

You can design additional forms to validate or process data to be submitted to/pkmssu.form. These forms can be used to assist the administrator by populatingsome of the entries on the switch user form.

Some examples are:v An administrator might have chosen to have different destination URLs, to be

accessed based on the user identity. Another form could be written to build andpresent a list of these URLs, from which the administrator could select theappropriate entry.

v A form could be developed to call another program, such as a CGI script, tosupply a list of user identities for whom switch user is allowed. This list couldhelp administrators determine if access to a user identity through switch user isallowed.

v A form could be developed to display a list of user identities for whom switchuser is not allowed. This list would be based on the memberships of thesu-excluded and securitygroup groups.

Part 5: Stopping and restarting WebSEALTo activate the new configuration changes you must stop and restart WebSEAL.This enables WebSEAL to use the new values that were specified to webseald.confin “Part 1: Configuring user access” on page 74 and “Part 2: Configuring switchuser authentication mechanisms” on page 75.

The methods for stopping and restarting the WebSEAL server are described in“Starting and stopping WebSEAL” on page 20.

Using switch userWhen the configuration steps in the previous section have been completed,WebSEAL administrators can use the switch user function.

To use the switch user function, complete the following steps:1. Log in as a user who has permission to access the switch user function.

This function is usually accessed by administrators. The user must be amember of the su-admins group.

2. Invoke the switch user HTML form.The default file name is switchuser.html. For information on the full path name,see “Part 3: Configuring the switch user HTML form” on page 77.

3. On the form, specify:v The name of the user identity that you want to assume.v A destination URLv An authentication method


This action results in a POST request being sent to /pkmssu.form. WebSEALsends a redirect to the browser for the destination URL supplied in the switchuser form. The request is processed using the user’s credential, and the URL isaccessed.

4. Make other requests as necessary.All authorization decisions for these requests are based on the credential of theuser.

5. When finished, end the switch user session by using the standard Tivoli AccessManager /pkmslogout utility.

For more information on how the switch user function works, see “Overview ofthe switch user function” on page 72.

Additional switch user featuresThis section describes switch user support for additional features such asreauthentication, step-up authentication, user session management, and auditing.

Session cache timeoutThe functionality of the configured WebSEAL session cache inactivity and lifetimetimeout values is not affected by the switch user operation. The inactivity andlifetime timers are associated with the administrator’s session cache entry and notthe cache data that changes during a switch user operation.

The inactivity timer continues to be reset while the administrator performsrequests as the ″switched-to″ user. When the administrator ends the switch usersession, the inactivity is still valid for the re-established administrator session.

The lifetime value is not extended because of a switch user operation. It is possiblefor the lifetime timeout of the session cache entry to expire during a switch useroperation. If this timeout occurs, the session cache is deleted and the administratoris logged off. The administrator must reauthenticate and begin the switch useroperation again.

Step-up authenticationThe shared library specification can take additional arguments in the form:<library>& <arg1> <arg2> .... <argx>

You can designate step-up authentication levels using the –l option followed by thelevel number. For example:su-password = /opt/PolicyDirector/lib/libsuformauthn.so& -l 1su-certificate = /opt/PolicyDirector/lib/libsucert.so& -l 0su-token-card = /opt/PolicyDirector/lib/libsucustom.so& -l 2

Note: The administrator must know the user’s password to successfully performstep-up authentication.

ReauthenticationWebSEAL reauthentication functionality is recognized by the switch user operation.If reauthentication is required during a switch user operation, the administratormust authenticate as the ″switched-to″ user.

Note: The administrator must know the ″switched-to″ user’s password tosuccessfully reauthenticate.


User session managementThe switch user operation supports user session management. The administratorhas a unique User Session ID. Additionally, during a switch user operation, aunique User Session ID exists for the ″switched-to″ user. The terminate single usersessions task and terminate all user sessions task perform as expected.

Tag-valueThe tag-value capability often used by a CDAS is recognized and supported by theswitch user functionality.

AuditingIt is possible to audit the administrator during a switch user operation. The switchuser functionality adds an extended attribute to the ″switch-to″ user credential thatidentifies the administrator. The extended attribute, as stored in the credential, iscalled tagvalue_su-admin:tagvalue_su-admin = <su-admin-name>

This extended attribute is available to any auditing mechanism.

Developing a custom CDAS for switch userThe switch user functionality also supports custom CDAS authenticationmechanisms. This support is important because an existing CDAS authenticationmechanism often returns additional information about the user that is incorporatedinto the user’s credential. A custom CDAS can be used to perform further checksregarding switch user capability, such as determining which users can switch userto other users’ identities, or specifying time periods when switch user capability isnot allowed.

If you are using the switch user feature in such an environment, you must write aspecial switch user CDAS that emulates the behavior of your existing CDAS whilesupporting the requirement of returning a credential without requiring the userpassword for input.

The Tivoli Access Manager CDAS API provides a set of identity components thatcan be used to pass client authentication information to the shared switch userCDAS library. This information is passed using a name/value list format, wherethe name is an identifier that specifies the value type.

The information is stored in the xnlist_t data type. Values can be accessed by usingthe utility function xnvlist_get().

Identity components appropriate for a switch user CDAS include:xauthn_su_methodxauthn_admin_namexauthn_admin_credxauthn_existing_credxauthn_usernamexauthn_qopxauthn_ipaddrxauthn_browser_info

The xauthn_browser_info, xauthn_qop, and xauthn_ipaddr identity componentsrepresent those of the administrator, not the ″switched to″ user. This data issupplied for any CDAS that must perform additional validations of theadministrator’s account.


Note: Refer to the IBM Tivoli Access Manager WebSEAL Developer’s Reference forcomplete information and reference material related to writing a customCDAS.

Configuring a custom CDAS for switch user

The following example expands on the example presented in “Part 2: Configuringswitch user authentication mechanisms” on page 75. The example adds a CDASmechanism to list of enabled authentication mechanisms. The example, for aSolaris platform, shows an existing environment that has three authenticationmethods enabled:v Forms authentication using the built-in libldapauthn libraryv Certificates authentication using the built-in libsslauthn libraryv Token authentication using a custom CDAS mechanism

In this example, the administrator wants to be able to use switch userauthentication for all three authentication methods. Thus, three additionalauthentication parameters for switch user must be enabled in the webseald.confconfiguration file. The third parameter represents the new custom CDAS librarythat was written to emulate the existing token CDAS and support the requirementsof switch user authentication:

The configuration file entries before enabling switch user for the threeauthentication mechanism are:[authentication-mechanisms]passwd-ldap = /opt/PolicyDirector/lib/libldapauthn.socert-ssl = /opt/PolicyDirector/lib/libsslauthn.sotoken-cdas = /opt/PolicyDirector/lib/libcustom.so

Note that the example token CDAS library is called libcustom.so. The new switchuser version of this token CDAS library will be called libsucustom.so

After adding the switch user authentication mechanism, the configuration fileentries are:[authentication-mechanisms]passwd-ldap = /opt/PolicyDirector/lib/libldapauthn.socert-ssl = /opt/PolicyDirector/lib/libsslauthn.sotoken-cdas = /opt/PolicyDirector/lib/libcustom.sosu-password = /opt/PolicyDirector/lib/libsuformauthn.sosu-certificate = /opt/PolicyDirector/lib/libsucert.sosu-token-card = /opt/PolicyDirector/lib/libsucustom.so

Notice the following changes:v The new entry for the CDAS has the name su-token-card. The value for this

entry is the full pathname to the CDAS that has been extended to supportswitch user.

v For the non-CDAS authentication methods in this example, remember that:– The su-forms authentication method supplied in the switch user form is

mapped to the su-password authentication mechanism parameter inwebseald.conf.

– The supplied libsuauthn library has been renamed for both the Forms andcertificate mechanisms.


Configuring WebSEAL server-side request caching

BackgroundIn past versions of WebSEAL using Forms authentication, WebSEAL created acache entry for the URL of a user request whenever authentication was required.Upon successful authentication, WebSEAL sent an HTTP redirect to the browserthat included this URL. The browser then followed the redirect to the originalresource location.

The limitation of this implementation became apparent when, for example, a POSTrequest was interrupted by a session timeout that prompted a re-authenticationprocess. Since WebSEAL only cached the URL of the original request, the POSTdata (including the METHOD and Message Body) were lost during the HTTPredirect. The user had to rebuild the POST request.

WebSEAL now caches a more complete set of request data and uses this cacheddata to rebuild the request during the HTTP redirect, if a re-authenticationrequirement interrupts the completion of the request processing. This solutionparticularly benefits POST and PUT requests, because these requests types caninclude a variety of information fields.

Server-side caching process flowWhen an authentication requirement interrupts a request, WebSEAL caches allinformation necessary to rebuild the request during the HTTP redirect that followsafter re-authentication. Cached request data includes URL, METHOD, MessageBody, query strings, and all HTTP headers (including cookies). This data istemporarily stored in the WebSEAL credentials/session cache.

Upon successful authentication (or re-authentication), WebSEAL sends an HTTPredirect to the browser. The browser follows the redirect to the original URLcontained in the redirect. WebSEAL intercepts the redirect and rebuilds the requestusing the cached data. The rebuilt request is delivered to the URL destination.

The following diagram illustrates a typical server-side request caching processflow:1. User successfully logs in (Forms authentication) and submits an HTTP request

for a resource involving a CGI-generated data form. WebSEAL creates andcaches a session ID for the user.

2. The back-end application server returns the form to the user.3. During the time it takes the user to fill in the form, the configured session

timeout for the user expires. WebSEAL removes the user’s credentials cacheentry and session ID.

4. The user eventually submits the completed form (POST). WebSEAL finds nocache entry for the user, creates a new cache, and temporarily caches thecomplete information contained in the POST request.

5. Because WebSEAL finds no credentials for this user, the user must authenticate.WebSEAL sends a login form to the user.

6. The user returns the completed login form to WebSEAL (POST). Authenticationis successful. The cache now contains the user’s credentials, as well as thecached request.

7. WebSEAL sends an HTTP redirect back to the browser containing the URL ofthe originally requested resource.


8. The browser follows the redirect (GET). WebSEAL intercepts the redirect andrebuilds the original request (form) using the cached POST data. The restoredrequest (form) is delivered to the URL designation.

Configuring server-side caching parametersAlthough request caching occurs automatically for WebSEAL Forms authentication,you can specify limits to the size of the requests that WebSEAL caches. Therequest-max-cache and request-body-max-read parameters are located in the[server] stanza of the webseald.conf configuration file.

request-max-cache

The request-max-cache parameter specifies the maximum amount of data, in bytes,that WebSEAL caches for each request. The minimum acceptable value is 512 bytes.If the request-max-cache parameter is set to a lower value, WebSEAL defaults to512 bytes. For example:[server]request-max-cache = 8192

As described below, you must consider the value of the request-body-max-readparameter when specifying request-max-cache.

request-body-max-read

Client WebSEALWeb

ApplicationServer

junction

login and request request

application form

session time out

submit form cacherequest data

Forms login page

authenticate

HTTP redirect

browser followsredirect (GET)

original requestdata received

WebSEAL interceptsand suppliescached data

1

2

4

5

6

7

8

3

Figure 15. Example WebSEAL request caching process flow


The request-body-max-read parameter specifies the maximum size of the requestmessage body, in bytes, that WebSEAL caches for each request. This parameterspecifically impacts request types that contain message body data, such as POSTand PUT requests. For example:[server]request-body-max-read = 4096

This parameter can be set to equal zero. This parameter does not limit themaximum POST size (which is unlimited) for requests that do not requireauthentication.

Note that the request-max-cache parameter value must correctly accommodate therequest-body-max-read value plus the size of all other components of the request.For example, if you specify 2048 bytes as the cache limit for request messagebodies and anticipate the maximum size of all other request components (such asheaders and cookies) to be 4096 bytes, then:v Set request-body-max-read = 2048v Set request-max-cache = 2048 + 4096 = 6144

If either request-body-max-read or request-max-cache settings are exceeded duringa request, WebSEAL aborts the request caching process, returns a Request CachingFailed error message to the browser, and writes the error to the log file. You cancustomize this error message. See “Managing custom HTTP error message pages”on page 31.

Notes and limitationsv The request-body-max-read value also impacts dynamic URL requests because

the query portion of the POST request is contained in the request message body.v The request-body-max-read value also impacts Forms authentication by placing

a limit on the size of the POST data that is processed during authentication.v The request-body-max-read and request-max-cache parameters protect the

WebSEAL from denial of service attack types that cause WebSEAL to cache moredata than it can handle.

v Server-side request caching will not function correctly if the user session timeout value expires during the login process. In this situation, the cache entry islost.

v Server-side request caching can cause limitations with the browser’s ability tomanipulate the resource. The browser is unaware that WebSEAL has rebuilt theHTTP redirect. Therefore the browser’s reload/refresh function and cachingability can be hindered.

Handling UTF-8 encoded charactersAccording to HTTP specifications, browsers are limited to the character set that canlegally be used within a URL. This range is defined to be the printable charactersin the ASCII character set (between hex code 0x20 and 0x7e). For non-Englishlanguages, and other purposes, characters outside the printable ASCII character setare often required in URLs. These characters can be encoded using printablecharacters for transmission and interpretation.

There are a number of different encoding methods for transmitting charactersoutside the permitted range. Despite the HTTP specifications, there are also manycommercial Web servers that simply tolerate and accept characters outside the legalrange. WebSEAL, acting as a Web proxy, must be able to handle all these cases.


The most widely accepted (″de facto standard″) character encoding method isUTF-8. Many current commercial Web servers can be configured to accept UTF-8encoding.

The utf8-url-support-enabled parameter in the [server] stanza of thewebseald.conf configuration file controls how WebSEAL interprets URLs sent frombrowsers. The parameter recognizes three settings:v yes

WebSEAL only recognizes UTF-8 encoding in URL strings and decodes theinformation into native character set (local code page). Other encodingtechniques, such as double-byte character set (DBCS) and Unicode, are notaccepted.

v no

WebSEAL does not recognize UTF-8 encoding in URL strings. Any UTF-8encoded information is not interpreted correctly. Other encoding techniques areaccepted.

v auto

WebSEAL attempts to distinguish between UTF-8 and other forms of languagecharacter encoding (DBCS and Unicode). WebSEAL correctly processes anycorrectly constructed UTF-8 encoding. If the encoding does not appear to beUTF-8, then the coding is processed as DBCS or Unicode.

When utf8-url-support-enabled is set to ″yes″ (default), WebSEAL assumes URLscan include UTF-8 encoded characters. These UTF-8 characters are then validatedand taken into account when determining access rights to the URL. The URL isnormalized (that is, encoded characters are converted to their local code pageequivalents), and ACL checking is applied to the normalized URL. The defaultsetting does not allow URLs with DBCS or Unicode characters of the form%uXXXX. The default setting is the recommended configuration for WebSEAL.

Some existing applications and Web servers do not function correctly withWebSEAL if UTF-8 support is enabled, as these applications use DBCS (such asShift-JIS) in the URL, or other encoding mechanisms.

If this is the case for your deployment, you need to perform the following twotasks:1. Edit webseald.conf and set the new parameter as follows:

utf8-url-support-enabled = no

2. Ensure that all junctioned servers do NOT accept UTF-8 encoded URLs. It isimportant from a security perspective, that WebSEAL is interpreting URLs inthe same manner as the junctioned servers.

The recommended deployment strategy is as follows:1. Unless required for content purposes, immediately check and set the

default-webseal ACL on existing production deployments to NOT allowunauthenticated ″r″ access. This limits security exposure to users who do havea valid account within the Tivoli Access Manager domain.

2. Ensure that the utf8-url-support-enabled parameter is set to the default valueof ″yes″.

3. Test your applications. If they function correctly, use this setting.4. If any applications fail with ″Bad Request″ errors, retry the application with the

utf8-url-support-enabled parameter set to ″no″. If this works, you may deploy


with the parameter set to ″no″. However, you should also ensure that nojunctioned Web server is configured to accept UTF-8 encoded URLs.

Preventing vulnerability caused by cross-site scriptingCross-site scripting refers to a technique used to cause Web server vulnerability byembedding malicious code into the URLs of Web requests. WebSEAL providescertain built-in protection for this type of vulnerability and allows you to furtherrefine the protection by configuring URL string filtering.

Note: The term ″cross-site scripting″, although accepted by the industry, does notentirely describe the range of issues involving embedded malicious code.

BackgroundCross-site scripting is a specific type of Web Server vulnerability created when aclient URL request includes embedded malicious scripting. For example(JavaScript):<script>malicious_code</script>

Other scripting tags that could be used to create vulnerability include <OBJECT>,<APPLET>, and <EMBED>. When a user clicks on a link containing the maliciouscode (or enters such a URL directly), the script is executed when the HTML is readby the user’s browser.

For example, an attack can occur when a user clicks on a link that contains thefollowing URL:https://<webseal-host>/<script>malicious_code</script>

In this example, the object is not found and WebSEAL responds by returning a 404″Page Not Found″ HTML error page. This error page happens to include the URLcontaining the malicious JavaScript. The browser interprets the URL and executesthe script.

Refer to the following CERT advisory for complete information about themechanics of cross-site scripting and general preventative measures:

http://www.cert.org/advisories/CA-2000-02.html

Configuring URL string filteringThe problem of cross site scripting—and embedded malicious code in general—ishandled in two ways.

WebSEAL now encodes angle brackets (< >) in re-directed URLs. The encoding canhelp prevent normal interpretation of scripts by the browser.

In addition, you can now add a new stanza to the webseald.conf configuration file.The stanza, [illegal-url-substrings], can contain parameters specifying one or morestring fragments. For example:[illegal-url-substrings]substring = <scriptsubstring = <appletsubstring = <embed


If WebSEAL detects any configured string fragment in the requested URL, the URLis deemed illegal and not accepted. WebSEAL returns a 400 ″Bad Request″ errorpage.

This flexible mechanism allows you to handle future attack schemes by addingadditional substring values.

WebSEAL, by default, filters strings containing <script. You do not need tomanually add the [illegal-url-substrings] stanza to filter this particular string.However, when you require additional filtering, you must create the stanza and listall substrings individually, as in the example above.

You can completely disable the URL string filtering feature (including the defaultbehavior) by placing an empty [illegal-url-substrings] stanza into thewebseald.conf file.

Functional notes:v Substrings are located using a case insensitive searchv Substring filtering accommodates multi-byte charactersv The mechanism protects junctioned servers

Suppressing server identityHTTP server responses normally contain the identity and version of the server:content-type: text/htmldate: Tue, 05 Mar 2002 02:34:18 GMTcontent-length: 515server: WebSEAL/3.9.0last-modified: Thu, 21 Feb 2002 08:03:46 GMTconnection: close

For security reasons, you might want WebSEAL to suppress this information in itsresponses to clients. To suppress server identity in HTTP server responses, set thesuppress-server-identity parameter in the [server] stanza of the webseald.confconfiguration file to ″yes″:[server]suppress-server-identity = yes

The default setting is ″no″.

Configuring cryptographic hardware for encryption and key storageWebSEAL, using GSKit for SSL communication and key management, providesinterface support for cryptographic hardware. Cryptographic hardware can provideone or both of the following features:v Accelerated and secure SSL encryption and decryption tasks for performance

improvements during multiple online transactionsv Accelerated and secure digital certificate key storage and management for highly

secure architecture during online transactions

WebSEAL and GSKit support the following interfaces to this cryptographichardware:v BHAPI (RSA Security, Inc.’s API supporting its BSAFE product)v PKCS#11 (Public Key Cryptographic Standard)


Some cryptographic hardware supports both interfaces; some cryptographichardware supports only one of the interfaces.

In general, WebSEAL (and GSKit) uses the BHAPI interface to support encryptionand decryption. WebSEAL (and GSKit) uses PKCS#11 to support bothencryption/decryption and key storage.

WebSEAL supports several hardware devices for selected platforms. Consult theIBM Tivoli Access Manager for e-business Release Notes to obtain the latest informationon platform support for these hardware cards.

Cryptographic accelerator cards

v nCipher nForce 300v Rainbow CryptoSwift eCommerce Acceleratorv IBM 4960

Key Storage

v nCipher nForce 300v IBM 4758

The following matrix illustrates the relationship between functionality and interfacesupport for each of these cards:

BHAPI PKCS#11

SSL Acceleration v Rainbow CryptoSwift

v nCipher nForce 300

v IBM 4960


Key Storage v IBM 4758


The Rainbow CryptoSwift and nCipher nForce 300 (using BHAPI) are used forpublic key operations (RSA key decryption). Keys are not stored on the acceleratordevice, but are stored in the pdsrv.kdb file. Accelerator devices are used to speedup the public key cryptographic functions of SSL. Hardware acceleration frees upthe server processor, increases server throughput, and shortens wait time. TheRainbow CryptoSwift and nCipher nForce accelerators incorporate fasterperformance by providing more concurrent secure transactions.

With the PKCS#11 interface, RSA keys are stored on a cryptocard to ensureauthentication. The IBM 4758 performs only as a key storage device. The nCiphernForce device can either perform just acceleration or it can perform bothacceleration and key storage with PKCS#11 support. The IBM 4758 and nCiphernForce devices (with PKCS#11 support) ensure that keys are completelyinaccessible to the outside world. Keys are never revealed in an unencrypted formbecause they are stored on the hardware, providing enhanced key protection andauthentication.

Hardware cryptographic acceleration and key storage apply to the followingWebSEAL connections:v Browser to WebSEALv WebSEAL to back-end junctioned server


Conditions and prerequisitesIBM 4758–023

On Windows NT/2000, the IBM 4758–023 cryptographic card has an accesslimitation of 32 worker threads. Therefore, WebSEAL must be configured to use nomore than 32 worker threads. The recommendation is 30 worker threads. Thedefault setting for worker threads at WebSEAL installation time is 50 workerthreads. Refer to “Managing worker thread allocation” on page 56 for informationabout worker thread configuration.

Additional monitoring threads are used for any junctions configured with the –Koption (WebSEAL authenticates with a client-side certificate) where the key(certificate) is stored on the IBM 4758 hardware. In this situation, further reducethe number of worker threads by one for each SSL –K junction using keys storedon the IBM 4758 card.

Configuring WebSEAL for cryptographic hardware over BHAPI1. Install the device driver for the specific cryptographic hardware you are using.2. GSKit (and therefore WebSEAL) detects the hardware and automatically uses it.

If required, you can configure WebSEAL to disable the automatic use of thehardware for SSL acceleration over BHAPI. The disable-ncipher-bsafe anddisable-rainbow-bsafe parameters are available in the [ssl] stanza of thewebseald.conf configuration file. By default, both parameters are set to ″no″ (thatis, WebSEAL automatically uses the hardware for SSL acceleration over BHAPI).For example:[ssl]disable-ncipher-bsafe = nodisable-rainbow-bsafe = no

Configuring WebSEAL for cryptographic hardware overPKCS#11

Install the cryptographic card and device driverFollow the instructions provided by the specific vendor to install the cryptographiccard and its device driver (with PKCS#11) for the specific cryptographic hardwareyou are using. This procedure involves shutting down and restarting the computermachine.

Create a token device label and password to store WebSEALkeysIn the context of cryptographic hardware and the associated device drivers, atoken is a logical device that acts as a ″container″ for storing key, data, andcertificate objects. Key objects can include public keys and private keys. When youconfigure a cryptographic card to perform key storage (using the PKCS#11interface), you must define one or more tokens (or ″containers″) that store keys fordifferent situations.

When you configure a cryptographic card to perform key storage tasks forWebSEAL (GSKit), you must specify a token label (and password) that representsthe token device that stores the WebSEAL public/private key pair. WebSEAL sendsthe public key in the server-side certificate that it uses to authenticate itself to anyclient.


Use the instructions provided with the installed cryptographic hardware to create alabel for the token device that stores the WebSEAL key.

For example:token = websealtokenpassword = secret

Configure iKeyman to use the PKCS#11 module (shared library)The GSKit iKeyman utility needs to be configured for the PKCS#11 device module(shared library) of the installed cryptographic hardware device. This moduleallows iKeyman to understand the the hardware device’s WebSEAL token label,the password (or PIN) for the token, and the key label of any WebSEAL key storedon the device.

Configure the GSKit iKeyman utility (gsk5ikm) to use the PKCS#11 module(shared library) for the installed cryptographic hardware device:

Locate the file ikmuser.sample in the following directory:

Solaris and HPUX: /opt/ibm/gsk5/classes

AIX: /usr/opt/ibm/gskkm/classes

Windows: C:\Program Files\ibm\gsk5\classes

Copy and rename this file to ikmuser.properties.

Edit this new file by adding the following appropriate line that specifies thelocation of the module (shared library) for the installed cryptographic hardware:

UNIX:

nCipher nForce:DEFAULT_CRYPTOGRAPHIC_MODULE=/opt/nfast/toolkits/pkcs11/libcknfast.so

IBM 4758-023 and IBM 4960:DEFAULT_CRYPTOGRAPHIC_MODULE=/usr/lib/pkcs11/PKCS11_API.so

Windows:

nCipher nForce:DEFAULT_CRYPTOGRAPHIC_MODULE=C:\\nfast\\toolkits\\pkcs11\\cknfast.dll

IBM 4758-023:DEFAULT_CRYPTOGRAPHIC_MODULE=C:\\Program Files\\ibm\\PKCS11\\bin\\nt\\cryptoki.dll

When the appropriate shared library is configured, the GSKit iKeyman utilityincludes a new menu option: ″Cryptographic Token″. Now you can use iKeymanto create, store, and manipulate keys for WebSEAL on the cryptographic hardware.

Open the WebSEAL token device using iKeyman1. Start the iKeyman utility (gsk5ikm).

A new additional menu option, ″Cryptographic Token″, appears.2. From the Cryptographic Token menu, select Open.

The Open dialog box appears.


3. Select the token label previously created for WebSEAL (for this example,″websealtoken″).

4. Specify the same password used when you created the token label using thevendor instructions for the installed hardware (for this example, ″secret″).

5. Additionally, if you want to open an existing secondary key database (for keydata not stored on the cryptographic hardware—such as CA root certificates),check ″Open Existing Key Database″.

6. Browse for and select the default WebSEAL key database:UNIX:/opt/pdweb/www/certs/pdsrv.kdb

Windows:C:\Program Files\Tivoli\pdweb\www\certs\pdsrv.kdb

7. Click OK.The Token Password dialogue box appears.

8. Enter the default password ″pdsrv″. Click OK.9. The main iKeyman window returns.

Request and store the WebSEAL server certificate1. Follow instructions in the Secure Sockets Layer Introduction and iKeyman User’s

Guide to request a secure, signed digital certificate for WebSEAL from aCertificate Authority (CA).

2. Follow instructions in the Secure Sockets Layer Introduction and iKeyman User’sGuide to receive the WebSEAL certificate from the CA and store it in a keydatabase. When performing this procedure, select the token device representingthe cryptographic hardware as the storage location for the certificate.

3. When it is stored on the token device, the key (certificate) appears (forexample) as:websealtoken:webseal

The WebSEAL key is stored on the cryptographic hardware and assigned to thetoken device labeled ″websealtoken″.

Configure WebSEAL (and GSKit) to use the PKCS#11 sharedlibraryConfigure WebSEAL to use the PKCS#11 module (shared library).

Edit the webseald.conf configuration file and add the appropriate line identifyingthe location of the shared library under the [ssl] stanza:

UNIX

nCipher nForce:[ssl]pkcs11-driver-path = /opt/nfast/toolkits/pkcs11/libcknfast.so

IBM 4758-023 and IBM 4960:[ssl]pkcs11-driver-path = /usr/lib/pkcs11/PKCS11_API.so

Windows

nCipher nForce:


[ssl]pkcs11-driver-path = C:\nfast\toolkits\pkcs11\cknfast.dll

IBM 4758-023:[ssl]pkcs11-driver-path = C:\Program Files\ibm\PKCS11\bin\nt\cryptoki.dll

In addition, specify the names of the token label and password under the same[ssl] stanza:

For this example:[ssl]pkcs11-token-label = websealtokenpkcs11-token-pwd = secret

Modify the WebSEAL server certificate labelConfigure WebSEAL to use this new hardware-based key rather than the defaultkey in its communications with browser clients. Modify the webseal-cert-keyfile-label parameter in the [ssl] stanza of the webseald.conf configuration file todesignate the new key label.[ssl]webseal-cert-keyfile-label = <token-name>:<key-label>

For this example:[ssl]webseal-cert-keyfile-label = websealtoken:webseal

Disable acceleration mode for nCipher nForce 300If you want to use the nCipher nForce 300 device only for key storage, and notSSL acceleration, you can configure WebSEAL to disable the automatic use of thisdevice for BHAPI acceleration. The disable-ncipher-bsafe parameter is available inthe [ssl] stanza of the webseald.conf configuration file.

To disable automatic SSL acceleration over the BHAPI interface, set this parameterto ″yes″. For example:[ssl]disable-ncipher-bsafe = yes

By default, this parameter is set to ″no″ (that is, WebSEAL automatically uses thehardware for SSL acceleration over the BHAPI interface).

Restart WebSEALYou must restart WebSEAL for all cryptographic hardware configuration to takeeffect.

You can verify that WebSEAL is using the cryptographic hardware by examiningentries contained in the msg_webseald.log file.

Problem determination tools for WebSEALThe following problem determination tools for WebSEAL are discussed in the IBMTivoli Access Manager Problem Determination Guide.v statistics utilityv pdadmin trace command


Chapter 4. WebSEAL security policy

This chapter contains information that describes how you can configure andcustomize WebSEAL security policy.

Topic Index:v “WebSEAL-specific ACL policies”v “Three strikes login policy” on page 96v “Password strength policy” on page 98v “Authentication strength POP policy (step-up)” on page 101v “Network-based authentication POP policy” on page 105v “Quality of protection POP policy” on page 108v “Handling unauthenticated users (HTTP / HTTPS)” on page 108

WebSEAL-specific ACL policiesThe following security considerations apply for the /WebSEAL container in theprotected object space:v The WebSEAL object begins the chain of ACL inheritance for the WebSEAL region

of the object spacev If you do not apply any other explicit ACLs, this object defines (through

inheritance) the security policy for the entire Web spacev The traverse permission is required for access to any object below this point

Refer to the IBM Tivoli Access Manager Base Administrator’s Guide for completeinformation about Tivoli Access Manager ACL policies.

/WebSEAL/<host>This sub-directory entry represents the beginning of the Web space for a particularWebSEAL server instance. The following security considerations apply for thisobject:v The traverse permission is required for access to any object below this pointv If you do not apply any other explicit ACLs, this object defines (through

inheritance) the security policy for the entire object space on this machine

/WebSEAL/<host>/<file>This sub-directory entry represents the resource object checked for HTTP access.The permissions checked depend on the operation being requested.

WebSEAL ACL permissionsThe following table describes the ACL permissions applicable for the WebSEALregion of the object space:

Operation Description

r read View the Web object

x execute Run the CGI program.

d delete Remove the Web object from the Web space.


Operation Description

m modify PUT an HTTP object. (Place - publish - an HTTP object in theWebSEAL object space.)

l list Required by policy server to generate an automated directorylisting of the Web space.

This permission also governs whether a client can see thedirectory contents listing when the default index.html page isnot present.

g delegation Assigns trust to a WebSEAL server to act on behalf of a clientand pass requests to a junctioned WebSEAL server.

Default /WebSEAL ACL policyCore entries for the WebSEAL ACL, default-webseal, include:Group iv-admin TcmdbsvarxlGroup webseal-servers TgmdbsrxlUser sec_master TcmdbsvarxlAny-other TrxUnauthenticated T

At installation, this default ACL is attached to the /WebSEAL container object inthe object space.

The group, webseal-servers, contains an entry for each WebSEAL server in thesecure domain. The default permissions allow the servers to respond to browserrequests.

The traverse permission allows expansion of the Web space as represented in theWeb Portal Manager. The list permission allows the Web Portal Manager to displaythe contents of the Web space.

Valid characters for ACL namesThe following characters are valid for creating ACL names:v A-Zv a-zv underscore (_)v hyphen (-)v backslash (\)v Any character from a double-byte character set

For detailed information about creating ACL names, refer to the IBM Tivoli BaseAdministrator’s Guide.

Three strikes login policyThe three strikes login policy, available for LDAP-based Tivoli Access Managerinstallations, enables you to specify a maximum number of failed login attempts(n) and a penalty lockout time (x), such that after ″n″ failed login attempts a user islocked out for ″x″ seconds (or the account is disabled).

The three strikes login policy is used to prevent computer password attacks,including dictionary attacks. The policy creates a condition where a user must wait


a period of time before making more login attempts that fail. For example, a policycould dictate 3 failed attempts followed by a 180 second penalty. This type of loginpolicy can prevent random computer-generated login attempts occurring manytimes a second.

The three strikes login policy requires the joint contribution of two pdadminpolicy command settings:v Maximum number of failed login attempts

policy set max-login-failures

v Penalty for exceeding failed login attempt settingpolicy set disable-time-interval

The penalty setting can include an account lockout time interval or a completedisabling of the account.

If a login policy is set (as an example) for three failed attempts followed by specificlockout time penalty, a fourth attempt (correct or incorrect) will result in an errorpage that states the account is temporarily unavailable because of password policy.

The time interval is specified in seconds—the minimum recommended timeinterval is 60 seconds.

If the disable-time-interval policy is set to ″disable″, the user is locked out of theaccount and the LDAP account valid attribute for this user is set to ″no″. Anadministrator re-enables the account through the Web Portal Manager.

Note: Setting the disable-time-interval to ″disable″ results in additionaladministration overhead, because the account must be manually re-enabledby the administrator. Once the account is re-enabled, the updated accountvalid information might not be immediately available. This situation canoccur when using WebSEAL with an LDAP environment that includesreplicated LDAP servers. In this case, the updated information is propagatedto the LDAP replicas according to the LDAP configuration settings thatspecify the time interval for performing updates.

Account lock policy with load-balanced WebSEAL serversYou use the three strikes login policy to ensure that an account is locked after aspecified number of login attempts. This policy performs as expected in aconfiguration involving one WebSEAL server. In a configuration involving multiplefront-end WebSEAL servers with a load-balancing mechanism, the results of thepolicy are affected by the fact that each WebSEAL server maintains its own localcount of failed login attempts.

For example, if the max-login-failures value is set to three (3) attempts, and theclient fails the first three attempts, the account on this server is locked. However,as the client continues login attempts, the load-balancing mechanism—detecting afailure to connect to the first server—redirects the request to another availablereplicated WebSEAL server. Now the client has three more opportunities to attempta successful login.

For ″n″ attempts configured on each WebSEAL server, and ″m″ front-end replicatedWebSEAL servers, you are guaranteed an initial account lock on one server after″n″ attempts. You are also guaranteed ″n″ x ″m″ total attempts to log in across allconfigured servers. However, after ″n″ attempts, it is not clear whether subsequent

Chapter 4. WebSEAL security policy 97

authentication failures are due to the lock on a particular server, or due tocontinuing incorrect login attempts across the remaining replicated servers.

The ″n″ x ″m″ calculation provides a fixed maximum upper limit on the totalnumber of consecutive login attempts before a complete lockout occurs. A case canbe made that this number is still probably far less than the number of attemptsstatistically required to ″break″ a password.

If your business security solution requires a three strikes login policy, understandthe implications of a load-balanced/multiple front-end WebSEAL configuration onthis policy.

Command syntaxThe following pdadmin commands are appropriate for use only with an LDAPregistry.

Command Description

policy set max-login-failures {<number>|unset} [-user <username>]

policy get max-login-failures [-user <username>]

Manages the policy controlling the maximum number of failedlogin attempts allowed before a penalty is imposed. This commanddepends on a penalty set in the policy set disable-time-intervalcommand.

As the administrator, you can apply this policy to a specific user orapply the policy globally to all users listed in the LDAP registry.

The unset parameter eliminates settings for the specified user. Theglobal policy will continue to be enforced.

The default setting is 10 attempts.

policy set disable-time-interval {<number>|unset|disable} [-user <username>]

policy get disable-time-interval [-user <username>]

Manages the penalty policy controlling the time period an accountshould be disabled if the maximum number of failed loginattempts is reached.

As the administrator, you can apply this penalty policy to aspecific user or apply the policy globally to all users listed in theLDAP registry.

The unset parameter eliminates settings for the specified user. Theglobal policy will continue to be enforced.

The default setting is 180 seconds.

Password strength policyPassword strength policy, available for LDAP-based Tivoli Access Managerinstallations, refers to the stipulations placed on the construction of a password bypassword policy rules. Tivoli Access Manager provides two means of controllingpassword strength policy:v Five pdadmin password policy commandsv A plugable authentication module (PAM) that allows you to customize a

password policy


Refer to the IBM Tivoli Access Manager WebSEAL Developer’s Reference.

Password strength policy set by the pdadmin utilityThe five password strength attributes implemented through the pdadmin utilityinclude:v Minimum password lengthv Minimum alphabetic charactersv Minimum non-alphabetic charactersv Maximum repeated charactersv Spaces allowed

These policies are enforced when you create a user with pdadmin or the WebPortal Manager, and when a password is changed with pdadmin, the Web PortalManager, or the pkmspasswd utility.

Command syntaxThe following pdadmin commands are appropriate for use only with an LDAPregistry. The unset option disables this policy attribute—that is, the policy is notenforced.

Command Description

policy set min-password-length {<number>|unset} [-user <username>]

policy get min-password-length [-user <username>]

Manages the policy controlling the minimum length of a password.

As the administrator, you can apply this policy to a specific user orapply the policy globally to all users listed in the default registry.

The default setting is 8.

policy set min-password-alphas {<number>|unset} [-user <username>]

policy get min-password-alphas [-user <username>]

Manages the policy controlling the minimum number of alphabeticcharacters allowed in a password.



policy set min-password-non-alphas {<number>|unset} [-user <username>]

policy get min-password-non-alphas [-user <username>]

Manages the policy controlling the minimum number ofnon-alphabetic (numeric) characters allowed in a password.



policy set max-password-repeated-chars {<number>|unset} [-user <username>]

policy get max-password-repeated-chars [-user <username>]


Command Description

Manages the policy controlling the maximum number of repeatedcharacters allowed in a password.



policy set password-spaces {yes|no|unset} [-user <username>]

policy get password-spaces [-user <username>]

Manages the policy controlling whether a password can containspaces.


The default setting is unset.

Default policy parameter valuesThe following table lists the policy parameters and the default values:

Parameter Default Value

min-password-length 8

min-password-alphas 4

min-password-non-alphas 1

max-password-repeated-chars 2

password-spaces not set

To create the password policy behavior found in earlier releases of Tivoli AccessManager, apply the unset option to each of the five password parameters listedabove.

Valid and invalid password examplesThe following table illustrates several password examples and the policy resultsbased on the default values of the five pdadmin parameters:

Example Result

password Not valid: must contain at least one non-alphabetic character.

pass Not valid: must contain at least 8 characters.

passs1234 Not valid: contains more than two repeated characters.

12345678 Not valid: must contain at least four alphabetic characters.

password3 Valid.

Specific user and global settingsThe pdadmin policy commands can be set for a specific user (with the - useroption) or globally (by not using the - user option). Any user-specific settingoverrides a global setting for the policy. You can also disable (unset) a policyparameter, which means the parameter contains no value. Any policy with theunset option is not checked or enforced.


For example:pdadmin> policy set min-password-length 8

pdadmin> policy set min-password-length 4 -user matt

pdadmin> policy get min-password-length

Minimum password length: 8

pdadmin> policy get min-password-length -user matt

Minimum password length: 4

(User matt has a minimum password length policy of 4 characters; all other usershave a minimum password length policy of 8.)pdadmin> policy set min-password-length unset -user matt

(User matt is now governed by the global minimum password length policy of 8characters.)pdadmin> policy set min-password-length unset

(All users, including user matt, now have no minimum password length policy.)

Authentication strength POP policy (step-up)You can use protected object policies (POP) to enforce certain access conditions onspecific resources. The authentication strength POP policy makes it possible tocontrol access to objects based on authentication method.

You can use this functionality—sometimes known as step-up authentication—toensure that users accessing more sensitive resources use a stronger authenticationmechanism. You might want this condition because of the greater threat ofimproper access to certain resources.

For example, you can provide greater security to a junctioned region of the Webspace by applying a step-up POP policy that requires a stronger level ofauthentication than the client used when initially entering the WebSEAL domain.

Authentication strength policy is set in the IP Endpoint Authentication Methodattribute of a POP policy.

Configuring levels for step-up authenticationThe first step in configuring authentication-specific access is to configure thesupported authentication methods and determine the order in which theseauthentication methods should be considered stronger.

Any client accessing a WebSEAL server has an authentication level, such as″unauthenticated″ or ″password″, which indicates the method by which the clientlast authenticated with WebSEAL.

In some situations it may be necessary to enforce minimum ″safe″ levels ofauthentication required to access certain resources. For example, in oneenvironment, authentication by token passcode may be considered more securethan authentication by username and password. Another environment mightrequire different standards.


Rather than forcing clients to restart their sessions with WebSEAL when they donot meet the required level of authentication, the step-up authenticationmechanism provides clients a second chance to reauthenticate using the requiredmethod (level).

Step-up authentication means that users are not immediately shown a ″denied″message when they try to access a resource that requires a ″higher″ authenticationlevel than the one they logged in with. Instead, they are presented with a newauthentication prompt that requests information to support the higherauthentication level. If they are able to supply this level of authentication thentheir original request will be permitted.

WebSEAL recognizes three authentication methods (levels) for use in the step-upauthentication mechanism:v unauthenticatedv passwordv token-card

You configure authentication levels in the [authentication-levels] stanza of thewebseald.conf configuration file. Initially, only two levels are configured:[authentication-levels]level = unauthenticatedlevel = password

Based on the order of the methods in the list, each method is assigned a levelindex, ranging from 0 to 2.v The ″unauthenticated″ method must always be the first in the list and therefore

is assigned a level index of 0.v Subsequent methods can be placed in any order.

See “Step-up authentication notes and limitations” on page 104.v By default, ″password″ appears at the next level—making it level index 1.v There must be at least two entries to enable step-up authentication,

Note: See Chapter 5, “WebSEAL authentication”, on page 111 for detailedinformation about setting up the required authentication mechanisms.

Enabling step-up authenticationStep-up authentication is implemented using a POP policy placed on the objectsrequiring authentication-sensitive authorization. You use the IP EndpointAuthentication Method attribute of a POP policy.

The pdadmin pop modify set ipauth command specifies both the allowednetworks and the required authentication level in the IP Endpoint AuthenticationMethod attribute.

The configured authentication levels can be linked to IP address ranges. Thismethod is intended to provide management flexibility. If filtering users by IPaddress is not important, you can set a single entry for anyothernw (any othernetwork). This setting will affect all accessing users, regardless of IP address, andrequire them to authenticate at the specified level. This is the most commonmethod for implementing step-up authentication.

Syntax:


pdadmin> pop modify <pop-name> set ipauth anyothernw <level-index>

The anyothernw entry is used as a network range that will match any network nototherwise specified in the POP. This method can be used to create a default entrythat could either deny all unmatched IP addresses or allow anyone access who canmeet the authentication level requirement.

By default, anyothernw appears in a POP with an authentication level index of 0.The entry appears as ″Any Other Network″ in the pop show command:pdadmin> pop show test

Protected object policy: testDescription: Test POPWarning: noAudit level: noneQuality of protection: noneTime of day access: sun, mon, tue, wed, thu, fri, sat:

anytime:localIP Endpoint Authentication Method Policy

Any Other Network 0

Example1. Configure authentication levels in webseald.conf:

[authentication-levels]level = unauthenticatedlevel = token-card

2. Configure IP Endpoint Authentication Method POP attribute:pdadmin> pop modify test set ipauth anyothernw 1

pdadmin> pop show testProtected object policy: testDescription: Test POPWarning: noAudit level: noneQuality of protection: noneTime of day access: mon, wed, fri:anytime:localIP Endpoint Authentication Method Policy

Any Other Network 1

This policy requires a step-up to the token-card authentication method (level 1)for all users initially accessing as ″unauthenticated″ (level 0). Allunauthenticated users attempting to access objects protected by this POP policyare issued a prompt for username and token passcode.

See also “Network-based authentication POP policy” on page 105.

Step-up login formWebSEAL presents a special form when the step-up POP policy on the requestedresource forces the client to reauthenticate. The location of this HTML form isspecified by the stepup-login parameter in the [acnt-mgt] stanza of thewebseald.conf configuration file.[acnt-mgt]stepup-login = stepuplogin.html

You can configure this HTML form to meet your requirements, in the same manneras you might configure the login.html or tokenlogin.html forms.

This file contains macros, in the form of %TEXT% sequences, which are replacedwith the appropriate values. This substitution occurs within WebSEAL’s template


file processing functions and allows the form to be used for both password andtoken authentication methods with correct formatting. It also allows otherinformation, such as error message and method name (stepping up to), to besupplied in the form for the user.

Step-up authentication algorithmWebSEAL uses the following algorithm to process the conditions in a POP:1. Check the IP endpoint authentication method policy on the POP.2. Check ACL permissions.3. Check time-of-day policy on the POP.4. Check the audit level policy on the POP.

Step-up authentication notes and limitations1. Step-up authentication is supported over both HTTP and HTTPS.2. You cannot step-up from the HTTP protocol to HTTPS.3. Unauthenticated must always be the first method in the level list, and may not

occur anywhere else in the list.4. Methods can be specified only once in the level list.5. Certificate authentication is not a supported method for step-up authentication.

Note: Step-up authentication actually handles client-side certificates as a specialcase. If a client accesses WebSEAL with a client-side certificate, andWebSEAL is configured to accept certificates, the client is treated asunauthenticated with a level index of 0.

From Method: Can step-up to:

unauthenticated password token-card

password token-card

token-card password

6. Authentication levels are represented by authentication methods, which meansthat it is impossible to specify a precise authentication mechanism forauthentication at that level.Authentication methods may be supported by multiple authenticationmechanisms, including local authenticators and custom external authenticators.WebSEAL follows specific rules for determining which authenticator to selectwhen multiple instances of the same authentication method type have beenconfigured.

7. If there are three configured levels, the valid index values are: 0,1,2. If anyother index value is configured, WebSEAL presents an error page wheneverany object with that POP attached is requested.

8. Incorrect configuration of step-up authentication levels in the webseald.confconfiguration file results in the disabling of step-up functionality withinWebSEAL. This situation can lead to unexpected authentication behavior, suchas the password login page being issued for objects protected by a POP thatrequires the token passcode authentication method.After configuring step-up authentication levels, check the webseald.log file forreports of any configuration errors.


Distinguishing step-up from multi-factor authenticationTivoli Access Manager step-up authentication and multi-factor authentication aretwo different and distinct mechanisms for controlling access to resources. TivoliAccess Manager provides only step-up authentication functionality, as described inthis chapter.

Multi-factor authentication forces a user to authenticate using two or more levelsof authentication. For example, the access control on a protected resource canrequire that the user authenticate with both user name/password and username/token passcode.

Tivoli Access Manager step-up authentication relies on a pre-configured hierarchyof authentication levels and enforces a specific level of authentication according tothe policy set on a resource. Step-up authentication does not force the user toauthenticate using multiple levels of authentication to access any given resource.Instead, step-up authentication requires the user to authenticate at a level at leastas high as that required by the policy protecting the resource.

Step-up authentication example:

Configured authentication levels:v authentication level 1 = user name/passwordv authentication level 2 = user name/token passcode

The following object is protected by a POP requiring authentication level 1:/WebSEAL/hostA/junction

The following object is protected by a POP requiring authentication level 2./WebSEAL/hostA/junction/applicationA

Under step-up authentication, user name/password (level 1) authentication isrequired to access /WebSEAL/hostA/junction.

However, user name/token passcode (level 2) authentication is required to access/WebSEAL/hostA/junction/applicationA. If the user is currently logged in with auser name and password, a prompt appears requesting user name and tokenpasscode information (the step-up). However, if the user initially logs in toWebSEAL with user name and token passcode, access to applicationA isimmediate (assuming a positive ACL check).

Multi-factor authentication would require both level 1 and level 2 authentication foraccess to applicationA.

Network-based authentication POP policyThe network-based authentication POP policy makes it possible to control access toobjects based on the IP address of the user. You can use this functionality toprevent specific IP addresses (or IP address ranges) from accessing any resources inyour secure domain.

You can also apply step-up authentication configuration to this policy and requirea specific authentication method for each specified IP address range.


Network-based authentication policy is set in the IP Endpoint AuthenticationMethod attribute of a POP policy. You must specify two requirements in thisattribute:v Authentication levelsv Allowed networks

Configuring authentication levelsWebSEAL recognizes three authentication methods for use in the step-upauthentication mechanism:v unauthenticatedv passwordv token-card

Based on the order of the methods in the list, each method is assigned a levelindex, ranging from 0 to 2.

You configure authentication levels in the [authentication-levels] stanza of thewebseald.conf configuration file. Initially, only two levels are configured:[authentication-levels]level = unauthenticatedlevel = password

You can use these default settings when you configure network-basedauthentication. In this case, ″unauthenticated″ is level 0 and ″password″ is level 1.

See also “Configuring levels for step-up authentication” on page 101.

Specifying IP addresses and rangesNow you must specify the IP addresses and IP address ranges permitted by thisPOP policy.

The pdadmin pop modify set ipauth add command specifies both the network (ornetwork range) and the required authentication level in the IP EndpointAuthentication Method attribute.

Syntax:pdadmin> pop modify <pop-name> set ipauth add <network> <netmask> <level-index>

The configured authentication levels are linked to IP address ranges. This methodis intended to provide flexibility. If filtering users by IP address is not important,you can set a single entry for anyothernw (any other network). This setting affectsall accessing users, regardless of IP address, and require them to authenticate at thespecified level.

Syntax:pdadmin> pop modify <pop-name> set ipauth anyothernw <level-index>

Conversely, if you wish to ignore the authentication level and want to allow ordeny access based only on IP address, you can use level 0 for ranges that you wantto allow in and ″forbidden″ for ranges you want to deny.

The anyothernw entry is used as a network range that matches any network nototherwise specified in the POP. This method can be used to create a default entry


that could either deny all unmatched IP addresses or allow access to anyone whomeets the authentication level requirement.

By default, anyothernw appears in a POP with an authentication level index of 0.The entry appears as ″Any Other Network″ in the pop show command:pdadmin> pop show test

Protected object policy: testDescription: Test POPWarning: noAudit level: noneQuality of protection: noneTime of day access: sun, mon, tue, wed, thu, fri, sat:

anytime:localIP Endpoint Authentication Method Policy

Any Other Network 0

Refer to “Configuring levels for step-up authentication” on page 101 for a moredetailed discussion on setting authentication levels.

ExamplesRequire users from IP address range 9.0.0.0 and netmask 255.0.0.0 to use level 1authentication (″password″ by default):pdadmin> pop modify test set ipauth add 9.0.0.0 255.0.0.0 1

Require a specific user to use level 0 authentication:pdadmin> pop modify test set ipauth add 9.1.2.3 255.255.255.255 0

Prevent all users (other than those specified as in the examples above) fromaccessing the object:pdadmin> pop modify test set ipauth anyothernw forbidden

Disabling step-up authentication by IP addressSyntax:pdadmin> pop modify <pop-name> set ipauth remove <network> <netmask>

For example:pdadmin> pop modify test set ipauth remove 9.0.0.0 255.0.0.0

Network-based authentication algorithmWebSEAL uses the following algorithm to process the conditions in a POP:1. Check the IP endpoint authentication method policy on the POP.2. Check ACL permissions.3. Check time-of-day policy on the POP.4. Check the audit level policy on the POP.

Network-based authentication notes and limitationsThe IP address used by WebSEAL for enforcing the network-based authenticationpolicy should be the IP address of the originator of the TCP connection. If yournetwork topology uses HTTP proxies, the address that appears to WebSEAL mightbe the IP address of the proxy server.

In this case, WebSEAL is not able to definitively identify the true client IP address.You must be careful when setting a network-based authentication policy thatnetwork clients can directly connect to the WebSEAL server.


Quality of protection POP policyThe quality of protection POP attribute allows you to specify what level of dataprotection is required when performing an operation on an object.

The quality of protection POP attribute is used to determine whether access will begranted to requested resource. When an ACL check for a resource succeeds, thequality of protection POP is checked. If a quality of protection POP exists, and theresource manager (WebSEAL) cannot guarantee the required level of protection, therequest is denied.pdadmin> pop modify <pop-name> set qop {none|integrity|privacy}

When QOP level is set to either integrity or privacy, WebSEAL requires dataencryption through the use of Secure Socket Layer (SSL).

For example:pdadmin> pop modify test set qop privacy

Handling unauthenticated users (HTTP / HTTPS)WebSEAL accepts requests from both authenticated and unauthenticated users overHTTP and HTTPS. WebSEAL then relies on the authorization service to enforcesecurity policy by permitting or denying access to protected resources.

The following conditions apply to unauthenticated users who access WebSEALover SSL:v The exchange of information between the unauthenticated user and WebSEAL is

encrypted—just as it is with an authenticated user.v An SSL connection between an unauthenticated user and WebSEAL requires

only server-side authentication.

Processing a request from an anonymous client1. An anonymous client makes a request to WebSEAL (over HTTP or HTTPS).2. WebSEAL creates an unauthenticated credential for this client.3. The request proceeds, with this credential, to the protected Web object.4. The authorization service checks the permissions on the unauthenticated entry

of the ACL for this object, and permits or denies the requested operation.5. Successful access to this object depends on the unauthenticated ACL entry

containing at least the read (r) and traverse (T) permissions.6. If the request fails the authorization decision, the client receives a login form

(BA or Forms-based).

Forcing user loginYou can force an unauthenticated user to log in by correctly setting the appropriatepermissions on the unauthenticated entry in the ACL policy that protects therequested object.

The read (r) and traverse (T) permissions allow unauthenticated access to an object.

To force an unauthenticated user to log in, remove the read (r) permission from theunauthenticated entry in the ACL policy that protects the object. The user receivesa login prompt (BA or Forms-based).


Applications of unauthenticated HTTPSThere are many practical business reasons for supporting unauthenticated access toWebSEAL over HTTPS:v Some applications do not require a personal login, but require sensitive

information, such as addresses and credit card numbers. Examples includeonline purchases of airline tickets and other merchandise.

v Some applications require that you register for an account with the businessbefore you can proceed with further transactions. Again, sensitive informationmust be passed over the network.

Controlling unauthenticated users with ACL/POP policies

Note: The ″any-authenticated″ entry type is equivalent to the ″any-other″ entrytype.

1. To permit unauthenticated user access to public objects, protect the publiccontent with an ACL that contains at least the read (r) and traverse (T)permissions for the unauthenticated and any-authenticated entries:unauthenticated Trany-authenticated Tr

Note: The unauthenticated entry is a mask (a bitwise ″and″ operation) againstthe any-authenticated entry when permissions are determined. Apermission for unauthenticated is granted only if the permission alsoappears in the any-authenticated entry. Because unauthenticateddepends on any-authenticated, it makes little sense for an ACL tocontain unauthenticated without any-authenticated. If an ACL doescontain unauthenticated without any-authenticated, the default responseis to grant no permissions to unauthenticated.

2. To require encryption (SSL), protect the content with a Protected Object Policy(POP) that specifies privacy as a condition.See “Quality of protection POP policy” on page 108.


Chapter 5. WebSEAL authentication

This chapter discusses how WebSEAL maintains session state and handles theauthentication process. Successful authentication results in a Tivoli Access Manageridentity that represents the user. WebSEAL uses this identity to acquire credentialsfor that user. Credentials are used by the authorization service to permit or denyaccess to protected resources.

Topic Index:v “Understanding the authentication process” on page 111v “Managing session state” on page 113v “Authentication configuration overview” on page 122v “Configuring Basic Authentication” on page 125v “Configuring forms authentication” on page 126v “Configuring client-side certificate authentication” on page 127v “Configuring HTTP header authentication” on page 130v “Configuring IP address authentication” on page 132v “Configuring token authentication” on page 132v “Supporting multiplexing proxy agents” on page 134v “Configuring reauthentication based on security policy” on page 137v “Configuring reauthentication based on session inactivity policy” on page 140v “Configuring automatic redirection to a login home page” on page 144

Understanding the authentication processAuthentication is the method of identifying an individual process or entity that isattempting to login to a secure domain.v WebSEAL supports several authentication methods by default and can be

customized to use other methods.v The result of successful authentication to WebSEAL is a Tivoli Access Manager

user registry identity.v WebSEAL uses this identity to obtain a credential for that user.v The authorization service uses this credential to permit or deny access to

protected objects after evaluating the ACL permissions and POP conditionsgoverning the policy for each object.

Note: ACL = access control list policy POP = protected object policy

During authentication, WebSEAL examines a client request for the followinginformation:v Session data

Session data is information that identifies a specific connection between theclient and the WebSEAL server. Session data is stored with the client andaccompanies subsequent requests by that client. It is used to re-identify the clientsession to the WebSEAL server and avoid the overhead of establishing a newsession for each request.

v Authentication data


Authentication data is information from the client that identifies the client to theWebSEAL server. Authentication data types include client-side certificates,passwords, and token codes.

When WebSEAL receives a client request, WebSEAL always looks for session datafirst, followed by authentication data. The initial client request never containssession data.

Supported session data typesWebSEAL supports the following session data types:v SSL ID (defined by the SSL protocol)v Server-specific session cookiev BA header datav HTTP header datav IP address

When WebSEAL examines a client request, it searches for session data in the orderspecified in this list.

Supported authentication methodsAlthough WebSEAL functions independently of the authentication process,WebSEAL uses credentials to monitor all users participating in the secure domain.To obtain the necessary identity information for credentials acquisition, WebSEALrelies on the information gained from the authentication process.

The following authentication methods are supported by WebSEAL for credentialsacquisition:

Authentication MethodSupported Connection

Type

1. Failover cookie HTTP and HTTPS

2. CDSSO ID token HTTP and HTTPS

3. Client-side certificate HTTPS

4. Token passcode HTTP and HTTPS

5. Forms authentication (username and password) HTTP and HTTPS

6. Basic Authentication (username and password) HTTP and HTTPS

7. HTTP headers HTTP and HTTPS

8. IP address HTTP and HTTPS

When WebSEAL examines a client request, it searches for authentication data inthe order specified in this table.

Authentication methods can be independently enabled and disabled for both HTTPand HTTPS transports. If no authentication methods are enabled for a particulartransport, the authentication process is inactive for clients using that transport.


Managing session stateA secure connection, or session, between a client and a server requires that theserver have the ability to remember—over numerous requests—who it is talking to.The server must have some form of session state information that identifies theclient associated with each request.

This section contains the following topics:v “Session state overview” on page 113v “GSKit and WebSEAL session cache overview” on page 113v “Configuring the GSKit SSL session ID cache” on page 114v “Configuring the WebSEAL session/credentials cache” on page 114v “Maintaining state with session cookies” on page 115v “Determining valid session ID data types” on page 118v “Configuring failover cookies” on page 118

Session state overviewWithout an established session state between client and server, the communicationbetween the client and the server must be renegotiated for each subsequentrequest. Session state information improves performance by eliminating repeatedclosing and re-opening of client/server connections. The client can log in once andmake numerous requests without performing a separate login for each request.

WebSEAL handles both HTTP and HTTPS communication. HTTP is a ″stateless″protocol and does not provide any means of distinguishing one request fromanother. The SSL transport protocol, on the other hand, is specifically designed toprovide a session ID to maintain session state information. HTTP communicationcan be encapsulated over SSL to become HTTPS.

However, WebSEAL must often handle HTTP communication fromunauthenticated clients. And there are times when the SSL session ID is not anappropriate solution. Therefore, WebSEAL is designed to use any of the followinginformation types to maintain session state with a client:v SSL IDv Server-specific session cookiev BA header datav HTTP header datav IP address

GSKit and WebSEAL session cache overviewA session cache allows a server to store the session ID information from multipleclients. WebSEAL uses two types of session caches to accommodate both HTTPSand HTTP session state information.v WebSEAL session/credentials cache

The WebSEAL session/credentials cache stores any type of session IDinformation (see the list above) plus the credential information obtained for eachclient.Credential information is cached to eliminate repetitive queries to the userregistry database during authorization checks.

v GSKit SSL session ID cache

Chapter 5. WebSEAL authentication 113

The GSKit session cache handles HTTPS (SSL) communication when SSL sessionID information is used to maintain session state.The GSKit cache also maintains session state information for the SSL connectionbetween WebSEAL and the LDAP user registry.

Configuring the GSKit SSL session ID cacheThe following configuration tasks are available for the GSKit SSL session ID cache:v Setting the cache entry timeout valuev Setting the maximum concurrent entries value

Setting the cache entry timeout valueThe parameters for setting the maximum lifetime timeout for an entry in the GSKitSSL session ID cache are located in the [ssl] stanza of the webseald.confconfiguration file. There are two parameters: one for SSL V2 connections(ssl-v2-timeout) and one for SSL V3 connections (ssl-v3-timeout).

The default SSL V2 session timeout (in seconds) is 100 (with a possible range of1-100):[ssl]ssl-v2-timeout = 100

The default SSL V3 session timeout (in seconds) is 7200 (with a possible range of1-86400):[ssl]ssl-v3-timeout = 7200

Setting the maximum concurrent entries valueThe ssl-max-entries parameter, located in the [ssl] stanza of the webseald.confconfiguration file, sets the maximum number of concurrent entries in the GSKitSSL session ID cache.

This value corresponds to the number of concurrent login sessions. When the cachesize reaches this value, entries are removed from the cache according to a leastrecently used algorithm to allow new incoming logins.

The default number of concurrent login sessions is 4096:[ssl]ssl-max-entries = 4096


Configuring the WebSEAL session/credentials cacheThe following configuration tasks are available for the WebSEALsession/credentials cache:v Setting the maximum concurrent entries valuev Setting the cache entry lifetime timeout valuev Setting the cache entry inactivity timeout value

Setting the maximum concurrent entries valueThe max-entries parameter, located in the [session] stanza of the webseald.confconfiguration file, sets the maximum number of concurrent entries in the WebSEALsession/credentials cache.


This value corresponds to the number of concurrent login sessions. When the cachesize reaches this value, entries are removed from the cache according to a leastrecently used algorithm to allow new incoming logins.

The default number of concurrent login sessions is 4096:[session]max-entries = 4096


Setting the cache entry lifetime timeout valueThe timeout parameter, located in the [session] stanza of the webseald.confconfiguration file, sets the maximum lifetime timeout value for all user sessionsstored in the WebSEAL session/credentials cache.

WebSEAL caches credential information internally. The session cache timeoutparameter dictates the length of time authorization credential information remainsin memory on WebSEAL.

The parameter is not an inactivity timeout. The value maps to a ″credentiallifetime″ rather than a ″session inactivity timeout″. Its purpose is to enhancesecurity by forcing the user to re-authenticate when the specified timeout limit isreached.

The default session cache entry lifetime timeout (in seconds) is 3600:[session]timeout = 3600

Note: This parameter is not appropriate for Basic Authentication (BA). BA suppliesauthentication data with each request, thereby repeatedly resetting thetimeout value.

Setting the cache entry inactivity timeout valueThe inactive-timeout parameter, located in the [session] stanza of thewebseald.conf configuration file, sets the timeout value for user session inactivity.

The default login session inactivity timeout (in seconds) is 600:[session]inactive-timeout = 600

To disable this timeout feature, set the parameter value to ″0″.

Note: This parameter is not appropriate for Basic Authentication (BA). BA suppliesauthentication data with each request, thereby repeatedly resetting theinactive timeout value.

Maintaining state with session cookiesOne method of maintaining session state between a client and a server is to use acookie to hold this session information. The server packages the state informationfor a particular client in a cookie and sends it to the client’s browser. For each newrequest, the browser re-identifies itself by sending the cookie (with the sessioninformation) back to the server.


Session cookies offer a possible solution for situations when the client uses abrowser that renegotiates its SSL session after very short periods of time. Forexample, some versions of the Microsoft Internet Explorer browser renegotiate SSLsessions every two or three minutes.

A session cookie provides re-authentication of a client only to the single, uniqueserver that the client had previously authenticated to within a short time period(around ten minutes). The mechanism is based on a ″server cookie″ that cannot bepassed to any machine other than the one that generated the cookie.

In addition, the session cookie contains only a random number identifier that isused to index the server’s session cache. There is no other information exposed inthe session cookie. The session cookie cannot compromise security policy.

Understanding session cookiesWebSEAL uses a secure server-specific session cookie. The following conditionsapply to this cookie mechanism:v Cookie contains session information only; it does not contain identity

informationv Cookie resides only in the browser memory (it is not written to the browser

cookie jar on the disk)v Cookie has a limited lifetimev Cookie has path and domain parameters that prohibit its use by other servers

Enabling and disabling session ID cookiesThe ssl-id-sessions parameter, located in the [session] stanza of the webseald.confconfiguration file, enables and disables session cookies. This parameter controlswhether the SSL session ID is used to maintain the login session for clientsaccessing over HTTPS. If the parameter is set to ″no″, session cookies are used formost authentication methods.[session]ssl-id-sessions = { yes | no }

A configuration setting of no for this parameter results in the following conditionsfor clients accessing over HTTPS:v The SSL session ID is never used as session ID data.v Cookies will be used to maintain sessions with clients authenticating with

failover cookies, CDSSO ID tokens, forms username and password, tokenpasscode, and client-side certificates.

v Cookies are used for Basic Authentication clients only when use-same-session =yes (see next section). Otherwise, the BA header is used for session ID data.

v The HTTP header is used as session ID data for clients authenticating withHTTP headers

v The IP address is used as session ID data for clients authenticating with IPaddresses.

When ssl-id-sessions is set to yes, several different values determine the timeoutfor the session. The session cache entry lifetime timeout is set in the timeout entryin the [session] stanza , and the session inactivity timeout is set byinactive-timeout in the same stanza. SSL timeouts are set in the [ssl] stanza,where both ssl-v2–timeout and ssl-v3–timeout are declared. Thus, whenssl-id-sessions = yes, the timeout is set to the lowest of the values set for each ofthe following timeouts:


[session]timeoutinactive-timeout[ssl]ssl-v2-timeoutssl-v3-timeout

When you use cookies to maintain session state, the cookie is sent to the browseronly once, following a successful login. However, some browsers enforce a limit onthe number of in-memory cookies they can store concurrently. In someenvironments, applications can place a large number of in-memory cookies perdomain on client systems. In this case, any configured WebSEAL session cookie orfailover cookie can be easily replaced by another cookie.

When you configure WebSEAL to use session cookies (and perhaps failovercookies), you can set the resend-webseal-cookies parameter, located in the[session] stanza of the webseald.conf configuration file, to have WebSEAL sendthe session cookie and the failover cookie to the browser with every response. Thisaction helps to ensure that the session cookie and the failover cookie remain in thebrowser memory.

The resend-webseal-cookies parameter has a default setting of ″no″:[session]resend-webseal-cookies = no

Change the default setting to ″yes″ to send WebSEAL session cookies and failovercookies with every response.

Enabling and disabling same sessionsYou can configure WebSEAL to use the same session ID data when a client logs inover one type of transport (HTTP, for example), disconnects, and re-logs in overanother type of transport (HTTPS, for example).

The use-same-session parameter, located in the [session] stanza of thewebseald.conf configuration file, enables and disables the recognition of the samesession ID data. By default, this parameter is set to ″no″:[session]use-same-session = no

A ″yes″ configuration setting for this parameter results in the following conditions:v Session cookies are used to identify the following client types for subsequent

logins over another transport:– Failover cookies– Client-side certificates– CDSSO ID token– Token passcode– Forms username and password– Basic Authentication

v The HTTP header is used for clients accessing with HTTP headers.v The IP address is used for clients accessing with IP addresses.v The ssl-id-sessions configuration is ignored; the resulting behavior is the same

as if ssl-id-sessions were set to “no”.This logic is important because HTTP clients do not have an SSL session IDavailable as session data.


v Because the cookies are available to both HTTP and HTTPS clients, they are notflagged as secure cookies.

Determining valid session ID data typesThe session data type for a client accessing with a particular authentication methodis determined by specific combinations of the following configuration parameters:v Enabling or disabling session cookies (ssl-id-sessions)v Enabling or disabling the ability to use the same session data when a client

switches between HTTP and HTTPS (use-same-session)

The following tables summarizes the valid session ID data for any givenconfiguration that combines the ssl-id-sessions and use-same-session parameters:

HTTPS Clients

Authentication Method ssl-id-sessions = yesssl-id-sessions = no

use-same-session = nouse-same-session = yesssl-id-sessions ignored

Failover cookie SSL ID Cookie Cookie

Certificate SSL ID Cookie Cookie

CDSSO SSL ID Cookie Cookie

Token SSL ID Cookie Cookie

Forms SSL ID Cookie Cookie

BA SSL ID BA header Cookie

HTTP header SSL ID HTTP header HTTP header

IP address SSL ID IP address IP address

HTTP Clients

Authentication Method use-same-session = no use-same-session = yes

Failover cookie Cookie Cookie

CDSSO Cookie Cookie

Token Cookie Cookie

Forms Cookie Cookie

BA BA header Cookie

HTTP header HTTP header HTTP header

IP address IP address IP address

Configuring failover cookiesThe following failover cookie feature (for HTTP and HTTPS) is appropriate for aclient connecting to a replicated front-end WebSEAL server cluster through aload-balancing mechanism. The purpose of a failover cookie is to prevent forcedre-authentication when the server that has the original session with the clientsuddenly becomes unavailable.

A front-end WebSEAL cluster can be implemented to provide high availability ofresources for large numbers of clients. The load-balancing mechanism interceptsthe incoming requests and distributes the requests across the available front-endservers.


Refer to the following diagram during this discussion.

The client is not aware of the replicated front-end server configuration. Theload-balancing mechanism is the single point of contact for the requested URL. Theload-balancing mechanism connects a client with an available server (such as WS1).A session state is established with WS1 and all subsequent requests from that clientare sent to WS1.

The problem that can be solved by failover cookies involves a situation when WS1becomes unavailable for some reason (for example, system failure or taken off lineby an administrator). If WS1 becomes unavailable, the load-balancing mechanismredirects the request to one of the other replicated servers (WS2 or WS3). Theoriginal session-to-credential mapping is now lost. The client is new to thissubstitute server and is normally forced to authenticate again.

You can configure the replicated WebSEAL servers to encrypt client identificationdata in a server-specific cookie. The cookie is placed on the browser when theclient first connects. If the initial WebSEAL server becomes temporarilyunavailable, the cookie (with the encrypted identity information) is presented tothe substitute server.

The failover cookie contains the user name, time stamp, and original authenticationmethod. The replicated WebSEAL servers share a common key that can decrypt thecookie information. When the substitute WebSEAL server receives this cookie, itcan use the user name and authentication method to re-generate the client’scredential, including any extended attributes. The client can now establish a newsession with a replica WebSEAL sever without being forced to re-authenticate.

The reference point for the cookie is the DNS of the load-balancing mechanism.This single point of reference is important because the cookie is a server-specificcookie, and not a domain-specific cookie. The cookie is accepted only by a serverwith the same DNS name as the server that created the cookie. The client alwaysmakes requests through the load-balancing mechanism. Therefore, the cookie isalways accepted and then passed to the next available server during a failoveroperation.

Client


WS1

WS2

WS3

Replicated Front-endWebSEAL Servers

Back-endResources

Figure 16. Failover cookie scenario


Enabling failover cookiesThe failover-auth parameter, located in the [failover] stanza of the webseald.confconfiguration file, enables or disables server-specific failover cookies:v To enable failover cookies, enter ″http″, ″https″, or ″both″.v To disable failover cookies, enter ″none″ (default).

For example:[failover]failover-auth = https

You must set this parameter on each of the front-end WebSEAL servers.

For each supported authentication method in the WebSEAL cluster environment,you must also enable an equivalent failover method parameter in the[authentication-mechanisms] stanza of the webseald.conf configuration file. Eachfailover authentication method parameter points to a special authentication sharedlibrary that mimics the original authentication shared library and, additionally,recovers any extended attributes that were originally placed in the user’scredential.

The following failover authentication method parameters are available:[authentication-mechanisms]#failover-password = <failover-password-library>#failover-token-card = <failover-tokeb-card-library>#failover-certificate = <failover-certificate-library>#failover-http-request = <failover-http-request-library>#failover-cdsso = <failover-cdsso-library>

WebSEAL supplies one standard failover shared library that functions for all theabove authentication methods. This library is called:

Solaris libfailoverauthn.so

AIX libfailoverauthn.a

HP-UX libfailoverauthn.sl

Windows failoverauthn.dll

You can, alternatively, supply a custom CDAS library that provides specificauthentication capabilities required by your environment.

For example:1. The user authenticates to WS1 via user name and password. The standard

libldapauthn library adds (via an HTTP-Tag-Value extended attribute on thejunction) certain extended attributes from LDAP to the user’s credential.Additionally, a chained CDAS module adds other extended attributes to theuser’s credential via its cred-ext-attrs library.

2. WS1 server fails and the user is redirected to the WS2 server.3. WS2 receives the failover cookie from the user’s browser and decodes the

cookie. Because the user originally authenticated with the user name andpassword method, the libfailoverauthn library connects to the LDAP serverand retrieves the standard credential data for this method, plus the extendedattributes supplied by the tag/value mechanism.Then the user identity is passed to the custom cred-ext-attrs library thatsupplies its additional extended attributes.


Now WS2 has generated the same complete credential for the user that wasused by WS1.

If the environment for this example also includes support for certificateauthentication, the [authentication-mechanisms] stanza would appear as follows:[authentication-mechanisms]passwd-ldap = /opt/pdweb/lib/libldapauthn.socert-ssl = /opt/pdweb/lib/libsslauthn.sofailover-password = /opt/pdweb/lib/libfailoverauthn.sofailover-certificate = /opt/pdweb/lib/libfailoverauthn.socred-ext-attrs = /usr/lib/custom-ext-attrs-CDAS.so

Encrypting and decrypting the cookie dataTo secure the cookie data, use the cdsso_key_gen utility provided by WebSEAL.This utility generates a symmetric key that encrypts and decrypts the data in thecookie. Specify the location (absolute pathname) of the key file when you run theutility. You must also use a full path name to run this utility:

UNIX:# /opt/pdweb/bin/cdsso_key_gen <keyfile-location>

Windows:MSDOS> C:\Program Files\Tivoli\PDWeb\bin\cdsso_key_gen <keyfile-location>

Run the utility on one of the replicated servers and manually copy the key file toeach of the remaining replicated servers. Enter this key file location in the[failover] stanza of the webseald.conf configuration file of each server. If you donot specify a key file, the failover cookie functionality is disabled for that server:[failover]failover-cookies-keyfile = <absolute-pathname>

You can give the key file any appropriate name, such as ws.key.

Configuring the cookie lifetimeThe value for the failover cookie lifetime (in minutes) is set with thefailover-cookie-lifetime parameter:[failover]failover-cookie-lifetime = 60

Enabling domain-wide failover cookiesYou can allow failover cookies to be sent to any server within the same domain asthe WebSEAL server by setting the enable-failover-cookie-for-domain parameterequal to ″yes″. By default, domain-wide failover cookie functionality is disabled:[failover]enable-failover-cookie-for-domain = no

Enabling compatibility with previous releasesIn this release of Tivoli Access Manager, the level of security has been increased forthe encryption of the cookie data. The new encryption algorithm is not backwardcompatible. If you are integrating failover cookies with servers using previousversions of Tivoli Access Manager, you must enable the pre-410-compatible-tokensparameter in the [server] stanza of the webseald.conf configuration file. Forexample:pre-410-compatible-tokens = yes

The default setting for this parameter is ″no″.


Authentication configuration overviewYou can enable and disable authentication for both HTTP and HTTPS clients on aper-method basis.

The mechanisms for all authentication methods supported by WebSEAL areconfigured in the [authentication-mechanisms] stanza of the webseald.confconfiguration file. Supported authentication method parameters include:v Local (built-in) authenticators

Parameters for local authenticators specify the appropriate built-in shared library(UNIX) or DLL (Windows) files.

v Custom external authenticatorsWebSEAL provides template server code that you can use to build and specify acustom external Cross Domain Authentication Service (CDAS) server.An external CDAS authenticator specifies the appropriate custom shared library.

Local authentication parametersThe following parameters specify local built-in authenticators:


Forms and Basic Authentication

passwd-ldap Client access with LDAP username and password.

Token Authentication

token-cdas Client access with LDAP username and SecurID tokenpasscode.

Client-side Certificate Authentication

cert-ssl Client access with client-side certificate over SSL.

HTTP Header and / or IP Address Authentication

http-request Client access via special HTTP header and / or IP address.

SSO ID Token Authentication

sso-create

sso-consume

Cross-server Single Sign-on authentication.

You use the [authentication-mechanisms] stanza to configure the authenticationmethod and the implementation in the following format:<authentication-method-parameter> = <built-in-shared-library>

External custom CDAS authentication parametersThe following additional parameters (and the parameters listed in the sectionabove) are available to specify custom shared libraries for external CDAS servers:


passwd-cdas Client access with username and password for a third-partyregistry.

cred-ext-attrs Used by CDAS to supply extended attribute data to usercredential.


You use the [authentication-mechanisms] stanza to configure the authenticationmethod and the implementation in the following format:<authentication-method-parameter> = <custom-shared-library>

Refer to the IBM Tivoli Access Manager WebSEAL Developer’s Reference for details onbuilding and configuring a custom shared library that implements a CDAS server.

Default configuration for WebSEAL authenticationBy default, WebSEAL is set to authenticate clients over SSL using BasicAuthentication (BA) usernames and passwords (LDAP registry).

WebSEAL is normally enabled for both TCP and SSL access. Therefore, a typicalconfiguration of the [authentication-mechanisms] stanza includes support forusername and password (LDAP registry) and support for client-side certificatesover SSL.

The following example represents the typical configuration of the[authentication-mechanisms] stanza for Solaris:[authentication-mechanisms]passwd-ldap = libldapauthn.socert-ssl = libsslauthn.so

To configure other authentication methods, add the appropriate parameter with itsshared library (or CDAS module).

Configuring multiple authentication methodsYou modify the [authentication-mechanism] stanza of the webseald.confconfiguration file to specify the shared library to be used for any supportedauthentication method.

The following conditions apply when you configure multiple authenticationmethods:v All authentication methods can function independently from each other. It is

possible to configure a shared library for each supported method.v The cert-cdas method overrides the cert-ssl method when both are configured.

You must enable one of these to support client-side certificates.v Only one password type authenticator is actually used when more than one is

configured. WebSEAL uses the following order of priority to resolve multipleconfigured password authenticators:1. passwd-cdas

2. passwd-ldap

v It is possible to configure the same custom library for two differentauthentication methods. For example, you could write a custom shared library toprocess both username/password and HTTP header authentication. For thisexample, you would configure both the passwd-cdas and http-requestparameters with the same shared library. It is the responsibility of the developerto maintain session state and avoid conflicts between the two methods.

Prompting for loginWebSEAL prompts a client for a login under the following conditions:v An unauthenticated client that fails an authorization checkv A forms or Basic Authentication client that fails an authorization check


The following client types are presented a ″403 failure″ error:v When an authorization check fails:

– Client-side certificate– Failover cookie– CDSSO– IP address– HTTP header

v When a client authenticates with a method that is disabled by WebSEAL

Logout and change password commandsTivoli Access Manager provides the following commands for supporting clientswho authenticate over HTTP or HTTPS.

pkmslogoutClients can use the pkmslogout command to log out from the current sessionwhen they use an authentication method that does not supply authentication datawith each request. For example, pkmslogout does not work for clients using BasicAuthentication, certificates, or IP address authentication. In this case, you mustclose the browser to log out.

The pkmslogout command is appropriate for authentication using token passcode,forms authentication, and certain implementations of HTTP header authentication.

Run the command as follows:https://www.tivoli.com/pkmslogout

The browser displays a logout form defined in the webseald.conf configurationfile:[acnt-mgt]logout = logout.html

You can modify the logout.html file to suit your requirements.

The pkmslogout utility also supports multiple logout response pages when thenetwork architecture requires different exit screens for users logging out ofdistinctly different back-end systems.

The following expression identifies a specific response file:https://www.tivoli.com/pkmslogout?filename=<custom_logout_file>

where custom_logout_file is the filename of the logout response. This file mustreside in the same lib/html/C directory that contains the default logout.html fileand other sample HTML response forms.

pkmspasswdYou can use this command to change your login password when using BasicAuthentication (BA) or forms authentication. This command is appropriate overHTTP or HTTPS.

For example:https://www.tivoli.com/pkmspasswd

To assure maximum security when BA is used with WebSEAL, this command hasthe following behavior for a BA client:


1. The password is changed.2. The client user is logged out from the current session.3. When the client makes an additional request, the browser presents the client

with a BA prompt.4. The client must re-log in to continue making requests.

This scenario only applies to a client using Basic Authentication.

Post password change processingWebSEAL provides support for customized post password change processing.Administrators can write a CDAS authentication module that will be called after apassword is successfully changed through WebSEAL using the pkms passwordchange page, as described in “Logout and change password commands” onpage 124. This module can be used to update passwords in an external userregistry.

This feature enables passwords in external user registries, which may be unknownto Tivoli Access Manager, to be updated with passwords that the user changedduring the course of attempting authentication when challenged by WebSEAL.

For information on implementing a post password change processing module, seeIBM Tivoli Access Manager WebSEAL Developer’s Reference.

Configuring Basic AuthenticationBasic Authentication (BA) is a standard method for providing a username andpassword to the authentication mechanism. BA is defined by the HTTP protocoland can be implemented over HTTP and over HTTPS.

By default, WebSEAL is configured for authentication over HTTPS via BasicAuthentication (BA) username and password.

Enabling and disabling Basic AuthenticationThe ba-auth parameter, located in the [ba] stanza of the webseald.confconfiguration file, enables and disables the Basic Authentication method.v To enable the Basic Authentication method, enter ″http″, ″https″, or ″both″.v To disable the Basic Authentication method, enter ″none″.

For example:[ba]ba-auth = https

Setting the realm nameThe realm name is the text that is displayed in the dialog box that appears whenthe browser prompts the user for login data.The realm name is also the name ofthe realm to which the user will be authenticated when the user login succeeds.

The configuration parameter that sets the realm name is located in the [ba] stanzaof the webseald.conf configuration file.

For example:[ba]basic-auth-realm = Access Manager


The dialog box would display (for example):Enter username for Access Manager at www.ibm.com:

Configuring the Basic Authentication mechanismThe passwd-ldap parameter specifies the shared library used to handle usernameand password authentication.v On UNIX, the file that provides the built-in mapping function is a shared library

called libldapauthn.v On Windows, the file that provides the built-in mapping function is a DLL

called ldapauthn.

AuthenticationMechanism

Shared Library

Solaris AIX Windows HP-UX

passwd-ldap libldapauthn.so libldapauthn.a ldapauthn.dll libldapauthn.sl

You can configure the username and password authentication mechanism byentering the passwd-ldap parameter with the platform-specific name of the sharedlibrary file in the [authentication-mechanism] stanza of the webseald.confconfiguration file. For example:

Solaris:[authentication-mechanisms]passwd-ldap = libldapauthn.so

Windows:[authentication-mechanisms]passwd-ldap = ldapauthn.dll

Configuration conditionsIf forms authentication is enabled for a specific transport, the Basic Authenticationsettings for that transport will be ignored.

Configuring forms authenticationTivoli Access Manager provides forms authentication as an alternative to thestandard Basic Authentication mechanism. This method produces a custom HTMLlogin form from Tivoli Access Manager instead of the standard login promptresulting from a Basic Authentication challenge.

When you use forms-based login, the browser does not cache the username andpassword information as it does in Basic Authentication.

Enabling and disabling forms authenticationThe forms-auth parameter, located in the [forms] stanza of the webseald.confconfiguration file, enables and disables the forms authentication method.v To enable the forms Authentication method, enter ″http″, ″https″, or ″both″.v To disable the forms Authentication method, enter ″none″.

For example:[forms]forms-auth = https


Configuring the forms authentication mechanismThe passwd-ldap parameter specifies the shared library used to handle usernameand password authentication.v On UNIX, the file that provides the built-in mapping function is a shared library

called libldapauthn.v On Windows, the file that provides the built-in mapping function is a DLL

called ldapauthn.


Shared Library


passwd-ldap libldapauthn.so libldapauthn.a ldapauthn.dll libldapauthn.sl

You can configure the username and password authentication mechanism byentering the passwd-ldap parameter with the platform-specific name of the sharedlibrary file in the [authentication-mechanism] stanza of the webseald.confconfiguration file. For example:

Solaris:[authentication-mechanisms]passwd-ldap = libldapauthn.so

Windows:[authentication-mechanisms]passwd-ldap = ldapauthn.dll

Configuration conditionsIf forms authentication is enabled for a specific transport, the Basic Authenticationsettings for that transport will be ignored.

Customizing HTML response formsForms authentication requires you to use a custom login form. By default, thesample login.html form is located in the following directory:<install-directory>/lib/html

You can customize the content and design of this form.

For detailed information on the available HTML forms you can customize, see“Managing custom account management pages” on page 34.

Configuring client-side certificate authenticationWebSEAL supports secure communication with clients using client-side digitalcertificates over SSL. In this authentication method, certificate information (such asthe Distinguished Name or DN) is mapped to a Tivoli Access Manager identity.

Background: Mutual authentication using certificatesThe exchange of server-side and client-side certificates over SSL results in a trustrelationship between the client and server based on the certificates. A securecommunication channel is also established.

The SSL digital certificate handshake that results in mutual authentication takesplace in two phases:


v WebSEAL identifies itself to SSL clients with its server-side certificatev WebSEAL uses its database of Certificate Authority (CA) root certificates to

validate clients accessing with client-side certificates1. A client requests a connection over SSL with a WebSEAL server.2. In response, WebSEAL sends its public key in a signed server-side certificate.

This certificate has been previously signed by a trusted third-party certificateauthority (CA).

3. The client checks whether the certificate’s issuer is one that it can trust andaccept. The client’s browser usually contains a list of root certificates fromtrusted CAs. If the signature on WebSEAL’s certificate matches one of theseroot certificates, then the server can be trusted.

4. If there is no match for the signature, the browser informs its user that thiscertificate was issued by an unknown certificate authority. It is then the user’sresponsibility to accept or reject the certificate.

5. If the signature matches an entry in the browser’s root certificate database,session keys are securely negotiated between the client and the WebSEALserver.The end result of this process is a secure channel.

6. Now the client sends its public key certificate to the WebSEAL server.7. WebSEAL attempts to match the signature on the client certificate to a known

CA. Like a client browser, the WebSEAL server maintains a list of rootcertificates from trusted CAs in its key database.

8. If there is no match for the signature, WebSEAL will generate an SSL errorcode and send it to the client.

9. If there is a match for the signature, then the certificate can be trusted.10. Tivoli Access Manager authenticates the client by using the built-in shared

library to exactly match the Distinguished name (DN) in the Subject field ofthe client-side certificate with an existing DN entry in the LDAP registry or byusing a custom CDAS to perform an alternative identity matching.The result of successful authentication is an Tivoli Access Manager identitythat is then used to build a credential for that user. It is the credential that isrequired for the client to participate in the Tivoli Access Manager securedomain.

Request

Client

Response

WebSEAL Server

"I can trust who you are."

verisign

www.tivoli.com

Server'sDigital ID

belsigncertisignentrustverisign

...

Browser's CARoot Certificates

Figure 17. Client validates the WebSEAL certificate


The WebSEAL test certificateAt installation, WebSEAL contains a self-signed test server certificate. Although thistest certificate allows WebSEAL to respond to an SSL-enabled browser request, itcannot be verified by the browser (which does not contain an appropriate root CAcertificate). Because the private key for this default certificate is contained in everyWebSEAL distribution, this certificate offers no true secure communication.

To ensure secure communication over SSL, it is very important to register for andobtain a unique site server certificate from a trusted Certificate Authority (CA).You can use the GSKit iKeyman utility to generate a certificate request that is sentto the CA. You can also use iKeyman to install and label the new site certificate.

Use the webseal-cert-keyfile-label parameter in the [ssl] stanza of thewebseald.conf configuration file to designate the certificate as the active WebSEALserver-side certificate (this setting overrides any certificate designated as “default”in the keyfile database).

If you require different certificates for other scenarios (such as for mutuallyauthenticated junctions), you can use the iKeyman utility to create, install, andlabel these additional certificates. See “Configuring key database parameters” onpage 39.

It is also important to ensure that validation of certificates includes checking ofCertificate Revocation Lists (CRLs). Configure WebSEAL to access the appropriateLDAP server as an LDAP user with sufficient permission to access the appropriateCRLs. Supply values for the following configuration file entries:[ssl]crl-ldap-servercrl-ldap-server-portcrl-ldap-usercrl-ldap-user-password

WebSEAL can be configured to cache CRLs. To configure the cache, supply valuesfor the following configuration file entries:[ssl]gsk-crl-cache-sizegsk-crl-cache-entry-lifetime

Instructions for setting values that affect CRL access and handling, including validranges for cache settings, are specified in the “Secure Socket Layer” on page 264section in Appendix A, “WebSEAL configuration file reference”, on page 241. Seealso “Configuring the CRL cache” on page 41.

Enabling and disabling certificate authenticationYou can specify how WebSEAL is to handle authentication via client-sidecertificates over SSL by setting the accept-client-certs parameter, located in the[certificate] stanza of the webseald.conf configuration file.

By default, WebSEAL does not accept client-side certificates:[certificate]accept-client-certs = never

Additional values for this parameter include optional and required.

The following table describes the values allowed for the accept-client-certsparameter:


Value Description

never Do not accept X.509 certificates from clients.

optional Ask clients for an X.509 certificate and use certificate-basedauthentication, if certificate is supplied.

required Ask clients for an X.509 certificate and use certificate-basedauthentication. If client does not present a certificate, do not allowa connection.

Configuring the certificate authentication mechanismThe cert-ssl parameter specifies the shared library for mapping certificateauthentication information.v On UNIX, the file that provides the built-in mapping function is a shared library

called libsslauthn.v On Windows, the file that provides the built-in mapping function is a DLL

called sslauthn.


Shared Library


cert-ssl libsslauthn.so libsslauthn.a sslauthn.dll libsslauthn.sl

You can configure the certificate authentication mechanism by entering the cert-sslparameter with the platform-specific name of the shared library file in the[authentication-mechanism] stanza of the webseald.conf configuration file.

Solaris:[authentication-mechanisms]cert-ssl= libsslauthn.so

Windows:[authentication-mechanisms]cert-ssl = sslauthn.dll

During certificate authentication, the shared library identifies the Tivoli AccessManager user by exactly matching the Distinguished name (DN) in the Subjectfield of the client-side certificate with an existing DN entry in the LDAP registry

Configuring HTTP header authenticationTivoli Access Manager supports authentication via custom HTTP headerinformation supplied by the client or a proxy agent.

This mechanism requires a mapping function (a shared library) that maps thetrusted (pre-authenticated) header data to a Tivoli Access Manager identity.WebSEAL can take this identity and create a credential for the user.

WebSEAL assumes custom HTTP header data has been previously authenticated.For this reason, it is recommended that you implement this methodexclusively—with no other authentication methods enabled. It is possible toimpersonate custom HTTP header data.

By default, this shared library is built to map data from Entrust Proxy headers.


Enabling and disabling HTTP header authenticationThe http-headers-auth parameter, located in the [http-headers] stanza of thewebseald.conf configuration file, enables and disables the HTTP headerauthentication method.v To enable the HTTP header authentication method, enter ″http″, ″https″, or

″both″.v To disable the HTTP header authentication method, enter ″none″.

For example:[http-headers]http-headers-auth = https

Specifying header typesYou must specify all supported HTTP header types in the [auth-headers] stanza ofthe webseald.conf configuration file.[auth-headers]header = <header-type>

By default, this built-in shared library is hard-coded to support Entrust Proxyheader data.[auth-headers]header = entrust-client

You must customize this file to authenticate other types of special header data and,optionally, map this data to a Tivoli Access Manager identity. Refer to the IBMTivoli Access Manager WebSEAL Developer’s Reference for API resources.

Note: By design, WebSEAL only recognizes and processes the first header it findsin the user request that matches any one of the values configured in the[auth-headers] stanza. The HTTP header authentication mechanism is notdesigned to handle more than one HTTP header in a request.

Configuring the HTTP header authentication mechanismThe http-request parameter specifies the shared library for mapping HTTPauthentication header information.v On UNIX, the file that provides the built-in mapping function is a shared library

called libhttpauthn.v On Windows, the file that provides the built-in mapping function is a DLL

called httpauthn.


Shared Library


http-request libhttpauthn.so libhttpauthn.a httpauthn.dll libhttpauthn.sl

By default, this built-in shared library is hard-coded to map Entrust Proxy headerdata to a valid Tivoli Access Manager identity. You must customize this file toauthenticate other types of special header data and, optionally, map this data to aTivoli Access Manager identity. Refer to the IBM Tivoli Access Manager WebSEALDeveloper’s Reference for API resources.


You can configure the HTTP header authentication mechanism by entering thehttp-request parameter with the platform-specific name of the shared library file inthe [authentication-mechanism] stanza of the webseald.conf configuration file.

For example:

Solaris:[authentication-mechanisms]http-request = libhttpauthn.so

Windows:[authentication-mechanisms]http-request = httpauthn.dll

Configuration conditionsv Session ID cookies are not used to maintain state if ssl-id-sessions = no. The

unique header value is used to maintain state.v If the client encounters an authorization failure, the client receives a ″Forbidden″

page (HTTP 403).v Cookie headers cannot be passed to the HTTP header authentication mechanism.

Configuring IP address authenticationTivoli Access Manager supports authentication via an IP address supplied by theclient.

Enabling and disabling IP address authenticationThe ipaddr-auth parameter, located in the [ipaddr] stanza of the webseald.confconfiguration file, enables and disables the IP address authentication method.v To enable the IP address authentication method, enter ″http″, ″https″, or ″both″.v To disable the IP address authentication method, enter ″none″.

For example:[ipaddr]ipaddr-auth = https

Configuring the IP address authentication mechanismAuthentication using an IP address requires a custom shared library. Usehttp-request parameter for this shared library.

Configuring token authenticationTivoli Access Manager supports authentication using a token passcode supplied bythe client.

Enabling and disabling token authenticationThe token-auth parameter, located in the [token] stanza of the webseald.confconfiguration file, enables and disables the token authentication method.v To enable the token authentication method, enter ″http″, ″https″, or ″both″.v To disable the token authentication method, enter ″none″.

For example:


[token]token-auth = https

Configuring the token authentication mechanismThe token-cdas parameter specifies the shared library for mapping token passcodeauthentication information.v On UNIX, the file that provides the built-in mapping function is a shared library

called libxtokenauthn.v On Windows, the file that provides the built-in mapping function is a DLL

called xtokenauthn.


Shared Library


token-cdas libxtokenauthn.so libxtokenauthn.a xtokenauthn.dll libxtokenauthn.sl

By default, this built-in shared library is hard-coded to map SecurID (RSA) tokenpasscode data. This default token authentication mechanism expects the user nameused by the client to map to an existing user account in the Tivoli Access ManagerLDAP registry. You can also customize this library file to authenticate other typesof special token data and, optionally, map this data to an Tivoli Access Manageridentity. Refer to the IBM Tivoli Access Manager WebSEAL Developer’s Reference forExternal Authentication API resources.

You configure the token authentication mechanism by entering the token-cdasparameter with the platform-specific name of the shared library file in the[authentication-mechanism] stanza of the webseald.conf configuration file. Theshared library must include the –r <registry> option and argument. The registrytype must be specified as LDAP.

For example:

Solaris:[authentication-mechanisms]token-cdas = libxtokenauthn.so& -r LDAP

Windows:[authentication-mechanisms]token-cdas = xtokenauthn.dll& -r LDAP

Configuring WebSEAL to use the SecurID client libraryThe default shared library for token authentication maps SecurID (RSA) tokenpasscode data to a Tivoli Access Manager user identity. The authentication processrequires the RSA SecurID client, installed and configured on the WebSEAL servermachine, to communicate with a remote RSA server. The supported SecurID clientversion is 5.0.0.1.

For successful communication between the client and server, you must manuallyset the proper permissions on a SecurID node secret file. You must also set anenvironment variable that points WebSEAL to the location of the node secret file.The file is called securid. The file is sent upon the first successful authenticationbetween the SecurID client and server. Subsequent RSA client/servercommunication relies on an exchange of the node secret to verify one another’sauthenticity.


1. Change the permissions of the sercurid file to allow ″read″ access by everyone.The following example assumes the location of the file is the/opt/ace/ace/data directory:UNIX:# cd /opt/ace/ace/data# chmod 444 securid

Windows:

Set the Security Properties on the file for ″Everyone″.2. Set the VAR_ACE environment variable to inform WebSEAL of the directory

location of this file.The following example assumes the location of the file is the/opt/ace/ace/data directory:UNIX:# export VAR_ACE=/opt/ace/ace/data

Windows:

Start > Settings > Control Panel > System > Environment

Supporting multiplexing proxy agentsTivoli Access Manager provides solutions for securing networks that use aMultiplexing Proxy Agent (MPA).

Standard Proxy Agents (SPA) are gateways that support per-client sessionsbetween clients and the origin server over SSL or HTTP. WebSEAL can applynormal SSL or HTTP authentication to these per-client sessions.

Multiplexing Proxy Agents (MPA) are gateways that accommodate multiple clientaccess. These gateways are sometimes known as WAP gateways when clientsaccess using Wireless Access Protocol (WAP). Gateways establish a singleauthenticated channel to the origin server and ″tunnel″ all client requests andresponses through this channel.

To WebSEAL, the information across this channel initially appears as multiplerequests from one client. WebSEAL must distinguish between the authentication ofthe MPA server and the additional authentication of each individual client.


Because WebSEAL maintains an authenticated session for the MPA, it mustsimultaneously maintain separate sessions for each client. Therefore, the sessiondata and authentication method used for the MPA must be distinct (different) fromthe session data and authentication method used by the client.

Valid session data types and authentication methodsThe session data type used by the MPA to WebSEAL must be distinct (different)from the session data type used by the client to WebSEAL. The table below liststhe valid session types for the MPA and the client:

Valid Session Types

MPA-to-WebSEAL Client-to-WebSEAL

SSL Session ID

HTTP Header HTTP Header

BA Header BA Header

IP Address

Cookie Cookie

v The client cannot use an SSL session ID as the session data type.v As an example, if the MPA uses a BA header for the session data type, the

client’s choices for session data type include only HTTP header and cookie.v If the MPA uses an HTTP header for session data, the client can use a different

HTTP header type.v The server-specific cookie contains session information only; it does not contain

identity information.v If MPA support is enabled, the function of ssl-id-sessions changes. Normally, if

ssl-id-sessions=yes, only the SSL session ID is used to maintain sessions forHTTPS clients. To allow the MPA to maintain a session with an SSL session IDand have clients maintain sessions using another method, this restriction isremoved. See also “Determining valid session ID data types” on page 118.

The authentication method used by the MPA to WebSEAL must be distinct(different) from the authentication method used by the client to WebSEAL. Thetable below lists the valid authentication methods for the MPA and the client:

ClientB

MPAGateway

� multiple sessions over single SSL channel� MPA authenticates to WebSEAL� MPA has membership in webseal-mpa-servers

group

WebSEALServer

ClientA

ClientC

A B C

� clients authenticate to WebSEAL

Figure 18. Communication over an MPA Gateway


Valid Authentication Types

MPA-to-WebSEAL Client-to-WebSEAL

Basic Authentication Basic Authentication

Forms Forms

Token Token

HTTP Header HTTP Header

Certificate

IP Address

v As an example, if the MPA uses Basic Authentication, the client’s choices forauthentication methods includes forms, token, and HTTP header.

v Certificates and IP address authentication methods are not valid for use by theclient.

v Normally, if either forms (or token) authentication is enabled for a particulartransport, Basic Authentication is automatically disabled for that transport (see“Configuring the Basic Authentication mechanism” on page 126. If MPA supportis enabled, this restriction is removed. This allows the MPA to log in, forexample, with forms (or token) and clients to log in with Basic Authenticationover the same transport.

Authentication process flow for MPA and multiple clients1. The WebSEAL administrator performs the following preliminary

configuration:v Enable support for Multiplexing Proxy Agentsv Create a Tivoli Access Manager account for the specific MPA gatewayv Add this MPA account to the webseal-mpa-servers group

2. Clients connect to the MPA gateway.3. The gateway translates the request to an HTTP request.4. The gateway authenticates the client.5. The gateway establishes a connection with WebSEAL with the client request.6. The MPA authenticates to WebSEAL (using a method distinct from the client)

and an identity is derived for the MPA (which already has a WebSEALaccount).

7. WebSEAL verifies the MPA’s membership in the webseal-mpa-servers group.8. A credential is built for the MPA and flagged as a special MPA type in the

cache.Although this MPA credential accompanies each future client request, it is notused for authorization checks on these requests.

9. Now WebSEAL needs to further identify the owner of the request.The MPA is able to distinguish the multiple clients for proper routing of loginprompts.

10. The client logs in and authenticates using a method distinct from theauthentication type used for the MPA.

11. WebSEAL builds a credential from the client authentication data.12. Session data type used by each client must be distinct from the session data

type used by the MPA.13. The authorization service permits or denies access to protected objects based

on the user credential and the object’s ACL permissions.


Enabling and disabling MPA authenticationThe mpa parameter, located in the [mpa] stanza of the webseald.conf configurationfile, enables and disables MPA authentication:v To enable the MPA authentication method, enter ″yes″.v To disable the MPA authentication method, enter ″no″.

For example:[mpa]mpa = yes

Create a user account for the MPARefer to the IBM Tivoli Access Manager Base Administrator’s Guide for information oncreating user accounts.

Add the MPA account to the webseal-mpa-servers groupRefer to the IBM Tivoli Access Manager Base Administrator’s Guide for information onmanaging groups.

MPA authentication limitationsv This release of Tivoli Access Manager supports only one MPA per WebSEAL

server.v MPA authentication is not supported with step-up authentication configuration.v MPA is not supported with use-same-session = yes

Configuring reauthentication based on security policyTivoli Access Manager WebSEAL can force a user to perform an additional login(reauthentication) to ensure that a user accessing a protected resource is the sameperson who initially authenticated at the start of the session. Reauthentication canbe activated by a Protected Object Policy (POP) on the protected object or byexpiration of the inactivity timeout value of a WebSEAL session cache entry.

This section discusses reauthentication based on security policy as dictated by aPOP extended attribute.

Background material on the WebSEAL session cache is provided in “The WebSEALsession/credentials cache structure” on page 11.

Conditions affecting POP reauthenticationForced reauthentication provides additional protection for sensitive resources in thesecure domain. Reauthentication based on security policy is activated by a specificextended attribute in a POP that protects the requested resource object. The POPcan be directly attached to the object, or the object can inherit the POP conditionsfrom a parent object.

Reauthentication is supported by the following WebSEAL authentication methods:v Forms (user name and password) authenticationv Token authentication

In addition, a custom user name/password CDAS can be written to supportreauthentication.


Reauthentication assumes the user has initially logged in to the secure domain andthat a valid credential exists for the user. During reauthentication, the user mustlog in using the same identity that generated the existing credential. WebSEALpreserves the user’s original session information, including the credential, duringreauthentication. The credential is not replaced during reauthentication.

During reauthentication, WebSEAL also caches the request that prompted thereauthentication. Upon successful reauthentication, the cached data is used torebuild the request. See “Configuring WebSEAL server-side request caching” onpage 83.

If reauthentication fails, WebSEAL returns the login prompt again. Ifreauthentication succeeds, but the ACL check fails for that resource, a 403″Forbidden″ is returned and the user is denied access to the requested resource. Ineither case, the user is never logged off. Using a still valid credential, the user canabort the reauthentication process (by requesting another URL) and still participatein the secure domain by accessing other resources that do not requirereauthentication.

Configuration is available to reset the lifetime timer of WebSEAL session cacheentries. In addition, a grace period can be configured to allow sufficient time forthe reauthentication process to complete before the lifetime timeout of a sessioncache entry expires.

Creating and applying the reauthentication POPForced reauthentication based on security policy is configured by creating aprotected object policy (POP) with a special extended attribute named ″reauth″.You can attach this POP to any object that requires the extra protection providedby forced reauthentication.

Remember that all children of the object with the POP also inherit the POPconditions. Each requested child object requires a separate reauthentication.

Use the pdadmin pop create, pdadmin pop modify, and pdadmin pop attachcommands. The following example illustrates creating a POP called ″secure″ withthe reauth extended attribute and attaching it to an object (budget.html):pdadmin> pop create securepdadmin> pop modify secure set attribute reauth truepdadmin> pop attach /WebSEAL/hostA/junction/budget.html secure

Anyone attempting to access budget.html is forced to reauthenticate using thesame identity and authentication method that generated the existing credential.

If the user requesting the resource is unauthenticated, the POP forces the user toauthenticate. No reauthentication is necessary for this resource after successfulinitial login.

Details about the pdadmin command line utility can be found in the IBM TivoliAccess Manager Base Administrator’s Guide.

Configuring session cache entry lifetime reset and extension

Resetting the session cache entry lifetime valueThe user’s session cache entry has a limited lifetime, as specified by the timeoutparameter in the [session] stanza of the webseald.conf configuration file. Thedefault value, in minutes, is 3600 (1 hour):


[session]timeout = 3600

Regardless of session activity or inactivity, the session cache entry is removedwhen the lifetime value is reached, at which point the user is logged off.

However, you can configure the lifetime of the session cache entry to be resetwhenever reauthentication occurs. With this configuration, the user session nolonger has a single maximum lifetime value. Each time reauthentication occurs, thelifetime value of the session cache entry is reset.

You can configure session cache entry lifetime reset with the reauth-reset-lifetimeparameter in the [reauthentication] stanza of the webseald.conf configuration file:[reauthentication]reauth-reset-lifetime = yes

The default value is ″no″.

This parameter is also appropriate for reauthentication due to the expiration of theinactivity timeout value for a session cache entry. See “Configuringreauthentication based on session inactivity policy” on page 140.

Extending the session cache entry lifetime valueIt is possible for the lifetime value of a session cache entry to expire while the useris performing a reauthentication. This situation occurs under the followingconditions:v The user requests a resource protected by a reauthentication POPv The user’s session cache entry lifetime value is very near expiration

The lifetime of a session cache entry can expire after the reauthentication loginform is sent to the user and before the completed login form is returned. When thesession cache entry lifetime value expires, the session cache entry is deleted. Whenthe login form is returned to WebSEAL, there is no longer a session for that user.In addition, all cached user request data is lost.

You can configure a time extension, or ″grace period,″ for the session cache entrylifetime value if the session cache entry lifetime expires during reauthentication.The reauth-extend-lifetime parameter in the [reauthentication] stanza of thewebseald.conf configuration file provides this time extension, in seconds. Forexample (5 minutes):[reauthentication]reauth-extend-lifetime = 300

The default value, ″0″, provides no extension to the session cache entry timeoutvalue.

The reauth-extend-lifetime parameter applies to users with existing session cacheentries and who are required to reauthenticate. For example:v Users performing reauthentication resulting from POP security policyv Users performing reauthentication resulting from session cache inactivityv Users performing step-up authentication

The reauth-extend-lifetime option is intended to be used in conjunction with thereauth-reset-lifetime=yes option.


This parameter is also appropriate for reauthentication due to the expiration of thesession cache entry inactivity timeout value. See “Configuring reauthenticationbased on session inactivity policy” on page 140.

Customizing login forms for reauthenticationWebSEAL supports reauthentication for both forms and token authenticationmethods. By default, forms authentication uses the login.html page to request username and password information from the client (see “Custom HTML pagedescriptions” on page 35). By default, token authentication uses thetokenlogin.html page to request user name and token passcode information fromthe client (see “Custom HTML page descriptions” on page 35). These same defaultlogin pages are also used during reauthentication.

During initial login, both user name and password (passcode) fields are blank ineach of these login pages. However, it is possible to have the user name field inthese login pages automatically filled in during reauthentication by using the%USERNAME% macro (see “Macro support for account management pages” onpage 35). The client needs to complete only the password (passcode) field.

For example, modify the following line in the login.html page:<TD><INPUT NAME="username" SIZE="15"></TD>

to include the %USERNAME% macro:<TD><INPUT NAME="username" SIZE="15" VALUE="%USERNAME%"></TD>

During an initial login, the value for the %USERNAME% macro is empty and theuser name text field displayed on the login page appears blank. For areauthenticating client, the %USERNAME% macro now contains the value of theclient user name. The user name text field on the login page appears with theuser’s name automatically provided.

Configuring reauthentication based on session inactivity policyTivoli Access Manager WebSEAL can force a user to perform an additional login(reauthentication) to ensure that a user accessing a protected resource is the sameperson who initially authenticated at the start of the session. Reauthentication canbe activated by a Protected Object Policy (POP) on the protected object or byexpiration of the inactivity timeout value for a WebSEAL session cache entry.

This section discusses reauthentication based on the expiration of the inactivitytimeout value for a WebSEAL session cache entry.

Background material on the WebSEAL session cache is provided in “The WebSEALsession/credentials cache structure” on page 11.

Conditions affecting inactivity reauthenticationForced reauthentication provides additional protection for sensitive resources in thesecure domain. Reauthentication based on session inactivity policy is enabled by aconfiguration parameter and is activated by the expiration of the inactivity timeoutvalue of the session cache entry.

Reauthentication is supported by the following supported WebSEAL authenticationmethods:v Forms (user name and password) authentication


v Token authentication

In addition, a custom user name/password CDAS can be written to supportreauthentication.

Reauthentication assumes the user has initially logged in to the secure domain andthat a valid credential exists for the user. During reauthentication, the user mustlog in using the same identity that generated the existing credential. WebSEALpreserves the user’s original session information, including the credential, duringreauthentication. The credential is not replaced during reauthentication.

During reauthentication, WebSEAL also caches the request that prompted thereauthentication. After successful reauthentication, the cached data is used torebuild the request. See “Configuring WebSEAL server-side request caching” onpage 83.

A user’s session is normally regulated by a session inactivity value and a sessionlifetime value. When WebSEAL is configured for reauthentication based on sessioninactivity, the user’s session cache entry is ″flagged″ whenever the sessioninactivity timeout value expires. The session cache entry (containing the usercredential) is not removed. The user can proceed to access unprotected resources.However, if the user requests a protected resource, WebSEAL sends a loginprompt. After successful reauthentication, the inactive session ″flag″ is removedand the inactivity timer is reset.

If reauthentication fails, WebSEAL returns the login prompt again. The sessioncache entry remains ″flagged″ and the user can proceed as unauthenticated untilthe session cache entry lifetime value expires.

If reauthentication succeeds, but the ACL check fails for that resource, a 403″Forbidden″ is returned and the user is denied access to the requested resource.

The session cache entry lifetime value usually determines the maximum sessionlength. When this lifetime value expires, the session is normally terminatedregardless of activity. However, WebSEAL can be configured to allow the user toreauthenticate after the session lifetime value has expired. After successfulreauthentication, the lifetime value of the session cache entry is reset.

Two other conditions can end a user session: the user can explicitly log out or anadministrator can terminate a user session. See “Terminating user sessions” onpage 230.

Configuration is available to reset the WebSEAL session cache entry lifetime timer.In addition, a grace period can be configured to allow sufficient time for thereauthentication process to complete before the lifetime timeout of the sessioncache entry expires.

Enabling inactivity reauthenticationTo configure WebSEAL to ″flag″ inactive sessions rather than remove them fromthe session cache, set the value for the reauth-for-inactive parameter to ″yes″ in the[reauthentication] stanza of the webseald.conf configuration file:[reauthentication]reauth-for-inactive = yes

The default value for this parameter is ″no″.


Resetting and extending the session cache entry lifetimevalue

Resetting the session cache entry lifetime valueThe user’s session cache entry has a limited lifetime, as specified by the timeoutparameter in the [session] stanza of the webseald.conf configuration file. Thedefault value, in seconds, is 3600 (1 hour):[session]timeout = 3600

Regardless of session activity or inactivity, the session cache entry is removedwhen the lifetime value is reached, at which point the user is logged off.

However, you can configure the lifetime of the session cache entry to be resetwhenever reauthentication occurs. With this configuration, the user session nolonger has a single maximum lifetime value. Each time reauthentication occurs, thesession cache entry lifetime value is reset.

You can reset the lifetime value of session cache entries with thereauth-reset-lifetime parameter in the [reauthentication] stanza of thewebseald.conf configuration file:[reauthentication]reauth-reset-lifetime = yes

The default value is ″no″.

This parameter is also appropriate for reauthentication due security (POP) policy.See “Configuring reauthentication based on security policy” on page 137.

Extending the session cache entry lifetime valueIt is possible for the lifetime value of a session cache entry to expire while the useris performing a reauthentication. This situation occurs under the followingconditions:v The user requests a resource protected by a reauthentication POPv The user’s session cache entry lifetime value is very near expiration

The session cache entry lifetime can expire after the reauthentication login form issent to the user and before the completed login form is returned. When the sessioncache entry lifetime value expires, the session cache entry is deleted. When thelogin form is returned to WebSEAL, there is no longer a session for that user. Inaddition, all cached user request data is lost.

You can configure a time extension, or ″grace period,″ for the session cache entrylifetime if the lifetime of the session cache entry expires during reauthentication.The reauth-extend-lifetime parameter in the [reauthentication] stanza of thewebseald.conf configuration file provides this time extension, in seconds. Forexample (5 minutes):[reauthentication]reauth-extend-lifetime = 300

The default value, ″0″, provides no extension to the timeout value of the sessioncache entry.

The reauth-extend-lifetime parameter applies to users with existing session cacheentries and who are required to reauthenticate. For example:


v Users performing reauthentication resulting from POP security policyv Users performing reauthentication resulting from session cache inactivityv Users performing step-up authentication

The reauth-extend-lifetime option is intended to be used in conjunction with thereauth-reset-lifetime=yes option.

This parameter is also appropriate for reauthentication due to security (POP)policy. See “Configuring reauthentication based on security policy” on page 137.

Preventing session removal when the session lifetime expiresIt is possible for a user to remain active for the full duration of a session lifetime.When the session lifetime value expires, the session cache entry is normallyremoved and the user is logged off. To prevent this sudden session termination,you can configure WebSEAL to allow the user to reauthenticate after the sessiontimeout value has expired.

WebSEAL allows resetting of the session lifetime value, after it has expired, underthe following conditions:v Reauthentication based on inactivity policy is enabled (reauth-for-

inactive=yes)v The session lifetime value (timeout) has expiredv The time extension (″grace period″) for the session lifetime is enabled and set to

a reasonable value (for example, reauth-extend-lifetime=300)v The user activates the reauthentication prompt by requesting a protected

resource before the time extension (″grace period″) expires(WebSEAL does not allow repeated additions of the time extension to an end ofsession lifetime event.)

v Resetting the session cache lifetime is configured to be true (reauth-reset-lifetime=yes)

At the occurrence of a session lifetime expiration, WebSEAL checks the conditionslisted above. If all conditions are met, the lifetime timeout is extended by thereauth-extend-lifetime value and the user’s session cache entry is ″flagged″ asextended. The session cache entry (containing the user credential) is not removedand the use can proceed to access unprotected resources. When the user requests aprotected resource, WebSEAL prompts the user to reauthenticate.

The reauth-extend-lifetime value should be set to a reasonable value so the userhas enough time to trigger the reauthentication prompt. Note that if the user doesnot access a protected object during the ″grace period″, the reauthenticationprocess is not activated. In this case, it is possible for the reauth-extend-lifetimevalue to expire, in which case the session cache entry is removed.

Typically, however, reauthentication policy is implemented to secure an applicationthat is serving predominantly protected resources. A time extension (″graceperiod″) of 5–10 minutes should be adequate time to allow an active user to triggerthe reauthentication process, and thus reset the session lifetime value.

Customizing login forms for reauthenticationWebSEAL supports reauthentication for both forms and token authenticationmethods. By default, forms authentication uses the login.html page to request username and password information from the client (see “Custom HTML pagedescriptions” on page 35). By default, token authentication uses the


tokenlogin.html page to request user name and token passcode information fromthe client (see “Custom HTML page descriptions” on page 35). These same defaultlogin pages are also used during reauthentication.

During initial login, both user name and password (passcode) fields are blank ineach of these login pages. However, it is possible to have the user name field inthese login pages automatically filled in during reauthentication by using the%USERNAME% macro (see “Macro support for account management pages” onpage 35). The client needs to complete only the password (passcode) field.

For example, modify the following line in the login.html page:<TD><INPUT NAME="username" SIZE="15"></TD>

to include the %USERNAME% macro:<TD><INPUT NAME="username" SIZE="15" VALUE="%USERNAME%"></TD>

During an initial login, the value for the %USERNAME% macro is empty and theuser name text field displayed on the login page appears blank. For areauthenticating client, the %USERNAME% macro now contains the value of theclient user name. The user name text field on the login page appears with theuser’s name automatically provided.

Configuring automatic redirection to a login home pageWhen a user makes a request for a resource in a WebSEAL domain, WebSEALnormally sends the resource to the user upon successful authentication and policychecks. As an alternative to this standard response, it is possible to configureWebSEAL to automatically redirect the user to a specially designated home, orwelcome, page. This ″forced redirection″ at login would be appropriate when it isimportant to have users enter the WebSEAL domain through a home, or ″portal″,page. The technique of automatic redirection would also override attempts toaccess specific pages within the domain via user bookmarks.

Automatic redirection process flowThe following process flow assumes automatic redirection has been enabled for theappropriate authentication method:1. The user sends a request and is successfully authenticated.2. WebSEAL builds a custom response that is returned to the browser as a

redirect.This redirect response contains the URL value specified by thelogin-redirect-page parameter in the webseald.conf configuration file.

3. The browser follows the redirect response (containing the configured URL).4. WebSEAL returns the page located at the configured URL.

Conditions affecting automatic redirectionv Automatic redirection at login is enabled and disabled on a per-authentication

method basis.v Valid authentication methods that support automatic redirection configuration

include:– Basic authentication (ba-auth)– Forms authentication (forms-auth)– Token authentication (token-auth)


v Automatic redirection at login is not an option during reauthentication.

Configuring the custom URLThe login-redirect-page parameter in the [acnt-mgt] stanza of the webseald.confconfiguration file specifies the URL that the user is redirected to after login.

The URL can be expressed as an absolute or server-relative path. For example:[acnt-mgt]login-redirect-page = http://www.ibm.com

or[acnt-mgt]login-redirect-page = /jct/intro-page.html

Enabling and disabling automatic redirectionAutomatic redirection at login is enabled and disabled on a per-authenticationmethod basis. Valid authentication methods that support automatic redirectionconfiguration include:v Basic authentication (ba-auth)v Forms authentication (forms-auth)v Token authentication (token-auth)

You enable automatic redirection by specifying the appropriate authenticationmethods using the redirect parameter in the [enable-redirects] stanza of thewebseald.conf configuration file. Valid values for the redirect parameter includeforms-auth, basic-auth, and token-auth. Uncomment the appropriate existing linesin the [enable-redirects] stanza. For example:[enable-redirects]redirect = forms-authredirect = basic-authredirect = token-auth


Chapter 6. Cross-domain single sign-on solutions

When WebSEAL is implemented as a proxy server to provide protection to asecure domain, there is often a requirement to provide solutions for single sign-onto resources across unique domains and servers. This chapter discusses twocross-domain single sign-on solutions.

Topic Index:

CDSSO

v “Understanding CDSSO authentication” on page 147v “Configuring CDSSO authentication” on page 149

E-community

v “Understanding e-community single sign-on” on page 154v “Configuring e-community single sign-on” on page 161

Understanding CDSSO authenticationThe Tivoli Access Manager Cross-Domain Single Sign-on (CDSSO) provides adefault mechanism for transferring user credentials between unique servers anddomains. CDSSO allows Web users to perform a single sign-on and moveseamlessly between two separate secure domains when requesting a resource. TheCDSSO authentication mechanism does not rely on a Master Authentication Serveror MAS (see “Understanding e-community single sign-on” on page 154).

CDSSO supports the goals of scalable network architecture by allowing theintegration of multiple secure domains. For example, a large corporate extranet canbe set up with two or more unique domains—each with its own users and objectspace. CDSSO allows movement of users between the domains with a singlesign-on.

When a user makes a request to a resource located in another domain, the CDSSOmechanism transfers an encrypted user identity token from the first domain to thesecond domain. The identity information in this token indicates to the receivingdomain that the user is successfully authenticated in the first domain. The identitydoes not contain password information. The receiving server uses this token tobuild credentials in its own cache for that user. The user is not forced to performan additional login.

Customizing single sign-on authenticationCross-domain single sign-on solutions employ authentication tokens that conveyan encoded version of the user identity to the destination server. The constructionof these tokens by the initial server is called ″token creation.″ The decoding anduse of the token by the destination server is called ″token consumption.″ You cancreate custom token create and consume libraries to meet the specific requirementsof your network and Tivoli Access Manager implementation. Complete informationand API reference material for cross-domain external authentication can be foundin the IBM Tivoli Access Manager WebSEAL Developer’s Reference.


In many CDSSO scenarios, the default one-to-one mapping between users indifferent domains might not suit all deployment requirements.

The Cross-domain Mapping FrameWork (CDMF) is a programming interface thatallows you to build a custom shared library that can handle extended userattributes and provide mapping services for the user identity.

The CDMF programming interface allows flexibility in customizing the mapping ofuser identities and the handling of user attributes. Complete information and APIreference material for CDMF can be found in the IBM Tivoli Access ManagerWebSEAL Developer’s Reference.

CDSSO features and requirementsv All WebSEAL servers participating in CDSSO must have machine times

synchronized. Authentication between servers can fail when machine timedifferences are too great.

v For CDSSO to function successfully, each participating WebSEAL server mustreveal its fully qualified host name to the other participating servers in thecross-domain environment. If any host name does not include a domain, CDSSOcannot be enabled and an error message is logged in msg_webseald.log. Whensetting up a CDSSO environment, ensure that the machine-specific networkingsetup for each participating server is configured to identify the server with afully qualified host name.

v Because some WebSEAL configuration requires machine host names to bedescribed as fully qualified host names, you must ensure that your system andnetwork can resolve machine names into fully qualified host names. Forexample, using fully qualified host names allows for many host names (IPaddresses) per machine, as in the case of multiple WebSEAL instances.

Authentication process flow for CDSSO with CDMFThe following process flow description is illustrated in Figure 19.1. Any user who wants to participate in multiple domains must have a valid user

account in the initial domain and an identity that can be mapped into a validaccount in each of the participating remote domains.A user cannot invoke the CDSSO functionality without initially authenticatingto an initial secure domain (A) that contains the user’s account.

2. The user makes a request to access a resource in domain B via a custom link ona Web page.The link contains a special CDSSO management page expression:/pkmscdsso?<destination-URL>

For example:http://websealA/pkmscdsso?https://websealB/resource.html

3. The request is first processed by the WebSEAL server in domain A. ThewebsealA server builds an authentication token that contains the user’scredentials, including the Tivoli Access Manager identity (short name), thecurrent domain (″A″), additional user information, and a time stamp. Thisprocess is performed by the ″token create″ function of the built-in singlesign-on authentication mechanism (library).The additional user information (extended attributes) can be obtained by a callout to the customized CDMF shared library (cdmf_get_usr_attributes). Thislibrary has the ability to supply user attributes that can be used by domain Bduring the user mapping process.


WebSEAL triple-DES encrypts this token data with the symmetric keygenerated by the cdsso_key_gen utility. This key file is shared and stored in the[cdsso-peers] stanza of the webseald.conf configuration file on both domain Aand domain B WebSEAL servers.The token contains a configurable time stamp (authtoken-lifetime) that definesthe lifetime of the token. The time stamp, when properly configured, canprevent replay attacks.The token is contained in a redirected request to the destination server, usingthe URL contained in the pkmscdsso link. For example:http://websealB/resource.html?PD-ID=<encoded-authentication-token>

4. The websealA server redirects the request containing the encrypted token backto the browser and then to the websealB server (HTTP redirection).

5. The webseal B server decodes and validates the token as coming from thereferring domain. This process is performed by the ″token consume″ function ofthe built-in single sign-on authentication mechanism (library).

6. The token consume functionality can further call out to a customized CDMFlibrary which performs the actual user mapping (cdmf_map_usr).The CDMF library passes the user’s identity, and any extended attributeinformation, back to the token consume library. The token consume library usesthis information to build a credential.

7. The websealB authorization service permits or denies access to protectedobjects based on the user’s credential and the specific ACL permissionsassociated with the requested objects.

Configuring CDSSO authentication

CDSSO configuration summaryThe following configuration steps are explained in detail in the remaining sectionsof this CDSSO chapter division.

WebSEALA

single sign-onClient

Domain A

/

WebSEALB

Domain B

/

� Client clicks on link to Domain B.� WebSEAL A CDSSO uses CDMF library to get

additional user information. Then builds andsends encrypted ID token with request.

� WebSEAL B decrypts and validates token� WebSEAL B CDSSO calls CDMF shared

library to map the user identity.� Credential is built and client participates in

Domain B

SSL

CDMFSharedLibrary

CDMFSharedLibrary

CDSSOLibrary

/pkmscdsso

Figure 19. Cross-domain single sign-on process with CDMF

Chapter 6. Cross-domain single sign-on solutions 149

Configuring default CDSSO token create functionality1. Enable CDSSO authentication to process single sign-on requests by

communication type (cdsso-auth).2. Configure the built-in single sign-on authentication mechanism (library) for

token create (sso-create).3. Create the key file used to encode and decode the token. Copy the key file to

all appropriate participating servers ([cdsso-peers] stanza).4. Configure the token time stamp (authtoken-lifetime)5. Configure the token label parameter (cdsso-argument).

Configuring default CDSSO token consume functionality1. Enable CDSSO authentication to process single sign-on requests by

communication type (cdsso-auth).2. Configure the built-in single sign-on authentication mechanism (library) for

token consume (sso-consume).3. Assign the appropriate key file ([cdsso-peers] stanza).4. Configure the token time stamp (authtoken-lifetime)5. Configure the token label parameter (cdsso-argument).

Enabling and disabling CDSSO authenticationThe cdsso-auth parameter, located in the [cdsso] stanza of the webseald.confconfiguration file, enables and disables the CDSSO authentication method, andprocesses single sign-on requests by communication type.v To enable the CDSSO authentication method, enter ″http″, ″https″, or ″both″.

The values ″http″, ″https″, and ″both″ specify the type of communication usedby CDSSO participants.

v To disable the CDSSO authentication method, enter ″none″.The value ″none″ disables CDSSO for that server. The default setting is ″none″.

For example:[cdsso]cdsso-auth = https

Configuring the single sign-on authentication mechanismThe default CDSSO configuration requires that you enable the sso-create andsso-consume single sign-on authentication mechanisms. The sso-create mechanismis required by the initial WebSEAL server for creating the CDSSO token andbuilding the redirected request. The sso-consume mechanism is required by thereceiving WebSEAL server to decode the token and build the user credentials fromthe identity information contained in the token. For the default CDSSOconfiguration, each parameter specifies a built-in CDSSO token library file. Onelibrary contains the code for the token create functionality and the other librarycontains the code for the token consume functionality.v On UNIX, the library files are called libssocreate. {so | a | sl} and

libssoconsume. {so | a | sl}.v On Windows, the library files are DLL files called ssocreate.dll and

ssoconsume.dll.



Single Sign-on Token Library


sso-create libssocreate.so libssocreate.a ssocreate.dll libssocreate.sl

sso-consume libssoconsume.so libssoconsume.a ssoconsume.dll libssoconsume.sl

You can configure the CDSSO authentication mechanism by specifying thesso-create and sso-consume parameters with the full path name of the appropriateplatform-specific default library file in the [authentication-mechanism] stanza ofthe webseald.conf configuration file.

For example:

Solaris:[authentication-mechanisms]sso-create = /opt/pdweb/lib/libssocreate.sosso-consume = /opt/pdweb/lib/libssoconsume.so

Windows:[authentication-mechanisms]sso-create = C:\Program Files\Tivoli\PDWeb\bin\ssocreate.dllsso-consume = C:\Program Files\Tivoli\PDWeb\bin\ssoconsume.dll

Encrypting the authentication token dataWebSEAL must encrypt the authentication data placed in the token using a keygenerated by the cdsso_key_gen utility. You must ″synchronize″ this key bysharing the key file with each participating WebSEAL server in each participatingdomain. Each participating WebSEAL server in each domain needs to use the samekey.

The generated key is a triple DES 192 bit key. You cannot specify a life span timeon this key.

Note: The distribution of key files is not a part of the Tivoli Access ManagerCDSSO process.

The cdsso_key_gen utility requires that you specify the location (absolutepathname) of the key file when you run the utility. You must also use a full pathname to run this utility:



Enter this key file location in the [cdsso-peers] stanza of the webseald.confconfiguration file of the participating WebSEAL server in each domain. The formatmust include the fully qualified host name of the WebSEAL server and theabsolute pathname to the key file location:[cdsso-peers]<fully-qualified-host-name> = <full-keyfile-pathname>

Configuration example for server websealA in domain A:


[cdsso-peers]websealB.domainB.com = <pathname>/A-B.key

This setting specifies what key websealA uses to encrypt a token destined forwebsealB in domain B.

Configuration example for server websealB in domain B:[cdsso-peers]websealA.domainA.com = <pathname>/A-B.key

This setting specifies what key websealB (in domain B) uses to decrypt a tokenreceived from websealA in domain A.

In the above example, the A-B.key file is generated on one machine (websealA, forexample) and manually (and securely) copied to the other machine (websealB, forexample).

Configuring the token time stampThe token contains a configurable time stamp that defines the lifetime of theidentity token. After the time stamp has expired, the token is considered invalidand is not used. The time stamp is used to help prevent replay attacks by setting avalue short enough to prevent the token from being stolen and replayed within itslifetime.

The authtoken-lifetime parameter, located in the [cdsso] stanza of thewebseald.conf configuration file, sets the token lifetime value. The value isexpressed in seconds. The default value is 180:[cdsso]authtoken-lifetime = 180

You must take into account any clock skew among the participating domains.Clock skew means that the system times differ on the relevant servers in eachdomain. When this difference approaches the value of authtoken-lifetime, theeffective lifetime of the token is greatly reduced. When this difference exceeds thevalue of authtoken-lifetime, tokens from one domain cannot be valid for theother domain. Administrators should adjust authtoken-lifetime accordingly.However, when clock skew requires that authtoken-lifetime be set to a largevalue, the risk of replay attacks increases. In this case, administrators shouldconsider synchronizing the system time on the relevant servers in each domain.

See “Cross-domain single sign on” on page 283 in Appendix A, “WebSEALconfiguration file reference”, on page 241.

Configuring the token label nameThe authentication information used for a single sign-on transaction is placed inthe redirected request as an encrypted token query string argument to the request.This token string requires a name, or label, to identify it. The label name uniquelyidentifies the request to the receiving WebSEAL server as a single sign-on requestto be handled by the CDSSO token consume mechanism (library).

You must configure this token label on both WebSEAL servers participating in thesingle sign-on functionality. To configure the token label, use the cdsso-argumentparameter located in the [cdsso] stanza of the webseald.conf configuration file. Forexample (default):


[cdsso]cdsso-argument = PD-ID

See “Cross-domain single sign on” on page 283.

Creating the CDSSO HTML linkThe HTML link (located on the original server) that connects the user to a resourceon the destination server must use a special CDSSO expression that directs therequest to a CDSSO management page pkmscdsso:/pkmscdsso?<destination-URL>

For example:http://websealA/pkmscdsso?https://websealB/resource.html

The token create library creates and encodes an authentication token (containingthe user’s identity information) and includes this token in a redirected request tothe resource using the destination URL information from the CDSSO link. Forexample:http://websealB/resource.html?PD-ID=<encoded-authentication-token>

Protecting the authentication tokenWhile the authentication token does not contain authentication information (suchas user name and password), it does contain a user identity that is trusted withinthe receiving domain. The token itself must therefore be protected against theft andreplay.

The token is protected against theft off the wire through the use of SSL to securecommunications between the WebSEAL servers and the users. The token couldconceivably be stolen from the user’s browser history. The time stamp on the tokenshould be short enough to make it unlikely that the token could be stolen andreplayed during the lifetime of the token.

However, a token that has expired with respect to its time stamp is still vulnerableto cryptographic attacks. If the key used to encrypt the token is discovered orotherwise compromised, malicious users could build their own tokens.

These tokens could then be inserted into a ″pseudo-CDSSO flow.″ They would beindistinguishable from real authentication tokens to the WebSEAL serversparticipating in the CDSSO domain. For this reason, the keys used to protect thetokens must also be carefully managed and changed on a regular basis.

Enabling compatibility with previous releasesIn this release of Tivoli Access Manager, the level of security has been increased forthe encryption of the authentication token. The new encryption algorithm is notbackward compatible. If you are integrating CDSSO with servers using previousversions of Tivoli Access Manager, you must enable the pre-410-compatible-tokensparameter in the [server] stanza of the webseald.conf configuration file. Forexample:pre-410-compatible-tokens = yes



Understanding e-community single sign-onE-community single sign-on is another implementation of cross-domainauthentication in an Tivoli Access Manager environment. The goal of cross-domainauthentication is to allow users to access resources across multiple servers inmultiple domains without re-authentication.

An ″e-community″ is a group of distinct domains (Tivoli Access Manager or DNS)that participate in a business relationship. These participating domains can beconfigured as part of one business (and perhaps using different DNS names forgeographic reasons) or as disparate businesses with a shared relationship (forexample, company headquarters, a life insurance company, and a financialmanagement company).

In either scenario, there is always one domain that is designated the ″home″ or″owner″ domain. In the case of participating businesses, the home domain ownsthe business agreements that govern the e-community.

In both scenarios, authentication information about the users who participate in thee-community (including the user names and passwords used for authentication) ismaintained in the home domain. This arrangement allows a single point ofreference for administration issues, such as help desk calls within the e-communitythat all refer to the home domain.

Alternatively, you can use the Tivoli Access Manager Web Portal Manager todelegate the management of this information such that participating domains haveresponsibility for the administration of their own users.

The diagram below illustrates a sample e-community with two participatingdomains: domain A (dA.com) and domain B (dB.com). In this example, domain Arepresents the home or owner domain. Domain B is a participating, or ″remote″,domain.


The home domain ″owns″ the users—that is, it controls the user’s authenticationinformation. Regardless of where a user makes a request for resources, the homedomain is always where the user must authenticate.

Authentication occurs against a master authentication server (MAS)—a server (orset of replica servers) that is located in the home domain and configured toauthenticate all users. The diagram represents the MAS as mas.dA.com. The dutyof the MAS should be restricted to providing authentication services. The MASshould not contain resources that are available to users.

After a user has successfully authenticated to the MAS, the MAS generates a″vouch for″ token. This token is passed back to the server where the user ismaking the request. The server treats this ″vouch for″ token as proof that the userhas successfully authenticated to the MAS and can participate in the e-community.

The transfer of information between e-community domains is described in detail inthe section “e-community process flow” on page 156.

e-community features and requirementsv The model supports access via direct URLs (bookmarks) to resources. This

feature contrasts with the CDSSO model that relies on a specially configuredpkmscdsso link (see “Understanding CDSSO authentication” on page 147).

v The e-community implementation requires a consistent configuration across allWebSEAL servers in all domains participating in the e-community.

v For e-community to function successfully, each participating WebSEAL servermust reveal its fully qualified host name to the other participating servers in thecross-domain environment. If any host name does not include a domain,e-community cannot be enabled and an error message is logged inmsg_webseald.log. When setting up an e-community environment, ensure that

Client

Domain A Domain B

mas.dA.com

WebSEAL 1

WebSEAL 2

WebSEAL MAS WebSEAL 3

WebSEAL 4

ws2.dA.com

ws1.dA.com

ws3.dB.com

ws4.dB.com

Figure 20. The e-community model


the machine-specific networking setup for each participating server is configuredto identify the server with a fully qualified host name.

v Because some WebSEAL configuration requires machine host names to bedescribed as fully qualified host names, you must ensure that your system andnetwork can resolve machine names into fully qualified host names. Forexample, using fully qualified host names allows for many host names (IPaddresses) per machine, as in the case of multiple WebSEAL instances.

v All WebSEAL servers participating in e-community must have machine timessynchronized. Authentication between servers can fail when machine timedifferences are too great.

v All users who are participating in the e-community authenticate against a singlemaster authentication server (MAS) located in the home domain.

v The e-community implementation allows for ″local″ authentication in remotedomains if the user does not have a valid account with the MAS (for example,users who belong to domain B but do not participate in the domain A-domain Be-community).A user who fails authentication with the MAS when requesting a resource in anon-MAS (but participating) domain is given the option to authenticate to thelocal server where the request is being made.

v The MAS (and eventually other selected servers in the remote domains) ″vouchfor″ the user’s authenticated identity.

v Domain-specific cookies are used to identify the server that can provide ″vouchfor″ services. This allows servers in a remote domain to request ″vouch for″information locally. The encrypted contents of e-community cookies do notcontain user identity or security information.

v Special tokens are used to pass encrypted ″vouched for″ user identity. The″vouch for″ token does not contain actual user authentication information.Integrity is provided by shared secret key (triple-DES). The token contains atime-out (lifetime) value to limit the duration of the token validity.

v The e-community implementation is supported on both HTTP and HTTPS.v Individual e-community domains manage their own user identities and

associated privileges. You can use the Cross-domain Mapping Function (CDMF)API to map a user from a remote domain to a valid user in the local domain.If the e-community domains share global user identities, those users could bedistinguished by different passwords in the different domains. For example, auser ″abc″ can exist in both domain A and domain B, using different passwordsfor each domain.

v Configuration for e-community is set in the webseald.conf file of eachparticipating WebSEAL server.

e-community process flowAn e-community consists of a master authentication WebSEAL server (MAS) andadditional WebSEAL servers located in the home domain and remote domains. TheMAS can exist as a single instance of a WebSEAL server, or a set of WebSEALreplicas located behind a load balancer (where the load balancer is identified as theMAS).

All participating local and remote WebSEAL servers need to be configured to usethe home domain MAS for initial client authentication. This is a hard requirementfor servers in the home domain, and a soft requirement for servers in remotedomains. For example, some servers in remote domains can be configured to


handle their own authentication. These servers, and the resources they protect, canoperate independently of the e-community, even if they are located in aparticipating e-community domain.

The e-community implementation is based on a ″vouch for″ system. Normally,when a user requests a resource from a WebSEAL server where the user has notestablished a valid session, WebSEAL prompts the user for authenticationinformation. In an e-community configuration, the WebSEAL server identifies a″vouch for″ server and requests verification from this ″vouch for″ server that theuser has authenticated.

The ″vouch for″ server has valid credential information for that user. For the user’sfirst request, the ″vouch for″ server is always the MAS. The MAS continues toserve as the ″vouch for″ server for resources located in the home domain. As theuser continues with resource requests across the e-community, an individual serverin each remote domain can build its own credential for the user (based on useridentity information from the MAS) and assume the role of ″vouch for″ server forresources in its domain.

The verification requested of the ″vouch for″ server takes the form of a ″vouch for″token. The ″vouch for″ server creates the token and returns it to the requestingWebSEAL server. The user identity information in the token is encrypted. Thetoken contains a lifetime limit.

Upon receipt of the ″vouch for″ token, the requesting server builds credentials anda local session for that user. The user can now access the requested resource basedon normal authorization controls. The user benefits from not having tore-authenticate—a goal of the e-community model.

Refer to the following diagram as you follow the e-community process flow in theremainder of this section. The process flow describes two possible FIRST accessscenarios (1 and 2). These are followed by two possible NEXT access scenarios (3and 4) which follow immediately after 2 or 3. Scenario 5 occurs any time after theinitial access.

″Vouch For″ Servers

Client

Domain A Domain B

mas.dA.com

ws1.dA.com

ws2.dA.com

WebSEAL 1

WebSEAL 2

WebSEAL MAS

ws3.dB.com

ws4.dB.com

WebSEAL 3

WebSEAL 4

Figure 21. e-community process flow


v The MAS is always used to authenticate a user accessing any part of thee-community for the first time.The MAS should perform only as an authentication server and not as a resourceprovider. The MAS should not be configured to act as a master authenticationserver and, simultaneously, protect resources. This recommendation addressesperformance concerns and is not a security requirement.

v The MAS is always the ″vouch for″ server for the home domain (domain A inthis example).

v A domain-specific e-community cookie is used to identify the ″vouch for″ serverfor all other servers within a given domain. The ″vouch for″ server is the firstserver in a domain that requests a ″vouch for″ token from the MAS. The ″vouchfor″ server provides ″vouch for″ information for the user within the domain.Subsequent requests for ″vouch for″ services in a given remote domain can bemade locally by this server, rather than accessing the out-of-domain MAS. In thehome domain, the e-community cookie identifies the MAS as the ″vouch for″server.

(1) FIRST e-Community Local (Domain A) Access: WebSEAL 1

1. User requests a resource protected by WebSEAL 1 (within the same domain asMAS). The browser contains no e-community cookie for this domain. WebSEAL1 has no cached credentials for the user.

2. WebSEAL 1 configuration has e-community authentication enabled andspecifies the location of the MAS. WebSEAL 1 redirects the browser to a special″vouch for″ URL on the MAS.

3. The MAS receives the ″vouch for″ request and, failing to find credentials forthat user, prompts the user to login.

4. After successful login, the MAS builds a credential for the user, stores it in thecache, and redirects the browser back to the originally requested URL onWebSEAL 1 with an encrypted ″vouch for″ token. In addition, a domainA-specific e-community cookie is placed on the browser to identify the ″vouchfor″ server for this domain (in this case, the MAS).If the login attempt is unsuccessful, the MAS returns a ″vouch for″ token thatindicates a failure status. This token is constructed to be indistinguishable froma success status ″vouch for″ token. The requesting server reacts to a failurestatus token as if the user had failed local authentication.

5. WebSEAL 1 decrypts the token and builds its own credential for the user.

Note: Identity mapping should not be required within the same domain. Ifidentity mapping is required, WebSEAL 1 must use the Cross-domainMapping Framework (CDMF).

6. The authorization service permits or denies the request.

(2) FIRST e-Community Remote (Domain B) Access: WebSEAL 3

1. User requests a resource protected by WebSEAL 3 (remote domain B). Thebrowser contains no e-community cookie for this domain. WebSEAL 3 has nocached credentials for the user.

2. WebSEAL 3 configuration has e-community authentication enabled andspecifies the location of the MAS. WebSEAL 3 redirects the browser to a special″vouch for″ URL on the MAS.

3. The MAS receives the ″vouch for″ request and, failing to find credentials forthat user, prompts the user to login.


4. After successful login, the MAS builds a credential for the user, stores it in thecache, and redirects the browser back to the originally requested URL onWebSEAL 3 with an encrypted ″vouch for″ token. In addition, a domainA-specific e-community cookie is placed on the browser to identify the ″vouchfor″ server for this domain (in this case, the MAS).If the login attempt is unsuccessful, the MAS returns a ″vouch for″ token thatindicates a failure status. This token is constructed to be indistinguishable froma success status ″vouch for″ token. If the user fails authentication at the MAS,then the user is prompted for a local authentication at WebSEAL 3. If the user’saccount exists on this server, authentication then succeeds.

5. WebSEAL 3 decrypts the token and builds its own credential for the user.6. WebSEAL 3 creates and sets a second e-community cookie (valid for domain B)

on the browser, identifying WebSEAL 3 as the ″vouch for″ server for domain B.7. The authorization service permits or denies the request.

(3) NEXT e-Community Local (Domain A) Access: WebSEAL 2

1. User requests a resource protected by WebSEAL 2 (within the same domain asMAS). The browser contains a domain A e-community cookie identifying theMAS as the ″vouch for″ server. WebSEAL 2 receives this cookie. WebSEAL 2has no cached credentials for the user.

2. WebSEAL 2 configuration has e-community authentication enabled andspecifies the location of the MAS. The presence of the domain A e-communitycookie overrides the WebSEAL 2 configuration for the MAS location. Thecookie provides WebSEAL 2 with the identity of the ″vouch for″ server. (Ifscenario 2 occurred first, there would also be a domain B cookie maintained onthe browser that would not be sent to a domain A server.)

3. WebSEAL 2 redirects the browser to a special ″vouch for″ URL on the domainA ″vouch for″ server identified in the cookie (in this case the MAS, becauseWebSEAL 2 is in domain A).

4. The MAS receives the ″vouch for″ request and finds credentials for that user inthe cache (this occurred in scenario 1 and 2).

5. The MAS redirects the browser back to the originally requested URL onWebSEAL 2 with an encrypted ″vouch for″ token.

6. WebSEAL 2 decrypts the token and builds its own credential for the user.7. The authorization service permits or denies the request.

(4) NEXT e-Community Remote (Domain B) Access: WebSEAL 4

1. User requests a resource protected by WebSEAL 4 (remote domain B). Ifscenario 2 occurred first, the browser contains a domain B e-community cookieidentifying WebSEAL 3 as the ″vouch for″ server. WebSEAL 4 has no cachedcredentials for the user.

2. WebSEAL 4 configuration has e-community authentication enabled andspecifies the location of the MAS. The presence of a domain B e-communitycookie overrides the WebSEAL 4 configuration for the MAS location. Thecookie provides WebSEAL 4 with the identity of the ″vouch for″ server. (Ifscenario 1 occurred first, there would only be a domain A cookie maintained onthe browser that would not be sent to a domain B server. The configured MASlocation would be used instead. WebSEAL 4 would then become the ″vouchfor″ server for domain B.)

3. If scenario 2 occurred first, WebSEAL 4 redirects the browser to a special″vouch for″ URL on the domain B ″vouch for″ server identified in the domain Bcookie (in this case WebSEAL 3).


4. WebSEAL 3 receives the ″vouch for″ request and finds credentials for that userin the cache (this occurred in scenario 2).

5. WebSEAL 3 redirects the browser back to the originally requested URL onWebSEAL 4 with an encrypted ″vouch for″ token.

6. WebSEAL 4 decrypts the token and builds its own credential for the user.7. The authorization service permits or denies the request.

(5) ANOTHER e-Community Local (Domain A) Access: WebSEAL 2

1. User connects to WebSEAL 2 (domain A) with a request. If scenario 3 occurred,WebSEAL 2 has cached credentials for the user.

2. The authorization service permits or denies the request.

Logout from the e-Community

v If the user logs out by closing the browser, all SSL sessions and all e-communitycookies are cleared.

v If the user logs out via the /pkmslogout page, the SSL session and e-communitycookie for that domain are cleared.

Understanding the e-community cookiev The e-community cookie is a domain-specific cookie set by one WebSEAL server,

stored in the memory of the user’s browser, and transmitted to other WebSEALservers (in the same domain) in subsequent requests.

v The domain-specific cookie contains the name of the ″vouch for″ server, thee-community identity, a location (URL) of the ″vouch for″ server andfunctionality, and a lifetime value. The cookie contains no user or securityinformation.

v The e-community cookie allows servers in participating domains to request″vouch for″ information locally. The e-community cookie for the domain wherethe MAS resides plays a less significant role.

v The cookie has a lifetime (timeout) value that is set in the webseald.confconfiguration file. This lifetime value specifies how long a remote server is ableto provide ″vouch for″ information for the user. When the cookie lifetime hasexpired, the user must be redirected to the MAS for authentication.

v The cookie is cleared from memory when the browser is closed. If the user logsout of a specific domain, the e-community cookie is overwritten as empty. Thisaction effectively removes it from the browser.

Understanding the ″vouch for″ request and replyThe e-community ″vouch for″ operation requires dedicated functionality accessedthrough two specially constructed URLs: the ″vouch for″ request and the ″vouchfor″ reply.

The ″vouch for″ RequestThe ″vouch for″ request is triggered when a user requests a resource from a targetserver (configured for e-community) that contains no credential information forthat user. The server sends a redirect to the ″vouch for″ server (either the MAS or adelegated ″vouch for″ server identified in an e-community cookie).

The ″vouch for″ request contains the following information:https://<vouch-for-server>/pkmsvouchfor?<ecommunity-name>&<target-URL>


The receiving server checks the ecommunity-name to validate the e-communityidentity. The receiving server uses the target-URL in the ″vouch for″ reply toredirect the browser back to the originally requested page.

The pkmsvouchfor ″vouch for″ URL is configurable.

For example:https://mas.dA.com/pkmsvouchfor?companyABC&https://ws5.dB.com/index.html

The ″vouch for″ ReplyThe ″vouch for″ reply is the response from the ″vouch for″ server to the targetserver. The ″vouch for″ server is either the MAS or a delegated ″vouch for″ serverin a domain remote from the MAS domain.

The ″vouch for″ reply contains the following information:https://<target-URL>?PD-VFHOST=<vouch-for-server>&PD-VF=<encrypted-token>

The PD-VFHOST label identifies the server that performed the ″vouch for″operation. The receiving (target) server uses this information to select the correctkey required to decrypt the ″vouch for″ token. The PD-VF label identifies theencrypted token in the ″vouch for″ reply URL.

For example:https://w5.dB.com/index.html?PD-VFHOST=mas.dA.com&PD-VF=3qhe9fjkp...ge56wgb

Understanding the “vouch for” tokenIn order to achieve cross-domain single sign-on, some user identity informationmust be transmitted between servers. This sensitive information is handled using aredirect that includes the identity information encrypted as part of the URL. Thisencrypted data is called a ″vouch for″ token.v The token contains the ″vouch for″ success or failure status, the user’s identity

(if successful), the fully qualified name of the server that created the token, thee-community identity, and a creation time value.

v The holder of a valid ″vouch for″ token can use this token to establish a session(and set of credentials) with a server without explicitly authenticating to thatserver.

v The token is encrypted using a shared triple-DES secret key so that itsauthenticity can be verified.

v Encrypted token information is not stored on the browser.v The token is passed only once. The receiving server uses this information to

build user credentials in its own cache. The server uses these credentials forfuture requests by that user during the same session.

v The token has a lifetime (timeout) value that is set in the webseald.confconfiguration file. This value can be very short (seconds) to reduce the risk of are-play attack.

Configuring e-community single sign-on

E-community configuration summaryAn e-community is configured under the following conditions and guidelines:v The ″vouch for″ server (the MAS or a delegated ″vouch for″ server) always has

the token create responsibility


v The receiving server (where the requested resource is located) always has thetoken consume responsibility

v A delegated ″vouch for″ server (for all domains remote from the MAS domain)must have both token create and token consume capabilities

The following configuration steps are explained in detail in the remaining sectionsof this e-community chapter division:

Configuring default token create functionality on the ″vouch for″server1. Enable e-community authentication to process single sign-on requests by

communication type (e-community-sso-auth).2. Specify the unifying name of the e-community for all participating servers

(e-community-name).3. Configure the built-in single sign-on authentication mechanism (library) for

token create (sso-create).4. Create the key file used to encode and decode the ″vouch for″ token. Copy the

key file to all appropriate participating servers ([e-community-domain-keys]stanza).

5. Configure the token label parameter used in the ″vouch for″ reply(vf-argument).

6. Specify if this server is the MAS or not the MAS (is-master-authn-server).7. Specify the ″vouch for″ URL used in the ″vouch for″ request (vf-url).8. Configure token and ec-cookie lifetime values (vf-token-lifetime and

ec-cookie-lifetime).

Configuring default token consume functionality on the receivingserver1. Enable e-community authentication to process single sign-on requests by

communication type (e-community-sso-auth).2. Specify the unifying name of the e-community for all participating servers

(e-community-name).3. Configure the built-in single sign-on authentication mechanism (library) for

token consume (sso-consume).4. Assign the appropriate key file ([e-community-domain-keys] stanza).5. Configure the token label parameter used in the ″vouch for″ reply

(vf-argument).6. Specify that this server is not the MAS (is-master-authn-server).7. Specify the ″vouch for″ URL used in the ″vouch for″ request (vf-url).8. Configure token and ec-cookie lifetime values (vf-token-lifetime and

ec-cookie-lifetime).

Enabling and disabling e-community authenticationThe e-community-sso-auth parameter, located in the [e-community-sso] stanza ofthe webseald.conf configuration file, enables and disables the e-communityauthentication method, and processes single sign-on requests by communicationtype.v To enable the e-community authentication method, enter ″http″, ″https″, or

″both″.The values ″http″, ″https″, and ″both″ specify the type of communication usedby e-community participants.


v To disable the e-community authentication method, enter ″none″.The value ″none″ disables e-community for that server. The default setting is″none″.

For example:[e-community-sso]e-community-sso-auth = https

Specifying an e-community nameThe e-community-name parameter identifies the unifying name of thee-community for all participating servers in all participating domains. For example:[e-community-sso]e-community-name = companyABC

The e-community-name value must be the same for all WebSEAL servers in alldomains that are participating in the e-community.

Configuring the single sign-on authentication mechanismThe default e-community configuration requires that you enable the sso-create andsso-consume single sign-on authentication mechanisms. The sso-create mechanismis required by the initial WebSEAL server for creating the ″vouch for″ token andbuilding the redirected request. The sso-consume mechanism is required by thereceiving WebSEAL server to decode the ″vouch for″ token and build the usercredentials from the identity information contained in the token. For the defaulte-community configuration, each parameter specifies a built-in ″vouch for″ tokenlibrary file. One library contains the code for the token create functionality and theother library contains the code for the token consume functionality.v On UNIX, the library files are called libssocreate. {so | a | sl} and

libssoconsume. {so | a | sl}.v On Windows, the library files are DLL files called ssocreate.dll and

ssoconsume.dll.


Single Sign-on Token Library


sso-create libssocreate.so libssocreate.a ssocreate.dll libssocreate.sl

sso-consume libssoconsume.so libssoconsume.a ssoconsume.dll libssoconsume.sl

You can configure the e-community authentication mechanism by specifying thesso-create and sso-consume parameters with the full path name of the appropriateplatform-specific default library file in the [authentication-mechanism] stanza ofthe webseald.conf configuration file.

For example:

Solaris:[authentication-mechanisms]sso-create = /opt/pdweb/lib/libssocreate.sosso-consume = /opt/pdweb/lib/libssoconsume.so

Windows:[authentication-mechanisms]sso-create = C:\Program Files\Tivoli\PDWeb\bin\ssocreate.dllsso-consume = C:\Program Files\Tivoli\PDWeb\bin\ssoconsume.dll


Encrypting the ″vouch for″ tokenWebSEAL must encrypt the authentication data placed in the token using a keygenerated by the cdsso_key_gen utility. You must ″synchronize″ this key bysharing the key file with each WebSEAL server in each participating domain. Eachparticipating WebSEAL server in each domain needs to use the same key.

Note: The distribution of key files is not a part of the Tivoli Access Managere-community process. You must manually and securely copy keys to eachparticipating server.

The cdsso_key_gen utility requires that you specify the location (absolutepathname) of the key file when you run the utility. You must also use a full pathname to run this utility:



The location of the key files used to secure tokens sent between serversparticipating in the e-community is specified in the [e-community-domain-keys]stanza.[e-community-domain-keys]<domain-name> = <full-keyfile-pathname><domain-name> = <full-keyfile-pathname>

E-community Domain KeysThe location of the key files required for encrypting and decrypting the tokensexchanged among the servers participating in the e-community is specified in the[e-community-domain-keys] stanza. You must specify fully qualified domainnames for the servers and absolute path names for the key file locations.

The following example provides the MAS (domain A) with key files forcommunicating with two remote domains(dB and dC) and a key forcommunicating with other servers in domain A:[e-community-domain-keys]dA.com = /abc/xyz/key.fileA-AdB.com =/abc/xyz/key.fileA-BdC.com =/abc/xyz/key.fileA-C

In this example, key.fileA-A identifies the key file used between all of the serversin domainA.

key.fileA-B identifies the key file used between domain A and domain B.

key.fileA-C identifies the key file used between domain A and domain C.

Each remote server needs to have a copy of the appropriate key file used by theMAS. To exchange tokens with the MAS (domain A), all servers in domain Brequire copies of key.fileA-B:[e-community-domain-keys]dA.com =/efg/hij/key.fileA-B

To exchange tokens with the MAS (domain A), all servers in domain C requirecopies of key.fileA-C:


[e-community-domain-keys]dA.com =/efg/hij/key.fileA-C

Any servers in domain A which use authentication services provided by the MASmust have a copy of key.fileA-A:[e-community-domain-keys]dA.com =/efg/hij/key.fileA-A

Configuring the ″vouch for″ token label nameThe authentication information used for a single sign-on transaction is placed inthe redirected request as an encrypted token query string argument to the request.This token string requires a name, or label, to identify it. The label name uniquelyidentifies the request to the receiving WebSEAL server as a single sign-on requestto be handled by the single sign-on token consume mechanism (library).

You must configure this token label on both WebSEAL servers participating in thesingle sign-on functionality. To configure the token label, use the vf-argumentparameter located in the [e-community-sso] stanza of the webseald.confconfiguration file. For example (default):[e-community-sso]vf-argument = PD-VF

See “e-community single sign-on” on page 284.

Specifying the master authentication server (MAS)You must specify which server machine in the e-community is to function as themaster authentication server (MAS). You must also specify if a server machine isnot the MAS.

is-master-authn-server

Use the is-master-authn-server parameter to specify whether a server is the MASor not. Values include ″yes″ or ″no″.

For example:[e-community-sso]is-master-authn-server = yes

Multiple WebSEALs can be configured to act as master authentication servers andthen placed behind a load balancer. In this scenario, the load balancer is″recognized″ as the MAS by all other WebSEAL servers in the e-community.

If the server you are configuring is not the MAS, use the master-authn-server tospecify to this server the location of the MAS.

master-authn-server

If the is-master-authn-server parameter is set to ″no″, this parameter must beuncommented and specified. The parameter identifies the fully qualified domainname of the MAS.

For example:[e-community-sso]master-authn-server = mas.dA.com


Additionally, you can specify the HTTP and HTTPS listening ports used by theMAS if these port values are other than the default (port 80 for HTTP and port4443 for HTTPS).

master-http-port

If e-community-sso-auth enables HTTP e-community authentication and themaster authentication server listens for HTTP requests on a port other than thestandard HTTP port (port 80), the master-http-port parameter identifies thenon-standard port. This parameter is ignored if this server is the masterauthentication server. By default, this parameter is disabled.[e-community-sso]master-http-port = <port-number>

master-https-port

If e-community-sso-auth enables HTTPS e-community authentication and themaster authentication server listens for HTTPS requests on a port other than thestandard HTTPS port (port 443), the master-http-port parameter identifies thenon-standard port. This parameter is ignored if this server is the masterauthentication server. By default, this parameter is disabled.[e-community-sso]master-https-port = <port-number>

Specifying the ″vouch for″ URLvf-url

The vf-url parameter specifies the ″vouch for″ URL. The value must begin with aforward-slash (/). The default value is /pkmsvouchfor.

For example:[e-community-sso]vf-url = /pkmsvouchfor

You can also express an extended URL:vf-url = /login_mechanism/login

The extended URL is used when the client is communicating with a MAS that isnot a WebSEAL server. This use of vf-url enables the client to specify access to aMAS with specialized authenication library, such as a customized tokenconsumption library.

Configure token and ec-cookie lifetime valuesvf-token-lifetime

The vf-token-lifetime parameter sets the lifetime timeout value (in seconds) of the″vouch for″ token. This value is checked against the creation time stamped on thecookie. The default value is 180 seconds. You must take into account clock skewamong participating servers.

For example:[e-community-sso]vf-token-lifetime = 180


You must take into account any clock skew among the participating domains.Clock skew means that the system times differ on the relevant servers in eachdomain. When this difference approaches the value of vf-token-lifetime, theeffective lifetime of the token is greatly reduced. When this difference exceeds thevalue of vf-htoken-lifetime, tokens from one domain cannot be valid for theother domain. Administrators should adjust vf-token-lifetime accordingly.However, when clock skew requires that vf-token-lifetime be set to a large value,the risk of replay attacks increases. In this case, administrators should considersynchronizing the system time on the relevant servers in each domain.

See “e-community single sign-on” on page 284.

ec-cookie-lifetime

The ec-cookie-lifetime parameter specifies the maximum lifetime (in minutes) ofthe e-community domain cookie. The default value is 300 minutes.

For example:[e-community-sso]ec-cookie-lifetime = 300

Enabling compatibility with previous releasesIn this release of Tivoli Access Manager, the level of security has been increased forthe encryption of the ″vouch for″ token. The new encryption algorithm is notbackward compatible. If you are integrating e-community with servers usingprevious versions of Tivoli Access Manager, you must enable thepre-410-compatible-tokens parameter in the [server] stanza of the webseald.confconfiguration file. For example:pre-410-compatible-tokens = yes



Chapter 7. WebSEAL junctions

A WebSEAL junction is an HTTP or HTTPS connection between a front-endWebSEAL server and a back-end Web application server. Junctions logicallycombine the Web space of the back-end server with the Web space of theWebSEAL server, resulting in a unified view of the entire Web object space. Ajunction allows WebSEAL to provide protective services on behalf of the back-endserver. WebSEAL performs authentication and authorization checks on all requestsfor resources before passing those requests across a junction to the back-end server.Junctions also allow a variety of single sign-on solutions between a client and thejunctioned back-end application.

You can create WebSEAL junctions with the pdadmin command-line utility or withthe Web Portal Manager. This chapter discusses the details of the many options forconfiguring WebSEAL junctions.

Topic Index:v “WebSEAL junctions overview” on page 169v “Using pdadmin to create junctions” on page 171v “Configuring a basic WebSEAL junction” on page 172v “Mutually authenticated SSL junctions” on page 174v “Creating TCP and SSL proxy junctions” on page 177v “WebSEAL-to-WebSEAL junctions over SSL” on page 178v “Modifying URLs to back-end resources” on page 178v “Additional junction options” on page 186v “Technical notes for using WebSEAL junctions” on page 195v “Using query_contents with third-party servers” on page 196

WebSEAL junctions overviewYou can create the following WebSEAL junction types:v WebSEAL to back-end server over TCP connectionv WebSEAL to back-end server over SSL connectionv WebSEAL to back-end server over TCP connection via HTTP proxy serverv WebSEAL to back-end server over SSL connection via HTTPS proxy serverv WebSEAL to WebSEAL over SSL connection

You must address the following two concerns when creating any junction:1. Decide where to junction (mount) the Web application server(s) in the

WebSEAL object space.2. Choose the type of junction.

Junction database location and formatWebSEAL junction information is now stored in XML-formatted database files. Thelocation of the junction database directory is defined in the [junction] stanza of thewebseald.conf configuration file. The directory is relative to the WebSEAL serverroot (server-root parameter in the [server] stanza):


[junction]junction-db = jct

v Each junction is defined in a separate file with a .xml extension.v Use pdadmin utility to create and manage junctions and options.v The XML format allows you to manually create, edit, duplicate, and backup

junction files.

Applying coarse-grained access control: summary1. Use the pdadmin utility or the Web Portal Manager to create a junction

between WebSEAL and the back-end server.2. Place an appropriate ACL policy on the junction point to provide

coarse-grained control to the back-end server.

Applying fine-grained access control: summary1. Use the pdadmin utility or the Web Portal Manager to create a junction

between WebSEAL and the back-end server.WebSEAL cannot automatically ″see″ and understand a third-party file system.You must inform WebSEAL of the third-party object space using a specialapplication, called query_contents, that inventories the third-party Web spaceand reports the structure and contents to WebSEAL.

2. Copy the query_contents program to the third-party server.3. Apply ACL policy to appropriate objects in the unified object space.

Guidelines for creating WebSEAL junctionsThe following guidelines summarize the ″rules″ for junctions:v You can add a junction anywhere in the primary WebSEAL object spacev You can junction multiple replica back-end servers at the same mount point

Multiple replica back-end servers mounted to the same junction point must be ofthe same type—TCP or SSL

v ACL policies are inherited across junctions to third-party serversv The junction point name should be unique and not match any directory in the

Web space of the local WebSEAL server. For example, if WebSEAL has resourcesof the form /path/..., do not create a junction point with the name /path.

v The junction point should not match any directory in the Web space of theback-end server if HTML pages from that server contain programs (such asJavascript or applets) with server-relative URLs to that directory. For example, ifpages from the back-end server contain programs with a URL of form/path/..., do not create a junction point of name /path.

v Do not create multiple WebSEAL junctions that point to the same back-endapplication server/port. This type of configuration can cause unpredictablecontrol of access to resources and therefore is not a recommended or supportedTivoli Access Manager configuration strategy.Each WebSEAL junction can be secured by a unique set of access controls(ACLs). However, the ACL policy of each newly created junction overlays thepolicies of previously created junctions attached to the same back-endserver/port. Subsequent junctions secured with more permissive ACLs cancompromise previous junctions secured with less permissive ACLs. WebSEALand the Tivoli Access Manager authorization model cannot guarantee secureaccess control with this type of junction implementation.

v WebSEAL supports HTTP 1.1 across junctions.


Additional references for WebSEAL junctionsSee “Understanding WebSEAL junctions” on page 12 for a conceptual overview ofWebSEAL junctions.

See Appendix B, “WebSEAL junction reference”, on page 329 for completeinformation on junction command options.

Using pdadmin to create junctionsBefore using pdadmin, you must login to a secure domain as the sec_masteradministration user.

For example:

UNIX:# pdadminpdadmin> loginEnter User ID: sec_masterEnter Password:pdadmin>

Windows:MSDOS> pdadminpdadmin> loginEnter User ID: sec_masterEnter Password:pdadmin>

To create WebSEAL junctions, you use the pdadmin server task create command:pdadmin> server task <server-identification> create <options>

The server-identification component of this command is a combination of the TivoliAccess Manager server used by this command and the Tivoli Access Managerserver host name.<Access-Manager-server>-<host-name>

Syntax for a single WebSEAL server:

For Tivoli Access Manager WebSEAL, the Access-Manager-server is webseald andthe host-name is the name of the WebSEAL server machine:pdadmin> server task webseald-<host-name> create <options>

The initial WebSEAL server installed on a machine is always named after themachine name. For example, if the machine name is cruz, the server identificationfor a single WebSEAL installation is:webseald-cruz

Syntax for multiple WebSEAL instances:

If you install multiple WebSEAL server instances on the same machine, theAccess-Manager-server is the configured name of the WebSEAL server instance,followed by webseald, followed by the host name:<instance-name>-webseald-<host-name>

For example, if the configured names for two additional WebSEAL instances arewebseal2 and webseal3, the server identifications appear as:

Chapter 7. WebSEAL junctions 171

webseal2-webseald-cruzwebseal3-webseald-cruz

Use the server list command to verify server identification:pdadmin> server listwebseald-cruzwebseal2-webseald-cruzwebseal3-webseald-cruz

Configuring a basic WebSEAL junctionWebSEAL supports both standard TCP (HTTP) and secure SSL (HTTPS) junctionsbetween WebSEAL and back-end Web application servers.

The junction between WebSEAL and the back-end server is independent of thetype of connection (and its level of security) between the client and the WebSEALserver.

The mandatory command options required to create a basic WebSEAL junctionusing pdadmin include:v Host name of the back-end application server ( –h option)v Junction type: tcp, ssl, tcpproxy, sslproxy, local ( –t option)v Junction point (mount point)pdadmin> server task webseald-<instance-name> create -t <type> -h \<host-name> <jct-point>

For example:pdadmin> server task webseald-cruz create -t tcp -h doc.tivoli.com /pubs

Note: A ″best practises″ recommendation is to always use the fully qualifieddomain name of the back-end server when specifying the argument to the–h option.

Creating TCP type junctionsA WebSEAL junction over a TCP connection provides the basic properties of ajunction but does not provide secure communication across the junction.

To create a secure TCP junction and add an initial server, use the create commandwith the –t tcp option:pdadmin> server task webseald-<instance-name> create -t tcp -h <host-name> \[-p <port>] <jct-point>

JunctionWebSEAL

Client

Secure Domain

WebApplication

Server

HTTP

/

/mnt

TCP

Figure 22. Non-secure TCP (HTTP) junction


The default port value for a TCP junction (if not specified) is 80.

Creating SSL type junctionsSSL junctions function exactly like TCP junctions, with the added value that allcommunication between WebSEAL and the back-end server is encrypted.

SSL junctions allow secure end-to-end browser-to-application transactions. You canuse SSL to secure communications from the client to WebSEAL and from WebSEALto the back-end server. The back-end server must be HTTPS-enabled when you usean SSL junction.

To create a secure SSL junction and add an initial server, use the create commandwith the –t ssl option:pdadmin> server task webseald-<instance-name> create -t ssl -h <host-name> \[-p <port>] <jct-point>

The default port value for an SSL junction (if not specified) is 443.

Verifying the back-end server certificateWhen a client makes a request for a resource on the back-end server, WebSEAL, inits role as a security server, performs the request on behalf of the client. The SSLprotocol specifies that when a request is made to the back-end server, that servermust provide proof of its identity using a server-side certificate.

When WebSEAL receives this certificate from the back-end server, it must verify itsauthenticity by matching the certificate against a list of root CA certificates storedin its certificate database.

Tivoli Access Manager uses the IBM Global Security Kit (GSKit) implementation ofSSL. You must use the GSKit iKeyman utility to add the root certificate of the CAwho signed the back-end server certificate to the WebSEAL certificate keyfile(pdsvr.kdb).

Examples of SSL junctionsJunction host sales.tivoli.com at junction point /sales over SSL:pdadmin> server task webseald-<instance-name> create -t ssl -h \sales.tivoli.com /sales

Note: In the above example, the –t ssl option dictates a default port of 443.

Junction host travel_svr on port 4443 at junction point /travel over SSL:

JunctionWebSEAL

Client

Secure Domain

WebApplication

Server

HTTPS

/

/mntSSLTCP

Figure 23. Secure SSL (HTTPS) junction


pdadmin> server task webseald-<instance-name> create -t ssl -p 4443 \-h travel_svr /travel

Adding back-end servers to a junctionTo increase high availability of the resources protected by Tivoli Access Manager,you can junction multiple replica back-end servers to the same junction point.v Multiple back-end servers junctioned to the same point must have identical

WebSEAL versions and identical Web document spaces.v Multiple back-end servers junctioned to the same point must use the same

connection type (TCP or SSL).v WebSEAL uses a least busy algorithm to determine which back-end server

replica has the fewest number of request connections and forwards any newrequest to that server.

Create the initial junction. For example:pdadmin> server task webseald-cruz create -t tcp -h server1 /sales

Add an additional back-end server replica. For example:pdadmin> server task webseald-cruz add -h server2 /sales

Mutually authenticated SSL junctionsWebSEAL supports mutual authentication between a WebSEAL server and aback-end server over an SSL junction (–t ssl or –t sslproxy). The following outlinesummarizes the supported functionality for mutual authentication over SSL(command options are listed where appropriate):1. WebSEAL authenticates the back-end server (normal SSL process)

v WebSEAL validates the server certificate from the back-end server. See“WebSEAL validates back-end server certificate” on page 175.

v WebSEAL verifies the Distinguished Name (DN) contained in the certificate(–D) (optional, but highly recommended) See “Distinguished name (DN)matching” on page 175.

2. Back-end server authenticates WebSEAL (two methods)v Back-end server validates client certificate from WebSEAL (–K). See

“WebSEAL authenticates with client certificate” on page 175.v Back-end server validates WebSEAL identity information in Basic

Authentication (BA) header (–B, –U, –W) See “WebSEAL authenticates withBA header” on page 176.

The command options that control mutual authentication over SSL provide thefollowing features:v You can specify client certificate or BA authentication method.v You can apply authentication methods on a per-junction basis.

Special considerations for combining the –b options (for handling BA information)with mutual authentication over SSL are described in “Handling client identityinformation across junctions” on page 176.


WebSEAL validates back-end server certificateWebSEAL verifies a back-end server certificate according to the standard SSLprotocol. The back-end server sends its server certificate to WebSEAL. WebSEALvalidates the server certificate against a pre-defined list of root CertificateAuthority (CA) certificates.

The Certificate Authority (CA) certificates that form the trust chain for theapplication server certificate (from the signing CA up to and including the rootcertificate) must be included in the key database in use by WebSEAL.

You use the iKeyman utility to create and manage the database of root CAcertificates.

Distinguished name (DN) matchingYou can enhance server-side certificate verification through Distinguished Name(DN) matching. To enable server DN matching, you must specify the back-endserver DN when you create the SSL junction to that server. Although DN matchingis an optional configuration, it is highly recommended that you implement thisfeature with mutual authentication over SSL junctions.

During server-side certificate verification, the DN contained in the certificate iscompared with the DN defined by the junction. The connection to the back-endserver fails if the two DNs do not match.

To enable the server DN matching, specify the back-end server DN when youcreate the SSL junction using the –D ″<DN>″ option. To preserve any blank spacesin the string, surround the DN string with double quotation marks. For example:-D "/C=US/O=Tivoli/OU=SecureWay/CN=Access Manager"

The –D option is appropriate only when used with the –K or –B option.

WebSEAL authenticates with client certificateUse the –K option to enable WebSEAL to authenticate to the junctioned back-endserver using its client certificate.-K "<key-label>"

The conditions for this scenario include:v The back-end server is set up to require verification of WebSEAL’s identity with

a client certificate.v Using the iKeyman utility to create, label, and store a special key that is used

solely as WebSEAL’s client certificate when authenticating to a junctionedback-end server.

v It is also highly recommended that you configure the junction for DN matching(–D).

The –K option uses an argument that specifies the key-label of the requiredcertificate as stored in the GSKit key database. Use the iKeyman utility to add newcertificates to the key database.

You must surround the key-label argument with quotation marks. For example:-K "cert1_Tiv"


If the key resides on cryptographic hardware, you must specify the WebSEALtoken device with the key label.-K "<token-name>:<key-label>"

For example:-K "websealtoken:junctionkey"

See “Configuring cryptographic hardware for encryption and key storage” on page88.

See “Configuring key database parameters” on page 39.

WebSEAL authenticates with BA headerUse the –B –U ″<username>″ –W ″<password>″ option to enable WebSEALauthentication via Basic Authentication.-B -U "<username>" -W "<password>"

The conditions for this scenario include:v The back-end server is set up to require verification of WebSEAL’s identity with

a BA header.v Do not configure the junction with any –b option. (Internally, however, the –B

option uses –b filter.)v WebSEAL is configured to pass its identity information in a BA header to

authenticate to the back-end server.v It is highly recommended that you also configure the junction for DN matching

(–D).

You must surround the user name and password arguments with double quotationmarks. For example:-U "WS1" -W "abCde"

Handling client identity information across junctionsA junction can be set up to specify client identity information in BA headers. The–b option allows four possible arguments: filter, supply, ignore, gso. You can finddetailed information about these arguments in “Configuring BA headers for singlesign-on solutions” on page 201.

The –b option has an impact on the junction settings for mutual authentication andyou must consider the correct combination of options.

Using –b supplyv WebSEAL authentication via BA header is not allowed with this option. This

option uses the BA header for the original client user name and a ″dummy″password.

v WebSEAL authentication via client certificate is allowed with this option.

Using –b ignorev WebSEAL authentication via BA header is not allowed with this option. This

option uses the BA header for the original client user name and password.v WebSEAL authentication via client certificate is allowed with this option.


Using –b gsov WebSEAL authentication via BA header is not allowed with this option. This

option uses the BA header for user name and password information supplied bythe GSO server.

v WebSEAL authentication via client certificate is allowed with this option.

Using –b filterv Internally, the –b filter option is used when WebSEAL authentication is set to

use BA header information.The WebSEAL BA header is used for all subsequent HTTP transactions. To theback-end server, WebSEAL appears logged on at all times.

v WebSEAL authentication via client certificate is allowed with this option.v If the back-end server requires actual client identity (from the browser), the CGI

variables HTTP_IV_USER, HTTP_IV_GROUP, and HTTP_IV_CREDS can beused. For scripts and servlets, use the corresponding Tivoli AccessManager-specific HTTP headers: iv-user, iv-groups, iv-creds.

Creating TCP and SSL proxy junctionsYou can create WebSEAL junctions that allow communication to traverse networktopologies that use HTTP or HTTPS proxy servers. You can configure the junctionto handle requests as standard TCP communication or protected SSLcommunication.

The create command requires one of the following arguments to the type option toestablish either a TCP-based or SSL-based junction through a proxy server:v –t tcpproxy

v –t sslproxy

Both create and add commands require the following options and arguments toidentify the proxy server and the target Web server:

–H <host-name> The DNS host name or IP address of the proxy server.

–P <port> The TCP port of the proxy server.

–h <host-name> The DNS host name or IP address of the target Web server.

–p <port> The TCP port of target Web server. Default is 80 for TCPjunctions; 443 for SSL junctions.

Example TCP proxy junction (entered as one line):pdadmin> server task webseald-<instance-name> create -t tcpproxy \-H clipper -P 8081 -h www.ibm.com -p 80 /ibm

Example SSL proxy junction (entered as one line):pdadmin> server task webseald-<instance-name> create -t sslproxy \-H clipper -P 8081 -h www.ibm.com -p 443 /ibm


WebSEAL-to-WebSEAL junctions over SSLTivoli Access Manager supports SSL junctions between a front-end WebSEALserver and a back-end WebSEAL server. Use the –C option with the createcommand to junction the two WebSEAL servers over SSL and provide mutualauthentication.

Example:pdadmin> server task webseald-<instance-name> create -t ssl -C -h serverA /jctA

Mutual authentication occurs in the following two stages:v The SSL protocol allows the back-end WebSEAL server to authenticate to the

front-end WebSEAL server through its server certificate.v The –C option enables the front-end WebSEAL server to pass its identity

information to the back-end WebSEAL server in a Basic Authentication (BA)header.

Additionally, the –C option enables the functionality of the –c option that allowsyou to place Tivoli Access Manager-specific client identity and group membershipinformation into the HTTP header of the request destined for the back-endWebSEAL server. The header parameters include iv-user, iv-groups, and iv-creds.See “Supplying client identity in HTTP headers (–c)” on page 187.

The following conditions apply to WebSEAL-to-WebSEAL junctions:v The junction is appropriate only with the –t ssl or –t sslproxy junction type.v Both WebSEAL servers must share a common LDAP registry. This allows the

back-end WebSEAL server to authenticate the front-end WebSEAL server identityinformation.

Modifying URLs to back-end resourcesPages returned to the client from back-end applications most often contain URLlinks to resources located on those application servers. It is important that theselinks are constructed to direct any requests back to the correct locations of theseresources.

For example (non-WebSEAL environment), the URL entered by a client for aresource on an application server might appear as follows:http://www.abc.com/file.html

Client WebSEALWeb

Server

www.ibm.com

Secure Domain

-H and -P

ProxyServer

Clipper Internet

-h and -pjunction at /ibm

Figure 24. Example proxy junction


WebSEAL, as a front-end reverse proxy, provides security services to back-endapplication servers via the WebSEAL junctioning feature. This feature results inresources being accessed via different URL expressions.

For example (WebSEAL environment), the URL entered by a client for the sameresource on a junctioned back-end application server must appear as follows:http://webseal.abc.com/jct/file.html

The junction feature of WebSEAL changes the server and path information thatmust be used to access resources on junctioned back-end systems. A link to aresource on a back-end junctioned server only succeeds if the URL contains theidentity of the junction.

To support the junction feature and maintain the integrity of URLs, WebSEALmust, where possible:1. Modify the URLs (links) found in responses sent to clients2. Modify requests for resources resulting from URLs (links) that WebSEAL could

not change

Note that WebSEAL’s rules and mechanisms for filtering and processing URLs donot apply to links that point to resources external to the Tivoli Access Managerjunctioned environment.

The following diagram summarizes the solutions available to WebSEAL formodifying URLs to junctioned back-end resources:

This section contains the following topics:v “Understanding path types used in URLs” on page 179v “Filtering URLs in responses” on page 180v “Processing URLs in requests” on page 183v “Handling cookies from servers across multiple -j junctions” on page 185

Understanding path types used in URLsAny HTML page is likely to contain URLs (links) to other resources on thatback-end server or elsewhere. URL expressions can appear in the followingformats:v relativev server-relativev absolute

Client WebSEALWeb

ApplicationServer

junction

Filtering responsesfrom back-end servers

Processing requestsfor back-end resources

1. junction cookies

2. junction mapping table(for server-relative URLs)

(for server-relative URLs)

1. standard filtering

2. script filtering

(for server-relative andabsolute URLs)

(for absolute URLs)

Figure 25. Summary: Modifying URLs to back-end resources


Links containing URLs expressed in relative format never require anymanipulation by WebSEAL. By default, the browser handles relative URLs in linksby prepending the correct scheme, server, and directory information (including thejunction) to the relative URL. The prepended information is derived from therequest URL for the page on which the link is located.

Example relative URL expressions:abc.html ../abc.html./abc.html sales/abc.html

However, difficulties arise with server-relative and absolute path formats. Links toback-end resources expressed in absolute or server-relative formats succeed only ifWebSEAL was able to modify the URL path expression and include junctioninformation.

Example server-relative URL expressions:/abc.html /accounts/abc.html

Example absolute URL expression:http://www.tivoli.com/abc.html

Note: All programmers of Web scripts are encouraged to use relative links (notabsolute or server-relative) for dynamically generated URLs.

Filtering URLs in responsesThis section describes how WebSEAL filters URLs in responses from junctionedback-end application servers.v “Standard URL filtering rules for WebSEAL” on page 180v “Modifying absolute URLs with script filtering” on page 181v “Filtering changes the Content-Length header” on page 182

Standard URL filtering rules for WebSEALWebSEAL uses a set of standard rules to filter URLs contained in pages that areresponses to client requests. To apply standard URL filtering, WebSEAL must beable to ″see″ the URLs on a page sent from the back-end server. WebSEAL cannotuse standard filtering rules for URLs embedded in scripts.

By default, WebSEAL filters only documents of MIME type ″text/html″ and″text/vnd.wap.wml″ that are received from junctioned servers. Additional MIMEtypes can be configured using the [filter-content-types] stanza of thewebseald.conf configuration file.

Relative URLs are always handled appropriately by the browser. By default, thebrowser handles relative URLs in links by prepending the correct scheme, server,and directory information (including the junction) to the relative URL. Theprepended information is derived from the request URL for the page on which thelink is located.

However, WebSEAL must add the junction name to the path of absolute andserver-relative URLs that refer to resources located on junctioned servers.v Server-relative URLs indicate a URL position in relation to the document root of

the junctioned server, for example:/dir/file.html


Server-relative URLs are modified by adding the junction point of the junctionedserver to the path name. For example:/jct/dir/file.html

v Absolute URLs indicate a URL position in relation to a host name or IP address(and, optionally, a network port). For example:http://<host-name>[:<port>]/file.html, orhttps://<host-name>[:<port>]/file.html

Absolute URLs are modified according to the following set of rules:– If the URL is HTTP and the host/port matches a TCP junctioned server, the

URL is modified to be server-relative to WebSEAL and reflect the junctionpoint. For example:http://<host-name>[:<port>]/file.html

becomes:/tcpjct/file.html

– If the URL is HTTPS and the host/port matches an SSL junctioned server, theURL is modified to be server-relative to WebSEAL and reflect the junctionpoint. For example:https://<host-name>[:<port>]/file.html

becomes:/ssljct/file.html

In addition:v Only URLs in content types defined in the [filter-content-types] stanza of the

webseald.conf configuration file are filtered.v META tags are always filtered for refresh requests, for example:

<META HTTP-EQUIV="Refresh" CONTENT="5;URL=http://server/url">

v If a BASE tag contains an HREF attribute, the tag is removed from the responseto the client.

Parameters for filtering URLs through junctioned servers are located in the[filter-url] stanza of the webseald.conf configuration file. The [filter-url] stanzacontains a list of HTML tags that the WebSEAL server filters or modifies to adjustabsolute URLs obtained through a junctioned server.

All commonly used HTML tags are configured by default. The administrator mayneed to add additional HTML tags that contain URLs.

Modifying absolute URLs with script filteringWebSEAL requires additional configuration to handle the processing of absoluteURLs embedded in scripts. Web scripting languages include Javascripts, VBscripts,ASP, JSP, ActiveX, and others. The webseald.conf configuration file contains aparameter that enables or disables filtering of embedded absolute URLs:[script-filtering]script-filter = no

Script-filtering is disabled by default. To enable script filtering, set:script-filter = yes

The script-filter mechanism expects absolute URLs with a standard scheme, server,resource format:


http://server/resource

The script-filter mechanism replaces the scheme and server portions of the linkwith the correct junction information (as a relative pathname):/junction-name/resource

This filtering solution parses a script embedded in HTML code and thereforerequires additional processing overhead that can negatively impact performance.Limit your use of the script-filter parameter only to junctions that require supportfor filtering of embedded absolute URLs.

The following diagram illustrates this absolute URL filtering solution:

You can optionally configure WebSEAL to rewrite the original absolute URL as anabsolute URL, instead of a relative URL (default). To enable this functionality, setthe rewrite-absolute-with-absolute parameter in the [script-filtering] stanza of thewebseald.conf configuration file to equal ″yes″:[script-filtering]rewrite-absolute-with-absolute = yes

With this functionality enabled, the example URL in the diagram above wouldappear as follows:http://<webseal-hostname>/jctA/abc.html

Filtering changes the Content-Length headerNormally, the Content-Length header in a response from a back-end serverindicates the size of the content being returned. When WebSEAL filters URLs andadds junction information to the path of URLs contained in the page, the actualsize of the page becomes larger than indicated in the Content-Header.

WebSEAL has no way of knowing what the new content length is until it actuallywrites the stream to the client. At this point, it is too late to insert a newContent-Length header. WebSEAL responds to this situation in the followingmanner:1. WebSEAL places the value of the original Content-Length header in a new

header called X-Old-Content-Length.Any applets or applications written to look for this header can have access tothe original (pre-filtered) Content-Length value.

2. WebSEAL logs the modified (post-filtered) Content-Length value in therequest.log file.

Client

WebSEAL Application Server(serves Javascript)

Script containingabsolute URL:

http://server/abc.html

Client receives:/jctA/abc.html

Request Request

Client makes requestusing link:

/jctA/abc.html

abc.htmlsuccessfully located

script-filtering=yesWebSEAL reformats link to:

/jctA/abc.html

1

2

3

/jctA

Figure 26. Filtering absolute URLs


3. The Content-Length header no longer appears.

Processing URLs in requestsA difficulty arises when URLs are dynamically generated by client-sideapplications (applets) or embedded in scripts in the HTML code. Web scriptinglanguages include Javascripts, VBscripts, ASP, JSP, ActiveX, and others. Theseapplets and scripts execute as soon as the page has arrived at the client browser.WebSEAL never has a chance to apply its standard filtering rules to thesedynamically generated URLs.

This section describes how WebSEAL processes client-side dynamically generatedserver-relative links found in requests for resources on junctioned back-endservers.v “Handling server-relative URLs with junction cookies (-j)” on page 183v “Handling server-relative URLs with junction mapping” on page 184

Note: There are no solutions available for handling absolute URLs generated onthe client-side.

Handling server-relative URLs with junction cookies (-j)Server-relative URLs generated on the client-side by applets and scripts initiallylack knowledge of the junction point. WebSEAL cannot filter the URL because it isgenerated on the client-side. During a client request for a resource using this URL,WebSEAL can attempt to reprocess the server-relative URL using junction cookies.

In the following scenario, a script located on the requested page dynamicallygenerates a server-relative URL expression upon arrival to the browser. If the clientrequests the resource specified by this link, WebSEAL receives a request for a localpage. After failing to find the page, it returns a ″Not Found″ error to the client.

The –j option provides a cookie-based solution for handling server-relative URLsthat are dynamically generated by a script that runs on the client machine.

General syntax:pdadmin> server task <server-name> create ... -j ...

For each requested page, a ″junction-identifier″ cookie is sent to the client. Thecookie contains the following header name and value:IV_JCT = </junction-name>

When the client makes a request from this page using a dynamically generatedserver-relative URL, WebSEAL (as before) receives a request for a local resource.When it fails to locate the resource, WebSEAL immediately retries the request usingthe junction information supplied by the cookie. With the correct junctioninformation in the URL expression, the resource is successfully located.

The following diagram illustrates this solution for filtering server-relative URLs


See also “Handling cookies from servers across multiple -j junctions” on page 185.

WebSEAL provides an alternative, non-cookie-based solution for handlingdynamically generated server-relative URLs. See “Handling server-relative URLswith junction mapping” on page 184.

Handling server-relative URLs with junction mappingServer-relative URLs generated on the client-side by applets and scripts initiallylack knowledge of the junction point. WebSEAL cannot filter the URL because it isgenerated on the client-side. During a client request for a resource using this URL,WebSEAL can attempt to reprocess the server-relative URL using junctionmapping.

Tivoli Access Manager provides an alternative to the cookie-based solution forfiltering dynamically generated server-relative URLs. You can create and activate ajunction mapping table that maps specific target resources to junction names.

WebSEAL checks the location information in the server-relative URL with the datacontained in the junction mapping table. If the path information in the URLmatches an entry in the table, WebSEAL directs the request to the junctionassociated with that location.

The table is an ASCII text file called jmt.conf. The location of this file is specifiedin the [junction] stanza of the webseald.conf configuration file:jmt-map = lib/jmt.conf

The format for data entry in the table consists of the junction name, a space, andthe resource location pattern. You can also use wildcard characters to express theresource location pattern.

In the following example of the junction mapping configuration file, two back-endservers are junctioned to WebSEAL at /jctA and /jctB:#jmt.conf#<junction-name> <resource-location-pattern>/jctA /documents/release-notes.html/jctA /travel/index.html/jctB /accounts/*/jctB /images/weather/*.jpg

Client

WebSEAL Application Server(serves Javascript)

Script containingserver-relative URL:

/abc.html

/jctA

with -j option

Script runs and generateslink: /abc.html

request request

Client makes requestusing link:/abc.html

abc.htmlsuccessfully locatedCookie sent

with request

WebSEAL retriesrequest as:

/jctA/abc.html

1

2

3

/jctA

WebSEAL sends cookieto identify junction

/jctA

Figure 27. Processing server-relative URLs


The original jmt.conf mapping table is an empty file. After you add data to thefile, you must use the jmt load command to “load” the data so that WebSEAL hasknowledge of the new information.pdadmin> server task <server-name> jmt loadJMT table successfully loaded.

The following conditions apply to the junction mapping table solution:v This solution does not require the –j option or junction cookiev The mapping table requires setup and activation by a security administratorv This solution does not handle links created with absolute URLsv Resource location pattern matching must be unique across the local Web space

and across junctioned Web application serversv If there is a duplicate pattern entry in the file, the mapping table does not load.

However, WebSEAL continues to run.v If there is an error loading the mapping table, the mapping table is not available.

However, WebSEAL continues to run.v If the mapping table is empty or there is an error in the table entries, the

mapping table does not load. However, WebSEAL continues to run.v Any errors that occur while loading the mapping table result in serviceability

entries in the WebSEAL server log file (webseald.log).

Handling cookies from servers across multiple -j junctions

Part 1: -j junctions modify Set-Cookie Path attributesIn addition to providing a junction identifier cookie to the browser, a junctionconfigured with the –j option also supports the handling of cookies sent withresponses from the back-end application.

Browser rule:

If a Set-Cookie header in a response from the server contains a Path attribute (suchas Path=/xyz), the browser returns the cookie only when a request URL (activatedfrom the returned page) begins with this path (such as /xyz/memo.html).

Problem:

When the junction environment contains mixed solutions for handling visible andembedded URLs in responses, the ability of the browser to return cookies iscompromised. For example, standard WebSEAL filtering of visible server-relativeURLs normally adds the junction name to the Path attribute of a server cookie (forexample, Path=/jct/xyz) in addition to modifying the URL itself. This matchbetween URL path name and the cookie Path attribute allows the browser to returnthe cookie when the link is activated by the user.

However, the –j junction-cookie-based solution adds the junction name to a URLonly after the link (URL) has been activated by the user. When the pre-modifiedlink is activated, the URL path name (/xyz/memo.html) does not match the Pathattribute (Path=/jct/xyz). The server cookie is not returned.

Solution:


The –j option converts the Path attribute for any server cookie (Set-Cookie) to ″/″(for example, Path=/). Because all server-relative path names begin with a ″/″, allserver cookies are returned regardless of the requirements of the original Pathattribute specifications.

Part 2: -j junctions modify Set-Cookie Name attributesThe –j option also supports cookies returned from servers across multiplejunctions.

Browser rule:

Browsers always replace any stored cookie with a newly arrived cookie containingthe same Name attribute (Set-Cookie), unless the Path or Domain attributes, orboth are unique.

Problem:

The previous section describes how the –j junction option modifies the Pathattribute of a Set-Cookie header to allow the browser to return cookies in anenvironment where WebSEAL is applying different filtering rules for visible andembedded URLs contained in the response page.

In a scenario where multiple back-end servers are connected to WebSEAL acrossdifferent junctions (such as in a WebSphere environment), it is possible for eachserver to send cookies (Set-Cookie) with the same Name attribute. If the junctionsuse the –j option, the Path attributes for each cookie become identical (Path=/).Because the same WebSEAL server is the point of contact for the browser, theDomain attribute likewise becomes identical. Although these identical cookiesarrive from unique back-end applications, the browser overwrites the identicallynamed cookies.

Solution:

The –j junction option provides an additional feature that uniquely renames anycookie returned with a response from a back-end application server. The Nameattribute of a Set-cookie header is prepended with a special string. The stringcontains the name of the specific junction responsible for delivering the response(with cookie).AMWEBJCT_<jct-name>_

For example, if a cookie with Name=JSESSIONID arrives across a junction named/jctA, the cookie Name attribute is changed to :Name=AMWEBJCT_jctA_JSESSIONID

Additional junction optionsYou can provide the following additional WebSEAL junction functionality withadditional options:v “Forcing a new junction (–f)” on page 187v “Supplying client identity in HTTP headers (–c)” on page 187v “Supplying client IP addresses in HTTP headers (–r)” on page 189v “Limiting the size of WebSEAL-generated HTTP headers” on page 189v “Passing session cookies to junctioned portal servers (–k)” on page 190v “Supporting case-insensitive URLs (–i)” on page 190


v “Stateful junction support (–s, –u)” on page 191v “Specifying back-end server UUIDs for stateful junctions (–u)” on page 191v “Junctioning to Windows file systems (–w)” on page 194

Forcing a new junction (–f)You must use the –f option when you want to force a new junction to overwrite anexisting junction.

The following example (server instance name = cruz) illustrates this procedure:1. Login to pdadmin:

# pdadminpdadmin> loginEnter User ID: sec_masterEnter Password:pdadmin>

2. Use the server task list command to display all current junction points:pdadmin> server task webseald-cruz list/

3. Use the server task show command to display details of the junction:pdadmin> server task webseald-cruz show /Junction point: /Type: LocalJunction hard limit: 0 - using global valueJunction soft limit: 0 - using global valueActive worker threads: 0Root Directory: /opt/pdweb/www/docs

4. Create a new local junction to replace the current junction point (the -f optionis required to force a new junction that overwrites an existing junction):pdadmin> server task webseald-cruz create -t local -f -d /tmp/docs /Created junction at /

5. List the new junction point:pdadmin> server task webseald-cruz list/

6. Display the details of this junction:pdadmin> server task webseald-cruz show /Junction point: /Type: LocalJunction hard limit: 0 - using global valueJunction soft limit: 0 - using global valueActive worker threads: 0Root Directory: /tmp/docs

Supplying client identity in HTTP headers (–c)The –c option allows you to insert Tivoli Access Manager-specific client identityand group membership information into the HTTP headers of requests destined forjunctioned third-party servers. The HTTP header information enables applicationson junctioned third-party servers to perform user-specific actions based on theclient’s Tivoli Access Manager identity.

HTTP header information must be transformed by the back-end server toenvironment variable format for use by a service on the back-end server. Headerinformation is transformed into a CGI environment variable format by replacing alldashes (-) with under bars (_) and prepending ″HTTP″ to the beginning of thestring. The value of the HTTP header becomes the value of the new environmentvariable.


PD-specificHTTP Header Fields

CGI EnvironmentVariable Equivalents Description

iv-user = HTTP_IV_USER = The short or long name of the client. Defaults to″Unauthenticated″ if client is unauthenticated(unknown).

iv-groups = HTTP_IV_GROUPS = A list of groups to which the client belongs. Consistsof comma separated quoted entries.

iv-creds = HTTP_IV_CREDS = Encoded opaque data structure representing anTivoli Access Manager credential. Suppliescredentials to remote servers so mid-tier applicationscan use the authorization API to call theauthorization service. Refer to the IBM Tivoli AccessManager Authorization C API Developer’s Reference.

The Tivoli Access Manager-specific HTTP header entries are available to CGIprograms as the environment variables HTTP_IV_USER, HTTP_IV_GROUPS andHTTP_IV_CREDS. For other application framework products, see the product’sdocumentation for instructions on extracting headers from HTTP requests.

–c syntaxThe –c option specifies what Tivoli Access Manager-specific HTTP header data issent to the back-end application server.-c <header-types>

The header-types arguments include: all, iv_user, iv_user_l, iv_groups, andiv_creds.

Argument Description

iv_user Provides the user name (short form) as the iv-user field in theHTTP header of the request.

iv_user_l Provides the full DN of the user (long form) as the iv-user field inthe HTTP header of the request.

iv_groups Provides the user’s list of groups as the iv-groups field in the HTTPheader of the request.

iv_creds Provides the user’s credential information as the iv-creds field inthe HTTP header of the request.

Note: Use either iv_user or iv_user_l, but not both.

The –c all option inserts all three types of identity information into the HTTPheader (the short name format (iv_user ) is used in this case).

Note: Separate multiple arguments with commas only. Do not enter any spaces.

Examples:-c all

-c iv_creds

-c iv_user,iv_groups

-c iv_user_l,iv_groups,iv_creds


Note: Refer also to the WebSEAL section of the IBM Tivoli Access ManagerPerformance Tuning Guide for a description of how to configure environmentvariables that cache –c junction information. It is possible to improveWebSEAL performance under –c junction conditions by applying thiscaching configuration.

Supplying client IP addresses in HTTP headers (–r)The –r option allows you to insert client IP address information into the HTTPheaders of requests destined for junctioned application servers. The HTTP headerinformation enables applications on junctioned third-party servers to performactions based on this IP address information.

HTTP header information must be transformed by the back-end server toenvironment variable format for use by a service on the back-end server. Headerinformation is transformed into a CGI environment variable format by replacing alldashes (-) with under bars (_) and prepending ″HTTP″ to the beginning of thestring. The value of the HTTP header becomes the value of the new environmentvariable.

Note: The value of the IP address does not always represent the address of theoriginating client machine. The IP address value could represent the addressof a proxy server or a network address translator (NAT).

PD-specificHTTP Header Field

CGI EnvironmentVariable Equivalent Description

iv-remote-address HTTP_IV_REMOTE_ADDRESS The IP address of the client. This value couldrepresent the IP address of a proxy server or anetwork address translator (NAT).

The –r option specifies that the IP address of the incoming request be sent to theback-end application server. The option is expressed without any arguments.

Limiting the size of WebSEAL-generated HTTP headersYou can limit the size of WebSEAL-generated HTTP headers that are inserted inrequests to junctioned back-end servers. The max-webseal-header-size parameterin the [junction] stanza of the webseald.conf configuration file specifies themaximum size, in bytes, of WebSEAL-generated HTTP headers. A value of ″0″disables this function:[junction]max-webseal-header-size = 0

This parameter can be useful if a back-end application server rejectsWebSEAL-generated HTTP headers because they are too large. For example, aniv-creds header for a user belonging to many groups could be too large.

When configured, this parameter causes WebSEAL-generated headers exceedingthe maximum value to split across multiple headers. The following example outputfrom a CGI application illustrates the effect of split headers:HTTP_IV_CREDS_1=Version=1, BAKs3DCCBnMMADCCBm0wggZpAgIDkDCCAYUwKzAHTTP_IV_CREDS_2=+0+8eAgI8iAICEdYCAgCkAgFUBAaSVNCJqncMOWNuPXNlY21==HTTP_IV_CREDS_SEGMENTS=2

If you enable this function, you must modify the back-end application to recognizesplit headers, instead of standard WebSEAL-specific HTTP headers.


Passing session cookies to junctioned portal servers (–k)A Web portal is a server that offers a broad array of personalized resources andservices. The –k option allows you to send the Tivoli Access Manager sessioncookie (originally established between the client and WebSEAL) to a back-endportal server. This option currently exists to directly support the integration ofWebSEAL with the Plumtree Corporate Portal solution.

When a client requests a personal resource list from the portal server, the portalserver builds this list by accessing resources located on other supportingapplication servers, also protected by WebSEAL. The session cookie allows theportal server to perform seamless single sign-on to these application servers, onbehalf of the client.

You include the –k option, without arguments, when you create the junctionbetween WebSEAL and the back-end portal server.

Conditions to consider for a portal server configuration:v For access via user name and password, Forms authentication is required. Do

not use Basic Authentication (BA).v The ssl-id-sessions parameter in the [session] stanza of the webseald.conf

configuration files must be set to ″no″. For HTTPS communication, this settingforces the use of a session cookie, instead of the SSL session ID, to maintainsession state.

v If the portal server is front-ended by a WebSEAL cluster, enable the failover typecookie. The failover cookie contains encrypted credential information that allowsauthentication to succeed with any replicated WebSEAL server that processes therequest.

Supporting case-insensitive URLs (–i)By default, Tivoli Access Manager treats URLs as case-sensitive when performingchecks on access controls. The –i option is used to specify that WebSEAL treatURLs as case-insensitive when performing authorization checks on a request to ajunctioned back-end server.

When you set this option on the junction, WebSEAL does not distinguish betweenuppercase and lowercase characters when parsing URLs. By default, Web serversare expected to be case-sensitive.

Although most HTTP servers support the HTTP specification that defines URLs ascase-sensitive, some HTTP servers treat URLs as case-insensitive.

For example, on case-insensitive servers, the following two URLS:http://server/sales/index.htm

http://server/SALES/index.HTM

are viewed as the same URL. This behavior requires an administrator to place thesame access controls (ACLs) on both URLs.

By junctioning a third-party server with the –i option, WebSEAL treats the URLsdirected to that server as case-insensitive.


Stateful junction support (–s, –u)Most Web-enabled applications maintain a ″state″ for a sequence of HTTP requestsfrom a client. This state is used, for example, to:v Track a user’s progress through the fields in a data entry form generated by a

CGI programv Maintain a user’s context when performing a series of database inquiriesv Maintain a list of items in an online shopping cart application where a user

randomly browses and selects items to purchase

Servers that run Web-enabled applications can be replicated in order to improveperformance through load sharing. When the WebSEAL server provides a junctionto these replicated back-end servers, it must ensure that all the requests containedwithin a client session are forwarded to the correct server, and not distributedamong the replicated back-end servers according to the load balancing rules.

By default, Tivoli Access Manager balances back-end server load by distributingrequests across all available replicated servers. Tivoli Access Manager uses a″least-busy″ algorithm. This algorithm directs each new request to the server withthe fewest connections already in progress.

The create command –s flag overrides this load balancing rule and creates a″stateful junction″ that ensures a client’s requests are forwarded to the same serverthroughout an entire session. When the initial client request occurs, WebSEALplaces a cookie on the client system that contains the UUID of the designatedback-end server. When the client makes future requests to the same resource, thecookie’s UUID information ensures that the requests are consistently routed to thesame back-end server.

The –s option is appropriate for a single front-end WebSEAL server with multipleback-end servers junctioned at the same junction point. Note that as soon as theinitial junction is created as stateful, the add command is used without the –soption to junction the remaining replicated back-end servers to the same junctionpoint.

If the scenario involves multiple front-end WebSEAL servers, all junctioned to thesame back-end servers, you must use the –u option to correctly specify eachback-end server UUID to each front-end WebSEAL server. See “Specifyingback-end server UUIDs for stateful junctions (–u)”.

Specifying back-end server UUIDs for stateful junctions (–u)When a new junction is created to a back-end Web application server, WebSEALnormally generates a Unique Universal Identifier (UUID) to identify that back-endserver. This UUID is used internally and also to maintain stateful junctions (create–s).

When the initial client request occurs, WebSEAL places a cookie on the clientsystem that contains the UUID of the designated back-end server. When the clientmakes future requests to the same resource, the cookie’s UUID information ensuresthat the requests are consistently routed to the same back-end server.


The handling of stateful junctions becomes more complex when there multiplefront-end WebSEAL servers junctioned to multiple back-end servers. Normally,each junction between a front-end WebSEAL server to a back-end server generatesa unique UUID for the back-end server. This means a single back-end server willhave a different UUID on each front-end WebSEAL server.

Multiple front-end servers require a load balancing mechanism to distribute theload between the two servers. For example, an initial ″state″ could be establishedto a back-end server through WebSEAL server 1 using a specific UUID.

However, if a future request from the same client is routed through WebSEALserver 2 by the load balancing mechanism, the ″state″ will no longer exist, unlessWebSEAL server 2 uses the same UUID to identity the same back-end server.Normally, this will not be the case.

The –u option allows you to supply the same UUID for a specific back-end serverto each front-end WebSEAL server.

As an example, consider two replicated front-end WebSEAL servers, each with astateful junction to two back-end servers. When you create the stateful junctionbetween WebSEAL server 1 and back-end server 2, a unique UUID (UUID A) isgenerated to identify back-end server 2. However, when a stateful junction iscreated between WebSEAL server 2 and back-end server 2, a new and differentUUID (UUID B) is generated to identify back-end server 2.

WebSEAL

ApplicationServer 1

(UUID1)

ApplicationServer 2

(UUID2)

ClientStateful

JunctionsCookiewith

UUID2

Figure 28. Stateful junctions use back-end server UUIDs

WebSEAL-1

ApplicationServer 2

StatefulJunctions

WebSEAL-2

UUID B

ApplicationServer 1UUID A

Figure 29. Dissimilar UUIDs


A ″state″ established between a client and back-end server 2, via WebSEAL server 1will fail if a subsequent request from the client is routed through WebSEAL server2.

Apply the following process for specifying a UUID during the creation of ajunction:1. Create a junction from WebSEAL server 1 to each back-end server.

Use create –s and add.2. List the UUID generated for each back-end server during Step 1.

Use show.3. Create a junction from WebSEAL server 2 to each back-end server and specify

the UUIDs identified in Step 2.Use create –s –u and add –u.

In the following figure, back-end server 1 is known by both WebSEAL-1 andWebSEAL-2 as UUID 1. Back-end server 2 is known by both WebSEAL-1 andWebSEAL-2 as UUID 2.

Example:In the following example,v WebSEAL-1 is called WS1v WebSEAL-2 is called WS2v Back-end server 1 is called APP1v Back-end server 2 is called APP2pdadmin> server task webseald-WS1 create -t tcp -h APP1 -s /mntpdadmin> server task webseald-WS1 add -h APP2 /mntpdadmin> server task webseald-WS1 show /mnt

(This reveals UUID1 and UUID2)pdadmin> server task webseald-WS2 create -t tcp -h APP1 -u <UUID1> -s /mntpdadmin> server task webseald-WS2 add -h APP2 -u <UUID2> /mnt

When a client establishes a stateful connection with back-end server 2, it receives acookie containing UUID2. The above example now ensures that the client willalways connect to back-end server 2, regardless of whether future requests arerouted through WebSEAL-1 or WebSEAL-2.

WebSEAL-1

ApplicationServer 2

(UUID 2)

StatefulJunctions

LoadBalancing

Mechanism

WebSEAL-2

Client

Cookiewith

UUID 2

ApplicationServer 1

(UUID 1)

Figure 30. Specifying back-end server UUIDs for stateful junctions


Junctioning to Windows file systems (–w)WebSEAL performs security checks on client requests to junctioned back-endservers based on the file paths specified in the URL. A compromise in this securitycheck can occur because Win32 file systems allow two different methods foraccessing long file names.

The first method acknowledges the entire file name. For example:abcdefghijkl.txt

The second method recognizes the old 8.3 file name format for backwardcompatibility. For example:abcdef~1.txt

When you create junctions in a Windows environments, it is important to restrictaccess control to one object representation only and not allow the possibility of″back doors″ that bypass the security mechanism.

The –w option on a junction provides the following measures of protection:v Prevents the use of the 8.3 file name format

When the junction is configured with the –w option, a user cannot avoid anexplicit ACL on a long file name by using the short (8.3) form of the file name.The server returns a ″403 Forbidden″ error on any short form file name entered.

v Disallows trailing dots in directory and file namesIf a file or directory contains trailing dots, a 403 ″Forbidden″ error is returned.

v Enforces case-insensitivity by setting the –i optionThe –w option automatically invokes the –i option. This option specifies thatWebSEAL treat URLs as case-insensitive when performing authorization checkson a request to a junctioned back-end server. After a successful ACL check, theoriginal case of the URL is restored when the request is sent to the back-endserver.

Note: If you require control over case-insensitivity only for file names, use onlythe –i option on the junction instead of the –w option.

Example:In a Windows environment, the file:\Program Files\Company Inc\Release.Notes

can also be accessed via the following paths:1. \progra~1\compan~2\releas~3.not

2. \Program Files\Company Inc.\Release.Notes

3. \program files\company inc\release.notes

Example 1 illustrates how Windows can create an alias (for DOS compatibility) thatcontains no spaces in the file names and conforms to the 8.3 format. The –w optioncauses WebSEAL to reject this format for ACL checks.

Example 2 illustrates how Windows can include trailing extension dots. The –woption causes WebSEAL to reject this format for ACL checks.

Example 3 illustrates how Windows allows case-insensitivity on the file name. The–w option invokes the –i option to ensure a case-insensitive ACL check.


Technical notes for using WebSEAL junctionsv “Mounting multiple servers at the same junction” on page 195v “Exceptions to enforcing permissions across junctions” on page 195v “Certificate authentication across junctions” on page 195v “Handling domain cookies” on page 196

Mounting multiple servers at the same junctionYou can mount multiple replicated servers at the same junction point. There can beany number of servers mounted at the same point.

All servers mounted at one junction point must be replicas (mirrored Web spaces),and must use the same protocol—HTTP or HTTPS. Do not mount dissimilarservers on the same junction point.

From the primary Tivoli Access Manager server Web space, access pages belongingto the junctioned servers. You should be able to access these pages (subject topermissions, of course) and the pages should appear consistent. If a page cannot befound occasionally, or if it changes occasionally, it means that page was notreplicated properly.

Check that the document exists and is identical in the document tree of bothreplicated servers.

Exceptions to enforcing permissions across junctionsCertain Tivoli Access Manager permissions are not enforceable across a junction.You cannot control, for example, the execution of a CGI script with the xpermission, or a directory listing with the l permission. WebSEAL has no means ofaccurately determining whether or not a requested object on a back-end server is,for example, a CGI program file, a dynamic directory listing, or a regular HTTPobject.

Access to objects across junctions, including CGI programs and directory listings, iscontrolled only through the r permission.

Certificate authentication across junctionsAt installation, WebSEAL is configured with a non-default test certificate. The testcertificate is designated as the active server-side certificate by thewebseal-cert-keyfile-label parameter in the [ssl] stanza of the webseald.confconfiguration file.

If a junctioned back-end application server requires WebSEAL to identify itselfwith a client-side certificate, you must first create, install, and label this certificateusing the iKeyman utility. Then, configure the junction using the –K <key-label>option. See “Mutually authenticated SSL junctions” on page 174.

If the junction is not configured with –K, GSKit handles a request for mutualauthentication by automatically sending the “default” certificate contained in thekeyfile database. If this is not the required response, you must ensure that there areno certificates marked as ″default″ (an asterisk mark) in the keyfile database(pdsrv.kdb).

In summary:v Identify all required certificates by label name.


v Do not mark any certificate in the keyfile database as ″default″.v Control the WebSEAL server-side certificate response with the

webseal-cert-keyfile-label parameter.v Control the WebSEAL client-side certificate response through the –K junction

option.

Handling domain cookiesThe allow-backend-domain-cookies parameter in the [session] stanza of thewebseald.conf configuration file allows you to control how WebSEAL handlesdomain attributes in cookie headers.

When this parameter is set to ″no″ (default), WebSEAL performs ″tail matching″ todetermine if the domain (contained as an attribute in the cookie header) is valid. Ifthe domain in the cookie header is valid, the cookie is sent to the browser with thedomain attribute removed from the cookie header. When a browser receives acookie with no domain attribute, it can return the cookie only to the originatingserver. If ″tail matching″ determines that the domain in the cookie header is notvalid, the cookie is not sent to the browser. The browser has no cookies to return.[session]allow-backend-domain-cookies = no

When this parameter is set to ″yes″, WebSEAL does not perform ″tail matching″and allows all cookies, regardless of the domain attribute value, to be sent to thebrowser. The browser can return the cookies to the appropriate server or servers.[session]allow-backend-domain-cookies = yes

Using query_contents with third-party serversIf you want to protect the resources of the third-party application Web space usingthe Tivoli Access Manager security service, you must provide WebSEAL withinformation about the contents of the third-party Web space.

A CGI program called query_contents provides this information. Thequery_contents program searches the third-party Web space contents and providesthis inventory information to the Web Portal Manager on WebSEAL. The programcomes with the WebSEAL installation, but must be manually installed on thethird-party server. There are different program file types available, depending onwhether the third-party server is running UNIX or Windows.

The Object Space manager of the Web Portal Manager automatically runsquery_contents any time the portion of the Protected Object Space representing thejunction is expanded in the Object Space management panel. Now that the WebPortal Manager knows about the contents of the third-party application space, youcan display this information and apply policy templates to appropriate objects.

Installing query_contents componentsInstalling query_contents is typically very easy. Installation involves copying oneor two files from the Tivoli Access Manager server to the third-party server andediting a configuration file.

The following Tivoli Access Manager directory contains a template of the program:

UNIX:


<install-path>/www/lib/query_contents

Windows:<install-path>\www\lib\query_contents

The contents of the directory includes:

File Description

query_contents.exe Main executable program for Win32 systems. Should beinstalled in the cgi-bin directory of the third-party Webserver.

query_contents.sh Main executable program for UNIX systems. Should beinstalled in the cgi-bin directory of the third-party Webserver.

query_contents.c Source code. The source is provided in case you need tomodify the behavior of query_contents. In most cases,this will not be necessary.

query_contents.html Help file in HTML format.

query_contents.cfg A sample configuration file that identifies the documentroot for the Web server.

Installing query_contents on third-party UNIX serversLocate the shell script named query_contents.sh in the following directory:<install-path>/www/lib/query_contents

1. Copy query_contents.sh into a functioning /cgi-bin directory on thethird-party Web server.

2. Remove the .sh extension from the file name.3. Manually edit the script file to correctly specify the doc root directory.4. Set the UNIX execute bit for the administration account of the Web server.

Installing query_contents on third-party Win32 serversSpecial junction option for Windows:

When you require, and install, the query_contents program on a back-endjunctioned Windows Web application server, you must use the –q option whencreating the junction to that server.

The reason for this requirement is that by default, WebSEAL looks for the program,query_contents, in the cgi-bin directory:/cgi-bin/query_contents

If you change the name of the query_contents program or change its directorylocation, you must use the –q <location> option when creating the junction. Thelocation argument specifies the new location and name of the program.

The name of the query_contents program used on the Windows platform isquery_contents.exe. The presence of the .exe extension makes the program namedifferent. Therefore, WebSEAL cannot find the default program name. You mustuse the –q <location> option and argument to tell WebSEAL where to find the file.For example:create -t tcp -h <host-name> ... -q /cgi-bin/query_contents.exe /<junction-name>


The –q option is not required for a UNIX server because the query_contentsprogram name and location matches the default condition.

Procedure:

Locate the executable program named query_contents.exe and the configurationfile named query_contents.cfg in the following directory:

Windows: <install-path>\www\lib\query_contents

1. Ensure that the third-party Web server has a CGI directory correctly configured.2. For testing purposes, ensure that a valid document exists in the document root

of the third-party Web server.3. Copy query_contents.exe into the CGI directory of the third-party Web server.4. Copy query_contents.cfg into the Windows directory.

Default values for this directory are shown in the table below:

Operating System Windows Directory

Windows 95 and 98 c:\windows

Windows NT 4.x and 2000 c:\winnt

5. Edit the query_contents.cfg file to correctly specify the document rootdirectory for the third-party Web server.The file currently contains sample entries for the Microsoft Internet InformationServer and Netscape FastTrack servers. The lines in this file that start with asemi-colon (;) are comments and are ignored by the query_contents program.

6. Create a junction to the back-end Windows server and use the –q option tospecify query_contents.exe as the correct file. For example:pdadmin> server task webseald-<instance-name> create -t tcp -h <host-name> ... \-q /cgi-bin/query_contents.exe /<junction-name>

Testing the configuration1. From an MS-DOS prompt on the Win32 machine, execute the query_contents

program from the CGI directory as follows:MSDOS> query_contents dirlist=/

You should see something similar to the following output:100index.htmlcgi-bin//pics//

The number 100 is a return status that indicates success. It is most important tosee at least the number 100 as the first (and perhaps only) value.

If you see an error code instead, then the configuration file is not in the correctplace, or does not contain a valid document root entry. Check the configurationof the query_contents.cfg file and make sure that the document root exists.

2. From a browser, enter the following URLhttp://<win32-machine-name>/cgi-bin/query_contents.exe?dirlist=/

This should return the same result as the preceding step. If it does not returnthis result, the CGI configuration of your Web server is not correct. See theserver’s documentation to correct the problem.


Customizing query_contentsThe job of query_contents is to return the contents of directories included in aURL request.

For example, to get the contents of the root directory of a server’s Web space, thebrowser runs query_contents on a URL such as:http://third-party-server/cgi-bin/query_contents?dirlist=/

The query_contents script performs the following actions:1. Reads $SERVER_SOFTWARE, a standard CGI environment variable, to

determine the server type.Based on the Web server type, the variable $DOCROOTDIR is set to a typicaldocument root location.

2. Reads the environment variable $QUERY_STRING from the requested URL toobtain the requested operation and get the object path.The operation value is stored in the variable $OPERATION, and the objectpath in $OBJPATH. In the above example, the $OPERATION is dirlist and$OBJPATH is ″/″.

3. Performs a directory listing (ls) on the object path and places the results onstandard output, for use by the Tivoli Access Manager server. Entries thatindicate subdirectories have a double slash (//) appended to them.Typical output looks like:100index.htmlcgi-bin//pics//

The number 100 is a return status that indicates success.

Customizing the doc root directoryUNIX:

To customize query_contents.sh for your UNIX server, you might need to modifythe document root directory setting.

If query_contents returns an error status (a number other than 100) and lists nofiles, examine the script and modify the $DOCROOTDIR variable, if needed, tomatch your server’s configuration.

If the document root directory is specified correctly and the script still fails, thecgi-bin location specification might be incorrect. Examine the $FULLOBJPATHvariable and modify the value assigned to it to reflect the correct cgi-bin location.

Windows:

To customize query_contents.exe for your Windows server, modify thequery_contents.cfg file.

Additional functionalityThe source code for the query_contents program (query_contents.c) is distributedroyalty-free with Tivoli Access Manager.

Additional functionality can be added to this program to support special featuresof some third-party Web servers. These features include:


v Directory mapping — where a sub-directory not below the document root ismapped into the Web space.

v Generation of a Web space that is not file system based.This might be the case for a database-hosted Web server.

Securing query_contentsThe query_contents CGI program is used by Tivoli Access Manager to displayjunctioned Web server object spaces in the Web Portal Manager. It is veryimportant to secure this file to prevent unauthorized users from running it.

You must set a security policy that allows only the policy server (pdmgrd) identityto have access to the query_contents program. The following example ACL(query_contents_acl) meets this criteria:group ivmgrd-servers Tl

user sec_master dbxTrlcam

Use the pdadmin utility to attach this ACL to the query_contents.sh (UNIX) orquery_contents.exe (Windows) object on the junctioned servers. For example(UNIX):pdadmin> acl attach /WebSEAL/<host>/<junction-name>/query_contents.sh \query_contents_acl


Chapter 8. Single sign-on solutions across junctions

When WebSEAL is implemented as a proxy server to provide protection to asecure domain, there is often a requirement to provide solutions for single sign-onto Web resources located on junctioned back-end servers. This chapter discussessingle sign-on solutions for the junctioned Web space of a WebSEAL proxyconfiguration. Examples include specially configured junctions, Global Sign-on, andLTPA.

Topic Index:v “Configuring BA headers for single sign-on solutions” on page 201v “Using global sign-on (GSO)” on page 205v “Configuring single sign-on to IBM WebSphere (LTPA)” on page 208v “Configuring single sign-on forms authentication” on page 210

Configuring BA headers for single sign-on solutionsThis section discusses the possible solutions for creating single sign-onconfigurations across WebSEAL junctions using the –b options.v “Single sign-on (SSO) concepts” on page 201v “Supplying client identity in BA headers” on page 202v “Supplying client identity and generic password” on page 202v “Forwarding original client BA header information” on page 203v “Removing client BA header information” on page 204v “Supplying user names and passwords from GSO” on page 205

Single sign-on (SSO) conceptsWhen a protected resource is located on a back-end Web application server, a clientrequesting that resource can be required to perform multiple logins — one for theWebSEAL server and one for the back-end server. Each login likely requiresdifferent login identities.

The problem of administering and maintaining multiple login identities can oftenbe solved with a single sign-on (SSO) mechanism. A single sign-on solution allows

Client WebSEALWeb

ApplicationServer

Junction

Login #1 Login #2

Figure 31. Multiple logins


the user to access a resource, regardless of the resource’s location, using only oneinitial login. Any further login requirements from back-end servers are handledtransparently to the user.

Supplying client identity in BA headersYou can configure WebSEAL junctions to supply the back-end server with originalor modified client identity information. The set of –b options allows you to supplyspecific client identity information in HTTP Basic Authentication (BA) headers.

As the administrator, you must analyze your network architecture and securityrequirements, and determine answers to the following questions:1. Is authentication information required by the back-end server?

(WebSEAL uses the HTTP Basic Authentication header to convey authenticationinformation.)

2. If authentication information is required by the back-end server, where doesthis information come from?(What information does WebSEAL place in the HTTP header?)

3. Does the connection between WebSEAL and the back-end server need to besecure?(TCP or SSL junction?)

After the initial authentication between the client and WebSEAL, WebSEAL canbuild a new Basic Authentication header. The request uses this new header as itcontinues across the junction to the back-end server. You use the –b options todictate what specific authentication information is supplied in this new header.

Supplying client identity and generic password–b supply

The –b supply option instructs WebSEAL to supply the authenticated Tivoli AccessManager user name (client’s original identity) with a static, generic (″dummy″)password. The original client password is not used in this scenario.

A generic password eliminates password administration and supports theapplication on a per-user basis. The ″dummy″ password is set inbasicauth-dummy-passwd parameter of the webseald.conf configuration file:[junction]basicauth-dummy-passwd = <password>

This scenario assumes the back-end server requires authentication from a TivoliAccess Manager identity. By mapping a client user to a known Tivoli Access

Client WebSEALWeb

ApplicationServer

New BA header withWebSEAL-supplied

authenticationinformation

Initial authentication resultsin Policy Director

credentials

junction

request request

Figure 32. Supplying authentication information to back-end servers


Manager user, WebSEAL manages authentication for the back-end server andprovides a simple domain-wide single sign-on solution.

The following conditions exist for this solution:v WebSEAL is configured to supply the back-end server with the user name

contained in the original client request plus a generic (″dummy″) password.v The ″dummy″ password is configured in the webseald.conf configuration file.v The back-end server registry must recognize the Tivoli Access Manager identity

supplied in the HTTP BA header.v Because sensitive authentication information (user name and password) is

passed across the junction, the security of the junction is important. An SSLjunction is highly recommended.

LimitationsThe same Tivoli Access Manager ″dummy″ password is used for all requests; allusers have the same password in the back-end server registry. The use of thecommon ″dummy″ password offers no basis for the application server to prove thelegitimacy of the client logging in with that user name.

If clients always go through WebSEAL to access the back-end server, this solutiondoes not present any security problems. However, it is important to physicallysecure the back-end server from other possible means of access.

Because this scenario has no password-level security, the back-end server mustimplicitly trust WebSEAL to verify the legitimacy of the client.

The back-end server registry must also recognize the Tivoli Access Manageridentity in order to accept it.

Forwarding original client BA header information–b ignore

The –b ignore option instructs WebSEAL to pass the original client BasicAuthentication (BA) header straight to the back-end server without interference.WebSEAL can be configured to authenticate this BA client information or ignorethe BA header supplied by the client and forward the header, withoutmodification, to the back-end server.

Client WebSEALSSL junction Web

ApplicationServer

WebSEAL supplies PolicyDirector identity and "dummy"

password

anyauthentication

mechanism

Registry Registry

Figure 33. BA Header contains identity and ″dummy″ password

Chapter 8. Single sign-on solutions across junctions 203

Note: This is not a true single sign-on mechanism, but rather a direct login to thethird-party server, transparent to WebSEAL.

The following conditions exist for this solution:v The back-end server requires client identity information via BA

The back-end server will send a Basic Authentication challenge back to theclient. The client responds with user name and password information which theWebSEAL server passes through without modification.

v The back-end server maintains its own client-supplied passwordsv WebSEAL is configured to supply the back-end server with the user name and

password contained in the original client request.v Because sensitive authentication information (user name and password) is

passed across the junction, the security of the junction is important. An SSLjunction is highly recommended.

Removing client BA header information–b filter

The –b filter option instructs WebSEAL to remove all Basic Authentication headerinformation from any client requests before forwarding the requests to theback-end server. In this scenario, WebSEAL becomes the single security provider.

The following conditions exist for this solution:v Basic Authentication is configured between the client and WebSEALv The back-end server does not require Basic Authenticationv The back-end server can be accessed only through WebSEALv WebSEAL handles authentication on behalf of the back-end server

Client WebSEALjunction Web

ApplicationServer

WebSEAL supplies originalclient authentication (BA)

information

BasicAuthentication

Registry Registry

Figure 34. WebSEAL forwards original client identity information


If you need to supply the back-end server with some client information, you cancombine this option with the –c option to insert Tivoli Access Manager clientidentity information into HTTP header fields. See “Supplying client identity inHTTP headers (–c)” on page 187.

Supplying user names and passwords from GSO–b gso

The –b gso option instructs WebSEAL to supply the back-end server withauthentication information (user name and password) obtained from a server thatis set up to handle global sign-on (GSO).

The following conditions exist for this solution:v The back-end server applications require different user names and passwords

that are not contained in the WebSEAL registry.v Security is important for both WebSEAL and the back-end server.

Because sensitive authentication information (user name and password) is passedacross the junction, the security of the junction is important. An SSL junction ishighly recommended.

This mechanism is fully described in “Using global sign-on (GSO)”.

Using global sign-on (GSO)Tivoli Access Manager supports a flexible single sign-on solution that features theability to provide alternative user names and passwords to the back-end Webapplication server.

Global Sign-on grants users access to the computing resources they are authorizedto use — through a single login. Designed for large enterprises consisting ofmultiple systems and applications within heterogeneous, distributed computingenvironments, GSO eliminates the need for end users to manage multiple usernames and passwords.

The integration is achieved by creating ″aware″ junctions between WebSEAL andback-end Web servers. GSO resources and GSO resource groups must first becreated using the Web Portal Manager or the pdadmin utility.

When WebSEAL receives a request for a resource located on the junctioned server,WebSEAL asks the user registry server for the appropriate authentication

Client WebSEALWeb

ApplicationServer

TCP or SSLjunction

BasicAuthentication

no authenticationrequired

WebSEAL removes originalclient identity information

from BA header

Figure 35. Removing client BA header information


information. The user registry server contains a database of mappings—for eachregistered user—that provides alternative user names and passwords for specificresources and applications.

The following figure illustrates how the GSO mechanism is used to retrieve usernames and passwords for back-end application resources.1. The client authenticates to WebSEAL with a request for access to an application

resource on an back-end server. A Tivoli Access Manager identity is obtained.

Note: The single sign-on process is independent of the initial authenticationmethod.

2. WebSEAL passes the Tivoli Access Manager identity to the user registry server.3. The registry returns a user name and password appropriate for the user and

the requested application resource.4. WebSEAL inserts the user name and password information in the HTTP Basic

Authentication header of the request that is sent across the junction to theback-end server.

Mapping the authentication informationThe following example illustrates how the user registry provides authenticationinformation to WebSEAL. If user Michael wants to run the travel-app applicationresource (refer to Figure 36), WebSEAL asks the user registry server for Michael’sauthentication information.

The user registry server maintains a complete database of authenticationinformation in the form of mappings of resources to specific authenticationinformation. The authentication information is a user name / passwordcombination known as a resource credential. Resource credentials can be createdonly for registered users.

The registry contains a database for Michael that maps the resource travel-app to aspecific resource credential.

junctions (-b gso)

WebSEAL

Client

Secure Domain

Resources:- accounts-app

- travel-app

HTTPSResources:

- expenses-app- payroll-app

HTTP

Host: sales_svr

Host: adm_svr

SSL junction provides encryptedcommunication

/

/sales

/admin

Access ManagerIdentity

Username /password

1

2

3

4

User RegistryServer

Figure 36. Global sign-on mechanism


The following table illustrates the structure of the GSO resource credentialdatabase:

Michael Paul

resource: travel-appusername=mikepassword=123

resource: travel-appusername=bundypassword=abc

resource: payroll-appusername=powellpassword=456

resource: payroll-appusername=jensenpassword=xyz

In this example, the registry returns user name ″mike″ and password ″123″ toWebSEAL. WebSEAL uses this information when it constructs the BasicAuthentication header in the request sent across the junction to the back-endserver.

Configuring a GSO-enabled WebSEAL junctionSupport for GSO is configured at the junction between WebSEAL and a back-endserver.

To create a junction that enables GSO, use the create command with the –b gsooption. The following example illustrates the syntax for the create command:create -t tcp -h <host-name> -b gso -T <resource> <jct-point>

Options for setting up GSO junctions are listed below:

Options Description

–b gso Specifies that GSO should provide authenticationinformation for all requests crossing this junction.

–T <resource/resource-group> Specifies the GSO resource or resource group. Theresource name used as the argument to this optionmust exactly match the resource name as listed in theGSO database. Required for gso junctions.

A junction used in a WebSEAL/GSO solution can be made secure through SSL byadditionally applying the –t ssl option when creating the junction.

Always use SSL junctions with GSO to ensure encryption of credentials and alldata.

Examples of GSO-enabled WebSEAL junctionsJunction the application resource travel-app on host sales_svr to junction point/sales:create -t tcp -b gso -T travel-app -h sales_svr /sales

Junction the application resource payroll-app on host adm_svr to junction point/admin and make the junction secure with SSL:create -t ssl -b gso -T payroll-app -h adm_svr /admin

Note: In the above example, the –t ssl option dictates a default port of 443.


Configuring the GSO cacheThe Global Sign-on (GSO) cache functionality allows you to improve theperformance of GSO junctions in a high load environment. By default, the GSOcache is disabled. Without the enhancement of the cache, a call to the user registryserver is required for each retrieval of GSO target information (GSO user name andGSO password).

Parameters for configuring the GSO cache are located in the [gso-cache] stanza ofthe webseald.conf configuration file. You must first enable the cache. Theremaining parameters configure the cache size and the timeout values for cacheentries. Larger lifetime and inactivity timeout values improve performance, butincrease the risk of information being exposed in the WebSEAL memory. Do notenable the GSO cache if GSO junctions are not used in your network solution.


gso-cache-enabled Enable and disable the GSO cache functionality.Values include ″yes″ and ″no″. Default is ″no″.

gso-cache-size Sets the maximum number of entries allowed inthe cache hash table. Set this value toapproximate the peak number of concurrent usersessions that access an application across a GSOjunction. A high value uses more memory butresults in faster information access. Each cacheentry consumes approximately 50 bytes.

gso-cache-entry-lifetime Maximum time (in seconds) any cache entry canremain in the cache, regardless of activity. After acache entry expires, the next request by thatsame user requires a new call to the user registryserver. Default value is 900 seconds.

gso-cache-entry-idle-timeout Maximum time (in seconds) an inactive cacheentry can remain in the cache. Default value is120 seconds.

For more information, see “Global Sign-On cache” on page 315 in Appendix A,“WebSEAL configuration file reference”, on page 241.

Configuring single sign-on to IBM WebSphere (LTPA)WebSEAL can provide authentication and authorization services and protection toan IBM WebSphere environment. When WebSEAL is positioned as a protectivefront-end to WebSphere, accessing clients are faced with two potential login points.Therefore, WebSEAL supports a single sign-on solution to one or more IBMWebSphere servers across WebSEAL junctions.

WebSphere provides the cookie-based lightweight third-party authenticationmechanism (LTPA). You can configure WebSEAL junctions to support LTPA andprovide a single sign-on solution for clients.

When a user makes a request for a WebSphere resource, the user must firstauthenticate to WebSEAL. After successful authentication, WebSEAL generates anLTPA cookie on behalf of the user. The LTPA cookie, which serves as anauthentication token for WebSphere, contains the user identity, key and token data,


buffer length, and expiration information. This information is encrypted using apassword-protected secret key shared between WebSEAL and the WebSphereserver.

WebSEAL inserts the cookie in the HTTP header of the request that is sent acrossthe junction to WebSphere. The back-end WebSphere server receives the request,decrypts the cookie, and authenticates the user based on the identity informationsupplied in the cookie.

To improve performance, WebSEAL can store the LTPA cookie in a cache and usethe cached LTPA cookie for subsequent requests during the same user session. Youcan configure lifetime timeout and idle (inactivity) timeout values for the cachedcookie.

Configuring an LTPA junctionSingle sign-on to WebSphere via an LTPA cookie requires the followingconfiguration tasks:1. Enable the LTPA mechanism.2. Provide the location of the key file used to encrypt the identity information.3. Provide the password to this key file.

These three configuration requirements are specified in three additional options tothe junction create command.v The –A option enables LPTA cookies.v The –F <″keyfile″> option and argument specifies the full path name location

(on the WebSEAL server) of the key file used to encrypt the identity informationcontained in the cookie. The shared key is originally created on the WebSphereserver and copied securely to the WebSEAL server. Refer to the appropriateWebSphere documentation for specific details regarding this task.

v The –Z <″keyfile-password″> specifies the password required to open the keyfile.The password appears as encrypted text in the junction XML file.

Use these options in addition to other required junction options when you createthe junction between WebSEAL and the back-end WebSphere server. For example:create ... -A -F "/abc/xyz/key.file" -Z "abcdefg" ...

Configuring the LTPA cacheThe creation, encryption, and decryption of LTPA cookies introduces processingoverhead. The LTPA cache functionality allows you to improve the performance ofLTPA junctions in a high load environment. Without the enhancement of the cache,a new LTPA cookie is created and encrypted for each subsequent user request. Bydefault, the LTPA cache is enabled.

Parameters for configuring the LTPA cache are located in the [ltpa-cache] stanza ofthe webseald.conf configuration file. Parameters specify the cache size and thetimeout values for cache entries. Larger lifetime and inactivity timeout valuesimprove performance, but increase the risk of information being exposed in theWebSEAL memory.



ltpa-cache-enabled Enable and disable the LTPA cache functionality.Values include ″yes″ and ″no″. Default value is″yes″.

ltpa-cache-size Sets the maximum number of entries allowed inthe cache hash table. Set this value toapproximate the peak number of concurrent usersessions that access an application across anLTPA junction. A high value uses more memorybut results in faster information access. Eachcache entry consumes approximately 50 bytes.Default value is 4096 entries.

ltpa-cache-entry-lifetime Maximum time (in seconds) any cache entry canremain in the cache, regardless of activity. After acache entry expires, the next request by thatsame user requires the creation of a new LTPAcookie. Default value is 3600 seconds

ltpa-cache-entry-idle-timeout Maximum time (in seconds) an inactive cacheentry can remain in the cache. Default value is600 seconds.

For more information, see “Lightweight Third Party Authentication cache” onpage 317 in Appendix A, “WebSEAL configuration file reference”, on page 241.

Technical notes for LTPA single sign-onv The key file contains information about a specific WebSphere server. An LTPA

junction is specific to one WebSphere server. If you add more than one server tothe same junction point, all servers will share the same key file.

v For single sign-on to succeed, WebSEAL and the WebSphere server must sharethe same registry information.

v The WebSphere server is responsible for setting up LTPA and the creation of theshared secret key. The WebSEAL participation involves the junction and cacheconfigurations.

Configuring single sign-on forms authenticationSingle sign-on forms authentication allows WebSEAL to transparently log anauthenticated Tivoli Access Manager user in to a back-end junctioned applicationserver that requires authentication via an HTML form.

Background and goalsSingle sign-on forms authentication supports existing applications that use HTMLforms for authentication and cannot be modified to directly trust the authenticationperformed by WebSEAL. Enabling single sign-on forms authentication producesthe following results:v WebSEAL interrupts the authentication process initiated by the back-end

applicationv WebSEAL supplies data required by the login form and submits the login form

on behalf of the user.v WebSEAL saves and restores all cookies and headersv The user is unaware that a second login is taking place.


v The back-end application is unaware that the login form is not coming directlyfrom the user.

WebSEAL must be configured to:v Recognize and intercept the login formv Fill in the appropriate authentication data

The administrator enables forms single sign-on by:v Creating a configuration file to specify how the login form is to be recognized,

completed, and processedv Enable forms single sign-on by configuring the appropriate junction with the –S

option (which specifies the location of the configuration file)

Forms single sign-on process flowThe following scenario assumes that WebSEAL has already authenticated the user.

1. Client browser requests the page:https://webseal/formsso/content.html

2. WebSEAL passes the request to the junction.3. Because the back-end application requires the user to authenticate, a redirect

to the application’s login page (login.html) is sent back across the junction.4. WebSEAL passes the redirect to the browser.5. The browser follows the redirect and requests:

https://webseal/formsso/login.html

Clientbrowser

WebSEAL ApplicationServer

junction -S

request1 2

4

5 6

7

8

3

910

11 12

login required

redirect tologin page

browser followsredirect

fsso begins;cookies saved

applicationreturns login form

WebSEALcompletes form

login succeeds;redirect to request

saved cookiesrestored;fsso ends

browser followsredirect

applicationprocesses request

Figure 37. Forms single sign-on process flow


Note: Everything to this point in the process flow is standard WebSEALfunctionality.

6. WebSEAL has been configured for forms single sign-on (–S option on thejunction). WebSEAL recognizes the request as a request for a login page, basedon information contained in the forms SSO configuration file. The request ispassed to the junction. WebSEAL saves all cookies sent by the browser for usein step 8.

7. The application returns the login page and perhaps application-specificcookies.WebSEAL parses the HTML returned to identify the login form. WhenWebSEAL finds an HTML form in the document, it compares the action URIin the form to the value of the login-form-action parameter in the customconfiguration file. If there is a match, WebSEAL uses the form found.Otherwise, WebSEAL keeps searching for other forms. If no form in the pagematches the action URI pattern from the configuration file, then WebSEALterminates forms single sign-on processing and returns an error to thebrowser.WebSEAL parses the HTML page to identify the request method, the actionURI, and any other input fields in the form, and saves them for use in step 8.

8. WebSEAL generates the authentication request (completes the login form) andsends it to the back-end application.

9. The application authenticates the user using the authentication data suppliedby WebSEAL in the form. The application returns a redirect to content.html.

10. WebSEAL combines any cookies saved from the responses at step 7 and step9, and returns these cookies with the redirect to the browser.

Note: This completes the forms SSO-specific functionality.11. The browser follows the redirect and requests:

https://webseal/formsso/content.html

12. WebSEAL passes the request to the back-end application across the junction.

During this process, the browser makes three requests to WebSEAL. From theuser’s perspective, only a single request forhttps://webseal/formsso/content.html is made. The other requests occurautomatically through HTTP redirects.

Requirements for application supportSingle sign-on for forms authentication is supported on applications that meet thefollowing requirements:v The login page or pages for the application must be uniquely identifiable via a

single regular expression or several regular expressions.v The login page can include more than one HTML form. However, the login form

must be identified by applying a regular expression to the action URIs of each ofthe login forms, or the login form must be the first form in the login page. Notethat when using the ″action″ attribute to identify the login form, the ″action″attribute has not passed through WebSEAL’s HTML filtering. The regularexpression should match the action URI prior to being filtered.

v Client-side scripting may be used to validate input data, but it must not modifythe input data (such as using Javascript to set cookies in the user’s browser).

v Login data is submitted at only one point in the authentication process.v The junction where the authentication request is directed must be the same

junction where the login page is returned.


Creating the configuration file for forms single sign-onThe forms single sign-on configuration file is custom-created by the administratorand saved in any location. The –S option on the junction enables the forms singlesign-on functionality and specifies the location of the configuration file. See“Enabling forms single sign-on” on page 216. A sample configuration file(containing commented instructions) is provided with the WebSEAL installationand is located in the following directory:

UNIX:/opt/pdweb/etc/fsso.conf.template

Windows:C:\Program Files\Tivoli\PDWeb\etc\fsso.conf.template

The configuration file must begin with the [forms-sso-login-pages] stanza and hasthe following format[forms-sso-login-pages]login-page-stanza = <xxxxx>#login-page-stanza = <aaaaa>#login-page-stanza = <bbbbb>

[<xxxxx>]login-page = <regular-expression-page-match>login-form-action = <regular-expression-form-match>gso-resource = <gso-target>argument-stanza = <yyyyy>

[<yyyyy>]<name> = <method>:<value>

The [forms-sso-login-pages] stanzaThe forms single sign-on configuration file must always begin with the[forms-sso-login-pages] stanza. The stanza contains one or more login-page-stanzaentries that point to other custom-named stanzas that contain configurationinformation for the login pages found on the back-end application server.

The ability to support multiple login pages on a single junction is importantbecause a single back-end server might host several applications that each use adifferent authentication method.

For example:[forms-sso-login-pages]login-page-stanza = loginpage1login-page-stanza = loginpage2

The custom login page stanzaEach custom login page stanza is used to intercept a particular URL pattern. Thestanza can contain the following parameters:


login-page This parameter specifies a pattern, using a regular expression, thatuniquely identifies requests for an application’s login page.WebSEAL intercepts these pages and begins the forms singlesign-on process. The regular expression is compared against therequest URI and is relative to (and not including) the junctionpoint where the server is mounted.



login-form-action This parameter specifies a pattern, using a regular expression, thatidentifies which form contained in the intercepted page is theapplication’s login form. If there is only a single form in the page,or if the login form is the first form in the document, then theexpression can be ″*>. Otherwise, the regular expression shouldmatch the ″action> attribute of the login form.

gso-resource This parameter specifies the GSO resource to use when retrievingthe GSO user name and password from a GSO database. Leavethis parameter blank if GSO is not used to store a GSO user nameand password.

argument-stanza This parameter points to another custom stanza that lists the fieldsand data required for completing the login form.

For example:[loginpage1]login-page = /cgi-bin/getloginpage*login-form-action = *gso-resource =argument-stanza = form1-data

About the login-page parameter:

The value of the login-page parameter is a regular expression that WebSEAL usesto determine if an incoming request is actually a request for a login page. If this isthe case, WebSEAL intercepts this request and begins the forms single sign-onprocessing.

Only one login-page parameter is allowed in each custom login page stanza. Youmust create an additional custom login page stanza for each additional login-pageparameter.

The login-page regular expression is compared against the request URI, relative tothe junction. In the following example, the URI of a request to a WebSEAL servercalled ″websealA″ for a resource on a junction called ″junctionX″ might appear asfollows:https://websealA.ibm.com/junctionX/auth/login.html

The part of this URL that is compared to the login-page regular expression is:/auth/login.html

About the login-form-action parameter:

The login-form-action parameter is used to identify the login form on theintercepted page. Only one login-form-action parameter is allowed in each stanza.

The value of the login-form-action parameter is a regular expression that iscompared against the contents of the ″action″ attribute of the HTML ″form″ tag.The ″action″ attribute is a URI expressed as a relative, server-relative, or absolutepath. The login-form-action parameter must match this path as it comes from theback-end server - even if it would normally be modified by WebSEAL before beingforwarded to the client.

If multiple ″action″ attributes on the page match the regular expression, only thefirst match is accepted as the login form.


If the regular expression does not match any form on the page, an error is returnedto the browser reporting that the form could not be found.

You can set login-form-action = * as a simple way to match the login form whenthe page includes only one login form.

Using regular expressionsThe following table lists the special characters allowed in regular expressions usedin the forms single sign-on configuration file.

* Matches zero or more characters

? Matches any one character

\ Escape character (for example, \? matches ?)

[acd] Matches character a, c, or d (case-sensitive)

[^acd] Matches any character except a, c, or d (case-sensitive)

[a-z] Matches any character between a and z (lowercase letter)

[^0-9] Matches any character not between 0 and 9 (not a number)

[a-zA-Z] Matches any character between a and z (lowercase) or A and Z(uppercase)

In most cases, special characters are not required because the login page request isa single identifiable URI. In some cases, you can use the ″*″ at the end of theexpression so that any query data at the end of the URI does not prevent the loginpage from being matched.

The argument stanzaThe custom argument stanza contains one or more entries in the following form:<name> = <method>:<value>

name

The value of the name parameter is set to equal the value of the ″name″ attribute ofthe HTML ″input″ tag. For example:<input name=uid type=text>Username</input>

This parameter can also use the value of the ″name″ attribute of the HTML ″select″or ″textarea″ tags.

method:value

This parameter combination retrieves the authentication data required by the form.The authentication data can include:v Literal string data

string:<text>

The input used is the text string.v GSO user name and password

gso:usernamegso:password

The input is the current user’s GSO username and password (from the targetspecified in the custom login page stanza.


v Value of an attribute in the user’s credentialcred:<cred-ext-attr-name>

By default, the credential includes information such as the user’s Tivoli AccessManager user name and DN. To use the user’s Tivoli Access Manager user nameas the input value, specify the value as:cred:azn_cred_principal_name

The user’s DN may be accessed as:cred:azn_cred_authzn_id

Custom credential attributes (added via the tag/value mechanism) can also beused.

It is not necessary to specify hidden input fields in this stanza. These fields areautomatically retrieved from the HTML form and submitted with theauthentication request.

For example:[form1-data]uid = string:brian

Enabling forms single sign-onAfter completing the custom forms single sign-on configuration file and locatingthe file in an appropriate directory, you must configure the appropriate junction tosupport forms single sign-on. Use the –S junction option with the pdadmin createcommand:-S <config-file-path>

The config-file-path argument specifies the location of the custom forms singlesign-on configuration file. The –S junction option enables the forms single sign-onfunctionality on the junction.

For example:pdadmin> server task webseald-<instance> -t tcp -h websvrA \-S /opt/pdweb/fsso/fsso.conf /jctX

The configuration file is read when the junction is created and each time WebSEALis started. Errors in the configuration file can cause WebSEAL to fail at start-up.

Example configuration file for IBM HelpNowThe IBM HelpNow site invokes its own forms-based login and is therefore anexample of how a forms single sign-on solution can provide seamless access to thesite for its enrolled users.

This section contains:v A form section, similar to the form sent on the HTML login page returned by

the HelpNow applicationv The custom forms single sign-on configuration file used to process this form

The form found in the intercepted HTML page:<form name="confirm" method="post" action="../files/wcls_hnb_welcomePage2.cgi"><p>Employee Serial Number:


<input name="data" size="10" maxlength="6"><p>Country Name:<select name="Cntselect" size="1"><OPTION value="notselected" selected>Select Country</OPTION><OPTION value=675>United Arab Emirates - IBM</OPTION><OPTION value=866>United Kingdom</OPTION><OPTION value=897>United States</OPTION><OPTION value=869>Uruguay</OPTION><OPTION value=871>Venezuela</OPTION><OPTION value=852>Vietnam</OPTION><OPTION value=707>Yugoslavia</OPTION><OPTION value=825>Zimbabwe</OPTION></select><p><input type=submit value=Submit></form>

The custom configuration file used to process this form:helpnow FSSO configuration:

[forms-sso-login-pages]login-page-stanza = helpnow

[helpnow]# The HelpNow site redirects you to this page# you are required to log in.login-page = /bluebase/bin/files/wcls_hnb_welcomePage1.cgi

# The login form is the first in the page, so we can just call it# ’*’.login-form-action = *

# The GSO resource, helpnow, contains the employee serial number.gso-resource = helpnow

# Authentication arguments follow.argument-stanza = auth-data

[auth-data]# The ’data’ field contains the employee serial number.data = gso:username

# The Cntselect field contains a number corresponding to the employee’s# country of origin. The string "897" corresponds to the USA.Cntselect = string:897


Chapter 9. Application integration

WebSEAL supports third-party application integration through environmentvariables and dynamic URL capability. WebSEAL extends the range of environmentvariables and HTTP headers to enable third-party applications to performoperations based on a client’s identity. In addition, WebSEAL can provide accesscontrol on dynamic URLs, such as those that contain query text.

Topic Index:v “Supporting CGI programming” on page 219v “Supporting back-end server-side applications” on page 221v “Junction ″best practices″ for application integration” on page 221v “Building a custom personalization service” on page 223v “Enabling dynamic business entitlements (tag/value)” on page 224v “Maintaining session state between client and back-end applications” on page

228v “Providing access control to dynamic URLs” on page 231v “Dynamic URL example: The Travel Kingdom” on page 237

Supporting CGI programmingTo support CGI programming, WebSEAL adds three additional environmentvariables to the standard set of CGI variables. These environment variables can beused by CGI applications running on either the local WebSEAL server or ajunctioned back-end server. The variables provide Tivoli Access Manager-specificuser, group, and credential information to the CGI application.

On a local WebSEAL server, these environment variables are automaticallyavailable to CGI programs.

Environment variables used by a CGI application running on a junctionedthird-party server are produced from the HTTP header information passed to theserver from WebSEAL. You must use the –c option to create a junction thatsupports Tivoli Access Manager-specific header information in HTTP requestsdestined for a back-end server.

See also“Supplying client identity in HTTP headers (–c)” on page 187.

Additional Tivoli Access Manager-specific environment variables:

CGI Environment Variables Description

HTTP_IV_USER The Tivoli Access Manager user account name of therequester.

HTTP_IV_GROUPS The Tivoli Access Manager groups to which the requesterbelongs. Specified as a comma-separated list of groups —each group is surrounded by double-quotation marks.


CGI Environment Variables Description

HTTP_IV_CREDS Encoded opaque data structure representing a TivoliAccess Manager credential. Supplies credentials to remoteservers so mid-tier applications can use the authorizationAPI to call the authorization service. Refer to the IBMTivoli Access Manager Authorization C API Developer’sReference.

The REMOTE_USER variable on a local WebSEAL server:

On a local server environment controlled by WebSEAL, the value of theHTTP_IV_USER variable listed above is provided as the value for the standardREMOTE_USER variable. Note that the REMOTE_USER variable may also bepresent in the environment of a CGI application running on a junctioned back-endserver. However, in this situation, its value is not controlled by WebSEAL.

CGI Environment Variable Description

REMOTE_USER Contains the same value as the HTTP_IV_USER field.

Windows: Supporting WIN32 environment variablesThis section applies to local junctions only.

Windows does not automatically make all of its system environment variablesavailable to processes such as CGI applications. Typically, the system environmentvariables you require are present.

However, if any Windows system environment variables that you require are notpresent in the CGI environment, you can explicitly make them available to CGIprograms through the webseald.conf configuration file. (Note that the TivoliAccess Manager environment variables mentioned in the previous section areautomatically available on all platforms).

Add any of the required Windows system environment variables to the[cgi-environment-variables] stanza of the webseald.conf configuration file. Use thefollowing format:ENV = <variable-name>

For example:[cgi-environment-variables]#ENV = SystemDriveENV = SystemRootENV = PATHENV = LANGENV = LC_ALLENV = LC_CTYPEENV = LC_MESSAGESENV = LOCPATHENV = NLSPATH

Any uncommented lines are inherited by a CGI environment.


Supporting back-end server-side applicationsWebSEAL also provides support for executable code that runs as an embeddedcomponent of a back-end Web server. Examples of such server-side executable codeinclude:v Java servletsv Cartridges for Oracle Web Listenerv Server-side plug-ins

When you create a junction to a back-end server using the –c option, WebSEALinserts Tivoli Access Manager-specific client identity and group membershipinformation into the HTTP headers of requests destined for that server.

The Tivoli Access Manager-specific HTTP header information enables applicationson junctioned third-party servers to perform user-specific actions based on theclient’s Tivoli Access Manager identity.

WebSEAL provides the following Tivoli Access Manager-specific HTTP headers:

PD-specificHTTP Header Fields Description

iv-user = The short or long name of the client. Defaults to“Unauthenticated” if client is unauthenticated (unknown).

iv-groups = A list of groups to which the client belongs. Specified as acomma separated list of quoted groups.

iv-creds = Encoded opaque data structure representing a Tivoli AccessManager credential. Supplies credentials to remote servers somid-tier applications can use the authorization API to call theauthorization service. Refer to the IBM Tivoli Access ManagerAuthorization C API Developer’s Reference.

These HTTP headers are available to CGI applications as the environment variablesHTTP_IV_USER, HTTP_IV_GROUPS and HTTP_IV_CREDS. For other non-CGIapplication frameworks, see their associated product documentation forinstructions on extracting headers from HTTP requests.

See also “Supplying client identity in HTTP headers (–c)” on page 187.

Junction ″best practices″ for application integrationThis section includes “best practices” recommendations when using WebSEALjunctions.v “Supplying complete HOST header information with -v” on page 221v “Supporting standard absolute URL filtering” on page 222

Supplying complete HOST header information with -vVirtual host configurations and portal applications require correct IP addressinformation for proper socket connections, and complete server name informationfor accurate routing.

These special back-end application services require complete server name and portdesignation information in any requests from browsers. The HOST header of a

Chapter 9. Application integration 221

request contains this information and makes it available to the application. Whenusing WebSEAL junctions, this information is supplied to the HOST headerthrough the use of the –v junction option.

Insufficient or missing server name and port information degrades theperformance of virtual hosting and portal applications. In addition, domain cookiesset by these applications may not contain sufficient information.

To provide the most complete information to the HOST header, the “best practices”recommendation is to always use both the fully qualified domain name of thejunctioned server and the connection port number in the –v option when creatingor adding the junction.

The –v option uses the following syntax:-v <fully-qualified-host-name>[:<port>]

For example:-v xyz.ibm.com:7001

Note: The port designation should be supplied only if you are using anon-standard port number.

Supporting standard absolute URL filteringWebSEAL, as a front-end reverse proxy, provides security services to back-endjunctioned application servers. Pages returned to the client from back-endapplications most often contain URL links to resources located on the back-endjunctioned server.

It is important that these links include the junction name to successfully direct therequests back to the correct locations of the resources. WebSEAL uses a set ofstandard rules to filter static URLs and supply this junction information.Additional configuration is required to filter URLs in scripts and dynamicallygenerated URLs. For detailed information on URL filtering, see “Modifying URLsto back-end resources” on page 178.

WebSEAL’s ability to properly filter absolute URLs from static HTML pagesrequires information about the server name provided in the –h junction option.This option provides WebSEAL with the name of the back-end junctioned server.Arguments to this option can include:v Fully qualified domain name of the serverv Short name of the serverv IP address of the server

WebSEAL identifies absolute URLs to filter based on its knowledge of the back-endjunctioned server name. Depending on your network environment, the –h<short-name> configuration might not provide WebSEAL with sufficientinformation.

In the following example, a junction is created using the following option andargument for a back-end server, located in the ibm.com network, with a shortname of “xyz”:-h xyz

A link on an HTML page from this server appears as follows:


http://xyz.ibm.com/doc/release-notes.html

When this page passes to the client during a request, WebSEAL might fail to filterthis URL because, based on the information provided by –h, it could not recognize“xyz.ibm.com” as the server name. Without the junction name in the path, arequest for the release notes document fails.

To support proper filtering of static absolute URLs, the “best practices”recommendation is to always use the fully qualified domain name of thejunctioned server in the –h option when creating or adding the junction.

Building a custom personalization serviceA Web portal, or launch page, is an integrated Web site service that dynamicallyproduces a customized list of Web resources available to a specific user. Resourcescan include corporate content, support services, and learning tools. The portaloutput represents a personalized list of resources based on the access permissionsfor the particular user. The launch page displays only those resources that have thecorrect access permissions for that user.

You can use WebSEAL configuration options and the authorization APIentitlements service to build a custom portal solution in a Tivoli Access Managerenvironment.

The process flow for building a custom WebSEAL portal service includes thefollowing tasks:1. A specific region of the protected object space is created to locate the set of

portal resource objects.2. Appropriate explicit ACLs are attached to each of these resource objects.3. The WebSEAL configuration file is edited to include the URL to the portal

service, the path of the object space containing the portal resources, and thepermission bit required by the user for access to these resources.

4. For each user request to the portal URL, WebSEAL uses the AuthorizationEntitlement Service to search this object space and produce a list of resourcesthat meet the authorization conditions for that user.

5. WebSEAL places this information in a PD_PORTAL HTTP header that is sent tothe back-end (junctioned) portal server.

6. The custom portal service (such as a CGI or servlet) located on the back-endserver reads the PD_PORTAL header contents and, for example, maps thecontents to descriptions and URL links that are displayed to the user on a Webpage. This information represents the personalized list of resources available tothe user based on access control permissions.

Configuring WebSEAL for a personalization service1. Create a new WebSEAL junction to the personalization service. For example:

pdadmin> server task <server-name> create -t tcp -h portalhost.abc.com \/portal-jct

2. Edit the webseald.conf configuration file to add a new [portal-map] stanza:[portal-map]

3. The entry in this stanza identifies the server-relative URL of the portal serviceprogram and the region of the object space that is searched for availableprotected portal resources, followed by the permission required for access. Thisis the list that is placed in the PD_PORTAL header.


[portal-map]<URL> = <object-space-region>:<permission>

Note: Only resource objects with explicitly set ACLs containing the matchingpermission for that user are selected during the search.

4. After adding the stanza and the appropriate mapping entries, WebSEAL(webseald) must be re-started.

Personalization service examplev Create a junction to the portal server:

pdadmin> server task webseald-WS1 -t ssl -h PORTAL1 /portal

v Define the region of the WebSEAL protected object space that contains resourcesavailable to the personalization service:pdadmin> objectspace create /Resources “Portal Object Hierarchy” 10pdadmin> object create /Resources/Content ““ 10 ispolicyattachable yespdadmin> object create /Resources/Support ““ 10 ispolicyattachable yespdadmin> object create /Resources/Content/CGI ““ 11 ispolicyattachable yespdadmin> object create /Resources/Support/Servlet ““ 11 ispolicyattachable yes

Note: The “ispolicyattachable” argument must be set to “yes” for each resource.The search mechanism selects only qualified resource objects withexplicitly set ACLs.

v WebSEAL configuration (webseald.conf):[portal-map]/portal/servlet/PortalServlet = /Resources:r

v Portal URL used by the user:https://WS1/portal/servlet/PortalServlet

Enabling dynamic business entitlements (tag/value)Business enterprises and their partners often have the need to share commonentitlements such as partner data (in a business-to-business relationship) orcustomer data (in a business-to-customer relationship).v Generic entitlements are attributes describing information required by

service-providing applications. Examples of such attributes include customeraccount information and customer billing data.

v Security entitlements are attributes that provide fine-grained conditions used inthe authorizing of requests for resources. Examples of such conditions includeuser business roles, access control restrictions, and business rules that define atrading partner agreement.

Through an extension of the Cross Domain Authentication Service (CDAS), TivoliAccess Manager provides a flexible mechanism that allows you to includeentitlement information in user credentials at the point of authentication.Applications can extract this data from the credential directly using theauthorization API. For further information on implementing this CDAS extension,refer to the IBM Tivoli Access Manager WebSEAL Developer’s Reference.

Creating business entitlements from LDAP dataWebSEAL provides a specific built-in entitlement mechanism that allows you toinsert user-defined supplemental LDAP information into a user credential asextended attribute data. The values of these credential extended attributes can thenbe placed in the HTTP header of a request sent to a back-end junctionedapplication server.


The following process flow describes the sequence of events:1. User-defined supplemental data from any field of a user’s LDAP registry

account is added as extended attribute data in the user’s Tivoli Access Managercredential.

2. WebSEAL junction is configured to extract this data from the credential andplace it in an HTTP header of the request that goes to the back-end server.

3. The back-end application can extract the data from the header withoutrequiring special code or the authorization API.

WebSEAL configuration for inserting supplemental LDAP information into anHTTP header involves two steps:1. Retrieve supplemental data from the LDAP registry and insert this data in the

user credential at login.2. Based on an extended attribute set on the junction (HTTP-Tag-Value), extract

the appropriate data from the credential and insert it in an HTTP header of therequest that is sent across the junction.

Inserting supplemental LDAP data into a credentialThere are two methods of placing supplemental LDAP user data in a credential:v Create entries in the [ldap-ext-cred-tags] stanza of the pd.conf configuration file

that map specific LDAP data to extended attributes in the credential.This method is described in the remainder of this section.

v Write a custom CDAS module that maps any user-defined data to extendedattributes in the credential.Refer to the IBM Tivoli Access Manager WebSEAL Developer’s Reference forinformation on implementing this CDAS extension.

You can use the [ldap-ext-cred-tags] stanza of the pd.conf configuration file tomap specific data from the LDAP inetOrgPerson object class to a user-definedextended attribute in the user credential. The parameters in this stanza have thefollowing format:<cred-ext-attr-name> = <inetOrgPerson-name>

In the credential itself, each cred-ext-attr-name entry defined in the pd.confconfiguration file is prefixed with the phrase “tagvalue_”. This prefix prevents anyconflicts with other existing information in the credential. For example:

Name and value frominetOrgPerson object class:

employeeNumber:09876

The credential extended attribute name: ldap-employee-number

Associating the attribute name withthe LDAP data name in the pd.conf[ldap-ext-cred-tags] stanza:

[ldap-ext-cred-tags]ldap-employee-number = employeeNumber

Attribute name and value as theyappear in the user credential:

tagvalue_ldap-employee-number:09876

Conditions affecting LDAP extended attributes in credentialsv LDAP data can come from a standard or custom field in the inetOrgPerson

object class.v You can place multiple attribute entries in the [ldap-ext-cred-tags] stanza.v All extended attributes specified in the [ldap-ext-cred-tags] stanza are placed in

the credential upon a successful user login.


v LDAP data names are not case-sensitive.v Credential extended attribute names are case-sensitive.v The method of inserting extended attributes into a user credential using the

[ldap-ext-cred-tags] stanza does not provide handling and encoding of specialcharacters, including the double-byte character set (DBCS). A custom CDAS canbe used to encode extended attributes that use DBCS and to insert them into thecredential. Additionally, if these attributes are sent across a junction as HTTPheaders, the back-end application must be able to handle the encoded specialcharacters.

Authentication libraries supporting tag/valueTo support business entitlements using the tag/value mechanism, the sharedlibrary for a specific authentication method must recognize and handle credentialextended attributes when building the user credential. The shared libraries for thefollowing built-in authentication methods support business entitlements byhandling extended attributes in credentials:v user name and password (LDAP)v client-side certificatev token passcode

Tag/value support during user name and password authentication:

When the passwd-ldap authentication mechanism is enabled, the user mustauthenticate using an LDAP user name and password. The libldapauthn(ldapauthn) shared library that builds the user credential is coded to look in the[ldap-ext-cred-tags] stanza of the pd.conf configuration file for supplementaluser-defined information that is then added to the credential as an extendedattribute.

Tag/value support during certificate authentication:

When the cert-ssl authentication mechanism is enabled, the user must authenticateusing a client-side certificate. The libsslauthn (sslauthn) shared library that buildsthe user credential is coded to look in the [ldap-ext-cred-tags] stanza of thepd.conf configuration file for supplemental user-defined information that is thenadded to the credential as an extended attribute.

Tag/value support during token authentication:

When the token-auth authentication mechanism is enabled, the user mustauthenticate using a token passcode. The libxtokenauthn (xtokenauthn) sharedlibrary that builds the user credential is coded to look in the [ldap-ext-cred-tags]stanza of the pd.conf configuration file for supplemental user-defined informationthat is then added to the credential as an extended attribute.

Inserting credential data into the HTTP headerThe user-defined credential information created in the previous section can beplaced in an HTTP header of the request that is sent across a junction to aback-end server.

You must configure the junction to extract extended attribute data from thecredential and insert the data into the HTTP header of the request. Thisfunctionality is achieved by setting a junction extended attribute, calledHTTP-Tag-Value, on the junction object in the WebSEAL protected object space.


You use the pdadmin object modify set attribute command to set extendedattributes on a junction object in the WebSEAL protected object space.pdadmin> object modify <obj-name> set attribute <attr-name> <attr-value>

An extended attribute (″attr-name″) enables the junction to perform a specific typeof functionality. The HTTP-Tag-Value extended attribute instructs the junction toextract a particular value from a user’s credential and send the value to theback-end server in an HTTP header. The value of the HTTP-Tag-Value extendedattribute uses the following format:<cred-ext-attr-name>=<http-header-name>

The cred-ext-attr-name entry appears exactly as it does in the [ldap-ext-cred-tags]stanza of the pd.conf configuration file. The ″tagvalue_″ prefix, that appears in thecredential, is not used. The entry is case-sensitive. The http-header-name entryspecifies the name of the HTTP header used to deliver the data across the junction.

For example:pdadmin> object modify /WebSEAL/WS1/junctionA set attribute \HTTP-Tag-Value ldap-employee-number=employee-id

When WebSEAL processes a user request to a back-end application server, it looksfor any HTTP-Tag-Value attributes configured on the junction object.

In this example, the configured junction looks at the credential of the user makingthe request, extracts the value of the tagvalue_ldap-employee-number credentialextended attribute, and places it in an HTTP header as:employee-id:09876

In summary:

Value of HTTP-Tag-Value attributeset on the junction object:

ldap-employee-number=employee-id


tagvalue_ldap-employee-number:09876

HTTP header name and value: employee-id:09876

If the back-end application is a CGI application, the CGI specification dictates thatHTTP headers are made available to CGI programs as environment variables in theform:HTTP_<http-header-name>

For example:HTTP_employee-id=09876

Multiple user attribute data can be passed to the junctioned server in HTTPheaders by using multiple pdadmin object modify set attribute commands tospecify multiple HTTP-Tag-Value junction attributes (one attribute is specified percommand).


Maintaining session state between client and back-end applicationsWebSEAL can maintain session state with clients over HTTP and HTTPS.Additionally, you can configure WebSEAL to provide user session information toback-end junctioned application servers. With this user session information,back-end applications can maintain session state with clients.

Background to user session managementA secure connection, or session, between a client and a server requires that theserver have the ability to remember—over numerous requests—who it is talking to.The server must have some form of session state information that identifies theclient associated with each request.

Without an established session state between client and server, the communicationbetween the client and the server must be renegotiated for each subsequentrequest. Session state information improves performance by eliminating repeatedclosing and re-opening of client/server connections. The client can log in once andmake numerous requests without performing a separate login for each request.

WebSEAL maintains session state information through the GSKit SSL session IDcache and the WebSEAL session/credentials cache. The GSKit session cachesupports HTTPS (SSL) communication when the SSL session ID is used to maintainsession state. The WebSEAL credentials cache stores a WebSEAL session ID foreach client plus any credential information specific to each client.

You can configure WebSEAL to store a unique User Session ID for eachauthenticating client as an extended attribute in the credential of each client. Usingextended attributes for Tivoli Access Manager objects, you can configure a junctionto provide this User Session ID information to the back-end server. An applicationon this back-end server can take advantage of the user session information tomanage the client-server interaction, such as tracking the activity of users.

Enabling user session id managementThe user-session-ids parameter in the [session] stanza of the webseald.confconfiguration file allows you to enable and disable the creation of a unique UserSession ID in the credential of each client making a request. The default value is“yes” (enabled):[session]user-session-ids = yes

To disable the creation of unique User Session IDs, set user-session-ids = no.

The unique User Session ID is stored in a user’s credential as an extended attributewith a name and value:tagvalue_user_session_id = <user-session-id>

In the credential itself, the credential extended attribute name (user_session_id)appears with a “tagvalue_” prefix to prevent any conflicts with other existinginformation in the credential.

The value of the User Session ID is a string that uniquely identifies a specificsession for an authenticated user. The User Session ID is a MIME-64 encodedstring that includes the WebSEAL instance name (to support multiple WebSEALinstances) and the standard WebSEAL session ID for the user.


A single user that logs in multiple times (for example, from different machines) hasmultiple WebSEAL session IDs. Because the User Session ID is based on theWebSEAL session ID, there exists a one-to-one mapping between them. The uniqueuser session ID is stored as an attribute to the user’s credential. This allows thevalue to be passed across a junction as an HTTP header (using tag-valuefunctionality) and made available to a back-end application.

Inserting credential data into the HTTP headerThe goal of user session management is to provide the unique User Session ID tothe back-end application server. This goal is accomplished by configuring theHTTP-Tag-Value extended attribute on the junction.

You use the pdadmin object modify set attribute command to set an extendedattribute on a junction object in the WebSEAL protected object space.pdadmin> object modify <obj-name> set attribute <attr-name> <attr-value>

An attribute (“attr-name”) enables the junction to perform a specific type offunctionality. The HTTP-Tag-Value attribute enables the junction to extract a valuefrom a credential extended attribute and send the value to the back-end server inan HTTP header.

The value of the HTTP-Tag-Value extended attribute uses the following format:<cred-ext-attr-name>=<http-header-name>

For User Session ID data, the cred-ext-attr-name entry is the user_session_idextended attribute name in the user’s credential. The “tagvalue_” prefix, thatappears only in the credential, is not used. The entry is case-sensitive. The value ofthis extended attribute contains the unique User Session ID.

The http-header-name entry specifies the name of the HTTP header used to deliverthe data across the junction. In this example, a header called PD-USER-SESSION-ID is used:pdadmin> object modify /WebSEAL/WS1/junctionA set attribute \HTTP-Tag-Value user_session_id=PD-USER-SESSION-ID

When WebSEAL processes a user request to a back-end application server, it looksfor any HTTP-Tag-Value extended attributes configured on the junction object.

In this example, the configured junction looks at the credential of the user makingthe request, extracts the User Session ID value from the tagvalue_user_session_idextended attribute in the credential, and places the value in an HTTP header as:PD-USER-SESSION-ID:<user-session-id>

In summary:

Value of HTTP-Tag-Value attributeset on the junction object:

user_session_id=PD-USER-SESSION-ID


tagvalue_user_session_id:<user-session-id>

HTTP header name and value: PD-USER-SESSION-ID:<user-session-id>

If the back-end application is a CGI application, the CGI specification dictates thatHTTP headers are made available to CGI programs as environment variables in theform:


HTTP_<HTTP-header-name>

For example:HTTP_PD-USER-SESSION-ID=<user-session-id>

For more information about tag/value functionality, see “Enabling dynamicbusiness entitlements (tag/value)” on page 224.

Terminating user sessionsA user can initiate the termination of the current session through the pkmslogoutcommand. Additionally, the information in the User Session ID allowsadministrators and back-end applications to track and manage users. This sectiondescribes two methods of terminating the user session at an administration level:v “Using Administration API to terminate single user sessions” on page 230v “Using pdadmin to terminate all user sessions” on page 230

Using Administration API to terminate single user sessionsA back-end application can use the Tivoli Access Manager administration API toterminate a specific user session based on the User Session ID passed across thejunction. The application invokes the ivadmin_server_performtask() functioninside its terminate code. The WebSEAL server instance and the User Session IDare included as parameters to this function.

WebSEAL verifies that the back-end server initiating the terminate operation hasappropriate permissions before terminating the user session.

It is important to consider the conditions under which this command might beused. If the intent is to make sure a user is removed from the secure domainentirely, the termination of a single user is only effective when, in addition, theaccount for that user is made invalid (removed). Certain authenticationmethods—such as Basic Authentication, client-side certificate, and failovercookies—return cached authentication information automatically with no userintervention. The termination action would not prevent return logins for a userusing any of those authentication methods. You must additionally invalidate theappropriate user account in the registry.

Refer to the IBM Tivoli Access Manager Administration C API Developer’s Reference forfurther information.

Using pdadmin to terminate all user sessionsAn administrator can use the pdadmin utility to terminate all sessions for aspecified user based on the user ID.pdadmin> server task webseald-<instance-name> terminate all_sessions <user-id>

The WebSEAL credentials cache is organized to cross-reference user ID, WebSEALsession ID, and cache entry information. A user always has a unique user ID acrossmultiple sessions. Each WebSEAL session ID, however, is unique. The terminateall_sessions command removes all cache entries belonging to the user-id.


WebSEAL checks for appropriate permissions for the administrator initiating thecommand before terminating user sessions.

It is important to consider the conditions under which this command might beused. If the intent is to make sure a certain group of users are removed from thesecure domain entirely, the terminate all_sessions command is only effectivewhen, in addition, the accounts for those users are made invalid (removed).Certain authentication methods—such as Basic Authentication, client-sidecertificate, and failover cookies—return cached authentication informationautomatically with no user intervention. The terminate all_sessions commandwould not prevent return logins for users using any of those authenticationmethods. You must additionally invalidate the appropriate user accounts in theregistry.

Providing access control to dynamic URLsThe current Web environment gives users immediate access to rapidly changinginformation. Many Web applications dynamically generate Uniform ResourceLocators (URLs) in response to each user request. These dynamic URLs may existonly for a short time. Despite their temporary nature, dynamic URLs still needstrong protection from unwanted use or access.

Dynamic URL componentsSome sophisticated Web application tools use standard Web browsers tocommunicate with application servers through the CGI interface of a Web server.

All these tools use dynamic URLs and hidden form elements to communicate therequested operation (with its parameter value) to the application server. A dynamicURL augments the standard URL address with information about the specific

User ID Session ID Cache Data

userA 1234credential plus

user_session_idattribute

userB 5678credential plus


userA 1369credential plus


terminate all_sessions userA

WebSEAL Credentials Cache

Figure 38. Terminate all userA sessions


operation and its parameter values. The query string portion of the URL providesoperations, parameters, and values to the Web application interface.

Mapping ACL and POP objects to dynamic URLsWebSEAL uses the protected object space model, access control lists (ACL), andprotected object policies (POP) to secure dynamically generated URLs, such asthose generated by database requests. Each request to WebSEAL is resolved to aspecific object as the first step in the authorization process. An ACL/POP appliedto the object dictates the required protection on any dynamic URL mapped to thatobject.

Because dynamic URLs exist only temporarily, it is not possible to have entries forthem in a pre-configured authorization policy database. Tivoli Access Managersolves this problem by providing a mechanism where many dynamic URLs can bemapped to a single static protected object.

Mappings from objects to patterns are kept in a plain text file:/opt/pdweb/www/lib/dynurl.conf

The location of this file (relative to the server-root) is defined by the dynurl-mapparameter in the [server] stanza of the webseald.conf configuration file:[server]dynurl-map = lib/dynurl.conf

You must create this file; the file does not exist by default. The existence of this file(with entries) enables the dynamic URL capability.

Edit this file to modify these mappings. Entries in the file are of the format:<object> <template>

Tivoli Access Manager uses a subset of UNIX shell pattern matching (includingwildcards) to define the set of parameters that constitute one object in the objectspace. Any dynamic URL that matches those parameters is mapped to that object.

Tivoli Access Manager supports the following UNIX shell pattern-matchingcharacters:

Character Description

\ The character that follows the backslash is part of a special sequence.For example, \t is the TAB character. Can also act as an escapecharacter.

http://www.ibm.com/sales/web/fortecgi.cgi?name=catalog&product=shirt&color=red

Protocol WebServer

Directory Pathto CGI Program

Operation, Parameters,and Values for WebApplication Interface

CGIProgram

File

Base URL Query String

Figure 39. Passing data to a CGI gateway using a URL


Character Description

? Wildcard that matches a single character. For example, the string“abcde” is matched by the expression “ab?de”

* Wildcard that matches zero or more characters.

[] Defines a set of characters, from which any can match. For example,the string “abcde” is matched with the regular expression“ab[cty]de”.

^ Indicates a negation. For example, the expression [^ab] matchesanything but the ‘a’ or ‘b’ characters.

The following example illustrates the form of a dynamic URL that performs creditbalance lookup:http://<server-name>/home-bank/owa/acct.bal?acc=<account-number>

The object that represents this dynamic URL would appear as follows:http://<server-name>/home-bank/owa/acct.bal?acc=*

Careful examination of the dynamic URL in this example shows that it describes aspecific account number. The object for account balances at home-bank shows thatthe ACL and POP permissions apply to any account, because the last portion of theentry (acc=*) uses the asterisk wildcard which matches all characters.

The following figure illustrates a complete scenario of a specific dynamic URLmapped to a specific protected object:

Updating WebSEAL for dynamic URLsUse the dynurl update command to update the WebSEAL protected object spacewith entries made in the dynurl.conf configuration file.1. Create, edit, or delete a dynamic URL entry in the dynurl.conf configuration

file.2. After making your changes, use the dynurl update command to update the

server:

http://www.ibm.com/sales/web/db.cgi?service=SoftWear&catalog=clothing&product=shirt&color=red

www.ibm.com/

db.cgi

web/

sales/

redshirt

Dynamic URL entries:

Protected Object Namespace

"*product=shirt*color=red*"

Match query string with the Webnamespace entry "redshirt"

...group admin -abc---T-m----lrxgroup ABC_company -abc---T-m----lrxany_authenticated --------------unauthenticated --------------...

ACL associated with object:"www.ibm.com/sales/web/fortecgi.cgi/redshirt"

Figure 40. Authorization on a dynamic URL


pdadmin> server task webseald-<server-name> dynurl update

The server-name argument represents the unqualified host name of theWebSEAL machine.

Resolving dynamic URLs in the object spaceThe resolving of a dynamic URL to an object is dependent upon the ordering ofthe entries in the dynurl.conf configuration file.

When attempting to map a dynamic URL to an object entry, the list of mappings inthe dynurl.conf file is scanned from top to bottom until the first matching patternis found. When the first match is found, the corresponding object entry is used forthe subsequent authorization check.

If no matches are found, WebSEAL uses the URL itself, minus the http://<server>portion of the path.

Keep the mappings that correspond to the most restrictive ACLs higher up in thelist. For example, if the book.sales procedure of a sales order application is to berestricted to just a book club group, but the rest of the sales order application canbe accessed by all users, then the mappings should be in the order shown in thefollowing table:

Object Space Entry URL Template

/ows/sales/bksale /ows/db-apps/owa/book.sales*

/ows/sales/general /ows/db-apps/owa/*

Note that if the mapping entries were in the reverse order, all stored procedures inthe /ows/db-apps/owa directory would map to the /ows/sales/general object. Thiscould lead to possible breaches of security, due to this incorrect object spaceresolution.

When you map a URL regular expression to an object space entry, the URL formatshould take on the format as produced from the GET method — regardless ofwhether the POST or GET method is being used.

In the GET method of data transmission, the dynamic data (such as the datasupplied by a user in a form) is appended to the URL.

In the POST method of data transmission, the dynamic data is included in thebody of the request.

ACL and POP EvaluationAs soon as the dynamic URL has been resolved to an object space entry, thestandard ACL/POP inheritance model is used to determine if the request shouldbe processed or forbidden (due to insufficient privilege).

Configuring limitations on POST requestsThe content of a POST request is contained in the body of the request. In addition,a POST request contains the browser-determined length of this content and liststhe value in bytes.

request-body-max-read


The request-body-max-read parameter in the [server] stanza of the webseald.confconfiguration file limits the impact of large POST requests on WebSEAL byspecifying the maximum number of bytes to read in as content from the body ofPOST requests. The content read in by WebSEAL is subject to authorization checks,as described earlier in this section.

The request-body-max-read parameter value is considered when the POST requestis used for dynamic URL processing or Forms authentication. The default value is4096 bytes:[server]request-body-max-read = 4096

Note that this parameter does not limit the maximum POST content size (which isunlimited). The parameter protects WebSEAL from processing a POST request ofunreasonable size.

dynurl-allow-large-posts

Although the request-body-max-read parameter limits the amount of POSTcontent read and processed by WebSEAL, it does not prevent the request, in itsentirety, from being passed through to the application server. In this scenario,non-validated content is passed through to the application server. If the applicationserver does not have its own authorization capabilities, the situation might resultin a security risk.

The dynurl-allow-large-posts parameter allows you to control the way WebSEALhandles POST requests that have a content length larger than that specified byrequest-body-max-read. If the parameter value is set to “no” (default), WebSEALrejects, in total, any POST request with a content length larger than that specifiedby request-body-max-read.[server]dynurl-allow-large-posts = no

If the parameter value is set to “yes”, WebSEAL accepts the entire POST request,but only validates the amount of content equal to the request-body-max-readvalue.[server]dynurl-allow-large-posts = yes

Example 1:

v A large POST request is received (greater than the request-body-max-readvalue).

v dynurl-allow-large-posts = no

v Dynamic URLs are enabled.v Result: 500 “Server Error”

Example 2:

v A large POST request is received (greater than the post-request-body-max-read).v dynurl-allow-large-posts = yes

v Dynamic URLs are enabled.v Result: WebSEAL compares the amount of content up to request-body-max-read

with each of the regular expressions in the dynurl.conf configuration file, andperforms an authorization check on the corresponding object if a match is found.


Otherwise, the authorization check is performed on the object corresponding tothe URL received, as usual. The portion of the request body pastrequest-body-max-read is not validated.

v The following template contains the type of pattern matching arrangement thatinvites misuse by a large POST request:/rtpi153/webapp/examples/HitCount\?*action=reset*

Summary and technical notesSummary:

v To configure WebSEAL to securely handle dynamic URLs, create the followingfile:/opt/pdweb/www/lib/dynurl.conf

v The file must contain one or more lines of the format:<object> <template>

v If the file does not exist, or is empty, dynamic URL capability is not enabled.v After the file has been processed, the object name appears as a child resource in

the WebSEAL object space.v The template can contain a subset of the standard pattern matching characters.

The template can also be an exact string with no pattern matching characters.

The following sample dynurl.conf file defines three objects representing some ofthe sample Web applications that are part of the IBM WebSphere product:

Object Entry URL Template

/app_showconfig /rtpi153/webapp/examples/ShowConfig*

/app_snoop /rtpi153/servlet/snoop

/app_snoop /rtpi025/servlet/snoop

/app_hitcount/ejb /rtpi153/webapp/examples/HitCount\?source=EJB

/app_hitcount /rtpi153/webapp/examples/HitCount*

Technical Notes:

v Multiple URL templates can be mapped to the same object (for example,app_snoop maps to URLs on two different servers).

v Objects can be nested (for example, app_hitcount and app_hitcount/ejb).v An incoming URL request is compared against templates in order, from top to

bottom. When a match is found, processing stops. Therefore, place the morerestrictive templates at the top of the file.

v To activate the definitions in the dynurl.conf file, issue the dynurl updatecommand (use pdadmin server task).The update occurs immediately and the objects appear in the Web PortalManager when you refresh the protected object space view.

v Avoid uppercase characters in the object name. Use lowercase characters only.v Do not use an object name that already exists in the protected object space.v Before deleting an object in the dynurl.conf file, remove any ACLs attached to

the object.


Dynamic URL example: The Travel KingdomThe following example illustrates how a corporate intranet can secure URLsgenerated by an Oracle Web Listener.

The dynamic URL Web server used in this example is the Oracle Web Listener.This technology can be applied equally to other dynamic URL Web servers.

The applicationTravel Kingdom is an organization that offers clients a travel booking service overthe Internet. The business intends to operate two Oracle database applications onits Web server — accessible from within the corporate firewall and across theInternet.1. Travel Booking System

Authorized customers can make bookings remotely and query their owncurrent bookings. Travel Kingdom staff can also make bookings for telephonecustomers, process changes, and perform many other transactions. Becauseexternal customers pay for services with credit cards, the transmission of thatinformation must be strongly secured.

2. Administration Manager

Like most other companies, Travel Kingdom maintains an administrationdatabase containing salary, position, and experience information. This data isalso accompanied by a photograph of each member of the staff.

The interfaceAn Oracle Web Server is configured to provide access to the following storedprocedures in the database:

/db-apps/owa/tr.browse Gives all users the ability to inquire about traveldestinations, prices, and so on.

/db-apps/owa/tr.book Used to place a booking (travel agent staff orauthenticated customers).

/db-apps/owa/tr.change Used to review or change current bookings.

/db-apps/owa/admin.browse Used by any staff member to view unrestricted staffinformation, such as extension number, emailaddress, and photograph.

/db-apps/owa/admin.resume Gives staff members the ability to view or changetheir own resume information in the Administrationdatabase.

/db-apps/owa/admin.update Used by Administration staff to update informationon staff.

Web space structureA WebSEAL server is used to provide a secure interface to the unified Web spaceof Travel Kingdom.v A junction (/ows) is made to the Oracle Web Server running both the travel

booking application and the administration application.


The security policyTo provide suitable security to Web resources, while retaining an easy-to-usesystem, the business has established the following security goals:v Travel agent staff have complete control over all bookings.v Authenticated customers can make and change their own bookings, but cannot

interfere with the travel data of other authenticated customers.v Administration staff have complete access to all of the administration

information.v Travel Kingdom staff other than the Administration department can change their

own resume information and view partial information of other members of staff.

Dynamic URL to object space mappingsTo achieve the security goals described above, the mappings from dynamic URLsto ACL object entries need to be configured as shown in the following table.

Remember that the ordering of these mappings is an important part of achievingthe security goals discussed earlier.

Object Space Entry URL Pattern

/ows/tr/browse /ows/db-apps/owa/tr.browse\?dest=*&date=??/??/????

/ows/tr/auth /ows/db-apps/owa/tr.book\?dest=*&depart=??/??/????& return=??/??/????

/ows/tr/auth /ows/db-apps/owa/tr.change

/ows/admin/forall /ows/db-apps/owa/admin.resume

/ows/admin/forall /ows/db-apps/owa/admin.browse\?empid=[th]???

/ows/admin/auth /ows/db-apps/owa/admin.update\?empid=????

Secure clientsClient authenticate to WebSEAL over a secure, encrypted channel.

Customers who wish to use the Web interface must additionally register with theTravel Kingdom Webmaster to receive an account.

Account and group structureFour groups are created on the system:

Staff Members of the Travel Kingdom organization.

TKStaff Travel Kingdom travel agents.

AdminStaff Members of the Travel Kingdom Administration Department. Notethat Administration staff members are also in the Staff group.

Customer Customers of Travel Kingdom who want to make their travelbookings across the Internet.

Each user is given an account in the secure domain to be individually identified bythe WebSEAL server. The user’s identity is also passed to the Oracle Web Serversto provide a single sign-on solution to all of the Web resources.

Access controlThe following table lists the access controls resulting from application of thepreceding information:


/ows/tr/browse unauthenticated Trany_authenticated Tr

/ows/tr/auth unauthenticated -any_authenticated -group TKStaff Trgroup Customer PTr

/ows/admin/forall unauthenticated -any_authenticated -group Staff Tr

/ows/admin/auth unauthenticated -any_authenticated -group AdminStaff Tr

Customers and TKStaff have the same privileges on the booking and travel planmaintenance objects, except that the customers must encrypt information (privacypermission) to give them further security when submitting sensitive data (such ascredit card information) across the untrusted Internet.

ConclusionThis simple example illustrates the concepts of deploying a system capable of:v Securing sensitive informationv Authenticating usersv Authorizing access to sensitive information

In addition, the identities of the authenticated users of the system are known toboth the WebSEAL and Oracle Web Servers, and are used to provide an auditable,single sign-on solution.


Appendix A. WebSEAL configuration file reference

The operation of the WebSEAL server is controlled through the use of theWebSEAL configuration file, webseald.conf. The file contains sections that controlspecific portions of WebSEAL functionality. Each section contains further divisionscalled stanzas.

Stanza labels appear within brackets, such as: [stanza_name]. For example, the[ssl] stanza defines the SSL configuration settings for use by the WebSEAL server.

Each stanza in a Tivoli Access Manager configuration file contains one or morestanza entries. A stanza entry consists of a key value pair, which contain informationthat is expressed as a paired set of parameters. Each stanza entry has the followingformat:

key = value

The initial installation of WebSEAL establishes many of the default values. Somevalues are static and will never change; other values can be modified to customizeserver functionality and performance.

Guidelines for configuring stanzasThese guidelines are provided to help you make changes to the Tivoli AccessManager configuration files. The guidelines are divided into these types:v Generalv Default settingsv Stringsv Defined stringsv Listsv File namesv Integersv Boolean values

For instructions, see “Change configuration settings” on page 244.

General guidelinesUse the following general guidelines when making changes to the configurationsettings:v There is no order dependency or location dependency for stanzas in any

configuration file.v Stanza entries are marked as required or optional. When an entry is required,

WebSEAL requires that the entry contain a valid key and value.v Do not change the names of the keys in the configuration files. Changing the

key might cause unpredictable results for the servers.

Note: WebSEAL supports some stanza entries that do not rely upon defined keynames. See “Lists” on page 242.


v Capitalization of the keys is not important. For example, you can use UseSSL orusessl.

v Spaces are not allowed for names of keys.v For the key value pair format of key = value, the spaces surrounding the equal

sign (=) are not required but they are recommended.v WebSEAL ignores nonprintable characters (such as tabs, carriage returns, and

line feeds) that occur at the end of a stanza entry. Nonprintable characters areASCII characters with a decimal value less than 32.

Default valuesv Many values are created or modified only by using configuration programs. You

should not manually edit these stanzas or values.v Some values are filled in automatically during WebSEAL configuration. These

values are needed for the initialization of the server after the configuration.v The default values for a stanza entry might be different, depending on the server

configuration. Some stanza entries are not applicable to certain configurationsand are omitted from the default configuration file for this server.

StringsSome values accept a string value. When you manually edit the configuration file,use the following guidelines to change configuration settings that require a string:v String values are expected to be characters that are part of the local codeset.v Some WebSEAL strings impose additional or different restrictions on the set of

allowable string characters. For example, many strings are restricted to ASCIIcharacters. The restrictions applicable to each string are listed under theappropriate stanza entry discussion later in this chapter. Consult each stanzaentry description for any additional restrictions.

v Double quotation marks are sometimes, but not always, required if spaces ormore than one word are used for values. Refer to the descriptions or examplesfor each stanza entry when in doubt.

v The minimum and maximum lengths of user registry-related string values, ifthere are limits, are imposed by the underlying registry. For example, for ActiveDirectory the maximum length is 256 alphanumeric characters.

Defined stringsSome values accept a string value, but the value must be one of a set of definedstrings. When you manually edit the configuration file, make sure that the stringvalue you type matches one of the valid defined strings values.

For example, the [ba] stanza in the authentication mechanisms section contains thefollowing entry:ba-auth = { none | http | https | both }

WebSEAL expects the value of ba-auth to be either none or http or https or both.Any other value is invalid and will result in an error.

ListsThe WebSEAL configuration file contains some stanzas that use stanza entries thatdo not have defined key names. The contents of these stanzas are called lists. Lists


are configurable, and are specified by the administrator. Some lists are included bydefault and can be appended by the administrator. Other lists are empty be defaultand can be created by the administrator.

Lists are used by WebSEAL for a number of purposes. WebSEAL filters incomingdata based on document type, event handler type, MIME type, and header requestdata. WebSEAL also uses lists for content management in a number of areas,including tracking CGI types, compiling lists of icons for indexing, defining andsizing content caches, defining MIME types, and listing content encodings.

Examples of stanzas that use lists are [filter-url], [filter-events], and[content-mime-types]. There are additional stanzas that support lists. Consult thestanza descriptions in this chapter for complete information.

File namesSome values are file names. For each stanza entry that expects a file name as avalue, the description of the stanza entry specifies which of the followingconstructs are valid:v File name

No directory path included.v Relative file name

A directory path is allowed, but not mandatory.These files typically are expected to be relative to the location of a standardWebSEAL directory, such as the WebSEAL server-root or the document root,doc-root. The stanza entry for each relative lists the root directory to which thefile name is relative.

v Fully qualified ( absolute) pathAn absolute directory path is required.

Note: Some stanza entries allow more than one of the above choices.

The set of characters permitted in a file name is determined by the file system andby the local codeset. WebSEAL does not impose additional limitations on the set ofallowable characters in a file name. For Windows, file names cannot have thesecharacters: a backslash (\), a colon (:), a question mark (?), or double quotationmarks (″).

IntegersMany stanza entries expect the value for the entry to be expressed as an integer.v Stanza entries that take an integer value expect integer values within a valid

range. The range is described in terms of a minimum value and a maximumvalue.For example, in the [logging] stanza, the logflush stanza entry has a minimumvalue of 1 second and a maximum value of 600 seconds.

v For some entries, the integer value must be positive, and the minimum value is1. For other entries, a minimum integer value of 0 is allowed.Use caution when setting an integer value to 0. For some entries, an integervalue of 0 disables the feature controlled by the stanza entry. For example, in the[junction] stanza, the entry max-webseal-header-size limits the maximum size,in bytes, of HTTP headers generated by the WebSEAL server. A value of zero (0)disables this support for limiting header size.

Appendix A. WebSEAL configuration file reference 243

v For some entries requiring integer values, WebSEAL does not impose an upperlimit on the maximum number allowed. For example, there is typically nomaximum for timeout-related values, such as client-connect-timeout in the[server] stanza.For this type of entry, the maximum number is limited only by the size ofmemory allocated for an integer data type. This number can vary based onoperating system type. For systems that allocate 4 bytes for an integer, this valueis 2147483647.However, an administrator should not set integer values to the maximum size ofallocated memory. Instead, administrators should determine logical values foreach setting based on the feature that is being configured.

Boolean valuesMany stanza entries represent a boolean value. WebSEAL recognizes the booleanvalues yes and no.

Some of the entries in webseald.conf are read by other servers and utilities. Forexample, many entries in the [ldap] stanza are read by the LDAP client. Some ofthese other programs recognize additional boolean characters:v yes or true

v no or false

The recognized boolean entries are listed for each stanza entry. Refer to theindividual descriptions to determine when other values, such as true or false, arealso recognized.

Change configuration settingsTo change a configuration setting, do the following:1. Make a backup copy of the configuration file you plan to modify.

This allows you to return the configuration file to a known working state,should you encounter an error later.

2. Stop the WebSEAL server.3. Make the changes by using an ASCII text editor to edit the configuration file

(webseald.conf) . Save your changes.4. Restart the WebSEAL server.


Stanza organizationThis remainder of this appendix contains the following sections and stanzas:

Section Stanzas

“Server configuration” on page 247 [server]

“User registry” on page 252

“LDAP” on page 252 [ldap]

“Active Directory” on page 258 [uraf-ad]

“IBM Lotus Domino” on page 261 [uraf-domino]

“Secure Socket Layer” on page 264 [ssl]

“Authentication” on page 271

“Authentication mechanisms” on page 272 [ba][forms][token][certificate][http-headers][auth-headers][ipaddr][authentication-levels][mpa]

“Authentication libraries” on page 276 [authentication-mechanisms]

“Reauthentication” on page 280 [reauthentication]

“Authentication failover” on page 281 [failover][failover-attributes]

“Cross-domain single sign on” onpage 283

[cdsso][cdsso-peers]

“e-community single sign-on” on page 284 [e-community-sso][e-community-domain-keys]

“Quality of protection” on page 287 [ssl-qop][ssl-qop-mgmt-hosts][ssl-qop-mgmt-networks][ssl-qop-mgmt-default]

“Session” on page 289 [session]

“Content” on page 291


“Content management” on page 292 [content]

“Account management” on page 293 [acnt-mgt]

“Automatic redirect” on page 296 [content][enable-redirects]

“Local CGI” on page 297 [cgi][cgi-types][cgi-environment-variables]

“Icons” on page 299 [content-index-icons][icons]

“Content caching” on page 301 [content-cache]

“Content MIME types” on page 302 [content-mime-types]

“Content encodings” on page 303 [content-encodings]

“Junctions” on page 304

“Junction management” on page 305 [junction]

“Document filtering” on page 309 [filter-url]

“Event handler filtering” on page 310 [filter-events]

“Scheme filtering” on page 311 [filter-schemes]

“MIME types and header filtering” onpage 312

[filter-content-types][filter-request-headers]

“Script filtering” on page 313 [script-filtering][preserve-cookie-names]

“Global Sign-On cache” on page 315 [gso-cache]

“Lightweight Third Party Authenticationcache” on page 317

[ltpa-cache]

“Logging” on page 319 [logging]

“Auditing” on page 322 [aznapi-configuration]

“Policy database” on page 325 [aznapi-configuration]

“Entitlements services” on page 327 [aznapi-entitlements-services]

“Policy server” on page 328 [policy-director][manager]


Server configuration

[server] stanza

unix-user = user_name

UNIX user account for the WebSEAL server. This must be a valid UNIXuser name. It is possible for a UNIX user account and a UNIX group tohave the same name.

The validity of the user name specified depends on the requirements of theUNIX platform. Leading and trailing spaces are removed.

This stanza entry is required.

Default value: ivmgr

Example: unix-user = ivmgr

unix-group = group_name

UNIX group account for the WebSEAL server. This must be a valid UNIXgroup name. It is possible for a UNIX user account and a UNIX group tohave the same name.

The validity of the group name specified depends on the requirements ofthe UNIX platform. Leading and trailing spaces are removed.


Default value: ivmgr

Example: unix-group = ivmgr

unix-pid-file = fully_qualified_path

Location and name of a file into which WebSEAL will place its process ID(PID). Applies to UNIX and Windows systems. This value is setautomatically during WebSEAL configuration. Typically there is no need tochange this file name.


Example:

unix-pid-file = C:/Program Files/Tivoli/PDWeb//log/webseald.pid

server-root = fully_qualified_path

Root directory for the WebSEAL server. This value is set during WebSEALconfiguration.


The default value is operating-system specific:

v Windows

C:/Program Files/Tivoli/PDWeb//www

v UNIX

/opt/pdweb/www

Example: server-root = /opt/pdweb/www

server-name = WebSEAL_server_instance_name


The WebSEAL server instance name. When there is one WebSEAL serveron a host, this is typically the host name. When there is more than oneWebSEAL server on a host, this is a user-specified string.

This value is set by the administrator during WebSEAL configuration.WebSEAL instance names must be alphanumeric. The maximum number ofcharacters allowed is 20.


Default: The configuration defaults to the host name as specified inoperating system configuration files (for example, in the Windowsregistry). The administrator can optionally specify the fully qualifieddomain name.

When configuring the second or greater WebSEAL instance on a host, theconfiguration defaults to hostname-webinstance

Example first WebSEAL server, on a host named diamond:

server-name = diamond

Example multiple instance WebSEAL server, on a host named diamond:

server-name = diamond-web2


There is no default value.

Example: server-name = diamond

worker-threads = number_of_threads

Number of WebSEAL worker threads. The minimum allowed value is 1.The maximum number of threads is based on the number of filedescriptors set for WebSEAL at compile time. Note that this number variesper operating system. If the value is set to a number larger than theWebSEAL-determined limit, WebSEAL reduces the value to the acceptablelimit and issues a warning message.


Default: 50

Example:

worker-threads = 50

See also the IBM Tivoli Access Manager Performance Tuning Guide.

client-connect-timeout = number_of_seconds

Initial client connection timeout, in seconds. Must be a positive integer.Other values have unpredictable results and should not be used. Maximumallowed value: 2147483647.


Default value: 120

Example:

client-connect-timeout = 120

persistent-con-timeout = number_of_seconds


HTTP/1.1 connection timeout, in seconds. Must be a positive integer. Othervalues have unpredictable results and should not be used. Maximumallowed value: 2147483647.

This setting affects connections to clients, not to backend server systems.


Default value: 5

Example: persistent-con-timeout = 5

https = {yes|no}

Specifies whether HTTPS requests will be accepted by the WebSEAL server.This is a boolean value. Valid values are yes or no. This value is set by theadministrator during WebSEAL server configuration.



Example: https = yes

https-port = port_number

Port on which WebSEAL listens for HTTPS requests. This value is setduring WebSEAL configuration. When the port number is already in use,WebSEAL configuration uses the next available (unused) port number. Theadministrator can modify this number. Valid values include any portnumber not already in use on the host.


Default value: 443

Example: https-port = 443

http = {yes|no}

Specifies whether HTTP requests will be accepted by the WebSEAL server.Valid values are yes or no. This value is set by the administrator duringWebSEAL server configuration.



Example: http = yes

http-port = port_number

Port on which WebSEAL listens for HTTPS requests. This value is setduring WebSEAL configuration. When the port number is already in use,WebSEAL configuration uses the next available (unused) port number. Theadministrator can modify this number. Valid values include any portnumber not already in use on the host.


Default value: 80

Example: http-port = 80

request-body-max-read = number_of_bytes


Maximum number of bytes to read in as content from the body of POSTrequests. Used for dynurl, authentication, and request caching. Minimumnumber of bytes: 512. Maximum number of bytes: 32678..


Default value: 4096

Example: request-body-max-read = 4096

request-max-cache = number_of_bytes

Maximum amount of data to cache. This is used to cache request datawhen a user is prompted to authenticate before a request can be fulfilled.

This value should be a positive integer. If set to zero (0), the user loginsucceeds but the request fails because WebSEAL cannot cache the requestdata. There is no maximum value.


Default value: 8192

Example: request-max-cache = 8192

See also “Configuring server-side caching parameters” on page 84.

dynurl-map = relative_pathname

Location of the file that contains mappings for URLs to protected objects.The path is relative to the value of the server-root key in the [server]stanza.

The administrator can specify an alternate file name, and an alternatedirectory location. The file name can be any file name that is valid for theoperating system file system. On Windows systems, both backslashes (\)and forward slashes (/) are supported in the directory path.

This stanza entry is optional.

Default: None, but usually is configured to lib/dynurl.conf

Example: dynurl-map = lib/dynurl.conf

dynurl-allow-large-posts = {yes|no}

Allows or disallows POST requests larger than the current value for thestanza entry request-body-max-read in the [server] stanza.

When set to no, WebSEAL disallows POST requests with a body larger thanrequest-body-max-read. When set to yes, WebSEAL compares only up torequest-body-max-read bytes of POST request to the URL mappingscontained in dynurl configuration file (dynurl.conf).


Default value: no

Example: dynurl-allow-large-posts = no

utf8-url-support-enabled = {yes|no|auto}


Enable or disable support for UTF-8 encoded characters in URLs.

When set to auto, WebSEAL attempts to distinguish between UTF-8 andother forms of language character encoding, such as DBCS and Unicode.When encoding is not recognized as UTF-8, the coding is processed asDBCS or Unicode.


Default value: yes

Example: utf8-url-support-enabled = yes

double-byte-encoding = {yes|no}

Specifies whether WebSEAL will assume that encoded characters withinURLs are always encoded in Unicode, and do not contain UTF-8 encodedcharacters.


Default value: no

Example: double-byte-encoding = no

suppress-server-identity = {yes|no}

Suppresses the identity of the WebSEAL server from HTTP responses.These responses normally include the line:

Server: WebSEAL/version_number

Setting this value to yes deletes the above line from the server response.


Default value: no

Example: suppress-server-identity = no

pre-410–compatible-tokens = {yes|no}

WebSEAL supports a common method of generating tokens forcross-domain single sign-on, failover, and e-community single sign-on. Thesecurity of these tokens has been increased for Version 4.1. This increase isnot backwards compatible with previous versions of WebSEAL. When theTivoli Access Manager deployment includes multiple WebSEAL servers,and some of the WebSEAL servers are Version 3.9 or prior, set this value toyes.


Default value: no

Example: pre-410–compatible-tokens = no


User registryThis section contains the following topics and stanzas:

Section Stanzas

“LDAP” [ldap]

“Active Directory” on page 258 [uraf-ad]

“IBM Lotus Domino” on page 261 [uraf-domino]

LDAP

[ldap] stanza

ldap-server-config = fully_qualified_path

Location of the ldap.conf configuration file, represented as a fully qualified path.

The fully_qualified_path value must be an alphanumeric string.


Default value is based on the operating system type.

Example for UNIX: ldap-server-config = /opt/PolicyDirector/etc/ldap.conf

enabled = {yes|true|no|false}

Indicates whether or not LDAP is being used as the user registry.

Valid values are:yes|true

Enable LDAP user registry support.no|false

Disable LDAP user registry support. Anything other than yes|true,including a blank value, is interpreted as no|false,

This stanza entry is required when LDAP is the user registry.

The default value for a WebSEAL installation is determined from the configurationof the Tivoli Access Manager runtime. The Tivoli Access Manager runtimecomponent is a prerequisite for WebSEAL.

Example: enabled = yes

host = host_name


Host name of the LDAP server.

The WebSEAL configuration utility gets the host_name value from the pd.conf file.The pd.conf file is created when the Tivoli Access Manager runtime component isconfigured on the machine. The Tivoli Access Manager runtime component is aprerequisite for WebSEAL.

Valid values for host_name include any valid IP host name. The host_name does nothave to be a fully qualified domain name.


The default value is the value entered by the administrator during theconfiguration of the Tivoli Access Manager runtime component.

Examples:

host = surfhost = surf.santacruz.ibm.com

port = port_number

Number of the TCP/IP port used for communicating with the LDAP server. Notethat this is not for SSL communication.

A valid port number is any positive integer that is allowed by TCP/IP and that isnot currently being used by another application.

This stanza entry is required when LDAP is enabled.

Default value: 389.

Example: port = 389

bind-dn = LDAP_dn

LDAP user distinguished name (DN) that is used when binding (or signing on) tothe LDAP server. This is the name that represents the WebSEAL server daemon.


The default value is built by combining the daemon name webseald with thehost_name that was specified by the administrator during the configuration of theTivoli Access Manager runtime component.

Example: bind-dn = cn=webseald/surf,cn=SecurityDaemons,secAuthority=Default


bind-pwd = LDAP_password

Password for the LDAP user distinguished name declared in the bind-dn stanzaentry.


The default value of this stanza entry is set during WebSEAL configuration. TheWebSEAL configuration reads the LDAP_password that was specified by theadministrator during the configuration of the Tivoli Access Manager runtimecomponent. This value is read from the Tivoli Access Manager configuration file,pd.conf.

Example: bind-pwd = zs77WVoLSZn1rKrL

cache-enabled = {yes|true|no|false}


Enables or disable LDAP client-side caching. Caching is used to improveperformance for similar LDAP queries.


Enable LDAP client-side caching.no|false

Disable LDAP client-side caching.Anything other than yes|true, including a blank value, is interpreted as no|false.


Default value: disabled. When no value is specified (empty value), client-sidecaching is disabled.

Example: cache-enabled = yes


prefer-readwrite-server = {yes|true|no|false}

Allows or disallows the client to question the Read/Write LDAP server beforequerying any replica Read-only servers configured in the domain.


Enable the choice.no|false

Disable the choice.

Anything other than yes|true, including a blank value, is interpreted as no|false.


If this value is not specified, the prefer-readwrite-server option is disabled.

Example: prefer-readwrite-server = no

ssl-enabled = {yes|true|no|false}

Enables or disables SSL communication between WebSEAL and the LDAP server.


Enable SSL communication.no|false

Disable SSL communication.


SSL communication is disabled by default. During WebSEAL server configuration,the WebSEAL administrator can choose to enable it.

Example: ssl-enabled = yes

ssl-keyfile = fully_qualified_path


SSL key file name and location. The SSL key file handles certificates that are usedin LDAP communication.

The file name must be a fully qualified path. The file name can be any arbitrarychoice, but the extension is usually .kdb.

This stanza entry is required when SSL communication is enabled, as specified inthe ssl-enabled stanza entry. The WebSEAL administrator specifies this file nameduring WebSEAL configuration.

Example for UNIX:

ssl-keyfile = /var/pdweb/keytabs/webseald.kdb

Example for Windows:

ssl-keyfile = c:\keytabs\pd_ldapkey.kdb

For information on SSL keyfile management, see “Managing client-side andserver-side certificates” on page 38.

ssl-keyfile-label = keyLabel

String that specifies the key label of the client personal certificate within the SSLkey file. This key label is used to identify the client certificate that is presented tothe LDAP server.

This stanza entry is optional. A label is not required when one of the certificates inthe keyfile has been identified as the default certificate. The decision whether toidentify a certificate as the default was made previously by the LDAPadministrator when configuring the LDAP server. The WebSEAL configurationutility prompts the WebSEAL administrator to supply a label. When theadministrator knows that the certificate contained in the keyfile is the defaultcertificate, the administrator does not have to specify a label.

Example: ssl-keyfile-dn = "PD_LDAP"

ssl-keyfile-pwd = password

Password to access the SSL key file.

The password associated with the default SSL keyfile is gsk4ikm

Required only when SSL communication between WebSEAL and LDAP is enabled,as specified in the ssl-enabled stanza entry. The WebSEAL administrator specifiesthis password during WebSEAL configuration.

Example: ssl-keyfile-pwd = gsk4ikm

auth-using-compare = {yes|true|no|false}


Enables or disables authentication using password comparison. When disabled,authentication using LDAP bind is performed.

For those LDAP servers that allow it, a compare operation might perform fasterthan a bind operation.


A password compare operation is used to authenticate LDAP users.no|false

A bind operation is used to authenticate LDAP users.


The default value, when LDAP is enabled, is yes.

Example: auth-using-compare = yes


default-policy-override-support = {yes|true|no|false}

Indicates whether default policy overrides user level policy during LDAP searches.When this stanza entry is set to yes, only the default policy is checked.


User policy support is disabled and only the global (default) policy ischecked. This option allows the user policy to be ignored, even when it isspecified.

no|falseUser policy support is enabled. When a user policy is specified by theadministrator, it overrides the global policy.


By default, the value is not specified during WebSEAL configuration. When thevalue is not specified, the default behavior is enable user policy support. This isequivalent to setting this stanza entry to no.

Example: default-policy-override-support = yes


user-and-group-in-same-suffix = {yes|true|no|false}


Indicates whether the groups, in which a user is a member, are defined in the sameLDAP suffix as the user definition.

When a user is authenticated, the groups in which the user is a member must bedetermined in order to build a credential. Normally, all LDAP suffixes are searchedto locate the groups of which the user is a member.


The groups are assumed to be defined in same LDAP suffix as the userdefinition. Only that suffix is searched for group membership. Thisbehavior can improve the performance of group lookup because only asingle suffix is searched for group membership. This option should onlybe specified if group definitions are restricted to the same suffix as theuser definition.

no|falseThe groups might be defined in any LDAP suffix.


The value is not specified by default during WebSEAL configuration. When thevalue is not specified, the default value is no.

Example: user-and-group-in-same-suffix = yes



Active Directory

[uraf-ad] stanza

ad-server-config = fully_qualified_path

Location and file name of the Active Directory registry activedir.confconfiguration file. This value is generated, but it can be changed.

The fully_qualified_path value represents an alphanumeric, non-case sensitivestring. The maximum string length for the Active Directory user registry is 256alphanumeric characters.

This stanza entry is required when your user registry is Microsoft ActiveDirectory and is required only for configuration files other than activedir.conf.

Default value for UNIX:

/opt/PolicyDirector/etc/activedir.conf

Default value for Windows:

c:\Program files\tivoli\Policy Director\etc\activedir.conf

Example for UNIX:

ad-server-config = /opt/PolicyDirector/etc/activedir.conf

enabled = {yes|no}

Indication of whether Active Directory is being used as the user registry.

Valid values:yes Indicates that Active Directory is the user registry.no Indicates that Active Directory is not the user registry. Anything other

than yes, including a blank, is interpreted as no.

This stanza entry is required when your user registry is Microsoft ActiveDirectory.

Default value: no


multi-domain = {true|false}

Indication of whether the domain is a single-domain or multi-domainconfiguration. You select the value at the time the runtime is configured forTivoli Access Manager. The value is filled in automatically, based on informationsupplied during the runtime configuration.

Valid values:true For multiple Active Directory domains.false For a single Active Directory domain.



Example: multi-domain = true

hostname = hostname


Active Directory domain name system (DNS) host name. The value is filled inautomatically, based on information supplied during the runtime configuration.The hostname is an alphanumeric, non-case sensitive string. The dot (.) cannot bethe last character of the host name. The maximum string length for the ActiveDirectory user registry is 256 alphanumeric characters.



Example: hostname = adserver.tivoli.com

domain = root_domain_name

Active Directory root (primary) domain. The value is filled in automatically,based on information supplied during the runtime configuration. Theroot_domain_name is an alphanumeric, non-case sensitive string. The maximumlength for the domain name is user registry dependent. For Active Directorythat maximum length is 256 alphanumeric characters.

This stanza entry is required when multi-domain = true.

There is no default behavior.

Example: domain = dc=tivoli,dc=com

useEncryption = {true|false}

Indication of whether encryption communication to Active Directory is beingused. This value is filled in automatically, based on information supplied duringthe runtime configuration.

Valid values:true Enables encryption communication.false Disables encryption communication.


There is no default behavior.

Example: useEncryption = false

bind-id = ad_id

Active Directory administrator or user log-in identity that is used to bind (signon) to the registry server. If the ID belongs to a user rather than anadministrator, the Active Directory user must have enough privileges to updateand modify data in the user registry.

The ad_id value is an alphanumeric, non-case sensitive string. The minimumand maximum lengths of the ID, if there are limits, are imposed by theunderlying registry. For Active Directory the maximum length is 256alphanumeric characters.

This value is filled in automatically, based on information supplied duringserver configuration. Whenever you change this value after the configuration iscompleted, a conflict might occur.


The default value is generated; do not change it.

Example: bind-id = adpdadmin


bind-pwd = admin_password

Encoded administrator log-in password that is used to bind (or sign on) to theActive Directory registry server. Additional password requirements can bespecified for Tivoli Access Manager after the product is installed. However, theinitial password does not necessarily conform to those requirements.

The admin_password value is filled in automatically, based on information that issupplied during server configuration. The password is an encrypted string.



Example: bind-pwd = MyADbindPwd

dnforpd = ad_dn

Distinguished name that is used by Active Directory to store Tivoli AccessManager data. The ad_dn value is an alphanumeric, non-case sensitive string.The minimum and maximum lengths of the distinguished name, if there arelimits, are imposed by the underlying registry. For Active Directory themaximum length is 256 alphanumeric characters.



Example: dnforpd = dc=child2,dc=com


IBM Lotus Domino

[uraf-domino] stanza

domino-server-config = fully_qualified_path

Location and file name of the Active Directory registry activedir.confconfiguration file.

Name and location of the Lotus Domino registry domino.conf configuration file.

The fully_qualified_path represents an alphanumeric string.

This stanza entry is required when your user registry is Lotus Domino and isrequired only for configuration files other than domino.conf.

Default value for UNIX:

/opt/PolicyDirector/etc/domino.conf

Default value for Windows:

c:\Program files\tivoli\Policy Director\etc\domino.conf

Example for Windows:

domino-server-config = c:\Program files\tivoli\Policy Director\etc\domino.conf

enabled = {yes|no}

Indication of whether Domino is being used as the user registry.

Valid values:yes Indicates Domino is the user registry.no Indicates Domino is not the user registry. Anything other than

yes, including a blank, is interpreted as no.

This stanza entry is required when your user registry is Lotus Domino.

Default value: no


server = server_name

Name of the Lotus Domino™ server. The server_name value represents analphanumeric, non-case sensitive string. The minimum and maximum lengths ofthe name are imposed by the underlying registry.



Example: server = grizzly/Austin/IBM

Where grizzly is the Domino server machine host name and the remainder isthe Domino domain name.

hostname = hostname

Lotus Domino server TCP/IP host name. The hostname value is manually inputduring configuration. The hostname value must be an alphanumeric, non-casesensitive string. The format is the same as a typical TCP/IP host name.



Example: hostname = myhost.austin.ibm.com


LDAPPort = port_number

LDAP port number for the Lotus Domino server. The port_number value ismanually input during configuration. A valid port number is any positivenumber that is allowed by TCP/IP and that is not currently being used byanother application.


Default value: 389

Example: LDAPPort = 389

UseSSL = {yes|no}

Indication of whether to use SSL.

Value values:yes Specifies that you want to use SSL.no Specifies that you do not want to use SSL.


Default value: yes

Example: UseSSL = no

keyfile = filename

SSL key file name and location. Use the SSL key file to handle certificates thatare used in LDAP communication. The filename is an alphanumeric, non-casesensitive string that must conform to the underlying (Windows) file systemnaming convention. The file must be an existing file on the client machine. Thefile type can be anything but the extension is usually .kdb.

This stanza entry is required when UseSSL = yes

The default value is server-dependent.

Example for Windows: keyfile = C:/pd/keytab/ivacld.kdb

KeyFile_PW = password

Password for the SSL key file.


The default value is server-dependent.

Example: KeyFile_PW = mykeyfilepw

KeyFile_DN = cert_label

Distinguished name (DN) of the SSL key file private key. The cert_label value isan alphanumeric string that represents the certificate label of the client personalcertificate within the SSL key file. This key label is used to identify the clientcertificate that is presented to the Domino server.



password = password


Domino server password that is used to bind (or sign on) to the Dominoregistry server. The password is an encrypted string.

This stanza entry is required when enabled = yes

The value is generated; do not change it.

Example: password = myEncryptedSrvrPwd

NAB = names.nsf

Lotus Domino Name and Address Book (NAB) database. The names.nsfdatabase is set at configuration time and cannot be changed.


Default value: names.nsf

Example: NAB = names.nsf

PDM = nsf_filename

Tivoli Access Manager meta-data database. The nsf_filename represents a Dominodatabase file name. The file name conforms to the underlying operating systemfile naming conventions of the Domino server. The recommended file extensionis .nsf. This file is created on the Domino server during configuration.


Default value: PDMdata.nsf

Example: PDM = PDMdata.nsf


Secure Socket Layer

[ssl] stanza

webseal-cert-keyfile = fully_qualified_path

Path name to the WebSEAL certificate keyfile. This is the certificate thatWebSEAL exchanges with browsers when negotiating SSL sessions.


This path is set during WebSEAL configuration. The path consists of theWebSEAL installation directory plus: www/certs/pdsrv.kdb.

Example:

webseal-cert-keyfile =C:/Program Files/Tivoli/PDWeb//www/certs/pdsrv.kdb

This path is typically not modified by the WebSEAL administrator afterinitial WebSEAL configuration.

webseal-cert-keyfile-stash = fully_qualified_path

Name of the file containing an obfuscated version of the password used toprotect private keys in the keyfile.


This path is set during WebSEAL configuration. The path consists of theWebSEAL installation directory plus: www/certs/pdsrv.sth.

Example:

webseal-cert-keyfile-stash =C:/Program Files/Tivoli/PDWeb/www/certs/pdsrv.sth

webseal-cert-keyfile-pwd = password

Password used to protect private keys in WebSEAL certificate file. When thisstanza entry is assigned a value, that value is used instead of any passwordthat is contained in the stash file specified by webseal-cert-keyfile-stash.

This stanza entry is optional. This stanza entry stores the password in plaintext. For optimum security practice, use of the stash file is recommended.


Example: webseal-cert-keyfile-pwd = j73R45huu

webseal-cert-keyfile-label = label_name

String specifying a label to use for WebSEAL certificate keyfile. When this isnot specified, the default label is used.

This stanza entry is optional, but is set by default during WebSEALconfiguration.

Default value: WebSEAL-Test-Only

Example:

webseal-cert-keyfile-label = WebSEAL-Test-Only

ssl-keyfile = fully_qualified_path


String specifying the path to the the keystore WebSEAL uses forcommunicating with other Tivoli Access Manager servers over SSL.


The default value is set during WebSEAL configuration. The WebSEALinstallation directory path is combined with the following path:keytabs/webseald.kdb

Example:

ssl-keyfile = C:/Program Files/Tivoli/PDWeb//keytabs/webseald.kdb

This stanza entry is typically modified only by the WebSEAL configurationutility.

ssl-keyfile-pwd = password

String containing the password to protect the private keys in the SSL keyfile.When this stanza entry is assigned a value, that value is used instead of anypassword that is contained in the stash file specified by ssl-keyfile-stash.

This stanza entry is optional. This stanza entry stores the password in plaintext. For optimum security practice, use of the ssl-keyfile-stash isrecommended.


Example: ssl-keyfile-pwd = myPassw0rd


ssl-keyfile-stash = fully_qualified_path

Name of the file containing an obfuscated version of the password used toprotect private keys in the SSL keyfile.


This path is set during WebSEAL configuration. The path consists of theWebSEAL installation directory plus: keytabs/webseald.sth.

Example:

ssl-keyfile-stash =C:/Program Files/Tivoli/PDWeb//keytabs/webseald.sth


ssl-keyfile-label = label_name

String containing a label for the SSL certificate keyfile. When this label is notspecified, the default label is used.

This stanza entry is optional, but is assigned during WebSEAL configuration.

Default value: PD Server

Example:

ssl-keyfile-label = PD Server


disable-ssl-v2 = {yes|no}


Disables support for SSL Version 2. Support for SSL V2 is enabled by default.The value yes means support is disabled. The value no means the support isenabled.

This stanza entry is optional. When not specified, the default is no.

Default value: no. The WebSEAL configuration sets this value

Example: disable-ssl-v2 = no

disable-ssl-v3 = {yes|no}

Disables support for SSL Version 3. Support for SSL V3 is enabled by default.The value yes means support is disabled. The value no means the support isenabled.


Default value: no. The WebSEAL configuration sets this value.

Example: disable-ssl-v3 = no

disable-tls-v1 = {yes|no}

Disables support for TLS Version 1. Support for TLS V1 is enabled bydefault. The value yes means support is disabled. The value no means thesupport is enabled.


Default value: no. The WebSEAL configuration sets this value.

Example: disable-tls-v1 = no

ssl-v2-timeout = number_of_seconds

Session timeout in seconds for SSL v2 connections between clients andservers. This timeout value controls how often a full SSL handshake iscompleted between clients and WebSEAL.

Valid range of values for number_of_seconds is from 1-100 seconds.

This value is set by the WebSEAL configuration utility.

This stanza entry is required when SSL is enabled.

Default value: 100

Example: ssl-v2-timeout = 100

ssl-v3-timeout = number_of_seconds

Session timeout in seconds for SSL v3 connections between clients andservers. This timeout value controls how often a full SSL handshake iscompleted between clients and WebSEAL.

Valid range of values for number_of_seconds is from 10-86400 seconds, where86400 seconds is equal to 1 day. If you specify a number outside this range,the default number of 7200 seconds will be used.

This value is set by the WebSEAL configuration utility.

This stanza entry is required when SSL is enabled.

Default value: 7200

Example: ssl-v3-timeout = 7200

ssl-max-entries = number_of_entries


Integer value indicating the maximum number of concurrent entries in theSSL cache. The minimum value is zero (0) which means that caching isunlimited. Entries between 0 and 256 are set to 256. There is no maximumlimit.


When the stanza entry is not assigned a value, WebSEAL uses a defaultvalue of 0. The WebSEAL configuration utility, however, assigns a defaultvalue of 4096.

Example: ssl-max-entries = 4096


gsk-crl-cache-size = number_of_entries

Integer value indicating the maximum number of entries in the GSKit CRLcache. Minimum value is 0. A value of 0 means that no entries are cached.

Neither WebSEAL nor GSKit impose a maximum value on this cache. See thediscussion on maximum values for integers in “Guidelines for configuringstanzas” on page 241.

See the Secure Socket Layer Introduction and iKeyman User’s Guide for moreinformation on GSKit. See also the standards documents for SSL V3 and TLSV1 (RFC 2246) for more information on CRLs.


Default value: 0

Example: gsk-crl-cache-size = 0

gsk-crl-cache-entry-lifetime = number_of_seconds

Integer value specifying the lifetime timeout, in seconds, for individualentries in the GSKit CRL cache. The minimum value is 0. The maximumvalue is 86400.

Neither WebSEAL nor GSKit impose a maximum value on the cache entrylifetime. See the discussion on maximum values for integers in “Guidelinesfor configuring stanzas” on page 241.

See the Secure Socket Layer Introduction and iKeyman User’s Guide for moreinformation on GSKit. See also the standards documents for SSL V3 and TLSV1 (RFC 2246) for more information on CRLs.


Default value: 0

Example: gsk-crl-cache-entry-lifetime = 0

crl-ldap-server = server_name

Name of the LDAP server to be referenced for Certificate Revocation List(CRL) checking during SSL authentication.



Example: crl-ldap-server = surf.santacruz.ibm.com

crl-ldap-server-port = port_number


Port number for communication with the LDAP server specified incrl-ldap-server. The LDAP server is referenced for Certificate RevocationList (CRL) checking during SSL authentication.

This stanza entry is optional. When crl-ldap-server is set, this stanza entryis required.


Example: crl-ldap-server-port = 389

crl-ldap-user = user_DN

Fully qualified distinguished name (DN) of an LDAP user that has access tothe Certificate Revocation List.

This stanza entry is optional. A null value for crl-ldap-user indicates thatthe SSL authenticator should bind to the LDAP server anonymously.


Example: crl-ldap-user =cn=webseald/surf,cn=SecurityDaemons,secAuthority=Default

crl-ldap-user-password = password

Password for the user specified in crl-ldap-user.



Example: crl-ldap-user-password = mypassw0rd

pkcs11-driver-path = fully_qualified_path

Path to a shared library that provides GSKit support for external PKCS#11device drivers.



Example:

pkcs11-driver-path = /usr/lib/pkcs11/PKCS11_API.so

See “Configure WebSEAL (and GSKit) to use the PKCS#11 shared library” onpage 92.

pkcs11-token-label = name_of_label

Label for the token device that stores the WebSEAL public/private key pair.


There is no default value:

Example: pkcs11-token-label = websealToken

See “Configure WebSEAL (and GSKit) to use the PKCS#11 shared library” onpage 92.

pkcs11-token-pwd = password


String containing the password to protect the private keys in the tokenkeyfile.



Example: pkcs11-token-pwd = secret

disable-ncipher-bsafe = {yes|no}

Disables or permits the automatic use by WebSEAL of nCipher hardwarecards for SSL acceleration over BHAPI. WebSEAL detects this hardwarewhen present, and uses it unless this stanza entry is set to yes.


Default value: no

Example: disable-ncipher-bsafe = no

See “Disable acceleration mode for nCipher nForce 300” on page 93.

disable-rainbow-bsafe = {yes|no}

Disables or permits the automatic use by WebSEAL of Rainbow Cryptoswifthardware cards for SSL acceleration over BHAPI. WebSEAL detects thishardware when present, and uses it unless this stanza entry is set to yes.


Default value: no

Example: disable-rainbow-bsafe = no

See “Disable acceleration mode for nCipher nForce 300” on page 93.

ssl-auto-refresh = {yes|no}

Indicates whether automatic refresh of the SSL certificate and the keydatabase file password occur.

Valid values are:yes Automatic refresh is enabled. When enabled, the certificate and

password are regenerated if either is in danger of expiration (lessthan half the time left). This value is the default value.

no Turn off automatic certificate and password refresh.

This stanza entry is required only when SSL is enabled.

Default value: yes

Example: ssl-auto-refresh = yes

ssl-listening-port = {0|port_number}


TCP port to listen on for incoming requests.

Valid values are:0 Disables listening. The default value is 0 if not specified during

configuration.port_number

Enables listening at the specified port number. The valid range forport numbers is any positive number that is allowed by TCP/IPand is not currently being used by another application.


The default value is supplied by the WebSEAL configuration utility, and isdependent on the available TCP/IP ports. A typical value during WebSEALconfiguration is 7234.

Example: ssl-listening-port = 7234

ssl-pwd-life = number_of_days

Password lifetime for the key database file, specified in the number of days.

For automatic password renewal, the value for the lifetime of a password iscontrolled by the number_of_days value when the server is started.Note: If a certificate and the password to the keyring database filecontaining that certificate are both expired, then the password must berefreshed first.

Valid values for the number_of_days is from 1 to 7,299 days.

This stanza entry is required only if SSL is enabled.

Default value: 183

Example: ssl-pwd-life = 183

ssl-authn-type = authentication_type

Type of authentication.


Default value: certificate

Example: ssl-authn-type = certificate


AuthenticationThis section contains the following subsections and stanzas:

Section Stanzas

“Authentication mechanisms” on page 272 [ba][forms][token][certificate][http-headers][auth-headers][ipaddr][authentication-levels][mpa]

“Authentication libraries” on page 276 [authentication-mechanisms]

“Reauthentication” on page 280 [reauthentication]

“Authentication failover” on page 281 [failover][failover-attributes]

“Cross-domain single sign on” on page 283 [cdsso][cdsso-peers]

“e-community single sign-on” on page 284 [e-community-sso]

“Quality of protection” on page 287 [ssl-qop][ssl-qop-mgmt-hosts][ssl-qop-mgmt-networks][ssl-qop-mgmt-default]


Authentication mechanisms

[ba] stanza

ba-auth = {none|http|https|both}

Enables authentication using the Basic Authentication mechanism. Specifieswhich protocols are supported. The value both means both HTTP andHTTPS.

When basic authentication is enabled, you must also configure anappropriate authentication library by setting a key=value pair inthe [authentication-mechanisms] stanza. See “Authentication libraries” onpage 276 for more information.


Default value: https

Example: ba-auth = https

basic-auth-realm = Realm_name

String value that specifies the realm name. This name is displayed in thebrowser’s dialog box when the user is prompted for login information. Thestring must consist of ASCII characters, and can contain spaces.


Default value: Access Manager

Example: basic-auth-realm = Access Manager

[forms] stanza

forms-auth = {none|http|https|both}

Enables authentication using the Forms Authentication mechanism. Specifieswhich protocols are supported. The value both means both HTTP andHTTPS.

When forms authentication is enabled, you must also configure anappropriate authentication library by setting a key=value pair in the[authentication-mechanisms] stanza. See “Authentication libraries” onpage 276 for more information.


Default value: none

Example: forms-auth = none

[token] stanza

token-auth = {none|http|https|both}


Enables authentication using the Token Authentication mechanism. Specifieswhich protocols are supported. The value both means both HTTP andHTTPS.

When token authentication is enabled, you must also configure anappropriate authentication library by setting a key=value pair inthe [authentication-mechanisms] stanza. See “Authentication libraries” onpage 276 for more information.


Default value: none

Example: token-auth = none

[certificate] stanza

accept-client-certs = {never|required|optional}

Specifies how to handle certificates from HTTPS clients. Options are:

neverNever request a client certificate

requiredAlways request a client certificate. Do not accept the connection if theclient does not present a certificate. When this value is set to required,all other authentication settings are ignored for HTTPS clients.

optionalAlways request a client certificate. If presented, use it.

When certificate authentication is enabled, you must also configure anappropriate authentication library by setting a key=value pair in the[authentication-mechanisms] stanza. See “Authentication libraries” onpage 276 for more information.


Default value: never

Example accept-client-certs = never

[http-headers] stanza

http-headers-auth = {none|http|https|both}

Enables authentication using an HTTP header authentication mechanism.Specifies which protocols are supported. The value both means both HTTPand HTTPS.

When HTTP header authentication is enabled, you must also configure anappropriate authentication library by setting a key=value pair in the[authentication-mechanisms] stanza. See “Authentication libraries” onpage 276 for more information.


Default value: none

Example: http-headers-auth = none

[auth-headers] stanza


header = header_name

Use this stanza to specify all supported HTTP header types. By default, thebuilt-in shared library is hard-coded to support Entrust Proxy header data.

Values for header_name must be ASCII and conform to the HTTPspecification for header names. The values for header_name are typicallydetermined by a particular header name that is required by a third-partyapplication. The WebSEAL administrator configures WebSEAL to supportthese other header names by setting this value.

This stanza entry is optional


Example: header = entrust-client

[ipaddr] stanza

ipaddr-auth = {none|http|https|both}

Enables authentication using a client’s IP address. Specifies which protocolsare supported. The value both means both HTTP and HTTPS.

When IP address authentication is enabled, you must also configure anappropriate authentication library by setting a key=value pair in the[authentication-mechanisms] stanza. See “Authentication libraries” onpage 276 for more information.



Example: ipaddr-auth = none

[authentication-levels] stanza

level = {unauthenticated|password|token-card}

Step-up authentication levels. WebSEAL enables authenticated users toincrease the authentication level by use of step-up authentication. Thiskey=value pair specifies which step-up authentication levels are supportedby this WebSEAL server.

Do not specify an authentication level unless the authentication method isenabled. For example, you must enable either basic authentication or formsauthentication before setting level = password.

Enter a separate key=value pair for each supported level.


Default values:

level = authenticatedlevel = password

Example: level = password

[mpa] stanza

mpa = {yes|no}


Enables support for multiplexing proxy agents.


Default value: no

Example: mpa = no


Authentication libraries

[authentication-mechanisms] stanza

passwd-cdas = fully_qualified_path

Fully qualified path for the library that implements a CDAS library for eitherbasic authentication or forms authentication.



passwd-ldap = fully_qualified_path

Fully qualified path for a library that implements basic authentication with anLDAP user registry.



Example (entered as one line):passwd-ldap =C:\PROGRA~1\Tivoli\POLICY~1\bin\ldapauthn.dll& -cfgfile [C:/Program Files/Tivoli/PDWeb//etc/webseald.conf]

passwd-uraf = fully_qualified_path

Fully qualified path for a library that implements basic authentication using theTivoli Access Manager URAF interface to underlying user registry types.



cert-ldap = fully_qualified_path

Fully qualified path for a library that implements certificate authentication.


The default value for the built-in library on Solaris is:

/opt/PolicyDirector/lib/libcertauthn.so & -chgfile \[/opt/pdweb/etc/webseal-default.conf]

Example on Windows (entered as one continuous line):cert-ldap =C:\PROGRA~1\Tivoli\POLICY~1\bin\libcertauthn.dll &-cfgfile [C:/Program Files/Tivoli/PDWeb/etc/webseald.conf]

token-cdas = fully_qualified_path

Fully qualified path for a library that implements token authentication.



cert-ssl = fully_qualified_path

Fully qualified path for a library that implements certificate authentication.



http-request = fully_qualified_path


Fully qualified path for a library that implements HTTP header or IP addressauthentication.



sso-create = fully_qualified_path

Fully qualified path for a library that implements WebSEAL single sign-oncreation authentication.



sso-consume = fully_qualified_path

Fully qualified path for a library that implements WebSEAL single sign-onconsumption authentication.



passwd-strength = fully_qualified_path

Fully qualified path for a library that implements password strengthauthentication.



cred-ext-attrs = fully_qualified_path

Fully qualified path for a library that implements credential extended attributesauthentication.



su-passwd = fully_qualified_path

Fully qualified path for a library that implements switch user authentication forbasic authentication or forms authentication.



See “Configuring switch user” on page 72.

su-token-card = fully_qualified_path

Fully qualified path for a library that implements switch user authentication fortoken authentication.




su-certificate = fully_qualified_path


Fully qualified path for a library that implements switch user authentication forcertificate authentication.




su-http-request = fully_qualified_path

Fully qualified path for a library that implements switch user authentication forHTTP header or IP address authentication.




su-cdsso = fully_qualified_path

Fully qualified path for a library that implements switch user authentication forcross-domain single sign-on authentication.




failover-password = fully_qualified_path

Fully qualified path for a library that implements failover cookie authenticationfor basic authentication or forms authentication.



See “Configuring failover cookies” on page 118

failover-token-card = fully_qualified_path

Fully qualified path for a library that implements failover cookie authenticationfor token card authentication.




failover-certificate = fully_qualified_path

Fully qualified path for a library that implements failover cookie authenticationfor certificate authentication.




failover-http-request = fully_qualified_path


Fully qualified path for a library that implements failover cookie authenticationfor HTTP header authentication or IP address authentication.




failover-cdsso = fully_qualified_path

Fully qualified path for a library that implements failover cookie authenticationfor cross-domain single sign-on authentication.




post-pwdchg-process = fully_qualified_path

Fully qualified path for a library that implements post password changeprocessing. This is called by WebSEAL when the user changes a password usingthe pkms password change page.



The following example shows the path name to the built-in post passwordchange library, as supplied with WebSEAL on Solaris Operating Environment:

post-pwdchg-process = /opt/PolicyDirector/lib/libxauthn.so


Reauthentication

[reauthentication] stanza

reauth-for-inactive = {yes|no}

Enables WebSEAL to prompt users to reauthenticate when their entry in theWebSEAL credential cache has timed out due to inactivity.


Default value: no

Example: reauth-for-inactive = no

reauth-reset-lifetime = {yes|no}

Enables WebSEAL to reset the lifetime timer for WebSEAL credential cacheentries following successful reauthentication.


Default value: no

Example: reauth-reset-lifetime = no

reauth-extend-lifetime = number_of_seconds

Integer value expressing the time in seconds that the credential cache timershould be extended to allow clients to complete a reauthentication.

When the value is zero (0), the lifetime timer is not extended.

WebSEAL imposes no maximum. The maximum value is limited only by theinteger data type. See the discussion of integer maximum values in“Guidelines for configuring stanzas” on page 241.


Default value: 0

Example: reauth-extend-lifetime = 300


Authentication failoverv [failover]

v [failover-attributes]

[failover] stanza

failover-auth = {none|http|https|both}

Enables WebSEAL to accept failover cookies. Specifies which protocols aresupported. The value both means both HTTP and HTTPS.


Default value: none

Example: failover-auth = none

failover-cookies-keyfile = fully_qualified_path

Key file for failover cookie encryption. The cdsso_key_gen utility must beused to generate this file.



Example: failover-cookies-keyfile = /tmp/failover.key

failover-cookie-lifetime = number_of_minutes

Integer value specifying the number of minutes that failover cookie contentsare valid. Must be a positive integer. There is no maximum value. See thediscussion of integer maximum values in “Guidelines for configuringstanzas” on page 241.


Default: 60

Example: failover-cookie-lifetime = 60

enable-failover-cookie-for-domain = {yes|no}

Enables the failover cookie for the domain.


Default: no

Example: enable-failover-cookie-for-domain = no

[failover-attributes] stanza

attribute = attribute_name


A list of attributes from the user credential that should be included in thefailover cookie. The list is empty by default.

The attribute is a credential attribute name. The attribute_name is the namethe administrator wants to use in the failover cookie. See example.

The allowable characters for the attribute and attribute_name are determinedby the Tivoli Access Manager Authorization API. WebSEAL does not imposeany additional restrictions on the allowable character set.



Example: employee-name = failover_employee_name


Cross-domain single sign onv [cdsso]

v [cdsso-peers]

[cdsso] stanza

cdsso-auth = {none|http|https|both}

Enables WebSEAL to accept tokens. Specifies which protocols are supported.The value both means both HTTP and HTTPS.


Default value: none

Example: cdsso-auth = none

authtoken-lifetime = number_of_seconds

Positive integer that expresses the number of seconds for which the singlesign-on authentication token is valid. Minimum value: 1. There is nomaximum value. See the discussion of integer maximum values in“Guidelines for configuring stanzas” on page 241.


Default value: 180

Example: authtoken-lifetime = 180

cdsso-argument = argument_name

Name of the argument containing the cross-domain single sign-on token in aquery string in a request. This is used to identify incoming requests thatcontain CDSSO authentication information.

Valid characters are any ASCII characters, except for question mark ( ? ),ampersand ( & ), and equals sign ( = ).


Default value: PD-ID

Example: cdsso-argument = PD-ID

[cdsso-peers] stanza

fully_qualified_hostname = fully_qualified _path

List of peer servers that are participating in cross-domain single-sign on. Thepath name must specify the location of server’s key file.


There is no default value

Example: webhost2.ibm.com = /tmp/cdsso.key


e-community single sign-onv [e-community-sso]

v [e-community-domain-keys]

[e-community-sso] stanza

e-community-sso-auth = {none|http|https|both}

Enables participation in e-community single sign-on. Specifies whichprotocols are supported. The value both means both HTTP and HTTPS.


Default value: none

Example: e-community-sso-auth = none

e-community-name = name

String value that specifies an e-community name. When e-community singlesign on is supported, this name must match any vouch-for tokens ore-community cookies that are received.

The string must not contain the equals sign ( = ) or ampersand ( & ).



Example: e-community-name = company1

is-master-authn-server = {yes|no}

Specifies whether this WebSEAL server accepts vouch-for requests from otherWebSEAL instances. The WebSEAL instances must have domain keys listedin the [e-community-domain-keys] stanza. When this value is yes, thisWebSEAL server is the master authentication server.



Example: is-master-authn-server = no

master-authn-server = fully_qualified_hostname

Location of the master authentication server. This value must be specifiedwhen is-master-authn-server is set to no. If a local domain login has not beenperformed then authentication attempts are routed through the mastermachine. The master machine will vouch for the user identity. The domainkey for the master-authn-server needs to be listed in the[e-community-domain-keys] stanza.



Example: master-authn-server = diamond.dev.ibm.com

master-http-port = port_number


Integer value specifying the port number on which the master-authn-serverlistens for HTTP request. The setting is necessary when e-community-sso-auth permits use of the HTTP protocol, and the master-authn-server listensfor HTTP requests on a port other than the standard HTTP port (port 80).This stanza entry is ignored if this WebSEAL server is the masterauthentication server.



Example: master-http-port = 81

master-https-port = port_number

Integer value specifying the port number on which the master-authn-serverlistens for HTTPS requests. The setting is necessary whene-community-sso-auth permits use of the HTTPS protocol, and themaster-authn-server listens for HTTPS requests on a port other than thestandard HTTPS port (port 443). This stanza entry is ignored if thisWebSEAL server is the master authentication server.



Example: master-https-port = 444

vf-token-lifetime = number_of_seconds

Positive integer indicating the lifetime, in seconds, of the vouch-for token.This is set to account for clock skew between participant servers. Theminimum value is 1 second. There is no maximum value. See the discussionof integer maximum values in “Guidelines for configuring stanzas” onpage 241.


Default value: 180

Example: vf-token-lifetime = 180

vf-url = URL_designation

Designator for vouch-for URL. This specifies the start of a URL relative tothe server root. This is used to construct vouch-for requests for participatinge-community single sign-on servers, and to distinguish requests forvouch-for information from other requests by the master authenticationserver.

The URL_designation string can contain alphanumerics and the followingspecial characters: dollar sign ( $ ), hyphen ( - ), underscore ( _ ), period ( . ),plus sign ( + ), exclamation point ( ! ), asterisk ( * ), single quote ( ’ ),parentheses ″ ( ) ″ and comma ( , ).

Questions marks ( ? ) are not allowed


When the stanza entry is not present in the configuration file, the defaultvalue is /pkmsvouchfor.

Example: vf-url = /pkmsvouchfor

vf-argument = vouch-for_token_name


String value containing the name of the vouch-for token contained in avouch-for reply. This is used to construct the vouch-for replies by the masterauthentication server, and to distinguish incoming requests as ones withvouch-for information by participating e-community single sign-on servers.Valid characters for the string are ASCII characters except for ampersand ( &), equals sign ( = ), and question mark ( ? ).


Default value: PD-VF

Example: vf-argument = PD-VF

ec-cookie-lifetime = number_of_minutes

Positive integer value indicating the lifetime of an e-community cookie.Minimum value is 1. There is no maximum value. See the discussion ofinteger maximum values in “Guidelines for configuring stanzas” onpage 241.


Default: 300

Example: ec-cookie-lifetime = 300

[e-community-domain-keys] stanza

domain_name = fully_quailified_path

File names for keys for any domains that are participating in thee-community. This includes the domain in which the WebSEAL server isrunning. These are shared on a pair-wise-by-domain basis.



Example: ecssoserver.subnet.ibm.com = /tmp/ecsso.key


Quality of protectionv [ssl-qop]

v [ssl-qop-mgmt-hosts]

v [ssl-qop-mgmt-networks]

v [ssl-qop-mgmt-default]

[ssl-qop] stanza

ssl-qop-mgmt = {yes|no}

Enables or disables SSL quality of protection management. The value yesenables SSL quality of protection management. The value no disables it.


Default value: no

Example: ssl-qop-mgmt = no

[ssl-qop-mgmt-hosts] stanza

host-ip = {ALL|NONE|cipher_level}

List of string values to specify the allowed encryption levels for HTTPSaccess for a specific IP address. The value ALL allows all ciphers. The valueNONE disables all ciphers and uses an MD5 MAC check sum.

To specify allowable ciphers for a selected group of IP addresses, create aseparate entry for each address. For example:

111.222.333.444 = RC4-128222.666.333.111 = RC2-128



Example: 111.222.333.444 = ALL

Note that this stanza has been deprecated and is retained only for backwardscompatibility. For more information, including a list of supportedcipher_levels, see “Configuring a default quality of protection level” onpage 53.

[ssl-qop-mgmt-networks] stanza

network/netmask = {ALL|NONE|cipher_level}


List of string values to specify the allowed encryption levels for HTTPSaccess for a specific combination of IP address and netmask. The value ALLallows all ciphers. The value NONE disables all ciphers and uses an MD5MAC check sum.

To specify allowable ciphers for a selected group of IP addresses andnetmasks, create a separate entry for each address/netmask combination. Forexample:

111.222.333.444/255.255.255.0 = RC4-128222.666.333.111/255.255.0.0 = RC2-128



Example: 111.222.333.444/255.255.255.0 = RC4-128

Note that this stanza has been deprecated and is retained only for backwardscompatibility. For more information, including a list of supportedcipher_levels, see “Configuring a default quality of protection level” onpage 53.

[ssl-qop-mgmt-default] stanza

default = {ALL|NONE|cipher_level}

List of string values to specify the allowed encryption levels for HTTPSaccess. The value ALL allows all ciphers. The value NONE disables all ciphersand uses an MD5 MAC check sum.

To specify a selected group of ciphers, create a separate entry for each cipher.For example:

default = RC4-128default = RC2-128default = DES-168

Values specified in this stanza entry are used for all IP addresses that are notmatched in either the [ssl-qop-mgmt-hosts] stanza entries or the[ssl-qop-mgmt-networks] stanza entries.


Default value: ALL

Example: default = ALL

For more information, including a list of supported cipher_levels, see“Configuring a default quality of protection level” on page 53.


Session

[session] stanza

max-entries = number_of_entries

Maximum number of concurrent entries in the credentials cache.

The minimum number for this value is 0. A value of zero means that thecache is of unlimited size.

WebSEAL does not impose a maximum value. See the guidelines onmaximum size of integer values in “Guidelines for configuring stanzas”on page 241.


Default value: 4096

Example: max-entries = 4096

See also “Configuring the WebSEAL session/credentials cache” onpage 114 and the IBM Tivoli Access Manager Performance Tuning Guide.

timeout = number_of_seconds

Integer value for maximum lifetime, in seconds, for an entry in thecredential cache

The minimum number for this value is 0. A value of 0 means that thelifetime is unlimited.



Default value: 3600

Example: timeout = 3600

See also “Configuring the WebSEAL session/credentials cache” onpage 114.

inactive-timeout = number_of_seconds

Integer value for lifetime, in seconds, of inactive entries in the credentialcache.

The minimum number for this value is 0. A value of 0 means that whenthe cache is full, the entries are cleared based on a Least Recently Usedalgorithm.



Default value: 600

Example: inactive-timeout = 600

See also “Configuring the WebSEAL session/credentials cache” onpage 114.


ssl-id-sessions = {yes|no}

Indicates whether to use the SSL ID to maintain a user’s HTTP loginsession.


Default value: yes

Example: ssl-id-sessions = yes

See also “Maintaining state with session cookies” on page 115.

use-same-session = {yes|no}

Indicates whether to use the same session for SSL and HTTP clients.When set to yes, a user who has authenticated over HTTP will beauthenticated when connecting over HTTPS. Likewise, the user who hasauthenticated over HTTPS will be authenticated when connecting overHTTP.


Default value: no

Example: use-same-session = no

See also “Maintaining state with session cookies” on page 115

resend-webseal-cookies = {yes|no}

Indicates whether to send the WebSEAL cookies with every response.


Default value: no

Example: resend-webseal-cookies = no

See also “Maintaining state with session cookies” on page 115

allow-backend-domain-cookies = {yes|no}

Indicates whether WebSEAL is allowed to send domain cookies from aback-end server to a client.


Default value: no

Example: allow-backend-domain-cookies = no

See also “Handling domain cookies” on page 196

user-session-ids = {yes|no}

Enables or disables the creation and handling of user session IDs.


Default value: yes

Example: user-session-ids = yes

See also “Maintaining session state between client and back-endapplications” on page 228


ContentThis section contains the following topics and stanzas:

Section Stanzas

“Content management” on page 292 [content]

“Account management” on page 293 [acnt-mgt]

“Automatic redirect” on page 296 [content][enable-redirects]

“Local CGI” on page 297 [cgi][cgi-types][cgi-environment-variables]

“Icons” on page 299 [content-index-icons][icons]

“Content caching” on page 301 [content-cache]

“Content MIME types” on page 302 [content-mime-types]

“Content encodings” on page 303 [content-encodings]


Content management

[content] stanza

doc-root = fully_qualified_path

Root directory of the WebSEAL document tree.

The administrator can either accept the default value of www/docs orspecify an alternate location.

When the administrator accepts the default value, the WebSEALconfiguration appends the default value onto the WebSEAL installationdirectory. Thus the default fully_qualified_path isWebSEAL_installation_directory/www/docs

When the administrator changes this value during configuration, theadministrator must specify a fully qualified path. In this case, WebSEALdoes not append the entry on to the WebSEAL installation directory. Inthis case, the doc-root entry is matches the administrator’s input.


Default value: WebSEAL_installation_directory/www/docs

Example: doc-root = C:/Program Files/Tivoli/PDWeb/www/docs

directory-index = filename

Name of a directory index file. When a request is made for a directorylocated on the local WebSEAL server, WebSEAL looks for this file beforeattempting a directory listing.


Default value: index.html

Example: directory-index = index.html

delete-trash-dir = fully_qualified_path

Path name to a directory in which files removed by the DELETE methodare moved. Files are held there until an administrator removes them.

This key does not apply to empty directories, which are always deleted.

This key is inactive (commented out in the configuration file) by default.When the key is inactive, files removed by the DELETE method areimmediately removed from the file system.



Example: delete-trash-dir = /tmp/trashdir

user-dir = filename

Directory in a users’ home directories that contain public HTMLdocuments.


Default value: public_html

Example: user-dir = public_html


Account management

[acnt-mgt] stanza

mgt-pages-root = relative_pathname

Root of account management pages. The actual directory used is asubdirectory of this root directory, as determined by localization settings.This path is relative to the server-root value in the [server] stanza


Default value: lib/html

Example: mgt-pages-root = lib/html

login = filename

Standard login form.


Default value: login.html

Example: login = login.html

login-success = filename

Page displayed after successful login.


Default value: login_success.html

Example: login-success = login_success.html

logout = filename

Page displayed after successful logout.


Default value: logout.html

Example: logout = logout.html

account-locked = filename

Page displayed when the user authentication fails due to a locked useraccount.


Default value: acct_locked.html

Example: account-locked = acct_locked.html

passwd-expired = filename

Page displayed when the user authentication fails due to an expired userpassword.


Default value: passwd_exp.html

Example: passwd-expired = passwd_exp.html

passwd-change = filename


Page containing a change password form.


Default value: passwd.html

Example: passwd-change = passwd.html

passwd-change-success = filename

Page displayed when password change request succeeds.


Default value: passwd_rep.html

Example: passwd-change-success = passwd_rep.html

passwd-change-failure = filename

Page displayed when password change request fails.


Default value: passwd.html

Example: passwd-change-failure = passwd.html

help = filename

Page containing links to valid administration pages.


Default value: help.html

Example: help = help.html

token-login = filename

Token login form.


Default value: tokenlogin.html

Example: token-login = tokenlogin.html

next-token = filename

Next-token form.


Default value: nexttoken.html

Example: next-token = nexttoken.html

stepup-login = filename

Step-up authentication login form.


Default value: stepuplogin.html

Example: stepup-login = stepuplogin.html

switch-user = filename


Switch user management form.


Default value: switchuser.html

Example: switch-user = switchuser.html

cert-failure = filename

Page displayed when certificates are required and a client fails toauthenticate with a certificate.


Default value: certfailure.html

Example: cert-failure = certfailure.html


Automatic redirectv [content]

v [enable-redirects]

[content] stanza

login-redirect-page = Uniform_Resource_Locator

Uniform Resource Locator (URL) to which users are automaticallyredirected when attempting to access a resource that is protected byWebSEAL. The URL can be either server-relative, or can be an absoluteURL.



Example of a server relative URL:

login-redirect-page = /jct/page.html

Example of an absolute URL:

login-redirect-page = http://www.ibm.com/

See also “Configuring automatic redirection to a login home page” onpage 144.

[enable-redirects] stanza

redirect = {forms-auth|basic-auth|token-auth}

Enables redirection for use with one or more authentication mechanism.Redirection is supported for:

v Forms authentication

v Basic authentication

v Token authentication

The configuration file must contain a separate entry for eachauthentication mechanism for which redirection is enabled.



Example entries that enables redirection for forms authentication andbasic authentication:

redirect = forms-authredirect = basic-auth


Local CGIv [cgi]

v [cgi-types]

v [cgi-environment-variables]

[cgi] stanza

cgi-timeout = number_of_seconds

Integer value indicating the timeout, in seconds, for writing to andreading from child CGI processes


Minimum value is 0. This disables the timeout. Disabling the timeout isnot recommended.

WebSEAL imposes no maximum value. See the discussion on maximumsize for integers in “Guidelines for configuring stanzas” on page 241.

Example: cgi-timeout = 120

[cgi-types] stanza

file_extension = command

This stanza contains entries that map CGI file extensions to Windowscommands. On Windows servers, CGI files that have an extension that isnot in this list are not executed, with the exception of files with the .EXEextension.

This stanza is used on Windows servers only.

There are no default entries. The WebSEAL configuration file contains bydefault a number of entries that are commented out (inactive).

Administrators can add additional entries. Additional entries must consistof ASCII characters.


Examples of uncommented WebSEAL configuration file entries:

bat = cmdcmd = cmdpl = perlsh = shtcl = tclsh76

[cgi-environment-variables] stanza

ENV = environment_variable


List containing system environment variables that need to be exported toCGI applications. The administrator can add variables to this list, asneeded by specific applications. Entries must be valid environmentvariable names.

These entries are optional.

The following entries are provided in the default WebSEAL configurationfile:

ENV = SystemRootENV = PATHENV = LANGENV = LC_ALLENV = LC_CTYPEENV = LC_MESSAGESENV = LOCPATHENV = NLSPATH

The default WebSEAL configuration file provides one inactive(commented out) variable:

#ENV = SystemDrive


Iconsv [content-index-icons]

v [icons]

[content-index-icons] stanza

type = relative_pathname

Entries in this stanza specify icons to use in directory indices. Therelative_pathname is the path name to the location of the icon.

The type indicates a wildcard pattern for a collection of MIME types.

The path name is relative to the WebSEAL protected object space, as set inthe doc-root entry in the [content] stanza.

Administrators can add additional entries. The type must refer to validMIME types. The wildcard character (*) is limited to entries of onecollection of MIME types. For example, image/*. No further wildcardexpansion is done. For a list of MIME types, see the [content-mime-types]stanza.

The relative_pathname can be any valid URI within the WebSEAL protectedobject space, as defined is doc-root.

The entries in this stanza are optional.

The WebSEAL configuration file provides the following default entries:

image/* = /icons/image2.gifvideo/* = /icons/movie.gifaudio/* = /icons/sound2.giftext/html = /icons/generic.giftext/* = /icons/text.gifapplication/x-tar = /icons/tar.gifapplication/* = /icons/binary.gif

[icons] stanza

diricon = relative_pathname

Relative path name to a graphics file to display to indicate a subdirectory.This is used when when displaying a directory index.


This stanza entry is required. If the value is not specified, the value ofunknownicon is used.

Default value: /icons/folder2.gif

Example: diricon = /icons/folder2.gif

backicon = relative_pathname


Relative path name to a graphics file used to indicate the parent directory.This is used when when displaying a directory index.


This stanza entry is required. If the value is not specified, the value ofunknownicon is used.

Default value: /icons/back.gif

Example: backicon = /icons/back.gif

unknownicon = relative_pathname

Relative path name to a graphics file used to indicate an unknown filetype. This is used when when displaying a directory index.


This stanza entry is required. If this value is not specified, a broken linkGIF image is displayed.

Default value: /icons/unknown.gif

Example: unknownicon = /icons/unknown.gif


Content caching

[content-cache] stanza

MIME_type = cache_type:cache_size

List of entries that define the caches which WebSEAL uses to storedocuments in memory.

v MIME_type

Any valid MIME type conveyed in an HTTP Content-Type: responseheader. This value may contain an asterisk to denote a wildcard ( * ). Avalue of */* represents a default object cache that holds any object thatdoes not correspond to an explicitly configured cache.

v cache_type

Defines the type of backing store to use for the cache. Only memorycaches are supported.

v cache_size

The maximum size, in kilobytes, to which the cache grows beforeobjects are removed according to a least-recently-used algorithm. Theminimum allowable value is 1 kilobyte. WebSEAL reports an error andfails to start if the value is less than or equal to zero (0). WebSEALdoes not impose a maximum allowable value.


There are no default caches defined.

Examples:

text/html = memory:2000# image/* = memory:5000# */* = memory:1000


Content MIME types

[content-mime-types] stanza

extension = MIME_type

This stanza defines the MIME type for specific document extensions. Thestanza contains a list of extension = MIME_type pairs. Many common MIMEtypes are defined by default. Administrators can add additional entries. Bothextensions and MIME_types must be declared using the ASCII character set.The entry of invalid MIME types does not affect WebSEAL, but may causedifficulty for client browsers.

v extension

The file name extension of documents of this MIME type

v MIME_type

The corresponding MIME type

There following MIME types are defined by default:

html = text/htmlhtm = text/htmlgif = image/gifjpeg = image/jpegps = application/postscriptshtml = text/x-server-parsed-htmljpg = image/jpegjpe = image/jpegmpeg = video/mpegmpe = video/mpegmpg = video/mpegbin = application/octet-streamexe = application/octet-streamZ = application/octet-streamEXE = application/octet-streamdll = application/octet-streamDLL = application/octet-streamivsrv = application/octet-streampdf = application/pdfau = audio/basicsnd = audio/basicaiff = audio/x-aiffaifc = audio/x-aiffaif = audio/x-aiffwav = audio/x-wavai = application/postscripteps = application/postscriptrtf = application/rtfzip = application/zip

ief = image/ieftiff = image/tifftif = image/tiffras = image/x-cmu-rasterpnm = image/x-portable-anymappbm = image/x-portable-bitmappgm = image/x-portable-graymapppm = image/x-portable-pixmaprgb = image/x-rgbxbm = image/x-xbitmapxpm = image/x-xpixmapxwd = image/x-xwindowdumptxt = text/plainrtx = text/richtexttsv = text/tab-separated-valuesetx = text/x-setextqt = video/quicktimemov = video/quicktimeavi = video/x-msvideomovie = video/x-sgi-moviejs = application/x-javascriptls = application/x-javascriptmocha = application/x-javascriptwrl = x-world/x-vrmldir = application/x-directordxr = application/x-directordcr = application/x-directorcrt = application/x-x509-ca-certtar = application/x-tar

deftype = MIME_type

Default type to assign to pages that don’t match any of the extension =MIME_type entries defined in this stanza.

The administrator should not change this value.


Default value is text/plain

Example: deftype = text/plain


Content encodings

[content-encodings] stanza

extension = encoding_type

Entries in this stanza map a document extension to an encoding type. Thismapping is used by WebSEAL to report the correct MIME type in itsresponse content-type header for local junction files. This mapping isnecessary so that WebSEAL can communicate to a browser that encoded(binary) data is being returned.

The MIME types defined in this stanza must also be defined in[content-mime-types].


Default values are:

gz = x-gzipZ = x-compress

When WebSEAL encounters a document with two extensions, such as:.txt.Z, it produces two headers:

content-type: text/plaincontent-encoding: x-compress

Thus even though the data is compressed, the response to the browsersays text/plain. However, the extra content-encoding header tells thebrowser that the data is compressed text/plain.

In most cases, the administrator does not need to add additional entries.However, if the administrator introduces a new extension type thatrequires more than a text/plain response, the extension and encoding_typeshould be added to this stanza.


JunctionsThis sections contains the following topics and stanzas:

Section Stanza

“Junction management” on page 305 [junction]

“Document filtering” on page 309 [filter-url]

“Event handler filtering” on page 310 [filter-events]

“Scheme filtering” on page 311 [filter-schemes]

“MIME types and header filtering” onpage 312

[filter-content-types][filter-request-headers]

“Script filtering” on page 313 [script-filtering][preserve-cookie-names]

“Global Sign-On cache” on page 315 [gso-cache]

“Lightweight Third Party Authenticationcache” on page 317

[ltpa-cache]


Junction management

[junction] stanza

junction-db = relative_pathname

Relative path name containing the location of the junction database. This valueis relative to the value set in server-root key in the [server] stanza.


Default value: jct

Example: junction-db = jct

jmt-map = relative_pathname

Relative path name containing the location of the Junction-to- RequestMapping Table (JMT). This value is relative to the value set in server-root keyin the [server] stanza.

The administrator can rename this file if necessary. The file name can be anyfile name valid for the operating system file system.


Default value: lib/jmt.conf

Example: jmt-map = lib/jmt.conf

http-timeout = number_of_seconds

Integer value indicating the timeout, in seconds, for sending to and readingfrom a TCP junction. The minimum value is 1.

WebSEAL does not impose a maximum value. See the discussion of maximumvalues for integers in “Guidelines for configuring stanzas” on page 241.


Default value: 120

Example: http-timeout = 120

https-timeout = number_of_seconds

Integer value indicating the timeout, in seconds, for sending to and readingfrom a Secure Socket Layer (SSL) junction. The minimum value is 1. WebSEALdoes not impose a maximum value. See the discussion of maximum values forintegers in “Guidelines for configuring stanzas” on page 241.


Default value: 120

Example: http-timeout = 120

ping-time = number_of_seconds


Integer value indicating the number of seconds between pings issued by theWebSEAL server. The pings are issued periodically in the background to verifythat junctioned WebSEAL servers are running.

The minimum value is 1. WebSEAL does not impose a maximum value. Seethe discussion of maximum values for integers in “Guidelines for configuringstanzas” on page 241.


Default value: 300

Example: ping-time = 300

basicauth-dummy-passwd = dummy_password

Global password used when supplying basic authentication data overjunctions that were created with the -b supply argument.

Passwords must consist of ASCII characters.


Default value: dummy

Example: basicauth-dummy-passwd = dummy

worker-thread-hard-limit = number_of_threads

Integer value indicating the limit, expressed as a percentage, of the totalworker threads that are to be used for processing requests for junctions. Thedefault value of 100 means that there is no limit.

When the value of worker-thread-hard-limit is less than 100, and the limit isexceeded, WebSEAL generates an error message.


Default value: 100

Example: worker-thread-hard-limit = 100

See “Allocating worker threads for junctions (junction fairness)” on page 56and the IBM Tivoli Access Manager Performance Tuning Guide.

worker-thread-soft-limit = number_of_threads

Integer value indicating the limit, expressed as a percentage, of the totalworker threads that are to be used for processing requests for junctions. Thedefault value of 100 means that there is no limit.

When the value of worker-thread-soft-limit is less than 100, and the limit isexceeded, WebSEAL generates a warning message.


Default value: 100

Example: worker-thread-soft-limit = 100

See “Allocating worker threads for junctions (junction fairness)” on page 56and the IBM Tivoli Access Manager Performance Tuning Guide.

io-buffer-size = number_of_bytes


Positive integer value indicating the buffer size, in bytes, for reading from andwriting to a junction.

The minimum value is 1. WebSEAL does not impose a maximum value. Seethe discussion of maximum values for integers in “Guidelines for configuringstanzas” on page 241.


Default value: 4096

Example: io-buffer-size = 4096

max-webseal-header-size = number_of_bytes

Integer value indicating the maximum size, in bytes, of HTTP headersgenerated by the WebSEAL server. Headers greater in size that this value aresplit across multiple HTTP Headers.

A value of zero (0) disables this support. WebSEAL imposes no maximum onthis value. See the discussion on maximum values for integer data types in“Guidelines for configuring stanzas” on page 241.


Default value: 0

Example: max-webseal-header-size = 0

crl-ldap-server = server_name

Name of the LDAP server to be referenced for Certificate Revocation List(CRL) checking during authentication across SSL junctions.



Example: crl-ldap-server = surf.santacruz.ibm.com

crl-ldap-server-port = port_number

Port number for communication with the LDAP server specified incrl-ldap-server. The LDAP server is referenced for Certificate Revocation List(CRL) checking during authentication across SSL junctions.

This stanza entry is optional. When crl-ldap-server is set, this stanza entry isrequired.


Example: crl-ldap-server-port = 389

crl-ldap-user = user_DN

Fully qualified distinguished name (DN) of an LDAP user who haspermissions to retrieve the Certificate Revocation List.

This stanza entry is optional. A null value for crl-ldap-user indicates that theSSL authenticator should bind to the LDAP server anonymously.


crl-ldap-user-password = user_password


The password for the LDAP user specified in the crl-ldap-user stanza entry.

This stanza entry is optional. When crl-ldap-server is set, this stanza entry isrequired.


Example: crl-ldap-user-password = mypassw0rd


Document filtering

[filter-url] stanza

HTML_tag = attribute

List of URL attributes that WebSEAL server filters in responses fromjunctioned servers.

Administrators can add additional entries when necessary. New entriesmust consist of valid HTML tags and attributes. When adding new entries,maintain alphabetical order.

This list is required. Although not all tags are required by all applications,the unused tags do no harm. The recommended practice is to leave thedefault entries in this list.

Default HTML tags and attributes:

A = HREFAPPLET = CODEBASEAREA = HREFBASE = HREFBGSOUND = SRCBLOCKQUOTE = CITEBODY = BACKGROUNDDEL = CITEDIV = EMPTYURLDIV = IMAGEPATHDIV = URLDIV = VIEWCLASSEMBED = PLUGINSPAGEEMBED = SRCFORM = ACTIONFRAME = LONGDESCFRAME = SRCHEAD = PROFILEIFRAME = LONGDESCIFRAME = SRCILAYER = BACKGROUNDILAYER = SRCIMG = SRCIMG = LOWSRCIMG = LONGDESCIMG = USEMAPIMG = DYNSRC

INPUT = SRCINPUT = USEMAPINS = CITEISINDEX = ACTIONISINDEX = HREFLAYER = BACKGROUNDLAYER = SRCLINK = HREFLINK = SRCOBJECT = CODEBASEOBJECT = DATAOBJECT = USEMAPQ = CITESCRIPT = SRCTABLE = BACKGROUNDTD = BACKGROUNDTH = BACKGROUNDTR = BACKGROUNDWM:CALENDARPICKER = FOLDERURLWM:CALENDARPICKER = IMAGEPREVARROWWM:CALENDARPICKER = IMAGENEXTARROWWM:CALENDARVIEW = FOLDERURLWM:MESSAGE = DRAFTSURLWM:MESSAGE = URLWM:NOTIFY = FOLDERWM:REMINDER = FOLDER?IMPORT = IMPLEMENTATION


Event handler filtering

[filter-events] stanza

HTML_tag = event_handler

List of HTML tags used by WebSEAL to identify and filter absolute URLsembedded in JavaScript. JavaScript allows HTML tags to contain eventhandlers that are invoked when certain events occur. For example, the HTMLtag:

<form onsubmit="javascript:doSomething()">

causes the JavaScript function doSomething() to be called when the form issubmitted.

The entries in this stanza are used to identify HTML tags that may containJavaScript code. When such a tag is discovered, WebSEAL searches the tagto filter any absolute URLs embedded in the JavaScript. For example, if the″form onsubmit″ example looked like:

<form onsubmit="javaScript:doSomething(’http://junction.server.com’)">

WebSEAL HTML filtering would modify the tag to look like:

<form onsubmit="javaScript:doSomething(’/junction’)">

Administrators can add additional entries when necessary. New entriesmust consist of valid HTML tags that are built into JavaScript. When addingnew entries, maintain alphabetical order.

This list is required. Although not all tags are required by all applications,the unused tags do no harm. The recommended practice is to leave thedefault entries in this list.

Default HTML tags and event handlers:

A = ONCLICKA = ONDBLCLICKA = ONMOUSEDOWNA = ONMOUSEOUTA = ONMOUSEOVERA = ONMOUSEUPAREA = ONCLICKAREA = ONMOUSEOUTAREA = ONMOUSEOVERBODY = ONBLURBODY = ONCLICKBODY = ONDRAGDROPBODY = ONFOCUSBODY = ONKEYDOWNBODY = ONKEYPRESSBODY = ONKEYUPBODY = ONLOADBODY = ONMOUSEDOWNBODY = ONMOUSEUPBODY = ONMOVEBODY = ONRESIZEBODY = ONUNLOADFORM = ONRESETFORM = ONSUBMITFRAME = ONBLURFRAME = ONDRAGDROPFRAME = ONFOCUSFRAME = ONLOADFRAME = ONMOVE

FRAME = ONRESIZEFRAME = ONUNLOADIMG = ONABORTIMG = ONERRORIMG = ONLOADINPUT = ONBLURINPUT = ONCHANGEINPUT = ONCLICKINPUT = ONFOCUSINPUT = ONKEYDOWNINPUT = ONKEYPRESSINPUT = ONKEYUPINPUT = ONMOUSEDOWNINPUT = ONMOUSEUPINPUT = ONSELECTLAYER = ONBLURLAYER = ONLOADLAYER = ONMOUSEOUTLAYER = ONMOUSEOVERSELECT = ONBLURSELECT = ONCHANGESELECT = ONFOCUSTEXTAREA = ONBLURTEXTAREA = ONCHANGETEXTAREA = ONFOCUSTEXTAREA = ONKEYDOWNTEXTAREA = ONKEYPRESSTEXTAREA = ONKEYUPTEXTAREA = ONSELECT


Scheme filtering

[filter-schemes] stanza

scheme = scheme_name

List of URL schemes that are not to be filtered by WebSEAL. A scheme is aprotocol identifier.

This list is utilized when WebSEAL encounters a document containing abase URL. For example:

<head><base href="http://www.foo.com"></head><a href="mailto:[email protected]>Send me mail",/a>

WebSEAL identifies the scheme mailto because this scheme is included bydefault in the [filter-schemes] stanza. If mailto was not identified as ascheme, WebSEAL would interpret it as document and perform normalfiltering. WebSEAL would then rewrite the link as:

<a href="http://www.foo.com/mailto:[email protected]"

This would be incorrect.

WebSEAL provides a set of default schemes. The administrator can extendthe list if additional protocols are used. Recommended practice is to notdelete entries from this list.

Default list entries:

scheme = filescheme = ftpscheme = httpsscheme = mailtoscheme = newsscheme = telnet


MIME types and header filteringv [filter-content-types]

v [filter-request-headers]

[filter-content-types] stanza

type = type_name

List of entries that specify MIME types to be filtered by WebSEAL whenreceived from junctioned servers.

Administrators can add additional MIME types that refer to a documentthat contains HTML or HTML-like content.

This list of stanza entries is required. Do not remove the default entries.

Default list entries:

type = text/htmltype = text/vnd.wap.wml

See “Filtering URLs in responses” on page 180

[filter-request-headers] stanza

header = header_name

List of HTTP headers that WebSEAL filters before sending the request to ajunctioned server. A default list is built-in to WebSEAL. The default entriesare not included in the configuration file.

Default list:

hostconnectionproxy-connectionexpectteiv-ssl-jctiv-useriv_useriv-groupsiv_groupsiv-credsiv_credsiv_remote_addressiv-remote-address

The addition of new entries in this stanza is optional. For example, anadministrator could add the header accept-encoding. This would instructWebSEAL to remove any accept-encoding headers from requests beforeforwarding the request to the junction. The removal of theaccept-encoding header would cause the junction server to return thedocument in an unencoded form, allowing WebSEAL to filter thedocument if necessary.

New entries must consist of valid HTTP headers.


Script filteringv [script-filtering]

v [preserve-cookie-names]

[script-filtering] stanza

script-filter = {yes|no}

Enables or disables script filtering support. A value of yes meansenabled. A value of no means disabled. When enabled, WebSEAL canfilter absolute URLs encountered in scripts such as JavaScript.

This stanza entry is optional, but is included by default. When it is notdeclared, the value for the script-filter functionality is no by default.

Default value: no

Example: script-filter = no

See “Modifying absolute URLs with script filtering” on page 181.

rewrite-absolute-with-absolute = {yes|no}

Enables WebSEAL to rewrite absolute URLs with new absolute URLs thatcontain the protocol, host, and port (optionally) that represent how theuser accessed the WebSEAL server.


There is no default value, but if the entry is not specified in thisconfiguration file, WebSEAL assumes the value is no.

Example: rewrite-absolute-with-absolute = no

See “Modifying absolute URLs with script filtering” on page 181.

hostname-junction-cookie = {yes|no}

Enables WebSEAL to uniquely identify the cookie used for resolvingunfiltered links. This is used when another WebSEAL server has createda junction to this WebSEAL server, using a WebSEAL to WebSEALjunction.

This stanza entry is optional, but it is included by default in theconfiguration file.

Default value: no

Example: hostname-junction-cookie = no

[preserve-cookie-names] stanza

name = cookie_name


List of specific cookie names that WebSEAL must not modify.

WebSEAL, by default, modifies the names of cookies returned inresponses from junctions created with pdadmin using –j flag. WebSEALalso by default modifies the name of cookies listed in the junctionmapping table (JMT). This default modification is done to preventnaming conflicts with cookies returned by other junctions.

When a front-end application depends on the names of specific cookies,the administrator can disable the modification of cookie names for thosespecific cookies. The administrator does this by listing the cookies in thisstanza.

When entering a value for cookie_name, use ASCII characters.

There are no cookie names set by default.

Example:

Name = JSESSIONID


Global Sign-On cache

[gso-cache] stanza

gso-cache-enabled = {yes|no}

Enables or disables the Global Sign-on (GSO) cache.


Default value: no

Example: gso-cache-enabled = no

gso-cache-size = number_of_entries

Integer value indicating the number of entries allowed in the GSOcache. The value must be greater than or equal to zero. Zero meansthat there is no limit on the size of the GSO cache. This is notrecommended.

WebSEAL does not impose a maximum value. Choose yourmaximum value to stay safely within the bounds of your availablesystem memory. See the discussion of maximum values for integertypes in “Guidelines for configuring stanzas” on page 241.

This stanza entry is required, but is ignored when GSO caching isdisabled.

Default value: 1024

Example: gso-cache-size = 1024

gso-cache-entry-lifetime = number_of_seconds

Integer value that specifies the lifetime, in seconds, of a GSO cacheentry. The value must be greater than or equal to zero (0). A value of0 means that entries are not removed from the GSO cache due totheir entry lifetime being exceeded. However, they may still beremoved due to either the gso-cache-size being exceeded or thegso-cache-entry-idle-timeout stanza entry being exceeded.

WebSEAL does not impose a maximum value. See the discussion ofmaximum values for integer types in “Guidelines for configuringstanzas” on page 241


Default value: 900

Example: gso-cache-entry-lifetime = 900

gso-cache-entry-idle-timeout = number_of_seconds


Integer value that specifies the timeout, in seconds, for cache entriesthat are idle. The value must be greater than or equal to zero (0). Avalue of 0 means that entries are not removed from the GSO cachedue to inactivity. However, they may still be removed due to eitherthe gso-cache-size being exceeded or the gso-cache-entry-lifetimestanza entry being exceeded.



Default value: 120

Example: gso-cache-entry-idle-timeout = 120


Lightweight Third Party Authentication cache

[ltpa-cache] stanza

ltpa-cache-enabled = {yes|no}

Enables or disables the Lightweight Third Party Authenticationcache. A value of yes enables caching. A value of no disables caching.


Default value: yes

Example: ltpa-cache-enabled = yes

ltpa-cache-size = number_of_entries

Integer value indicating the number of entries allowed in the LTPAcache. The value must be greater than or equal to zero. Zero meansthat there is no limit on the size of the LTPA cache. This is notrecommended.

WebSEAL does not impose a maximum value. Choose yourmaximum value to stay safely within the bounds of your availablesystem memory. See the discussion of maximum values for integertypes in “Guidelines for configuring stanzas” on page 241.

This stanza entry is required, but is ignored when LTPA caching isdisabled.

Default value: 4096

Example: ltpa-cache-size = 4096

ltpa-cache-entry-lifetime = number_of_seconds

Integer value that specifies the lifetime, in seconds, of a LTPA cacheentry. The value must be greater than or equal to zero (0). A value of0 means that entries are not removed from the LTPA cache due totheir entry lifetime being exceeded. However, they may still beremoved due to either the ltpa-cache-size being exceeded or theltpa-cache-entry-idle-timeout stanza entry being exceeded.



Default value: 3600

Example: ltpa-cache-entry-lifetime = 3600

ltpa-cache-entry-idle-timeout = number_of_seconds


Integer value that specifies the timeout, in seconds, for cache entriesthat are idle. The value must be greater than or equal to zero (0). Avalue of 0 means that entries are not removed from the LTPA cachedue to inactivity. However, they may still be removed due to eitherthe ltpa-cache-size being exceeded or the ltpa-cache-entry-lifetime stanza entry being exceeded.



Default value: 600

Example: gso-cache-entry-idle-timeout = 600


Logging

[logging] stanza

server-log = fully_qualified_path

Fully qualified path to the server error log file.


The default location is log/webseald.log, located under the WebSEALinstallation directory.

Example on UNIX:

server-log = /var/pdweb/log/msg__webseald.log

max-size = number_of_bytes

Integer value indicating the size limit of the log files. The size limit is alsoreferred to as the rollover threshold. When the log file reaches this threshold,the original log file is renamed and a new log file with the original namewill be created.

When the value is zero (0), no rollover log file is created.

When the value is a negative integer, the logs are rolled over daily,regardless of the size.

When the value is a positive integer, the value indicates the maximum size,in bytes, of the log file before the rollover occurs. The allowable range isfrom 1 byte to 2 megabytes

An integer value indicating the size limit of log files. This value applies tothe request, referer, and agent logs.


Default value: 2000000

Example: max-size = 2000000

flush-time = number_of_seconds

Integer value indicating the frequency, in seconds, to force a flush of logbuffers.

The minimum value is 1 second.

The maximum value is 600 seconds.


Default value: 20

Example: flush-time = 20

requests = {yes|no}


Enables or disables the requests log. This log records standard logging ofHTTP requests. The value yes enables requests logging. The value nodisables requests logging.


Default value: yes

Example: requests = yes

For more information, see “Configuring default HTTP logging” on page 42.

requests-file = fully_qualified_path

Fully qualified path to the request log file.


The default location is www/log/request.log, located under the WebSEALinstallation directory.

Example on UNIX:

requests-file = /var/pdweb/www/log/request.log

referers = {yes|no}

Enables or disables the referers log. This log records the Referer: header ofeach HTTP request. The value yes enables referers logging. The value nodisables referers logging.


Default value: yes

Example: referers = yes


referers-file = fully_qualified_path

Fully qualified path to the referers log file.


The default location is www/log/referer.log, located under the WebSEALinstallation directory.

Example:

referers-file = /var/pdweb/www/log/referer.log

agents = {yes|no}

Enables or disables the agents log. This log records the contents of theUser_Agent: header of each HTTP request. The value yes enables agentslogging. The value no disables agents logging.


Default value: yes

Example: agents = yes


agents-file = fully_qualified_path


Fully qualified path to the agents log file.


The default location is www/log/agent.log, located under the WebSEALinstallation directory.

Example: agents-file = /var/pdweb/www/log/agent.log

gmt-time = {yes|no}

Enables or disables logging requests using Greenwich Mean Time (GMT)instead of the local timezone. A value of yes means to use GMT. A value ofno means to use the local timezone.


Default value: no

Example: gmt-time = no


Auditing

[aznapi-configuration] stanza

logclientid = webseald

Name of the daemon whose activities are audited through use ofauthorization API logging.


Default value: webseald

Example: logclientid = webseald

logsize = number_of_bytes

Integer value indicating the size limit of audit log files. The size limit is alsoreferred to as the rollover threshold. When the audit log file reaches thisthreshold, the original audit log file is renamed and a new log file with theoriginal name will be created.

When the value is zero (0), no rollover log file is created.

When the value is a negative integer, the logs are rolled over daily,regardless of the size.

When the value is a positive integer, the value indicates the maximum size,in bytes, of the audit log file before the rollover occurs. The allowable rangeis from 1 byte to 2 megabytes


Default value: 2000000

Example: max-size = 2000000

logflush = number_of_seconds

Integer value indicating the frequency, in seconds, to force a flush of logbuffers.

The minimum value is 1 second.

The maximum value is 600 seconds.


Default value: 20

Example: logflush = 20

logaudit = {yes|true|no|false}

Enables or disables auditing. The values yes or true enable auditing. Thevalues no or false disable auditing.

By default, when auditing is enabled using this key, and no configured auditevents are specified by auditcfg, all auditable events are captured.


Default value: no

Example: logaudit = no

auditlog = fully_qualified_path


Location of the audit trail file for WebSEAL.

The fully qualified path value represents an alphanumeric string.

This stanza entry is required when auditing is enabled.

The default value is set during WebSEAL configuration by appendinglog/aznapi_webseald.log to the path for the WebSEAL installation directory.

Example on UNIX:

auditlog = /var/pdweb/log/aznapi_webseald.log

auditcfg = {azn|authn|http}

Indicates the components for which auditing of events is configured. Toenable component specific audit records, add the appropriate definition.

Valid values are:azn Capture authorization events.authn Capture authentication events.http Capture HTTP events. These correspond to the events logged by the

request, referer, and agent logging clients.

This stanza entry is optional for WebSEAL. However, this stanza entry isrequired when auditing is enabled (logaudit = yes).

There is no default value for WebSEAL, because auditing is disabled bydefault.

Create a separate stanza entry for each component to be activated. Thecomponents are included in the default configuration file but are commentedout. To activate a commented out entry, remove the pound sign (#) from thestart of the entry.

Example:

auditcfg = azn#auditcfg = authn#auditcfg = http

logcfg = category:{stdout|stderr|file|pipe|remote}[ [parameter=value ][,parameter=value]...]


Specifies event logging for the specified category.

For WebSEAL, the categories are:

v azn

Authorization events

v authn

Credentials acquisition authentication.

v http

All HTTP logging information

v http.clf

HTTP request information in common log format.

v http.ref

HTTP Referer header information

v http.agent

HTTP User_Agent header information

v http.cof

NCSA combined format which captures HTTP request information (withtime stamp) and appends the quoted referer and agent strings to thestandard common log format.

Event logging supports a number of output destination types:

{stdout|stderr|file|pipe|remote}

WebSEAL auditing typically is configured to use the file type.

Each event logging type supports a number of optional parameter = valueoptions.

For more information about output destination types and optional parameter= value settings, see the IBM Tivoli Access Manager Base Administrator’s Guide.



Example entry for HTTP request.log (common log format) — entered as onelong line:

logcfg = http.clf:file path=request_file, \flush=time, rollover=max_size, \log=clf,buffer_size=8192,queue_size=48

For more information, see “Configuring HTTP logging using event logging”on page 45.


Policy database

[aznapi-configuration] stanza

db-file = fully_qualified_path

Fully qualified path to the WebSEAL policy database cache file.


The default value is a path name that has db/webseald.db appended to theWebSEAL installation directory path.

Example on UNIX:

db-file = /var/pdweb/db/webseald.db

cache-refresh-interval = {disable|default|number_of_seconds}

Poll interval between checks for updates to the master authorization server.

Valid values are:disable The interval value in seconds is not set.default When value is to default, an interval of 600 seconds is used.num_seconds

Integer value indicating the number of seconds between polls to themaster authorization server to check for updates.

The minimum number of seconds is 0. There is no maximum value. See thediscussion of maximum values for integer data types in “Guidelines forconfiguring stanzas” on page 241.


The default value for WebSEAL is disable

Example: cache-refresh-interval = disable

listen-flags = {enable|disable}

Enables or disables the reception by WebSEAL of policy cache updatenotifications from the master authorization server. A value of enable activatesthe notification listener. A value of disable deactivates the notification listener.


Default value: enable

Example: listen-flags = enable

mode = local

Specifies the authorization API client mode for the WebSEAL server. Only localmode is supported. This stanza entry is set by svrsslcfg during WebSEALconfiguration and should not be changed by the administrator.


Default value: local

Example: mode = local

azn-server-name = webseal_server_name


Specifies the WebSEAL server name for use when contacting the policy serveras an authorization API client.

This stanza entry is set during WebSEAL configuration and is typically notchanged by the administrator.


The default value consists of a combination of webseald with the hostname,separated by a hyphen (-):

Example: azn-server-name = webseald-surf

pd-user-name = webseal_server_identity

Tivoli Access Manager identity of the WebSEAL server.

This stanza entry is set by svrsslcfg during WebSEAL configuration and shouldnot be changed by the administrator.


The default value consists of a combination of webseald with the hostname,separated by a forward slash (/):

Example: pd-user-name = webseald/surf

pd-user-pwd = password

Password for the authorization API client identity. This identity represents theWebSEAL server daemon.

This stanza entry is set by svrsslcfg during WebSEAL configuration and shouldnot be changed by the administrator.



Example: pd-user-pwd = ZsLuBKSo


Entitlements services

[aznapi-entitlement-services] stanza

service-id = library_base_name

The Tivoli Access Manager authorization API provides a framework for addingentitlements services into the authorization decision making process. Theauthorization API obtains knowledge of active entitlements services by readingentries from stanza files, such as this one, and by reading initialization stanzaentries that are sent to the API upon startup.

WebSEAL uses a built-in entitlements service that is supplied as a shared library.This configuration file entry provides a service-id of AZN_ENT_EXT_ATR.Note: The Authorization API uses the service-id to denote the presence of aservice that is to be loaded at API initialization time. For more information, seeIBM Tivoli Access Manager Authorization C API Developer’s Reference.

This configuration file entry also specifies the name of the shared library:azn_ent_ext_attr.

The file name of the azn_ent_ext_attr shared library, and its location within thefile system, is specific to each operating system. For example, on Windowsplatforms, the names of shared libraries contain the suffix .dll. However, thebase name for the library is common across operating systems. This value isspecified in library_base_name.

WebSEAL reads the library_base_name and then uses an internal search algorithmto find the appropriate shared library by cycling through the known prefixes,suffixes, and file locations.

This stanza entry is required. Administrator should not change this entry.

For more information on entitlements services, see the IBM Tivoli Access ManagerAuthorization C API Developer’s Reference

WebSEAL contains one default entry for an entitlements service:

AZN_ENT_EXT_ATTR = azn_ent_ext_attr


Policy serverv [policy-director]

v [manager]

[policy-director] stanza

config-file = /opt/PolicyDirector/etc/pd.conf

Path name to the configuration file for the Tivoli Access Manager policyserver for the domain in which the WebSEAL server is configured. Thisstanza entry is set by WebSEAL configuration and should not be modified.


Default value of the configuration file path consists of the etc/pd.confappended to the Tivoli Access Manager installation directory.

Example on UNIX:

config-file = /opt/PolicyDirector/etc/pd.conf

[manager] stanza

master-host = policy_server_hostname

Hostname of the Tivoli Access Manager policy server for the domain towhich this WebSEAL server belongs.


There is no default value. This stanza entry is set by svrsslcfg duringWebSEAL configuration. Administrators should not modify this stanzaentry.

Example: master-host = server77

master-port = port_number

TCP port that the policy server host uses to communicate with WebSEAL.



Example: master-port = 7135

master-dn = LDAP_DN

Fully qualified DN of the policy server daemon for this Tivoli AccessManager secure domain.



Example:

master-dn = CN=ivmgrd/master,O=Policy Director,C=US


Appendix B. WebSEAL junction reference

The pdadmin utility provides an interactive command-line prompt from whichyou can perform WebSEAL junction tasks. This section describes the pdadminserver task command for creating WebSEAL junctions. Refer to the IBM TivoliAccess Manager Command Reference for complete syntax information for thepdadmin utility.

Topic Index:v “Using pdadmin to create junctions” on page 329v “The junction commands” on page 330v “Create a new junction for an initial server” on page 331v “Add a server to an existing junction” on page 333

Using pdadmin to create junctionsBefore using pdadmin, you must login to a secure domain as the sec_masteradministration user.

For example:

UNIX:# pdadminpdadmin> loginEnter User ID: sec_masterEnter Password:pdadmin>

Windows:MSDOS> pdadminpdadmin> loginEnter User ID: sec_masterEnter Password:pdadmin>

To create WebSEAL junctions, you use the pdadmin server task create command:pdadmin> server task <server-identification> create <options>

The server-identification component of this command is a combination of the AccessManager server used by this command and the Access Manager server host name.<Access-Manager-server>-<host-name>

Syntax for a single WebSEAL server:

For Access Manager WebSEAL, the Access-Manager-server is webseald and thehost-name is the name of the WebSEAL server machine:pdadmin> server task webseald-<host-name> create <options>

The initial WebSEAL server installed on a machine is always named after themachine name. For example, if the machine name is cruz, the server identificationfor a single WebSEAL installation is:webseald-cruz


Syntax for multiple WebSEAL instances:

If you install multiple WebSEAL server instances on the same machine, theAccess-Manager-server is the configured name of the WebSEAL server instance,followed by webseald, followed by the host name:<instance-name>-webseald-<host-name>

For example, if the configured names for two additional WebSEAL instances arewebseal2 and webseal3, the server identifications appear as:webseal2-webseald-cruzwebseal3-webseald-cruz

Use the server list command to verify server identification:pdadmin> server listwebseald-cruzwebseal2-webseald-cruzwebseal3-webseald-cruz

Mandatory junction command options:

The mandatory command options required to create a basic WebSEAL junctioninclude:v Host name of the back-end application server (–h option)v Junction type — tcp, ssl, tcpproxy, sslproxy, local (–t option)v Junction point (mount point)pdadmin> server task webseald-<host-name> create -t <type>-h <host-name> <jct-point>

The junction commandsThe following junction commands are available with pdadmin server task:

Command Description

create Create a new junction for an initial server.

add Add additional server(s) to an existing junction point.

remove Remove a server from a junction point.

Syntax: remove –i <server-id> <junction-point>

Use the show command to determine the ID of a particularserver.

delete Remove the junction point.

Syntax: delete <junction-point>

list List all junction points on this server.

Syntax: list

show Display the details of a junction.

Syntax: show <junction-point>


Command Description

jmt load jmt clear The jmt load command provides WebSEAL with junctionmapping table data (jmt.conf) to handle processing ofdynamically generated server-relative URLs.

The jmt clear command removes junction mapping table datafrom WebSEAL.

help List junction commands.

Syntax: help

help <command> Display detailed help on a specific junction commands.

exit Exits the pdadmin utility.

Syntax: exit

These commands, and associated options, are discussed in the following sections.

Create a new junction for an initial serverOperation: Creates a new junction point and junctions an initial server.

Syntax:create -t <type> -h <host-name> [<options>] <junction-point>

Junction Type

–t <type> **Required**

Type of junction. One of: tcp, ssl, tcpproxy, sslproxy,local.

Default port for –t tcp is 80. Default port for –t ssl is443.

Host Name

–h <host-name> **Required**

The DNS host name or IP address of the targetback-end server.

Options

Mutual Authentication Over SSL

–K <key-label> WebSEAL uses client certificate to authenticate toback-end server.

–B WebSEAL uses BA header information to authenticateto back-end server. Requires –U, and –W options.

–U <″username″> WebSEAL username. Use with –B to send BA headerinformation to back-end server.

–W <″password″> WebSEAL password. Use with –B to send BA headerinformation to back-end server.

–D <″DN″> Specify Distinguished Name of back-end servercertificate. This value, matched with actual certificateDN enhances authentication.

Proxy junction options (requires –t tcpproxy or –t sslproxy)

–H <host-name> The DNS host name or IP address of the proxy server.

Appendix B. WebSEAL junction reference 331


Supplying BA header information

–b <BA-value> Defines how the WebSEAL server passes HTTP BAauthentication information to the back-end server.One of:

filter (default), ignore, supply, gso

General TCP and SSL junction options

–c <id-types> Insert Access Manager client identity in HTTPheaders across the junction. The id-types argumentcan include any combination of the following AccessManager HTTP header types: iv-user, iv-user-l,iv-groups, iv-creds, all.

–i WebSEAL server treats URLs as case insensitive.

–j Supply junction identification in a cookie to handlescript generated server-relative URLs.

–k Send session cookie to back-end portal server.

–p <port> TCP port of the back-end third-party server. Default is80 for TCP junctions; 443 for SSL junctions.

–q <location> Relative path for query_contents script. By default,Access Manager looks for query_contents in/cgi_bin/. If this directory is different or thequery_contents file name is different, use this optionto indicate to WebSEAL the new URL to the file.Required for back-end Windows servers.

–r Insert incoming IP address in HTTP header across thejunction.

–s Specifies that the junction should support statefulapplications. By default, junctions are not stateful.

–T <resource/resource-group>

Name of GSO resource or resource group. Requiredfor and used only with –b gso option.

–u <UUID> Specifies the UUID of a back-end server connected toWebSEAL via a stateful junction (–s).

–v <virtual-host-name>[:<port>]

Virtual host name represented on the back-end server.This option supports a virtual host setup on theback-end server.

You use –v when the back-end junction server expectsa host name header because you are junctioning toone virtual instance of that server. The default HTTPheader request from the browser does not know thatthe back-end server has multiple names and multiplevirtual servers. You must configure WebSEAL tosupply that extra header information in requestsdestined for a back-end server set up as a virtualhost.

–w Win32 filesystem support.

Junction fairness

–l <percent-value> Defines the soft limit for consumption of workerthreads.

For performance considerations, see the IBM TivoliAccess Manager Performance Tuning Guide.


–L <percent-value> Defines the hard limit for consumption of workerthreads.

For performance considerations, see the IBM TivoliAccess Manager Performance Tuning Guide.

LTPA junctions

–A Enable and disable LTPA junctions.

–F <″keyfile″> Location of key file used to encrypt LTPA cookie data.

–Z <″keyfile-password″> Password for the key file

WebSEAL-to-WebSEAL SSL junctions

–C Mutual authentication between a front-end WebSEALserver and a back-end WebSEAL server over SSL.Requires –t ssl or –t sslproxy type.

Forms single sign-on

–S <config-file> Location of forms single sign-on configuration file.

Local junction options (use with –t local)

–d <dir> Local directory to junction. **Required.**

–f Force the replacement of an existing junction.

Junction Point

Location in the WebSEAL namespace to create the junction.

Add a server to an existing junctionOperation: Adds a server to an existing junction point.

Syntax:add -h <host-name> [<options>] <junction-point>

Host Name

–h <host-name> **Required**

The DNS host name or IP address of the targetback-end server.

Options

Mutual Authentication Over SSL

–D <″DN″> Specify Distinguished Name of back-end servercertificate. This value, matched with actual certificateDN enhances authentication.

Proxy junction options (required with –t tcpproxy and –t sslproxy)

–H <host-name> DNS host name or IP address of the proxy server.


General TCP and SSL junction options

–i WebSEAL server treats URLs as case insensitive.

–p <port> TCP port of back-end third-party server. Default is 80for TCP junctions; 443 for SSL junctions.

Appendix B. WebSEAL junction reference 333

–q <url> Relative URL for query_contents script. AccessManager looks for query_contents in /cgi_bin/. Ifthis directory is different or the query_contents filerenamed, use this option to indicate to WebSEAL thenew URL to the file.

–u <UUID> Specifies the UUID of a back-end server connected toWebSEAL via a stateful junction (–s).

–v <virt-host-name> Virtual host name represented on the back-end server.This option supports a virtual host setup on theback-end server.

You use –v when the back-end junction server expectsa host name header because you are junctioning toone virtual instance of that server. The default HTTPheader request from the browser does not know thatthe back-end server has multiple names and multiplevirtual servers. You must configure WebSEAL tosupply that extra header information in requestsdestined for a back-end server set up as a virtualhost.

–w Win32 filesystem support.

Junction Point

Add server to this existing junction point.


Appendix C. Using the pdbackup utility for WebSEAL

The pdbackup utility allows you to back up and restore Access Manager data. Thepdbackup utility uses, as an argument, a backup list file that specifies the files anddirectories that require backing up. Each major Access Manager component (suchas Base and WebSEAL) has its own list file. The amwebbackup.lst file specifies theWebSEAL files and directories that are backed up by the pdbackup utility.

This appendix describes how to use the pdbackup utility to back up and restoreWebSEAL data. The complete reference for the pdbackup utility is located in theIBM Tivoli Access Manager Command Reference.

Functionality

Backing up data:

The pdbackup utility backs up the list of files and directories contained in theWebSEAL backup list file (amwebbackup.lst).

UNIX:

By default, the amwebbackup.lst file resides in:/opt/pdweb/etc/

By default, the resulting backup archive is stored as a single .tar file in the/var/PolicyDirector/pdbackup directory.

The default .tar file name (amwebbackup) contains a date and time stamp:amwebbackup_<date>.<time>.tar

The date format specifies—in the following order—the day, month, and year. Thefollowing format is used:ddmmmyyyy

The time format specifies—in the following order—the hour and minutes. Thefollowing format is used:hh_mm

The default format of the .tar file appears as follows:amwebbackup.lst_ddmmyyy.hh_mm.tar

For example:amwebbackup.lst_30jul2002.10_39.tar

By default, the .tar file is stored in the following directory:/var/PolicyDirector/pdbackup

Alternatively, you can specify:v A custom file name for the .tar file (use the –file option)

This custom file name does not contain a date and time stamp.


v A custom directory location for the .tar file (use the –path option)

Windows:

By default, the amwebbackup.lst file resides in:C:\Program Files\Tivoli\PDWeb\etc\

By default, the resulting backup archive is stored as a directory tree in theC:\Program Files\Tivoli\Policy Director\pdbackup\ directory. The default .dirdirectory name (amwebbackup) contains a date and time stamp:amwebbackup_<date>.<time>.dir

The date format specifies—in the following order—the day, month, and year. Thefollowing format is used:ddmmmyyyy

The time format specifies—in the following order—the hour and minutes. Thefollowing format is used:hh_mm

The default format of the .dir directory appears as follows:amwebbackup.lst_ddmmyyy.hh_mm.dir

For example:amwebbackup.lst_30jul2002.10_39.dir

The .dir directory contains a sub-directory and a file:%C%Registry

The %C% directory contains the complete backup tree. The Registry file stores theregistry keys (.reg extensions).

Alternatively, you can specify:v A custom file name for the .dir directory (use the –file option)

This custom file name does not contain a date and time stamp.v A custom directory location for the .dir directory (use the –path option)

Restoring dataUNIX:

Archived files and directories are restored from the .tar file to the /opt/pdwebdirectory.

Windows:

Archived files are restored to their original installation directory locations.

SyntaxThe complete reference for the pdbackup utility is located in the IBM Tivoli AccessManager Command Reference.


pdbackup –action backup –list <backup-list-pathname> \[–path <custom-storage-directory>] [–file <custom-backup-filename>] [–usage] [–?]

pdbackup –action restore –file <archive-file-pathname> \[–path <custom-restore-directory>] [–usage] [–?]

Table 5. pdbackup command options and arguments

Option Description

–action [backup|restore|extract] Specifies backup, restore, or extractoperation.

–list <backup-list-filename> Specifies the fully qualified path to thebackup list file (amwebbackup.lst).

–path <custom-directory-name> For backup, specifies a custom archivedirectory location.

–file <custom-file-pathname> For backup, specifies a custom name for thearchive file.

For restore, specifies the fully qualified pathto the archive file that is to be restored.

You can use short versions of the command option names, but the abbreviationmust be unambiguous. For example, you can type a for action. However, valuesfor arguments to these options cannot be abbreviated.

Examples

UNIX examples1. The following example performs a standard back up with default values:

pdbackup -a backup -l /opt/pdweb/etc/amwebbackup.1st

This results in a file named amwebbackup.1st_<date>.<time>.tar that is storedin the /var/PolicyDirector/pdbackup directory.

2. The following example performs a back up and stores the default archive file inthe /var/backup directory:pdbackup -a backup -l /opt/pdweb/etc/amwebbackup.1st -p /var/backup

This results in a file named amwebbackup.1st_<date>.<time>.tar located in the/var/pdbackup directory.

3. The following example performs a back up and creates an archive file namedamwebarchive.tar:pdbackup -a backup -l /opt/pdweb/etc/amwebbackup.1st -f amwebarchive

The default archive extension (.tar) is appended to the custom amwebarchivefile name. This file is stored in the default /var/PolicyDirector/pdbackupdirectory.

4. The following example restores the archive file from the default directorylocation:pdbackup -a restore -f amwebbackup.1st_29Aug2002.07_24.tar

5. The following example restores the archive file from the /var/pdback directory:pdbackup -a restore -f /var/pdback/amwebbackup.1st_29Aug2002.07_25.tar

Appendix C. Using the pdbackup utility for WebSEAL 337

Windows examples1. The following example performs a standard backup with default values:

pdbackup -a backup -l <install-dir>\etc\amwebbackup.1st

This results in a file named amwebbackup.1st_<date>.<time>.tar located in the<install-dir>\pdbackup directory.

2. The following example performs a back up using the default archive file nameand stores the file in the C:\pdback directory:pdbackup -a backup -l <install-dir>\etc\amwebbackup.1st -path c:\pdback

3. The following example performs a back up and creates a file namedpdarchive.dir:pdbackup -a backup -l <install-dir>\etc\amwebbackup.1st -f pdarchive

The default archive extension (.dir) is applied to the custom pdarchive filename. The file is stored in the default <install-dir>\pdbackup directory.

4. The following example performs a back up to the \pdback directory on the F:drive:pdbackup -a backup -l amwebbackup.1st -p f:\pdback

5. The following example restores the archive file from the default directory:pdbackup -a restore -f <instl-dir>\pdbackup\amwebbackup.1st_29Jun2002.07_24.dir

6. The following example restores files from the H:\pdbackup directory:pdbackup -a restore -f h:\pdbackup\amwebbackup.1st_29Jun2002.07_25.dir

Contents of amwebbackup.lst[UNIX FILES]# fully qualified file names ; Required Flag (;R on the end - if file is required)./opt/pdweb/.configure./opt/pdweb/etc./opt/pdweb/www/jct./var/pdweb/keytabs./var/pdweb/www/certs

[UNIX CONF FILES]# configuration files that specify a file to include# file:stanza:option/opt/pdweb/etc/webseald.conf:server:server-root/opt/pdweb/etc/webseald.conf:server:ldap-server-config/opt/pdweb/etc/webseald.conf:server:ssl-keyfile/opt/pdweb/etc/webseald.conf:uraf-ad:ad-server-config/opt/pdweb/etc/webseald.conf:uraf-domino:domino-server-config/opt/pdweb/etc/webseald.conf:ldap:webseal-cert-keyfile/opt/pdweb/etc/webseald.conf:ldap:webseal-cert-keyfile-stash/opt/pdweb/etc/webseald.conf:ldap:ssl-keyfile/opt/pdweb/etc/webseald.conf:ldap:ssl-keyfile-stash/opt/pdweb/etc/webseald.conf:failover:failover-cookies-keyfile/opt/pdweb/etc/webseald.conf:e-community-sso:intra-domain-key/opt/pdweb/etc/webseald.conf:authentication-mechanisms:passwd-cdas/opt/pdweb/etc/webseald.conf:authentication-mechanisms:passwd-uraf/opt/pdweb/etc/webseald.conf:authentication-mechanisms:token-cdas/opt/pdweb/etc/webseald.conf:authentication-mechanisms:cert-ssl/opt/pdweb/etc/webseald.conf:authentication-mechanisms:http-request/opt/pdweb/etc/webseald.conf:authentication-mechanisms:cdsso-create/opt/pdweb/etc/webseald.conf:authentication-mechanisms:cdsso-consume/opt/pdweb/etc/webseald.conf:authentication-mechanisms:passwd-strength/opt/pdweb/etc/webseald.conf:authentication-mechanisms:cred-ext-attrs/opt/pdweb/etc/webseald.conf:authentication-mechanisms:su-password/opt/pdweb/etc/webseald.conf:authentication-mechanisms:su-token-card/opt/pdweb/etc/webseald.conf:authentication-mechanisms:su-certificate


/opt/pdweb/etc/webseald.conf:authentication-mechanisms:su-http-request/opt/pdweb/etc/webseald.conf:authentication-mechanisms:su-cdsso/opt/pdweb/etc/webseald.conf:authentication-mechanisms:failover-password/opt/pdweb/etc/webseald.conf:authentication-mechanisms:failover-token-card/opt/pdweb/etc/webseald.conf:authentication-mechanisms:failover-certificate/opt/pdweb/etc/webseald.conf:authentication-mechanisms:failover-http-request/opt/pdweb/etc/webseald.conf:authentication-mechanisms:failover-cdsso/opt/pdweb/etc/webseald.conf:content:doc-root/opt/pdweb/etc/webseald.conf:content:delete-trash-dir/opt/pdweb/etc/webseald.conf:logging:server-log/opt/pdweb/etc/webseald.conf:logging:requests-file/opt/pdweb/etc/webseald.conf:logging:referers-file/opt/pdweb/etc/webseald.conf:logging:agents-file/opt/pdweb/etc/webseald.conf:aznapi-configuration:auditlog/opt/pdweb/etc/webseald.conf:policy-director:config-file

[WINDOWS FILES]BASEDIR=SOFTWARE\Tivoli\Access Manager WebSEAL\4.1.0:Path# this line is required at top of stanza# fully qualified file names ; Required Flag (;R on the end - if file is required)<BASEDIR>etc<BASEDIR>www/jct<BASEDIR>keytabs

[WINDOWS CONF FILES]# configuration files that specify a file to include# file:stanza:option<BASEDIR>etc/webseald.conf:server:server-root<BASEDIR>etc/webseald.conf:server:ldap-server-config<BASEDIR>etc/webseald.conf:server:ssl-keyfile<BASEDIR>etc/webseald.conf:uraf-ad:ad-server-config<BASEDIR>etc/webseald.conf:uraf-domino:domino-server-config<BASEDIR>etc/webseald.conf:ldap:webseal-cert-keyfile<BASEDIR>etc/webseald.conf:ldap:webseal-cert-keyfile-stash<BASEDIR>etc/webseald.conf:ldap:ssl-keyfile<BASEDIR>etc/webseald.conf:ldap:ssl-keyfile-stash<BASEDIR>etc/webseald.conf:failover:failover-cookies-keyfile<BASEDIR>etc/webseald.conf:e-community-sso:intra-domain-key<BASEDIR>etc/webseald.conf:authentication-mechanisms:passwd-cdas<BASEDIR>etc/webseald.conf:authentication-mechanisms:passwd-uraf<BASEDIR>etc/webseald.conf:authentication-mechanisms:token-cdas<BASEDIR>etc/webseald.conf:authentication-mechanisms:cert-ssl<BASEDIR>etc/webseald.conf:authentication-mechanisms:http-request<BASEDIR>etc/webseald.conf:authentication-mechanisms:cdsso-create<BASEDIR>etc/webseald.conf:authentication-mechanisms:cdsso-consume<BASEDIR>etc/webseald.conf:authentication-mechanisms:passwd-strength<BASEDIR>etc/webseald.conf:authentication-mechanisms:cred-ext-attrs<BASEDIR>etc/webseald.conf:authentication-mechanisms:su-password<BASEDIR>etc/webseald.conf:authentication-mechanisms:su-token-card<BASEDIR>etc/webseald.conf:authentication-mechanisms:su-certificate<BASEDIR>etc/webseald.conf:authentication-mechanisms:su-http-request<BASEDIR>etc/webseald.conf:authentication-mechanisms:su-cdsso<BASEDIR>etc/webseald.conf:authentication-mechanisms:failover-password<BASEDIR>etc/webseald.conf:authentication-mechanisms:failover-token-card<BASEDIR>etc/webseald.conf:authentication-mechanisms:failover-certificate<BASEDIR>etc/webseald.conf:authentication-mechanisms:failover-http-request<BASEDIR>etc/webseald.conf:authentication-mechanisms:failover-cdsso<BASEDIR>etc/webseald.conf:content:doc-root<BASEDIR>etc/webseald.conf:content:delete-trash-dir<BASEDIR>etc/webseald.conf:logging:server-log<BASEDIR>etc/webseald.conf:logging:requests-file<BASEDIR>etc/webseald.conf:logging:referers-file<BASEDIR>etc/webseald.conf:logging:agents-file<BASEDIR>etc/webseald.conf:aznapi-configuration:auditlog<BASEDIR>etc/webseald.conf:policy-director:config-file

Appendix C. Using the pdbackup utility for WebSEAL 339

[WINDOWS REGISTRY]# specify keys to backupSOFTWARE\Tivoli\Access Manager WebSEAL

Additional backup dataThe following stanzas and parameters are not listed in the amwebbackup.lst fileand are therefore not automatically backed up. If you require this data to bebacked up, you must edit the amwebbackup.lst and add this information. Followthe format described at the beginning of the amwebbackup.lst file.[cdsso-peers]<machine-name> = <key-file-location>

[inter-domain-keys]master-authn-server = <server-name><domain-name> = <key-file>


Appendix D. Notices

This information was developed for products and services offered in the U.S.A.

IBM may not offer the products, services, or features discussed in this document inother countries. Consult your local IBM representative for information on theproducts and services currently available in your area. Any reference to an IBMproduct, program, or service is not intended to state or imply that only that IBMproduct, program, or service may be used. Any functionally equivalent product,program, or service that does not infringe any IBM intellectual property right maybe used instead. However, it is the user’s responsibility to evaluate and verify theoperation of any non-IBM product, program, or service.

IBM may have patents or pending patent applications covering subject matterdescribed in this document. The furnishing of this document does not give youany license to these patents. You can send license inquiries, in writing, to:

IBM Director of LicensingIBM CorporationNorth Castle DriveArmonk, NY 10504-1785U.S.A

For license inquiries regarding double-byte (DBCS) information, contact the IBMIntellectual Property Department in your country or send inquiries, in writing, to:

IBM World Trade Asia CorporationLicensing2-31 Roppongi 3-chomeMinato-kuTokyo 106Japan

The following paragraph does not apply to the United Kingdom or any othercountry where such provisions are inconsistent with local law: INTERNATIONALBUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION ″AS IS″WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED,INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OFNON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULARPURPOSE. Some states do not allow disclaimer of express or implied warranties incertain transactions, therefore, this statement may not apply to you.

This information could include technical inaccuracies or typographical errors.Changes are periodically made to the information herein; these changes will beincorporated in new editions of the publication. IBM may make improvementsand/or changes in the product(s) and/or the program(s) described in thispublication at any time without notice.

Any references in this information to non-IBM Web sites are provided forconvenience only and do not in any manner serve as an endorsement of those Websites. The materials at those Web sites are not part of the materials for this IBMproduct and use of those Web sites is at your own risk.


IBM may use or distribute any of the information you supply in any way itbelieves appropriate without incurring any obligation to you.

Licensees of this program who wish to have information about it for the purposeof enabling: (i) the exchange of information between independently createdprograms and other programs (including this one) and (ii) the mutual use of theinformation which has been exchanged, should contact:

IBM Corporation2Z4A/10111400 Burnet RoadAustin, TX 78758USA

Such information may be available, subject to appropriate terms and conditions,including in some cases, payment of a fee.

The licensed program described in this document and all licensed materialavailable for it are provided by IBM under terms of the IBM Customer Agreement,IBM International Program License Agreement or any equivalent agreementbetween us.

Any performance data contained herein was determined in a controlledenvironment. Therefore, the results obtained in other operating environments mayvary significantly. Some measurements may have been made on development-levelsystems and there is no guarantee that these measurements will be the same ongenerally available systems. Furthermore, some measurement may have beenestimated through extrapolation. Actual results may vary. Users of this documentshould verify the applicable data for their specific environment.

Information concerning non-IBM products was obtained from the suppliers ofthose products, their published announcements or other publicly available sources.IBM has not tested those products and cannot confirm the accuracy ofperformance, compatibility or any other claims related to non-IBM products.Questions on the capabilities of non-IBM products should be addressed to thesuppliers of those products.

All statements regarding IBM’s future direction or intent are subject to change orwithdrawal without notice, and represent goals and objectives only.

This information contains examples of data and reports used in daily businessoperations. To illustrate them as completely as possible, the examples include thenames of individuals, companies, brands, and products. All of these names arefictitious and any similarity to the names and addresses used by an actual businessenterprise is entirely coincidental.

COPYRIGHT LICENSE:

This information contains sample application programs in source language, whichillustrates programming techniques on various operating platforms. You may copy,modify, and distribute these sample programs in any form without payment toIBM, for the purposes of developing, using, marketing or distributing applicationprograms conforming to the application programming interface for the operatingplatform for which the sample programs are written. These examples have notbeen thoroughly tested under all conditions. IBM, therefore, cannot guarantee orimply reliability, serviceability, or function of these programs. You may copy,


modify, and distribute these sample programs in any form without payment toIBM for the purposes of developing, using, marketing, or distributing applicationprograms conforming to IBM’s application programming interfaces.

Each copy or any portion of these sample programs or any derivative work, mustinclude a copyright notice as follows:

© (your company name) (year). Portions of this code are derived from IBM Corp.Sample Programs. © Copyright IBM Corp. _enter the year or years_. All rightsreserved.

TrademarksThe following terms are trademarks or registered trademarks of InternationalBusiness Machines Corporation in the United States, other countries, or both:

AIXDB2IBMIBM logoSecureWayTivoliTivoli logoWebSphere

Microsoft, Windows, Windows NT, and the Windows logo are trademarks ofMicrosoft Corporation in the United States, other countries, or both.

Java and all Java-based trademarks and logos are trademarks or registeredtrademarks of Sun Microsystems, Inc. in the United States and other countries.

UNIX is a registered trademark of The Open Group in the United States and othercountries.

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

Appendix D. Notices 343

Index

Aabsolute URL filtering, best practices 222accept-client-certs 129accept-language HTTP header 36access control list (ACL) 4account management pages 34account-locked 34acct_locked.html 35ACL 4ACL policies

defining 4explicit 6inherited 6valid characters for ACL names 96WebSEAL-specific 95

acnt-mgt stanza 34, 145agent.log 42

event logging format 46example 44

agents 42agents-file 42allow-backend-domain-cookies 196amwebbackup.lst file 335application support, back-end 221argument-stanza 213audit records

authentication 50audit trail files 47auditing 47authentication

audit records 50authenticated access to resources 10automatic redirection 144basic authentication 125CDSSO 147certificate 127configuration overview 122configuring multiple methods 123custom CDAS parameters 122default configuration 123e-community 154forced redirection 144forms 126forms single sign-on 210goals 10HTTP header 130IP address 132local parameters 122login prompt 123multiplexing proxy agents (MPA) 134overview 9reauthentication 137, 140supported methods 112supported session data types 112switch user 72token 132unauthenticated access to resources 10understanding process 111

authentication methods, summary 112authentication strength POP policy 101, 105authentication-levels stanza 101, 106

authentication-mechanisms stanza 75authorization database replica location 55authorization database updates and polling 55authorization service 7authtoken-lifetime 152automatic redirection, to home page 144aznapi-configuration stanza 45, 55

Bba-auth 125back-end application support 221backicon 27basic authentication

configuring 125basic-auth-realm 125basicauth-dummy-passwd 202best practices

absolute URL filtering 222supplying HOST header information (-v) 221

BHAPI 88BSAFE (RSA) 88business entitlements (dynamic) 224

Ccache

GSKit (SSL) 113WebSEAL credentials 113

cache-refresh-interval 55CDMF library 147CDSSO authentication 147cdsso_key_gen 121, 151, 164cdsso-argument 152cdsso-auth 150cdsso-peers stanza 151cert-failure 34cert-ssl 122, 130certfailure.html 35certificate authentication 127certificates

GSKit 38iKeyman 38key database file types 38managing 38

CGI programmingsupporting 219supporting WIN32 environment variables 220

cgi-environment-variables stanza 220cgi-timeout 25cgi-types stanza 28client-connect-timeout 24common log format (request.log) 44content-caches stanza 29Content-Length header 182cookies

domain 196junction (IV_JCT) 183session 115, 190

cred-ext-attrs 122


credentialsextended attributes (tag/value) 224, 229inserting data in HTTP headers 225inserting LDAP data 224inserting user session id in HTTP header 229overview 12

credentials cache 113configuring 114inactivity timeout 115lifetime timeout 115maximum entries 114overview and structure 11

CRL cache, configuring 41gsk-crl-cache-entry-lifetime 42gsk-crl-cache-size 42

CRL checking, configuring 41crl-ldap-server 41crl-ldap-server-port 41crl-ldap-user 41crl-ldap-user-password 41cross-domain sign-on

CDSSO 147e-community 154

cross-site scriptingillegal-url-substrings stanza 87preventing vulnerability 87

cryptographic hardware configurationBHAPI 88IBM 4758 89IBM 4960 89nCipher nForce 300 89PKCS#11 88pkcs11–driver-path 92pkcs11–token-label 92pkcs11–token-pwd 92Rainbow CryptoSwift 89secure key storage 88SSL acceleration 88token 90webseal-cert-keyfile-label 93

Ddb-file 55default-webseal ACL policy 96directory index icons 27directory-index 27diricon 27disable-ncipher-bsafe 90, 93disable-rainbow-bsafe 90disable-ssl-v2 24disable-ssl-v3 24disable-tls-v1 24doc-root 26document caching 29

document-cache-control POP 30flush caches 30

document root directorychange location 26

document types for URL filtering 31document-cache-control POP extended attribute 30domain cookies 196dynamic business entitlements 224dynamic URLs

dynurl-allow-large-posts 235dynurl-map 232example 237

dynamic URLs (continued)GET and POST methods 234mapping ACL objects 232overview 231placing limitations on POST requests 234providing access control 231request-body-max-read 234resolving 234summary and technical notes 236updating, dynurl update 233

dynurl update 233dynurl-allow-large-posts 235dynurl-map 232dynurl.conf 232

Ee-community authentication 154

″vouch for″ request and reply 160″vouch for″ token 161configuring 161domain keys 164e-community cookie 160encrypting ″vouch for″ token 164features 155process flow 156

e-community cookie 160e-community-domain-keys stanza 164e-community-name 163e-community-sso-auth 162ec-cookie-lifetime 167enable-failover-cookie-for-domain 121enable-redirects stanza 145entitlements, dynamic business 224entrust-client 131error messages

HTTP 31macro support for HTTP 33serviceability 46

error.log 46event logging

HTTP logging 45event pool

http 45http.agent 45http.clf 45http.cof 45http.ref 45

explicit ACL policy 6extended attributes

document-cache-control (POP) 30HTTP-Tag-Value (junction) 225, 229in user credentials 225reauth (POP) 138

Ffailover cookies

configure cookie lifetime 121configuring 118enable domain-wide cookies 121enabling 120encrypting/decrypting cookie data 121

failover-auth 120failover-cdsso 120failover-certificate 120


failover-cookie-lifetime 121failover-cookies-keyfile 121failover-http-request 120failover-password 120failover-token-card 120fatal.log 46filter URLs

Content-Length header 182processing URLs in requests 183script filtering for absolute URLs 181standard filtering rules 180

filter-content-types stanza 31filter-schemes stanza 31filter-url stanza 181filtering

absolute URLs 181best practices for absolute URLs 222Content-Length header

X-Old-Content-Length 182filter absolute URLs with script filtering 181processing URLs in requests 183server-relative URLs 180specifying document MIME types 31standard URL filtering rules for WebSEAL 180static documents 180text/html 180text/vnd.wap.wml 180

flush caches 30flush-time 43forced redirection, to home page 144forms authentication 126

single sign-on solution 210forms-auth 126forms-sso-login-pages stanza 213front-end WebSEAL servers

replicate 58fsso.conf.template 213

GGET method 234global sign-on (GSO) 205gmt-time 43gsk-crl-cache-entry-lifetime 42gsk-crl-cache-size 42GSKit 38

CRL cache 41file types 38

GSKit (SSL) session cache 113configuring 114

GSO 205configure GSO cache 208

GSO cache, configure 208gso-cache-enabled 208gso-cache-entry-idle-timeout 208gso-cache-lifetime 208gso-cache-size 208gso-resource 213

Hheader 131help 34help.html 35HOST header, best practices for junctions 221

HTML account management pagesmacro support 35

HTML custom pages 34http 24HTTP common log format 44HTTP error messages 31

macro support 33http event pool 45HTTP header

accept-charset 37accept-language 36limiting size 189PD-USER-SESSION-ID 229

HTTP header authentication 130HTTP logging

default 42using event logging 45

HTTP server identity, suppressing 88HTTP_IV_CREDS 187, 219, 221HTTP_IV_GROUPS 187, 219, 221HTTP_IV_REMOTE_ADDRESS 189HTTP_IV_USER 187, 219, 221HTTP_PD_USER_SESSION_ID 227HTTP_PD-USER-SESSION-ID 230http-headers-auth 131http-port 24http-request 122, 131HTTP-Tag-Value junction attribute 227, 229http-timeout (junctions) 25HTTP/1.1 responses 20http.agent event pool 45http.clf event pool 45http.cof event pool (NCSA) 45http.ref event pool 45httpauthn 131https 24https-port 24https-timeout (junctions) 25

IIBM 4758 89IBM 4960 89iKeyman 40

configuration for cryptographic hardware 91mutually authenticated SSL junctions 175overview 40SSL type junctions 173WebSEAL test certificate 129

ikmuser.properties 91ikmuser.sample 91illegal-url-substrings stanza 87inactive-timeout 115inherited ACL policy 6instances, multiple WebSEAL 59IP address authentication 132ipaddr-auth 132is-master-authn-server 165IV_JCT (junction cookie) 183iv-creds 187, 221iv-groups 187, 221iv-remote-address 189iv-user 187, 221

Index 347

Jjmt load 184jmt-map 184jmt.conf 184junction cookies 183junction fairness 56junction mapping table 184junction stanza 57junction-db 169junctions

-b filter 204-b gso 205-b ignore 203-b supply 202authenticate with BA header (-B, -U, -W) 176best practices 221case-insensitive URLs (-i) 190certificate authentication 195client certificate (WebSEAL) (-K) 175command reference 329cookies across multiple -j junctions 185Distinguished Name (DN) matching (-D) 175enforcing permissions 195filter absolute URLs with script filtering 181filter URLs in responses 180forcing new junction (-f) 26, 187forms single sign-on (-S) 216global sign-on (GSO) 205gso options (-b gso, -T) 207guidelines for creating 170HOST header best practices (-v) 221host option (-h) 172HTTP-Tag-Value attribute 229HTTP/1.0 and 1.1 responses 20impact of -b options on mutually authenticated

junctions 176junction mapping table 184LTPA (-A, -F, -Z) 209modifying URLs from back-end applications 178mount multiple servers 195mutually authenticated (-D, -K, -B, -U, -W) 174overview 12, 169pdadmin server task 171process server-relative URLs with cookies (-j) 183process server-relative URLs with junction mapping 184processing URLs in requests 183proxy junctions (-H, -P) 177query_contents 196required options 172scalability 14session cookie to portal server (-k) 190specify back-end UUID (-u) 191stateful junction support (-s, -u) 191supply client identity in HTTP headers (-c) 187supply IP address in HTTP headers (-r) 189type option (-t) 172virtual host name (-v) 221WebSEAL client certificate (-K) 175WebSEAL-to-WebSEAL (-C) 178Windows file systems (-w) 194worker thread allocation (-l) 57worker thread allocation (-L) 58

Kkey database file types 38

LLDAP data in HTTP headers 224ldap-ext-cred-tags stanza 225, 227ldapauthn 126, 127libfailoverauthn shared library 120libhttpauthn 131libldapauthn 126, 127libsslauthn 130libsuauthn 75libtokenauthn 133listen-flags 55log file, WebSEAL 21logcfg 45logging

default HTTP 42HTTP (event logging) 45

logging stanza 21login 34

prompt conditions 123login prompt

conditions 123login_success.html 35login-form-action 213login-page 213login-page-stanza 213login-redirect-page 145login-success 34login.html 35, 127, 143logout 34, 124logout.html 35LTPA (WebSphere) 208

configure junction 209configure LTPA cache 209

LTPA cache, configure 209ltpa-cache stanza 209ltpa-cache-enabled 209ltpa-cache-entry-idle-timeout 209ltpa-cache-entry-lifetime 209ltpa-cache-size 209

Mmacro support

HTML account management pages 35HTTP error messages 33USERNAME, for reauthentication forms 143

maintenance tasksbacking up WebSEAL data (pdbackup) 335

management objects 3master-authn-server 165master-http-port 166master-https-port 166max-entries 114max-size 43max-webseal-header-size 189messages 46

error.log 46fatal.log 46notice.log 46routing file 46warning.log 46

mgt-pages-root 34MIME types, specifying for URL filtering 31mpa 137MPA authentication 134msg_webseald.log 21, 46


multi-factor authentication 105multi-locale support 36multiple WebSEAL instances

configuration overview 59configuring on UNIX 60configuring on Windows 65server start, stop, restart, status commands 70syntax in pdadmin commands 171, 330unconfiguring 69

multiplexing proxy agents (authentication) 134mutually authenticated junctions 174

NnCipher nForce 300 89NCSA combined format 45net command (Windows) 71network-based authentication POP policy 105next-token 34nexttoken.html 35notice.log 46

Ppasswd_exp.html 35passwd_rep.html 35passwd-cdas 122passwd-change 34passwd-change-failure 34passwd-change-success 34passwd-expired 34passwd-ldap 122, 126, 127passwd.html 35password strength policy 98PD_PORTAL header 223pd_start status command 70PD-USER-SESSION-ID HTTP header 229pd.conf 225pdadmin policy

disable-time-interval 96max-login-failures 96max-password-repeated-chars 98min-password-alphas 98min-password-length 98min-password-non-alphas 98password-spaces 98

pdadmin server taskterminate all_sessions 230

pdadmin server task (junctions) 171pdbackup utility 335

amwebbackup.lst file 335pdconfig 60, 65, 69pdweb command 20, 70persistent-con-timeout 24personalization service

configuring WebSEAL 223example 224overview 223

ping-time (junctions) 25PKCS#11 88pkcs11–driver-path 92pkcs11–token-label 92pkcs11–token-pwd 92pkmscdsso 153pkmslogout 124pkmspasswd 124

pkmsvouchfor 160, 166policy enforcer 7polling 55polling authorization database 55POP 5POP policy

authentication strength (step-up) 101defining 4document-cache-control extended attribute 30network-based authentication 105quality of protection 108reauth extended attribute 138

portal-map stanza 223POST method 234

configuring limitations 234POST request caching 83pre-410-compatible-tokens 121, 153, 167problem determination

statistics 93trace 93

protected object 3protected object policies 5protected object space 3

management objects 3protected object 3system resource 3user-defined objects 3Web objects 3WebSEAL server-name 20

Qquality of protection

default level 53hosts 54networks 54POP policy 108

query_contents 196customizing 199installing 196securing 200

query_contents.c 196query_contents.cfg 196query_contents.exe 196query_contents.html 196query_contents.sh 196

RRainbow CryptoSwift 89reauth POP extended attribute 138reauth-extend-lifetime 139, 142reauth-for-inactive 141, 143reauth-reset-lifetime 139, 142reauthentication

based on security (POP) policy 137based on session inactivity 140customizing login forms 143preventing session cache entry removel 143reauth POP extended attribute 138reauth-extend-lifetime 139, 142, 143reauth-for-inactive parameter 141reauth-reset-lifetime 139, 142, 143

redirect 145redirection, to home page 144referer.log 42

Index 349

referer.log (continued)event logging format 45example 44

referers 42referers-file 42regular expressions

for dynamic URLs 232for forms single sign-on 215list of 215

related publications xivREMOTE_USER 219replica authorization database location 55replicating front-end WebSEAL servers 58request caching 83request-body-max-read 84, 234request-max-cache 84request.log 42

event logging format 45example 44

requests 42requests-file 42resend-webseal-cookies 116resource manager 7rewrite-absolute-with-absolute 182root directory, WebSEAL installation 19routing file 46

Sscalability 14

replicated back-end servers 16replicated front-end servers 15

script filtering (absolute URLs)rewrite-absolute-with-absolute parameter 182script-filter parameter 181script-filtering stanza 181

script-filter 181SecureID (RSA) 133security policy

identifying content types 8levels of protection 8planning and implementing 8

securitygroup 74server identity (HTTP), suppressing 88server root directory 23server-log 21server-name 20, 58server-root 23, 78server-side application support 221server-side request caching 83serviceability messages 46

error.log 46fatal.log 46notice.log 46routing file 46warning.log 46

session cacheconfiguring 114GSKit (SSL) 113inactivity timeout 115lifetime timeout 115overview and structure 11WebSEAL credentials 113

session cookies 115enable 116

session data types 112session ID data types 118

session ID management 228session state

between client and back-end 228configuring GSKit SSL session ID cache 114configuring WebSEAL credentials cache 114enable session cookies 116failover cookies 118managing 113session cookies 115terminate all user sessions 230terminate single user session 230user session ID management 228valid session ID data types 118

set-cookie headerhandling the domain attribute 196modify Name attribute in -j junctions 186modify Path attribute in -j junctions 185

set-cookie header, as handled by -j junctions 185single sign-on

-b filter 204-b gso 205-b ignore 203-b supply 202CDSSO 147concepts 201configure GSO cache 208e-community 154forms authentication 210global sign-on (GSO) 205LTPA (WebSphere) 208supply client identity in BA headers 202

SSL connectivity 24SSL session ID 116ssl-id-sessions 116ssl-keyfile 40ssl-keyfile-label 40ssl-keyfile-pwd 40ssl-keyfile-stash 40ssl-listening-port 55ssl-max-entries 114ssl-qop-mgmt 53ssl-qop-mgmt-default stanza 53ssl-qop-mgmt-hosts stanza 54ssl-qop-mgmt-networks stanza 54ssl-v2-timeout 114ssl-v3-timeout 114sslauthn 130sso-consume 122, 150sso-create 122, 150stanzas

uraf-ad in activedir.conf 258uraf-domino 261

starting WebSEAL 20stateful junctions 191statistics utility 93step-up authentication 101stepup-login 34, 103stepuplogin.html 35, 103stopping WebSEAL 20su-admin extended attribute 81su-admins group 72, 74su-excluded group 74suauthn 75suppress-server-identity 88switch user 72

authentication mechanism 75built-in shared library 75


switch user (continued)CDAS shared library 81enabling 74excluding users 74securitygroup 74su-admin extended attribute 81su-admins group 72, 74su-excluded group 74using 79valid authentication methods 78

switch-user 34switchuser.html 35system resource 3

Ttag value 224, 229

support by certificate authentication 226support by token authentication 226support by user name authentication 226

tagvalue_user_session_id 229terminate all user sessions 230terminate single user session 230three strikes login policy 96timeout 115, 138, 142, 143timeout parameters

GSKit SSL session cache 114HTTP and HTTPS 24WebSEAL credentials/session cache 114

TLS connectivity 24token 90token authentication 132token-auth 132token-cdas 122, 133token-login 34tokenauthn 133tokenlogin.html 35, 143trace utility 93Transport Layer Security (TLS) 24type, MIME 31

Uunauthenticated users, controlling 108unknownicon 27update notification listening 55uraf-ad stanza in activedir.conf 258uraf-domino 261URL

about absolute paths 179about relative paths 179about server-relative paths 179filtering options 180handling UTF-8 85modifying URLs to back-end resources 178specifying document MIME types for filtering 31understanding path types 179using junction cookies 183using junction mapping table 184

use-same-session 116, 117User Registry Adapter Framework (URAF) 258user session ID management 228

tagvalue_user_session_id 228user-session-ids 228

user-defined objects 3user-session-ids 228

USERNAME macro, for reauthentication forms 143UTF-8 encoded characters 85utf8-url-support-enabled 86

Vvf-argument 165vf-token-lifetime 166vf-url 166vouch for request and reply 160

Wwarning.log 46Web objects 3Web Portal Manager 6WebSEAL

configuring multiple instances 59HTTP/1.1 responses 20in object space 20log file 21overview 1root directory of document tree 26root installation directory 19server root directory 23server-name 20starting and stopping server 20statistics 93trace 93webseald.conf configuration file 21

WebSEAL credentials/session cacheconfiguring 114overview 113overview and structure 11

WebSEAL junctions, See junctions 169webseal-cert-keyfile 39webseal-cert-keyfile-label 39, 93, 129, 195webseal-cert-keyfile-pwd 39webseal-cert-keyfile-stash 39webseal-mpa-servers group 136, 137webseald.conf

location 21overview 21

WebSphere LTPA 208WIN32 environment variables, supporting 220worker threads

global allocation 57junction fairness 56junctions 56managing 56per junction allocation 57WebSEAL 56

worker-thread-hard-limit 57worker-thread-soft-limit 57worker-threads 56

Index 351

��

Printed in U.S.A.

SC32-1134-01

Amweb41 Admin

Documents

Transcript of Amweb41 Admin