WebSEAL Administrator’s Guide - IBM...

IBM Tivoli Access Manager

WebSEAL Administrator’s GuideVersion 3.9

GC23-4682-00

IBM Tivoli Access Manager

WebSEAL Administrator’s GuideVersion 3.9

GC23-4682-00

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

Fifth Edition (April 2002)

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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ixWho should read this guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ixWhat this guide contains . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ixPublications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . x

IBM Tivoli Access Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xRelated publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiiiAccessing publications online . . . . . . . . . . . . . . . . . . . . . . . . . . . . xivOrdering publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvProviding feedback about publications . . . . . . . . . . . . . . . . . . . . . . . . . xv

Accessibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvContacting customer support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvConventions used in this book. . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvi

Typeface conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvi

Chapter 1. IBM Tivoli Access Manager WebSEAL overview . . . . . . . . . . . . . . 1Introducing IBM Tivoli Access Manager and WebSEAL . . . . . . . . . . . . . . . . . . . . . 1Understanding the 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 . . . . . . . . . . . . . . . . . . . . . . . . . . 21Introducing the webseald.conf configuration file . . . . . . . . . . . . . . . . . . . . . . 22WebSEAL 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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25Root directory of the Web document tree . . . . . . . . . . . . . . . . . . . . . . . . 26Configuring directory indexing . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27Windows: File naming for CGI programs . . . . . . . . . . . . . . . . . . . . . . . . 27Configuring Web document caching . . . . . . . . . . . . . . . . . . . . . . . . . . 29Specifying document types for filtering . . . . . . . . . . . . . . . . . . . . . . . . . 30

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

Managing custom account management pages. . . . . . . . . . . . . . . . . . . . . . . . 33

© Copyright IBM Corp. 1999, 2002 iii

Custom page parameters and values . . . . . . . . . . . . . . . . . . . . . . . . . . 33Custom HTML page descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

Managing client-side and server-side certificates . . . . . . . . . . . . . . . . . . . . . . . 35Understanding GSKit key database file types . . . . . . . . . . . . . . . . . . . . . . . 35Configuring key database parameters. . . . . . . . . . . . . . . . . . . . . . . . . . 36Using the iKeyman certificate management utility . . . . . . . . . . . . . . . . . . . . . 37Configuring CRL checking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38Configuring the CRL cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

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

Configuring HTTP logging using event logging . . . . . . . . . . . . . . . . . . . . . . . 42Logging WebSEAL serviceability messages . . . . . . . . . . . . . . . . . . . . . . . . . 43

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

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

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

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

Replicating front-end WebSEAL servers . . . . . . . . . . . . . . . . . . . . . . . . . . 50Configuring multiple WebSEAL server instances . . . . . . . . . . . . . . . . . . . . . . . 50

Configuration overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51Configuring multiple WebSEAL instances on UNIX . . . . . . . . . . . . . . . . . . . . . 51Configuring multiple WebSEAL instances on Win NT/2000 . . . . . . . . . . . . . . . . . . 54Unconfiguring multiple WebSEAL instances . . . . . . . . . . . . . . . . . . . . . . . 55Server start, stop, restart, status commands . . . . . . . . . . . . . . . . . . . . . . . . 56

Configuring switch user (SU) for administrators . . . . . . . . . . . . . . . . . . . . . . . 57Understanding the switch user process flow . . . . . . . . . . . . . . . . . . . . . . . 57Enabling switch user: A summary . . . . . . . . . . . . . . . . . . . . . . . . . . . 58Configuring the switch user HTML form . . . . . . . . . . . . . . . . . . . . . . . . 59Enabling and excluding users from switch user . . . . . . . . . . . . . . . . . . . . . . 60Configuring the switch user authentication mechanism . . . . . . . . . . . . . . . . . . . . 61Configuring a CDAS switch user mechanism . . . . . . . . . . . . . . . . . . . . . . . 62Impacting other WebSEAL functionality . . . . . . . . . . . . . . . . . . . . . . . . . 62

Configuring WebSEAL server-side request caching . . . . . . . . . . . . . . . . . . . . . . 63Background . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63Server-side caching process flow . . . . . . . . . . . . . . . . . . . . . . . . . . . 64Configuring server-side caching parameters . . . . . . . . . . . . . . . . . . . . . . . 65Notes and limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66

Handling UTF-8 encoded characters . . . . . . . . . . . . . . . . . . . . . . . . . . . 66Preventing vulnerability caused by cross-site scripting . . . . . . . . . . . . . . . . . . . . . 68

Background . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68Configuring URL string filtering . . . . . . . . . . . . . . . . . . . . . . . . . . . 68

Suppressing server identity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69Using WebSEAL statistics. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

pdadmin stats command syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . 69Statistics components and activity types . . . . . . . . . . . . . . . . . . . . . . . . . 72Enabling statistics statically using event logging . . . . . . . . . . . . . . . . . . . . . . 77

Using the trace utility to capture WebSEAL actions . . . . . . . . . . . . . . . . . . . . . . 78Basic trace command syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78WebSEAL trace components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79

iv IBM Tivoli Access Manager: WebSEAL Administrator’s Guide

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

/WebSEAL/<host>. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81/WebSEAL/<host>/<file> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81WebSEAL ACL permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81Default /WebSEAL ACL policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82Valid characters for ACL names . . . . . . . . . . . . . . . . . . . . . . . . . . . 82

Three strikes login policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82Command syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83

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

Authentication strength POP policy (step-up) . . . . . . . . . . . . . . . . . . . . . . . . 86Configuring levels for step-up authentication . . . . . . . . . . . . . . . . . . . . . . . 87Enabling step-up authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . 88Step-up login form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89Step-up authentication algorithm . . . . . . . . . . . . . . . . . . . . . . . . . . . 90Step-up authentication notes and limitations . . . . . . . . . . . . . . . . . . . . . . . 90Distinguishing step-up from multi-factor authentication . . . . . . . . . . . . . . . . . . . 91

Network-based authentication POP policy . . . . . . . . . . . . . . . . . . . . . . . . . 92Configuring authentication levels . . . . . . . . . . . . . . . . . . . . . . . . . . . 92Specifying IP addresses and ranges . . . . . . . . . . . . . . . . . . . . . . . . . . 92Disabling step-up authentication by IP address . . . . . . . . . . . . . . . . . . . . . . 93Network-based authentication algorithm . . . . . . . . . . . . . . . . . . . . . . . . 93Network-based authentication notes and limitations . . . . . . . . . . . . . . . . . . . . . 94

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

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

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

Supported session data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98Supported authentication methods. . . . . . . . . . . . . . . . . . . . . . . . . . . 98

Managing session state . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99Session state overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99GSKit and WebSEAL session cache overview . . . . . . . . . . . . . . . . . . . . . . . 99Configuring the GSKit SSL session ID cache . . . . . . . . . . . . . . . . . . . . . . . 100Configuring the WebSEAL session/credentials cache . . . . . . . . . . . . . . . . . . . . 101Maintaining state with session cookies . . . . . . . . . . . . . . . . . . . . . . . . . 101Determining valid session ID data types . . . . . . . . . . . . . . . . . . . . . . . . 104Configuring failover cookies . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104

Authentication configuration overview . . . . . . . . . . . . . . . . . . . . . . . . . . 107Local authentication parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . 108External custom CDAS authentication parameters . . . . . . . . . . . . . . . . . . . . . 108Default configuration for WebSEAL authentication . . . . . . . . . . . . . . . . . . . . . 108Configuring multiple authentication methods . . . . . . . . . . . . . . . . . . . . . . 109Prompting for login . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109Logout and change password commands . . . . . . . . . . . . . . . . . . . . . . . . 110

Configuring Basic Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111Enabling and disabling Basic Authentication . . . . . . . . . . . . . . . . . . . . . . . 111Setting the realm name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111Configuring the Basic Authentication mechanism . . . . . . . . . . . . . . . . . . . . . 112Configuration conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112

Configuring forms authentication. . . . . . . . . . . . . . . . . . . . . . . . . . . . 112Enabling and disabling forms authentication . . . . . . . . . . . . . . . . . . . . . . . 112Configuring the forms authentication mechanism . . . . . . . . . . . . . . . . . . . . . 113

Contents v

Configuration conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113Customizing HTML response forms . . . . . . . . . . . . . . . . . . . . . . . . . . 113

Configuring client-side certificate authentication . . . . . . . . . . . . . . . . . . . . . . . 113Background: Mutual authentication via certificates . . . . . . . . . . . . . . . . . . . . . 114The WebSEAL test certificate . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115Enabling and disabling certificate authentication. . . . . . . . . . . . . . . . . . . . . . 115Configuring the certificate authentication mechanism . . . . . . . . . . . . . . . . . . . . 116Configuration conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116

Configuring HTTP header authentication . . . . . . . . . . . . . . . . . . . . . . . . . 116Enabling and disabling HTTP header authentication . . . . . . . . . . . . . . . . . . . . 116Specifying header types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117Configuring the HTTP header authentication mechanism . . . . . . . . . . . . . . . . . . . 117Configuration conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117

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

Configuring token authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118Enabling and disabling token authentication . . . . . . . . . . . . . . . . . . . . . . . 118Configuring the token authentication mechanism . . . . . . . . . . . . . . . . . . . . . 118

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

Configuring reauthentication based on security policy . . . . . . . . . . . . . . . . . . . . . 122Conditions affecting POP reauthentication . . . . . . . . . . . . . . . . . . . . . . . . 122Creating and applying the reauthentication POP . . . . . . . . . . . . . . . . . . . . . 123Configuring session cache lifetime reset and extension . . . . . . . . . . . . . . . . . . . 123

Configuring reauthentication based on session inactivity policy . . . . . . . . . . . . . . . . . 125Conditions affecting inactivity reauthentication . . . . . . . . . . . . . . . . . . . . . . 125Enabling inactivity reauthentication . . . . . . . . . . . . . . . . . . . . . . . . . . 126Configuring session cache lifetime reset and extension . . . . . . . . . . . . . . . . . . . 126

Chapter 6. Cross-domain sign-on solutions . . . . . . . . . . . . . . . . . . . 129Configuring CDSSO authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . 129

Integrating a custom CDMF shared library . . . . . . . . . . . . . . . . . . . . . . . 129Authentication process flow for CDSSO with CDMF . . . . . . . . . . . . . . . . . . . . 129Enabling and disabling CDSSO authentication . . . . . . . . . . . . . . . . . . . . . . 131Configuring the CDSSO authentication mechanism . . . . . . . . . . . . . . . . . . . . . 131Encrypting the authentication token data . . . . . . . . . . . . . . . . . . . . . . . . 132Configuring the token time stamp . . . . . . . . . . . . . . . . . . . . . . . . . . 132Expressing CDSSO HTML links . . . . . . . . . . . . . . . . . . . . . . . . . . . 133Protecting the authentication token . . . . . . . . . . . . . . . . . . . . . . . . . . 133

Configuring e-community single sign-on . . . . . . . . . . . . . . . . . . . . . . . . . 133e-community features and requirements . . . . . . . . . . . . . . . . . . . . . . . . 134e-community process flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135Understanding the e-community cookie . . . . . . . . . . . . . . . . . . . . . . . . 139Understanding the “vouch for” request and reply . . . . . . . . . . . . . . . . . . . . . 139Understanding the “vouch for” token . . . . . . . . . . . . . . . . . . . . . . . . . 140Encrypting the “vouch for” token . . . . . . . . . . . . . . . . . . . . . . . . . . 140Configuring an e-community . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141

Chapter 7. WebSEAL junctions . . . . . . . . . . . . . . . . . . . . . . . . . 145WebSEAL junctions overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145

Junction database location and format . . . . . . . . . . . . . . . . . . . . . . . . . 145Applying coarse-grained access control: summary . . . . . . . . . . . . . . . . . . . . . 146Applying fine-grained access control: summary . . . . . . . . . . . . . . . . . . . . . . 146Guidelines for creating WebSEAL junctions . . . . . . . . . . . . . . . . . . . . . . . 146

vi IBM Tivoli Access Manager: WebSEAL Administrator’s Guide

Additional references for WebSEAL junctions. . . . . . . . . . . . . . . . . . . . . . . 146Using pdadmin to create junctions . . . . . . . . . . . . . . . . . . . . . . . . . . . 147Configuring a basic WebSEAL junction . . . . . . . . . . . . . . . . . . . . . . . . . . 148

Creating TCP type junctions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148Creating SSL type junctions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149Adding additional back-end servers to a junction . . . . . . . . . . . . . . . . . . . . . 150

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

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

Understanding path types used in URLs . . . . . . . . . . . . . . . . . . . . . . . . 155Filtering URLs in responses . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156Processing URLs in requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158

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

Technical notes for using WebSEAL junctions. . . . . . . . . . . . . . . . . . . . . . . . 168Mounting multiple servers at the same junction . . . . . . . . . . . . . . . . . . . . . . 168Exceptions to enforcing permissions across junctions . . . . . . . . . . . . . . . . . . . . 169Certificate authentication across junctions . . . . . . . . . . . . . . . . . . . . . . . . 169

Using query_contents with third-party servers . . . . . . . . . . . . . . . . . . . . . . . 169Installing query_contents components . . . . . . . . . . . . . . . . . . . . . . . . . 170Installing query_contents on third-party UNIX servers . . . . . . . . . . . . . . . . . . . 170Installing query_contents on third-party Win32 servers . . . . . . . . . . . . . . . . . . . 171Customizing query_contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172Securing query_contents. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173

Chapter 8. Web single sign-on solutions. . . . . . . . . . . . . . . . . . . . . 175Configuring BA headers for single sign-on solutions . . . . . . . . . . . . . . . . . . . . . 175

Single sign-on (SSO) concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175Supplying client identity in BA headers . . . . . . . . . . . . . . . . . . . . . . . . 176Supplying client identity and generic password . . . . . . . . . . . . . . . . . . . . . . 176Forwarding original client BA header information . . . . . . . . . . . . . . . . . . . . . 177Removing client BA header information . . . . . . . . . . . . . . . . . . . . . . . . 178Supplying user names and passwords from GSO . . . . . . . . . . . . . . . . . . . . . 179

Using global sign-on (GSO). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179Mapping the authentication information . . . . . . . . . . . . . . . . . . . . . . . . 181Configuring a GSO-enabled WebSEAL junction . . . . . . . . . . . . . . . . . . . . . . 181Configuring the GSO cache. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182

Configuring single sign-on to IBM WebSphere (LTPA) . . . . . . . . . . . . . . . . . . . . . 182Configuring an LTPA junction . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183Configuring the LTPA cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183Technical notes for LTPA single sign-on. . . . . . . . . . . . . . . . . . . . . . . . . 184

Configuring single sign-on forms authentication. . . . . . . . . . . . . . . . . . . . . . . 184Background and goals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184Forms single sign-on process flow . . . . . . . . . . . . . . . . . . . . . . . . . . 185Requirements for application support . . . . . . . . . . . . . . . . . . . . . . . . . 186Creating the configuration file for forms single sign-on . . . . . . . . . . . . . . . . . . . 186Enabling forms single sign-on . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190

Contents vii

Example configuration file for IBM HelpNow . . . . . . . . . . . . . . . . . . . . . . 190

Chapter 9. Application integration . . . . . . . . . . . . . . . . . . . . . . . 193Supporting CGI programming. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194

Windows: Supporting WIN32 environment variables . . . . . . . . . . . . . . . . . . . . 194Supporting back-end server-side applications. . . . . . . . . . . . . . . . . . . . . . . . 195Junction best practises for application integration . . . . . . . . . . . . . . . . . . . . . . 195

Supplying complete HOST header information with -v . . . . . . . . . . . . . . . . . . . 195Supporting standard absolute URL filtering . . . . . . . . . . . . . . . . . . . . . . . 196

Building a custom personalization service . . . . . . . . . . . . . . . . . . . . . . . . . 197Configuring WebSEAL for a personalization service . . . . . . . . . . . . . . . . . . . . 197Personalization service example . . . . . . . . . . . . . . . . . . . . . . . . . . . 198

Enabling dynamic business entitlements (tag/value) . . . . . . . . . . . . . . . . . . . . . 198Creating business entitlements from LDAP data . . . . . . . . . . . . . . . . . . . . . . 198

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

Providing access control to dynamic URLs . . . . . . . . . . . . . . . . . . . . . . . . 204Dynamic URL components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204Mapping ACL and POP objects to dynamic URLs . . . . . . . . . . . . . . . . . . . . . 205Updating WebSEAL for dynamic URLs . . . . . . . . . . . . . . . . . . . . . . . . . 206Resolving dynamic URLs in the object space . . . . . . . . . . . . . . . . . . . . . . . 207Configuring limitations on POST requests . . . . . . . . . . . . . . . . . . . . . . . . 207Summary and technical notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209

Dynamic URL example: The Travel Kingdom. . . . . . . . . . . . . . . . . . . . . . . . 210The application. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210The interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210The security policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211Secure clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211Access control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212Conclusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212

Appendix A. webseald.conf reference . . . . . . . . . . . . . . . . . . . . . . 223

Appendix B. WebSEAL junction reference . . . . . . . . . . . . . . . . . . . . 225Using pdadmin to create junctions . . . . . . . . . . . . . . . . . . . . . . . . . . . 225The junction commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226Create a new junction for an initial server . . . . . . . . . . . . . . . . . . . . . . . . . 227Add an additional server to an existing junction. . . . . . . . . . . . . . . . . . . . . . . 229

Appendix C. Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231Trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235

viii 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. WebSEAL is a high performance, multi-threaded Web serverthat applies fine-grained security policy to the protected Web object space.WebSEAL can provide single sign-on solutions and incorporate back-end Webapplication server resources into its security 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.

Who should read this guideThis guide is for system administrators responsible for configuring andmaintaining an 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 guide containsv Chapter 1: IBM Tivoli Access Manager WebSEAL overview

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

© Copyright IBM Corp. 1999, 2002 ix

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 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: Web single sign-on solutions

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: webseald.conf reference

v Appendix B: WebSEAL junction reference

PublicationsThis section lists publications in the Access Manager library and any other relateddocuments. It also describes how to access Tivoli publications online, how to orderTivoli publications, and how to make comments on Tivoli publications.

IBM Tivoli Access ManagerThe Access Manager library is organized into the following categories:v Release informationv Base informationv WebSEAL informationv Web security informationv Developer reference informationv Supplemental technical information

Publications in the product library are included in the Portable Document Format(PDF) on the product CD. To access these publications using a Web browser, openthe infocenter.html file, which is located in the /doc directory on the product CD.

For additional sources of information about Access Manager and related topics, seethe following Web sites:

http://www.ibm.com/redbookshttps://www.tivoli.com/secure/support/documents/fieldguides

x IBM Tivoli Access Manager: WebSEAL Administrator’s Guide

Release informationv IBM Tivoli Access Manager for e-business Read Me First

GI11-0918 (am39_readme.pdf)Provides information for installing and getting started using Access Manager.

v IBM Tivoli Access Manager for e-business Release Notes

GI11-0919 (am39_relnotes.pdf)Provides late-breaking information, such as software limitations, workarounds,and documentation updates.

Base informationv IBM Tivoli Access Manager Base Installation Guide

GC32-0844 (am39_install.pdf)Explains how to install, configure, and upgrade Access Manager software,including the Web portal manager interface.

v IBM Tivoli Access Manager Base Administrator’s Guide

GC23-4684 (am39_admin.pdf)Describes the concepts and procedures for using Access Manager services.Provides instructions for performing tasks from the Web portal managerinterface and by using the pdadmin command.

v IBM Tivoli Access Manager Base for Linux on zSeries™ Installation Guide

GC23-4796 (am39_zinstall.pdf)Explains how to install and configure Access Manager Base for Linux on thezSeries platform.

WebSEAL informationv IBM Tivoli Access Manager WebSEAL Installation Guide

GC32-0848 (amweb39_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 Guide

GC23-4682 (amweb39_admin.pdf)Provides background material, administrative procedures, and technicalreference information for using WebSEAL to manage the resources of yoursecure Web domain.

v IBM Tivoli Access Manager WebSEAL Developer’s Reference

GC23-4683 (amweb39_devref.pdf)Provides administration and programming information for the Cross-domainAuthentication Service (CDAS), the Cross-domain Mapping Framework (CDMF),and the Password Strength Module.

v IBM Tivoli Access Manager WebSEAL for Linux on zSeries Installation Guide

GC23-4797 (amweb39_zinstall.pdf)Provides installation, configuration, and removal instructions for WebSEALserver and the WebSEAL application development kit for Linux on the zSeriesplatform.

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

GC32-0850 (amwas39_user.pdf)

Preface xi

Provides installation, removal, and administration instructions for AccessManager for IBM WebSphere® Application Server.

v IBM Tivoli Access Manager for WebLogic Server User’s Guide

GC32-0851 (amwls39_user.pdf)Provides installation, removal, and administration instructions for AccessManager for BEA WebLogic Server.

v IBM Tivoli Access Manager Plug-in for Edge Server User’s Guide

GC23-4685 (amedge39_user.pdf)Describes how to install, configure, and administer the plug-in for IBMWebSphere Edge Server.

v IBM Tivoli Access Manager Plug-in for Web Servers User’s Guide

GC23-4686 (amws39_user.pdf)Provides installation instructions, administration procedures, and technicalreference information for securing your Web domain using the plug-in for Webservers application.

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

GC32-0849 (am39_authC_devref.pdf)Provides reference material that describes how to use the Access Managerauthorization C API and the Access Manager service plug-in interface to addAccess Manager security to applications.

v IBM Tivoli Access Manager Authorization Java Classes Developer’s Reference

GC23-4688 (am39_authJ_devref.pdf)Provides reference information for using the Java™ language implementation ofthe authorization API to enable an application to use Access Manager security.

v IBM Tivoli Access Manager Administration C API Developer’s Reference

GC32-0843 (am39_adminC_devref.pdf)Provides reference information about using the administration API to enable anapplication to perform Access Manager administration tasks. This documentdescribes the C implementation of the administration API.

v IBM Tivoli Access Manager Administration Java Classes Developer’s Reference

SC32-0842 (am39_adminJ_devref.pdf)Provides reference information for using the Java language implementation ofthe administration API to enable an application to perform Access Manageradministration tasks.

v IBM Tivoli Access Manager WebSEAL Developer’s Reference

GC23-4683 (amweb39_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 Performance Tuning Guide

GC43-0846 (am39_perftune.pdf)Provides performance tuning information for an environment consisting ofAccess Manager with IBM SecureWay Directory defined as the user registry.

v IBM Tivoli Access Manager Capacity Planning Guide

GC32-0847 (am39_capplan.pdf)

xii IBM Tivoli Access Manager: WebSEAL Administrator’s Guide

Assists planners in determining the number of WebSEAL, LDAP, and backendWeb servers needed to achieve a required workload.

v IBM Tivoli Access Manager Error Message Reference

SC32-0845 (am39_error_ref.pdf)Provides explanations and recommended actions for the messages produced byAccess Manager.

The Tivoli Glossary includes definitions for many of the technical terms related toTivoli software. The Tivoli Glossary is available, in English only, at the followingWeb site:

http://www.tivoli.com/support/documents/glossary/termsm03.htm

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

IBM DB2® Universal Database™

IBM DB2 Universal Database is required when installing IBM SecureWay Directory,z/OS™, and OS/390® SecureWay LDAP servers. DB2 information is available atthe following Web site:

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

IBM Global Security ToolkitAccess Manager provides data encryption through the use of IBM Global SecurityToolkit (GSKit). GSKit is shipped on the IBM Tivoli Access Manager Base CD foryour 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 in the /doc/GSKit directory: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 Access Manager secure domain.

IBM SecureWay DirectoryIBM SecureWay Directory, Version 3.2.2, is shipped on the IBM Tivoli AccessManager Base CD for your particular platform. If you plan to install the IBMSecureWay Directory server as your user registry, the following documents areavailable in the /doc/Directory path on the IBM Tivoli Access Manager Base CDfor your particular platform:v IBM SecureWay Directory Installation and Configuration Guide

(aparent.pdf, lparent.pdf, sparent.pdf, wparent.pdf)Provides installation, configuration, and migration information for IBMSecureWay Directory components on AIX®, Linux, Solaris, and Microsoft®

Windows® operating systems.v IBM SecureWay Directory Release Notes

(relnote.pdf)Supplements IBM SecureWay Directory, Version 3.2.2, product documentationand describes features and functions made available to you in this release.

v IBM SecureWay Directory Readme Addendum

(addendum322.pdf)

Preface xiii

Provides information about changes and fixes that occurred after the IBMSecureWay Directory documentation had been translated. This file is in Englishonly.

v IBM SecureWay Directory Server Readme

(server.pdf)Provides a description of the IBM SecureWay Directory Server, Version 3.2.2.

v IBM SecureWay Directory Client Readme

(client.pdf)Provides a description of the IBM SecureWay Directory Client SDK, Version3.2.2. This software development kit (SDK) provides LDAP applicationdevelopment support.

v SSL Introduction and iKeyman User’s Guide

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

v IBM SecureWay Directory Configuration Schema

(scparent.pdf)Describes the directory information tree (DIT) and the attributes that are used toconfigure the slapd32.conf file. In IBM SecureWay Directory Version 3.2, thedirectory settings are stored using the LDAP Directory Interchange Format(LDIF) in the slapd32.conf file.

v IBM SecureWay Directory Tuning Guide

(tuning.pdf)Provides performance tuning information for IBM SecureWay Directory. Tuningconsiderations for directory sizes ranging from a few thousand entries tomillions of entries are given where applicable.

For more information about IBM SecureWay Directory, see the following Web site:

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

IBM WebSphere Application ServerIBM WebSphere Application Server, Advanced Single Server Edition, Version 4.0.2,is installed with the Web portal manager interface. For information about IBMWebSphere Application Server, see the following Web site:

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

Accessing publications onlinePublications in the product libraries are included in Portable Document Format(PDF) on the product CD. To access these publications using a Web browser, openthe infocenter.html file, which is located in the /doc directory on the product CD.

When IBM publishes an updated version of one or more online or hardcopypublications, they are posted to the Tivoli Information Center. The TivoliInformation Center contains the most recent version of the publications in theproduct library in PDF or HTML format, or both. Translated documents are alsoavailable for some products.

You can access the Tivoli Information Center and other sources of technicalinformation from the following Web site:

xiv IBM Tivoli Access Manager: WebSEAL Administrator’s Guide

http://www.tivoli.com/support/documents/

Information is organized by product, including release notes, installation guides,user’s guides, administrator’s guides, and developer’s references.

Note: If you print PDF documents on other than letter-sized paper, select the Fit topage check box in the Adobe Acrobat Print dialog (which is available whenyou click File → Print) to ensure that the full dimensions of a letter-sizedpage are printed on the paper that you are using.

Ordering publicationsYou can order many Tivoli publications online at the following Web site:

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

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

http://www.tivoli.com/inside/store/lit_order.html

Providing feedback about publicationsWe are very interested in hearing about your experience with Tivoli products anddocumentation, and we welcome your suggestions for improvements. If you havecomments or suggestions about our products and documentation, contact us in oneof the following ways:v Send an e-mail to [email protected] Complete our customer feedback survey at the following Web site:

http://www.tivoli.com/support/survey/

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 can alsouse the keyboard instead of the mouse to operate all features of the graphical userinterface.

Contacting customer supportIf you have a problem with any Tivoli product, you can contact Tivoli CustomerSupport. See the Tivoli Customer Support Handbook at the following Web site:

http://www.tivoli.com/support/handbook/

The handbook provides information about how to contact Tivoli CustomerSupport, depending on the severity of your problem, and the followinginformation:v Registration and eligibilityv Telephone numbers and e-mail addresses, depending on the country in which

you are located

Preface xv

v What information to gather before contacting support

Conventions used in this bookThis guide uses several conventions for special terms and actions, operatingsystem-dependent commands and paths, and margin graphics.

Typeface conventionsThe following typeface conventions are used in this book:

Bold Command names and options, keywords, and other informationthat you must use literally appear in bold.

Italic Variables, command options, and values you must provide appearin italics. Titles of publications and special words or phrases thatare emphasized also appear in italics.

Monospace Code examples, command lines, screen output, file and directorynames, and system messages appear in monospace font.

xvi IBM Tivoli Access Manager: WebSEAL Administrator’s Guide

Chapter 1. IBM Tivoli Access Manager WebSEAL overview

IBM®Tivoli®Access Manager for e-business (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 AccessManager’s 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 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, AccessManager provides authentication, authorization, data security, and centralizedresource management capabilities. You use Access Manager in conjunction withstandard Internet-based applications to build highly secure and well-managedintranets.

At its core, Access Manager provides:v Authentication framework

Access Manager provides a wide range of built-in authenticators and supportsexternal authenticators.

v Authorization frameworkThe Access Manager authorization service, accessed via the Access Managerauthorization API, provides permit and deny decisions on requests for protectedresources located in the secure domain.

With Access Manager, businesses can securely manage access to private internalnetwork-based resources while leveraging the public Internet’s broad connectivityand ease of use. Access Manager, in combination with a corporate firewall system,can fully protect the Enterprise intranet from unauthorized access and intrusion.

IBM Tivoli Access Manager WebSEAL:

© Copyright IBM Corp. 1999, 2002 1

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 Access Manager’s protected Web object space.WebSEAL can provide single sign-on solutions and incorporate back-end Webapplication 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 Access Manager’s authorization service to determinewhether 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 Access Manager security modelThe security policy for an 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 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 identity of a user is proven to WebSEAL through the process of authentication.A user can participate in the secure domain as authenticated or unauthenticated.Only users with an entry in the user registry can become authenticated users.Using ACLs and POPs, the security administrator can make certain publicresources available to unauthenticated users. Other resources can be madeavailable only to certain authenticated users.

When a user successfully authenticates to WebSEAL, a credential is created for thatuser. The credential contains the user identity, any group memberships, and anyspecial (“extended”) security attributes.

The Access Manager authorization service enforces security policies by comparinga user’s authentication credentials with the policy permissions assigned to therequested 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 anAccess Manager secure domain. The virtual objects that appear in the hierarchicalobject 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 Access Managermanagement 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 Access Manager:v Web objects

These objects represent anything 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 Access Manager management objects

These objects represent the management activities that can be performed via theWeb portal manager. The objects represent the tasks necessary to define usersand set security policy. Access Manager supports delegation of managementactivities and can restrict an administrator’s ability to set security policy to asubset of the object space.

v User-defined objects

Chapter 1. IBM Tivoli Access Manager WebSEAL overview 3

These objects represent customer-defined tasks or network resources protectedby applications using the authorization service via the Access Managerauthorization API.

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

The Access Manager authorization service performs authorization decisions basedon the policies applied to these objects. When a requested operation on a protectedobject is permitted, the application responsible for the resource implements thisoperation.

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. 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 someoperation on that object.

POP policies contain additional conditions on the request that are passed back toAccess Manager Base and the resource manager (such as WebSEAL) along with the“yes” ACL policy decision from the authorization service. It is the responsibility ofAccess Manager and the resource manager to enforce the POP conditions.

The following tables list the available attributes for a POP:

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

Explicit and inherited policyPolicy can be explicitly applied or inherited. The Access Manager protected objectspace supports inheritance of ACL and POP policy attributes. This is an importantconsideration for the security administrator who manages the object space. The

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

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

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

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

ACL

(containing multiple

entries)

Figure 3. ACL policy


administrator only needs to apply explicit policies at points in the hierarchy wherethe rules must change.

Policy administration: The Web portal managerThe Web portal manager is a Web-based graphical application used to managesecurity policy in an Access Manager secure domain. The pdadmin command lineutility provides the same administration capabilities as the Web portal manager,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 Access Manager servers. You canalso 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, Access Manager security policy determines whetherthat client is permitted to perform an operation on a requested resource. Becauseaccess to every Web resource in a secure domain is controlled by WebSEAL,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 Access Manager authorization model, authorization policy is implementedindependently of the mechanism used for user authentication. Users canauthenticate their identity using either public/private key, secret key, orcustomer-defined mechanisms.

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.

ManagementObjects

WebObjects

User-DefinedObjects

Explicit RuleInherited

Rule

Figure 4. Explicit and inherited policies


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 Access Manager authorization API to callthe 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.

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

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

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 Access Manager authorization process


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

Planning and implementing the security policyA corporate security policy identifies:1. The Web resources requiring protection2. The level of protection

Access Manager uses a virtual representation of these Web resources, called theprotected object space. The protected object space contains objects that representactual 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 who 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 Access Manager is the Access Manager authorizationservice—which permits or denies access to protected objects (resources) based onthe user’s credentials and the access controls placed on the objects.

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 contentv Understand the strengths and weaknesses of the available WebSEAL

configuration 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 via HTTPv Unauthenticated credential used for access control to resourcesv Basic WebSEAL configuration requirements

2. Public content – access requires privacy (encryption)v Unauthenticated clients access via 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 via 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 only requires a client identity. From this identity, WebSEAL builds an

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

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

Client WebSEAL

Who are you?

Who are you?

Figure 6. Mutual authentication


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 only successful if the user has an account defined in theAccess Manager user registry or is processed successfully by a CDAS.Otherwise the user is designated as 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 Access Manager user.WebSEAL then builds the credentials appropriate to this user. This is known ascredentials acquisition.The credential represents a user’s privileges in the secure domain, describes theuser in a specific context, and is only valid 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 which permits ordenies access to requested objects in the WebSEAL protected object space.

Credentials can be used by any Access Manager service that requires informationabout the client. Credentials allow Access Manager to securely perform a multitudeof services such as authorization, auditing, and delegation.

Access Manager distinguishes the authentication of the user from the acquisition ofcredentials. A user’s identity is always constant. However, credentials—whichdefine the groups or roles in which a user participates—are variable.Context-specific credentials can change over time. For example, when a person ispromoted, credentials must reflect the new responsibility level.

See Chapter 5, “WebSEAL authentication” on page 97 for further information aboutsupport for specific authentication methods.

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

In either case, the Access Manager authorization service requires a user credentialto make authorization decisions on requests for resources in the secure domain.WebSEAL handles authenticated user credentials differently from unauthenticateduser 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 Access Manager user registry (or is processedsuccessfully via a CDAS). The authenticated user credential contains the useridentity, any group memberships, and any special (“extended”) security attributes.

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 authenticate. WebSEAL prompts the user tolog in.

v Successful authentication can only occur if the user is a member of the AccessManager 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 Access Manager authorization

service uses the credential information during the decision-making process.v When the user logs off, the cache entry for that user is removed and the session

is 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 authenticate. 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 junctionsAccess Manager provides authentication, authorization, and management servicesfor a network. In a Web-based network, these services are best provided by one ormore front-end WebSEAL servers that integrate and protect Web resources andapplications located on back-end Web servers.

WebSEAL session/credentials cache

Session ID Cache Data Time-stamps

1234user credentialinternal flagsinternal data

creation timelast 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, or junction. A WebSEAL junction is a TCP/IPconnection between 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 AccessManager security service (see “Using query_contents with third-party servers” onpage 169).

Junctions provide a scalable, secure environment that allows load balancing, highavailability, and state management capabilities—all performed transparent 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 transparent 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 will also correctly fail-over when a server is down and start re-usingthat server once it has been restarted.

If the back-end application requires 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 general administration andconfiguration tasks you can perform to customize the WebSEAL server for yournetwork.

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 25v “Managing custom HTTP error message pages” on page 30v “Managing custom account management pages” on page 33v “Managing client-side and server-side certificates” on page 35v “Configuring default HTTP logging” on page 39v “Configuring HTTP logging using event logging” on page 42v “Logging WebSEAL serviceability messages” on page 43

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 an Access Manager for Windows installation. Youcannot configure this path on UNIX installations of 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 Access Manager protected object space that represents this WebSEALserver 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 Access Managerprotected object space would appear as:/WebSEAL/sales1

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

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

WebSEAL returns HTTP/1.1HTTP/1.0 requests are only sent to junctioned back-end servers 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/webseald.log

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

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

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

Introducing 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\

Access Manager configuration files are ASCII text-based and can be edited using acommon text editor. The configuration files contain parameter entries in thefollowing format:parameter = value

The initial installation of Access Manager sets default values for most parameters.Some parameters are static and never change; others can be modified to customizeserver 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-schemes][filter-content-types][script-filtering][gso-cache][ltpa-cache]

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

SESSION [session]

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


Sections Stanzas

LOGGING [logging]

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

POLICY DIRECTOR [policy-director]

See Appendix A, “webseald.conf reference” on page 213.

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}

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 = nodisable-ssl-v3 = nodisable-tls-v1 = 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

Once 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 Description Default 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

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 27v “Configuring Web document caching” on page 28v “Specifying document types for filtering” on page 30

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


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 only used 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 only generated 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

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

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

Note: There are serious security issues involved in the use of .bat and .cmd files.Use these file types with caution.

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 wildcard (* ). A value of */* represents a default object cache that will hold anyobject that does not correspond to an explicitly configured cache.

cache-type Specifies the type of storage medium to use for the cache. This releaseof 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 only occurs 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 which 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 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 types for filteringYou can specify the document content types that WebSEAL filters in responsesfrom back-end junctioned servers. The type parameter in the [filter-content-types]stanza of the webseald.conf configuration file accepts a MIME type value.WebSEAL is configured by default to filter documents of two MIME types:[filter-content-types]type = text/htmltype = text/vnd.wap.wml

The MIME type specifications in this stanza determine what additional filtering isperformed by WebSEAL on responses from back-end junctioned servers.Additional filtering functionality includes:v URL scheme filtering

[filter-schemes] stanza in webseald.conf

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

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

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 access


v CGI programs cannot be executed because of incorrect UNIX file permissions orsomething 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

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 Description HTTP ErrorCode

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.


Filename Title Description HTTP ErrorCode

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

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 “/” ifnone.

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

Managing custom account management pagesAccess Manager includes sample account management HTML pages that can becustomized to contain site-specific messages or perform site-specific actions. Mostforms 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 locates its files in:lib/html/JP

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


Parameter Page Usage

help = help.html Any method

token-login = tokenlogin.html Token login

next-token = nexttoken.html Token login

stepup-login = stepuplogin.html Step-up authentication

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.

Macro support for account management pagesThere are also two macros available for use in these pages. These macro strings canbe placed in the template files. The macro dynamically substitutes appropriatevalues.

Macro Description

%USERNAME% The name of the logged in user.

%ERROR% The hard-coded error message returned from Access Manager.

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


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 via 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 36v “Using the iKeyman certificate management utility” on page 37v “Configuring CRL checking” on page 38

Understanding 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 encrypted version of the key database password. The stem name of thisfile is the same as the associated .kdb file.


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 is rejected.Included in the certificate request is the common name, organization, street address, and otherinformation that was specified at the time of the request, as well as the public and private keyassociated 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. The ASCII data in the .arm file is what you send to theCA during the certificate request process. Note: Any file type 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, the certificate of the CAthat issued the certificate, the issuer of the CA’s certificate, as well as his issuer, and so on. Becausea .p12 file contains a private key, it is password protected.

Configuring key database parametersWebSEAL Certificate Keyfile:

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.

Certificate Keyfile 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

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.

Internal 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 Access Manager servers. You should only modify theseparameters 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 a one or more key databasesv change key database passwordsv create new WebSEAL certificatesv set a new default WebSEAL certificate


v 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

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 certificate authentication are found in the [ssl] stanza of thewebseald.conf configuration file:[ssl]#ssl-ldap-server = <server-name>#ssl-ldap-server-port = <port-id>#ssl-ldap-user = <webseal-admin-name>#ssl-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 ssl-ldap-user indicates that the SSL authentication mechanismshould bind to the LDAP server as an anonymous user.

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, please 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 toactivate the cache. When gsk-crl-cache-size and gsk-crl-cache-entry-lifetime areboth 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 Files LocationParameter

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

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


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 may want to alter the frequency with which the server forces a flushof 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 Access Manager server isrecorded 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 takes the value of the From: header of the receivedHTTP request. The value “unauth” is used for an unauthenticateduser.


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 by using the logcfg event logging parameterto define one or more log agents (loggers) that gathers a specific category of loginformation from the event pool and directs this information to a destination:[aznapi-configuration]logcfg = <category>:{stdout|stderr|file|pipe|remote} [[<param>[=<value>]][,<param>[=<value>]]...]

Refer to the “Event Logging” chapter 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 39). 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 messagesAccess Manager WebSEAL serviceability messages are controlled by the AccessManager WebSEAL routing file. The routing file is located in the followingdirectory:

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:

Server ConfigurationFile

Log File Location

WebSEAL Server(webseald)

webseald.conf UNIX:[logging]server-log=/var/pdweb/log/webseald.logWindows:[logging]server-log=C:\Program Files\Tivoli\PDWeb\log\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).


Chapter 3. Advanced server configuration

This chapter contains information that describes general administration andconfiguration tasks you can perform to customize the WebSEAL server for yournetwork.

Topic Index:v “Configuring a default quality of protection level” on page 45v “Configuring authorization database updates and polling” on page 46v “Managing worker thread allocation” on page 47v “Replicating front-end WebSEAL servers” on page 50v “Configuring multiple WebSEAL server instances” on page 50v “Configuring switch user (SU) for administrators” on page 57v “Configuring WebSEAL server-side request caching” on page 63v “Handling UTF-8 encoded characters” on page 66v “Preventing vulnerability caused by cross-site scripting” on page 68v “Suppressing server identity” on page 69v “Using WebSEAL statistics” on page 69v “Using the trace utility to capture WebSEAL actions” on page 78

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-40# 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


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

Configuring authorization database updates and pollingThe Access Manager policy server (pdmgrd) manages the master authorizationpolicy database and maintains location information about other Access Managerservers in the secure domain. An Access Manager administrator can make securitypolicy changes to the secure domain at any time. The policy server makes thenecessary adjustments to the master authorization database whenever securitypolicy 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 enabledby default).

v Check (poll) the master authorization database at regular intervals (configurableand 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 enables and disables update notification listening byWebSEAL. By default, listening is enabled. To disable listening, enter “disable”.[aznapi-configuration]listen-flags = enable

The tcp-port parameter configures the TCP port for the listener:[aznapi-configuration]tcp-port = 12056

The udp-port parameter configures the TCP port for the listener:[aznapi-configuration]udp-port = 0

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

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

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.

Chapter 3. Advanced server configuration 47

Choosing the optimal number of worker threads depends on understanding thequantity and type of traffic on your network.

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 which 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: It is highly recommended that this parameter only be changed totroubleshoot a performance problem.

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 serves to act as a warning before the “hard” limit is reached.When the worker-thread-soft-limit is exceeded, warning messages are sent(every 30 seconds) 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 acts as the cut-off point for servicing requests across a junction.When the worker-thread-hard-limit is exceeded, error messages are sent (every30 seconds) to the WebSEAL error log file. In addition, the user is sent 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.

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 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 Access Manager supports a manual configuration procedure toreplicate 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. Stop WebSEAL on WS2.3. On WS2, change the value of the server-name parameter in the webseald.conf

configuration file from “WS2” to “WS1”:[server]server-name = WS1

4. Restart WebSEAL on WS2.

The WS2 server now uses the object /WebSEAL/WS1 as the base for authorizationevaluations. The WS2 server can also respond to object list and object showcommands for objects residing below /WebSEAL/WS1.

The pdadmin utility still lists the /WebSEAL/WS2 object as part of the object space.This object is now meaningless and can be removed:pdadmin> object delete /WebSEAL/WS2

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: If server WS2 is configured as a replica ofserver WS1, server WS2 uses /WebSEAL/WS1 as the base for authorizationevaluations.

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 instancesAccess Manager provides the capability for configuring multiple WebSEAL serverinstances 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 specified by the –m optionmust be unique for all WebSEAL instances.

Each configured WebSEAL instance has a unique name, a unique internal portnumber (for inter-Access Manager server communication), a unique directorylocation, and a unique configuration file. Multiple configuration files are madeunique by the server instance name, prepended with webseald-. For example:/opt/pdweb/etc/webseald-<instance-name>.conf

The required configuration tools for configuring and unconfiguring multipleWebSEAL server instances include:v UNIX systems:

PDWeb_config command line utilityPDWeb_unconfig command line utility

Note: The pdconfig utility can be used to create the initial WebSEAL instance.The PDWeb_config command line must be used to create all additionalinstances. This discussion of multiple instances assumes you haveconfigured an initial WebSEAL server.

v Windows systems:ivweb_setup command line utilityivweb_uninst command line utility

Configuring multiple WebSEAL instances on UNIXThe PDWeb_config utility is located in the following directory:/opt/pdweb/sbin/

PDWeb_config syntax:# ./PDWeb_config –i <instance-name> –m <internal-port> [–n <network-interface>]

Argument Description

instance-name Unique name for this instance. You must use this nameto unconfigure the instance. The length of this name islimited to 20 characters.

internal-port Unique port number for inter-Access Manager servercommunication. Value must be greater than 1023. (Valuesless than or equal to 1023 are reserved.)

network-interface Optional argument to specify the IP address of a networkinterface.


Note: The inter-server port value specified by the –m option must be unique forall WebSEAL instances.

Configuring multiple instances on unique HTTP/HTTPS ports:

1. Assumption: Machine is configured with an initial WebSEAL server (pdconfig)and a single network card/IP address (for example: 1.2.3.4).

2. Change directory location:# cd /opt/pdweb/sbin

3. Run the PDWeb_config command to create and configure an additionalWebSEAL instance.In this scenario, multiple server instances are made unique through uniqueinter-server port and HTTP/HTTPS listening port designations on the defaultnetwork interface. Therefore, do not use the –n option to specify a networkinterface. For example:# ./PDWeb_config –i webseal2 –m 3232

4. The configuration setup screen appears: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/docsa. Accept configuration and continue with installationx. Exit installationSelect item to change:

5. By default, the initial WebSEAL server listens for requests on *:80 and *:443.Select the HTTP and HTTPS port menu items and provide unique port valuesthat are not in use by any other server (for example, 81 and 444).

Note: A warning message appears if you select a port value already in use.You are given the opportunity to select a different value.

6. Run the PDWeb_config command to create and configure any additionalWebSEAL server instances (with unique inter-server ports). For example:# ./PDWeb_config –i webseal3 –m 3233

7. From the configuration setup screen, configure unique HTTP and HTTPS portvalues.

Note: The maximum number of allowed WebSEAL instances is governed bysystem configuration limitations, such as available RAM and disk space.If any system resource is exceeded, configuration error and startupfailure messages appear.

Configuring multiple instances on unique logical network interfaces:

1. Assumption: Machine is configured with an initial WebSEAL server(pdconfig) and a single network card/IP address.

2. By default, the initial WebSEAL server listens for requests on *:80 and *:443.You must assign a specific IP address for this initial network interface beforeyou can configure and run additional WebSEAL servers.

Note: Additional WebSEAL servers cannot start if the initial WebSEAL serverlistens on *:80 and *:443.

3. Edit the webseald.conf configuration file and specify the appropriate IPaddress for the initial WebSEAL server by adding the network-interfaceparameter to the [server] stanza. For example:


[server]network-interface = 1.2.3.4

4. Restart the WebSEAL server:# /opt/pdweb/bin/pdweb restart

5. For each additional WebSEAL server instance, configure an additional logicalnetwork interface (alias). For example (on Solaris version 2.8):# ifconfig hme0 addif 1.2.3.5 netmask w.x.y.z up# ifconfig hme0 addif 1.2.3.6 netmask w.x.y.z up

Note: Alternatively, you could assign each WebSEAL instance to a uniquepre-configured physical network card.


7. Run the PDWeb_config command to create and configure an additionalWebSEAL instance.In this scenario, multiple server instances are made unique through a uniquenetwork interface on common inter-server and HTTP/HTTPS listening ports.Therefore, you must use the –n option. For example:# ./PDWeb_config –i webseal2 –m 3232 –n 1.2.3.5

HP-UX (network interface name = lan0:1):# ./PDWeb_config –i webseal2 –m 3232 –n lan0:1

HP-UX uses the network interface name instead of the IP address. ThePDWeb_config utility checks if the interface has a valid IP address.

8. The configuration setup screen appears: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/docsa. Accept configuration and continue with installationx. Exit installationSelect item to change:

9. Accept the standard HTTP and HTTPS port values as listed.10. Run the PDWeb_config command to create and configure any additional

WebSEAL server instances. For example:# ./PDWeb_config –i webseal3 –m 3233 -n 1.2.3.6

HP-UX (network interface name = lan0:2):# ./PDWeb_config –i webseal3 –m 3232 –n lan0:2

11. From the configuration setup screen, accept the standard HTTP and HTTPSport values as listed.

Note: The maximum number of allowed WebSEAL instances is governed bysystem configuration limitations, such as available RAM and disk space. Ifany system resource is exceeded, configuration error and startup failuremessages appear.

Configuring multiple WebSEAL instances on Win NT/2000Assumptions:v Initial WebSEAL server instance has been configured


v Procedures described are appropriate for a Windows NT/2000 platform

ivweb_setup syntax:MSDOS> ivweb_setup -m <pdadmin-passwd> -i <instance-name> \-M <internal-port> -u {yes|no} -r <http-port> -U {yes|no} \-R <https-port> [-n <network-interface>]

Option and Argument Description

–m <pdadmin-password> Administration password.

–i <instance-name> Unique name for this instance. You must use this nameto unconfigure the instance. The length of this name islimited to 20 characters.

–M <internal-port> Unique port number for inter-Access Manager servercommunication. Value must be greater than 1023. (Valuesless than or equal to 1023 are reserved.)

–u {yes|no} Enable/disable HTTP access.

–r <http-port> Port number for HTTP access.

–U {yes|no} Enable/disable HTTPS access.

–R <https-port> Port number for HTTPS access.

–n <network-interface> Optional argument to specify the IP address of a networkinterface.

Note: The inter-server port value specified by the –M option must be unique forall WebSEAL instances.

Configuring multiple instances on unique HTTP/HTTPS ports:

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. Change directory location:MSDOS> cd C:\Program Files\Tivoli\Policy Director\PDWeb\bin

3. Run the ivweb_setup command to create and configure an additionalWebSEAL instance.In this scenario, multiple server instances are made unique through uniqueinter-server and HTTP/HTTPS listening port designations on a commonnetwork interface. Therefore, do not use the –n option to specify additionalnetwork interfaces. For example:MSDOS> ivweb_setup -m xxxxx –i webseal2 –M 3232 -u yes -r 81 -U yes -R 444

Note: A warning message appears if you select a port value already in use.You are given the opportunity to select a different value.

4. Run the ivweb_setup command to create and configure any additionalWebSEAL server instances. For example:MSDOS> ivweb_setup -m xxxxx –i webseal3 –M 3233 -u yes -r 82 -U yes -R 445

Configuring multiple instances on unique logical network interfaces:

1. Assumption: Windows is configured with an initial WebSEAL server and asingle network card/IP address.

2. By default, the initial WebSEAL server listens for requests on *:80 and *:443.You must assign a specific IP address for this initial network interface beforeyou can configure and run additional WebSEAL servers.


Note: Additional WebSEAL servers cannot start if the initial WebSEAL serverlistens on *:80 and *:443.

3. Edit the webseald.conf configuration file and specify the appropriate IP addressfor the initial WebSEAL server by adding the network-interface parameter tothe [server] stanza. For example:[server]network-interface = 1.2.3.4

4. Restart the WebSEAL server from the Services Control Panel.5. For each additional WebSEAL server instance, configure an additional logical

network interface (alias) using the Network Connections control panel. Forexample (on Windows 2000):a. Control Panel > Network Connectionsb. Right-click on Local Area Connections and select Properties.c. Select Internet Protocol (TCP/IP)d. Click on Properties and select Advancede. From IP Settings tab, click Addf. Enter an IP address for the new network interfaceg. Enter a subnet maskh. Click Addi. Open a command prompt window and enter:

MSDOS> ipconfig -all

All network interfaces should appear as listening.j. Repeat these steps for additional network interfaces

6. Change directory location:MSDOS> cd C:\Program Files\Tivoli\PDWeb\bin

7. Run the ivweb_setup command to create and configure an additionalWebSEAL instance.In this scenario, multiple server instances are made unique through a uniquenetwork interface on common inter-server and HTTP/HTTPS listening ports.Therefore, you must use the –n option. For example:MSDOS> ivweb_setup -m xxxxx –i webseal2 –M 3232 -u yes -r 80 -U yes \-R 443 -n 1.2.3.5

8. Run the ivweb_setup command to create and configure any additionalWebSEAL server instances. For example:MSDOS> ivweb_setup -m xxxxx –i webseal3 –M 3233 -u yes -r 80 -U yes \-R 443 -n 1.2.3.6

Unconfiguring multiple WebSEAL instancesYou cannot unconfigure the initial WebSEAL server until all server instances areunconfigured first.

UNIX:PDWeb_unconfig -i <instance-name>


2. Run the PDWeb_unconfig command for each instance. For example:# ./PDWeb_unconfig -i webseal2# ./PDWeb_unconfig -i webseal3


Windows:ivweb_uninst -deconfig -m <pdadmin-passwd> -i <instance-name>

1. Change directory location:MSDOS> cd C:\Program Files\Tivoli\PDWeb\bin

2. Run the ivweb_uninst command for each instance. For example:MSDOS> ivweb_uninst -deconfig -m xxxxxx -i webseal2MSDOS> ivweb_uninst -deconfig -m xxxxxx -i webseal3

Server start, stop, restart, 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 user (SU) for administratorsThe WebSEAL switch user functionality allows specific administrators to assumethe identity of a user who is a member of the Access Manager secure domain. Theswitch user implementation is similar to the su command in UNIX environments.In the WebSEAL environment, the administrator acquires the user’s true credentialsand interacts with resources and back-end applications with the exact sameabilities as the actual user.

Switch user can be used in a Help Desk environment to troubleshoot and diagnoseproblems. Switch user can also be used to test a user’s access to resources andperform application integration testing.

The following items highlight the important features of switch user:v Switch user does not require the user’s password.v The administrator uses a credential representing the actual user.v Switch user is restricted to members of a special administrator’s group. An

administrator cannot switch user to any other member of this group.v Access Manager processes, sec_master, and other selected users can be excluded

from the switch user capabilities through membership in an exclusion groupv A special HTML form is used to supply switch user information and activate a

special authentication mechanism that returns the specified user’s credentialwithout the requirement of a password.

v The administrator uses the pkmslogout utility to end a switch user session.

Understanding the switch user process flowThe following sequence describes the switch user process flow:1. Assumptions: The administrator (a member of the su-admins group) has

authenticated to WebSEAL, a session has been established, and an entry forthe administrator has been created in the WebSEAL session/credentials cache.

2. The administrator connects to a pre-configured switch user HTML form. Thisform is accessible only to members of the su-admins group.

3. The switch user form is completed and returned with the followinginformation: user name (administrator is “switched to” this user), adestination URL, an authentication method.This action results in a POST request being sent to /pkmssu.form.


4. A special switch user authentication is performed by the built-in switch usershared library or a custom switch user CDAS library. The switch user library(whether custom or built-in) returns a valid credential for the user withoutrequiring the user password for input.

5. During switch user authentication, WebSEAL checks the Access Managersu-admins, securitygroup and su-excluded groups to ensure the user namesupplied in the switch user form is not a member of one of these groups.

6. Upon successful authentication of the designated user, a new cache datastructure is created that contains the user credential.

7. The administrator’s original cache data is removed from the administrator’sWebSEAL session cache entry and stored in a separate location. The usercache data takes its place. Now the cache entry contains the administrator’soriginal session ID and the user’s cache data (with the credential). Thecredential also contains a new User Session ID that can be used for any usersession management situations. The session cache entry is indexed by thesame session ID used by the administrator before the switch user operation.

8. WebSEAL sends a redirect to the browser for the destination URL supplied inthe switch user form.

9. The request is processed normally, using the user’s credential, and the URL isaccessed. The administrator can continue to make other requests. Allauthorization decisions for these requests are based on the credential of theuser.

10. The administrator ends the switch user session using the standard AccessManager /pkmslogout utility.

11. Upon successful log out, the user’s cache data is deleted and theadministrator’s original cache data (and credential) is restored. Theadministrator is returned to the original page from which the switch user formwas requested. The authorization service uses the original credential of theadministrator for all subsequent requests.

Enabling switch user: A summaryTo enable switch user functionality:1. Uncomment the appropriate authentication mechanisms in webseald.conf and

add the path to the shared library that handles the switch user operation.2. Use the pdadmin utility to add administrators to the su-admins group account.

WebSEAL session/credentials cache

Session ID Cache Data

1234 - user credential- other user data

admincacheentry

- admin credential- other admin data

originaladministrator session ID

user cache datareturned from SU

authentication

administrator cache datastored during SU

Figure 15. Swapping administrator and user cache data during switch user


3. Use the pdadmin utility to add users to the su-excluded group account.4. Optionally, modify the switchuser.html form to specify pre-configured data,

such as the authentication method and the destination URL.5. Optionally, design other forms to validate or process data to be submitted to

/pkmssu.form.

Configuring the switch user HTML formThe switch user form is defined in the [acnt-mgt] stanza of the webseald.confconfiguration file.v The switch-user parameter specifies the name of the file. By default the file

name is switchuser.html:[acnt-mgt]switch-user = switchuser.html

v The mgt-pages-root parameter specifies the sub-directory location for thelocalization directory containing this file:[acnt-mgt}mgt-pages-root = lib/html/<LANG>

On US English systems, the LANG directory is called “C”.v The lib/html path segment is relative to the server-root parameter value:

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

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

The switch user form can be edited for customized appearance and functionality.The form contains requests for:v User name (the administrator “switches to” this user)

This user cannot be a member of su-excluded, su-admins, or securitygroupgroups.

v Destination URL

This page appears after a successful switch user operation. You can configurethis as hidden input containing an appropriate home page or a successful switchuser confirmation page.

v Authentication method

The authentication method determines the type of information used to build theuser credential. You can configure this field as hidden input. Refer to the notesbelow for a list of the valid authentication method parameters.

The default switch user form appears as follows:


Switch user form notes:

v The form is only available to members of the su-admins group. An ACL is notrequired on this file. WebSEAL performs an internally hard-coded groupmembership check. WebSEAL returns a 404 “Not Found” error when the groupmembership check fails.

v User name, destination URL, and authentication method are all required data.v The required data can be built into the form as hidden fields.v WebSEAL verifies that all required data is present in the submitted form. If data

is missing, the form is returned to the administrator with a descriptive message.v Valid values for the authentication method include:

su-basu-formssu-certificatesu-token-cardsu-http-requestsu-cdsso

These authentication method parameters specify which authenticationmechanism WebSEAL is to use.

v The su-ba and su-forms methods both map to the su-password authenticationmechanism specified in the webseald.conf configuration file.

v Switch user form data is submitted to the /pkmssu.form action URL.

Enabling and excluding users from switch userOnly administrators who are members of the su-admins group can use the switchuser function and receive the switch user HTML form. Switch user functionality isenabled for any user who is a member of the su-admins group.

Administrators can switch user to any Access Manager account, except thosebelonging to certain groups. You can exclude other Access Manager users fromswitch user through membership in the su-excluded group. In addition, membersof the Access Manager securitygroup group are excluded from switch userfunctionality. Typically, sec_master and the Access Manager processes are membersof the securitygroup.

During switch user, WebSEAL performs checks on all three groups. You cannot“switch to” someone who is a member of the su-admins, su-excluded, orsecuritygroup groups.

Figure 16. Switch user data form


Configuring the switch user authentication mechanismThe primary responsibility of the switch user authentication mechanism (a built-inshared library) is to create a credential representing the “switched-to” user, basedon the supplied user name and authentication method, without requiring apassword as input. A custom CDAS authentication mechanism must meet the samerequirement.

You specify switch user authentication mechanisms in the [authentication-mechanisms] stanza of the webseald.conf configuration file. The followingauthentication mechanisms are supported:[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>

Access Manager supplies a single switch user library that can be used to enableany of the above authentication mechanisms in a default, non-customizedenvironment. The switch user library differs from the standard authenticationlibraries. The library specifies an authentication mechanism that takes the useridentity (supplied in the switch user form) and returns a valid credential for thatuser without requiring the user password for input.

The built-in switch user shared library provided with Access Manager is called:

Solaris libsuauthn.so

AIX libsuauthn.a

HP-UX libsuauthn.sl

Windows suauthn.dll

The switch user functionality also supports custom CDAS authenticationmechanisms. This support is important because a custom CDAS often suppliesadditional information to the user credential.

You are responsible for writing a custom switch user CDAS that emulates thebehavior of your existing CDAS while supporting the requirement of returning acredential without requiring the user password for input. Refer to the IBM TivoliAccess Manager WebSEAL Developer’s Reference.

Each configured switch user authentication library must be uniquely named, evenwhen the default library (libsuauthn) is used for more than one authenticationmethod.

ExampleIn the following example (for a Solaris platform), an existing environment hasthree authentication methods enabled:1. Forms authentication using the built-in libldapauthn library2. Certificates authentication using the built-in libsslauthn library3. Token authentication using a custom CDAS mechanism

The environment is now expanded to support switch user functionality for any ofthose three authentication methods. Three additional authentication parameters forswitch user must be enabled in the webseald.conf configuration file. In addition, a


new custom CDAS library must be written to emulate the existing token CDASand support the requirements of switch user authentication:[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

Remember that the su-forms authentication method supplied in the switch userform is mapped to the su-password authentication mechanism parameter inwebseald.conf. In addition, the supplied libsuauthn library has been renamed forboth the Forms and certificate mechanisms.

Configuring a CDAS switch user mechanismAn existing CDAS authentication mechanism often returns additional informationabout the user that is incorporated into the user’s credential. If you are using theswitch user feature in such an environment, you must write a special switch userCDAS that emulates the behavior of your existing CDAS while supporting therequirement of returning a credential without requiring the user password forinput.

The Access Manager CDAS API provides a set of identity components that can beused to pass client authentication information to the shared switch user CDASlibrary. This information is passed using a name/value list format, where the nameis 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.

Refer to the IBM Tivoli Access Manager WebSEAL Developer’s Reference for completeinformation and reference material related to writing a custom CDAS.

Impacting other WebSEAL functionality

Impact on session cache timeout configurationThe 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 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.

Incorporating Step-up authentication levelsThe 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: For this version of Access Manager, the administrator must know the user’spassword to successfully perform step-up authentication.

Support for 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: For this version of Access Manager, the administrator must know the“switched-to” user’s password to successfully reauthenticate.

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

Support for tag-valueThe tag-value capability often used by a CDAS is recognized and supported by theswitch user functionality.

Auditing the administrator during switch userIt 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 is called su-admin:su-admin = <su-admin-name>

This extended attribute is available to any auditing mechanism.

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

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

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 17. Example WebSEAL request caching process flow


This parameter does not limit the maximum POST size (which is unlimited) forrequests that do not require authentication.

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:1. Set request-body-max-read = 20482. 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 30.

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 URL’s. 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 which simply tolerate and accept characters outside thelegal range. WebSEAL, acting as a Web proxy, must be able to handle all thesecases.

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 URL’s 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 URL’scan 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 URL’s with DBCS or Unicode chars of the form %uXXXX.This 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 URL’s. 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 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 deploywith the parameter set to “no”. However, you should also ensure that nojunctioned Web server is configured to accept UTF-8 encoded URL’s.


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.

Please 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 encodingcan help 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 to WebSEAL to suppress this information inits responses to clients. To suppress server identity in HTTP server responses, setthe suppress-server-identity parameter in the [server] stanza of the webseald.confconfiguration file to “yes”:[server]suppress-server-identity = yes

The default setting is “no”.

Using WebSEAL statisticsWebSEAL provides a series of built-in software modules that, when enabled, canmonitor specific server activity and collect information about those activities. Atany instance in time, you can display the statistics information gathered since thatmodule was enabled. In addition, you can direct this statistics information to logfiles.

When you display statistics information, you see a “snapshot” of the informationsince the module was enabled. The information gathered by WebSEAL statisticsprovides a relative view of the activity being recorded. If statistics are captured atregular intervals over a period of time, you can generate a graphical view of therelative relationship of the server activities.

pdadmin stats command syntaxUse the pdadmin stats command to manage statistics components. This sectiondescribes the valid operations for the pdadmin stats command:


Basic pdadmin stats commandpdadmin> server task webseald-<instance> stats <command>

You can perform the following tasks with the pdadmin stats command:

stats on Enable statistics dynamically, by component

stats off Disable statistics, by component or all components at once

stats show List enabled components

stats get Display current statistics values by component or all components at once

stats reset Reset statistics values by component or all components at once

stats list List all available statistics components

Enable statistics dynamicallyYou can enable statistics reporting dynamically with the pdadmin stats oncommand or statically with configuration parameters in the webseald.confconfiguration file.

Use the pdadmin stats on command to enable statistics gathering and set thestatistics report frequency, count, and destination for a component.stats on <component> [<interval> [<count>]] [<logagent>]


component The statistic component name. Required. Statistics are gathered inWebSEAL memory for this component. Statistics for this component canalso be recorded in a log file by specifying the optional arguments tothis command.

interval The time interval between reports of information. This argument isoptional and results in statistics being sent to a log file. When thisoption is specified, statistics are sent, by default, to standard out of theWebSEAL server, which is the WebSEAL log file. You can specifyanother output location using the logagent argument. If interval is notspecified, no statistics are sent to any log file. However, the statisticcomponent is still enabled. You can obtain reports dynamically at anytime using pdadmin stats get.

count The number of reports sent to a log file. This argument is optional andrequires that the interval argument be specified. If interval is specifiedwithout count, the duration of reporting is indefinite. After the countvalue is reached, reporting to a log file stops. However, the statisticcomponent is still enabled. You can obtain reports dynamically at anytime using pdadmin stats get.

logagent Optionally specifies a destination for the statistics information gatheredfor the specified component. Refer to the “Using event logging” chapterof the IBM Tivoli Access Manager Base Administrator’s Guide for completeconfiguration details.

Note: By default, the pdweb.threads, pdweb.doccache, and pdweb.jmtcomponents are always enabled and cannot be disabled.

See also “Enabling statistics statically using event logging” on page 77.

Example 1:


This example enables the pdweb.http component. Because the interval option is notspecified, you can only obtain statistics information for this componentdynamically using pdadmin stats get.pdadmin> server task webseald-<instance> stats on pdweb.http

Example 2:

This example enables the pdweb.http component. Because the interval argument isspecified, the information is sent (by default) to the standard WebSEAL log file.The interval and count arguments cause the log file to accumulate 100 entriesrepresenting statistics reports 20 seconds apart.pdadmin> server task webseald-<instance> stats on pdweb.http 20 100

Example 3:

This example enables the pdweb.http component. The logagent argument usesevent logging configuration to specify a destination file for the statisticsinformation. The interval argument (without a count value) sends statisticsinformation for this component to the log file every 20 seconds indefinitely. Thegrowth of the log file is controlled by the rollover_size parameter. Refer to the“Using event logging” chapter of the IBM Tivoli Access Manager Base Administrator’sGuide for complete event logging configuration details.pdadmin> server task webseald-<instance> stats on pdweb.http 20 filepath=/tmp/jmt-stats.log,rollover_size=-1,flush_interval=20

Example 4:

This example illustrates a limitation of managing statistics dynamically. The firstcommand enables the pdweb.http component and directs statistics information tothe A.log file. The second command attempts to activate a second log file, B.log.However, this action actually results in deactivating A.log while activating B.log.pdadmin> server task webseald-<instance> stats on pdweb.http 20 file path=/tmp/A.logpdadmin> server task webseald-<instance> stats on pdweb.http 20 file path=/tmp/B.log

Disable statisticsDisable statistics gathering for a component or all components at once.stats off [<component>]

Example:pdadmin> server task webseald-<instance> stats off pdweb.sescache

Note: By default, the pdweb.threads, pdweb.doccache, and pdweb.jmtcomponents are always enabled and cannot be disabled.

Show enabled statistics componentsList all enabled statistics components or a specific enabled component. If aspecified component is not enabled, no output is displayed.stats show [<component>]

Example 1:pdadmin> server task webseald-<instance> stats showpdweb.authnpdweb.doccachepdweb.jmtpdweb.sescachepdweb.threads


Example 2:pdadmin> server task webseald-<instance> stats show pdweb.authnpdweb.authn

Get current statistic values dynamicallyShow the current values of statistics being gathered by a component or all enabledcomponents.stats get [<component>]

Example:pdadmin> server task webseald-<instance> stats get pdweb.threadsactive:4total:50

Reset statistics valuesReset the values being gathered by an enabled component or all enabledcomponents at once.stats reset [<component>]

Example:pdadmin> server task webseald-<instance> stats reset pdweb.threads

List all available statistics componentsList all components available to gather and report statistics.stats list

Example:pdadmin> server task webseald-<instance> stats listpd.ras.stats.monitorpd.log.EventPool.queuepd.log.file.clfpd.log.file.refpd.log.file.agentpdweb.authnpdweb.authzpdweb.httppdweb.httpspdweb.threadspdweb.jmtpdweb.sescachepdweb.doccachepdweb.jct.1

Statistics components and activity typesThis section describes the statistics components available to IBM Tivoli AccessManager WebSEAL.

pdweb.authn componentThe pdweb.authn statistics component gathers information related to WebSEALauthentication. The following table describes the types of information available:

Type Description

pass The total number of successful authentications

fail The total number of failed authentications

pwd exp The total number of authentication attempts made with an expiredpassword

max The maximum time for a single authentication process


Type Description

avg The average time for a single authentication process

total The total time for all authentication processing

Example:pdadmin> server task webseald-<instance> stats get pdweb.authnpass : 2fail : 1pwd exp : 0max : 0.178avg : 0.029total : 0.382

pdweb.authz componentThe pdweb.authz statistics component gathers information related to WebSEALauthorization. The following table describes the types of information available:

Type Description

pass The total number of successful authorization requests (how manyresources were successfully accessed)

fail The total number of failed authorization requests

Example:pdadmin> server task webseald-<instance> stats get pdweb.authzpass : 2fail : 1

pdweb.http componentThe pdweb.http statistics component gathers information related to WebSEALHTTP communication. The following table describes the types of informationavailable:

Type Description

reqs The total number of HTTP requests received

max-worker The maximum time used by a single worker thread to process an HTTPrequest

total-worker The total time used by all worker threads that process HTTP requests

max-webseal The maximum time used to process a single HTTP request - measuredinside the worker thread, after the request headers have been read, andeliminating connection setup overhead

total-webseal The total time used to process all HTTP requests - measured inside theworker threads, after the request headers have been read, and eliminatingconnection setup overhead

Example:pdadmin> server task webseald-<instance> stats get pdweb.httpreqs : 0max-worker : 0.000total-worker : 0.000max-webseal : 0.000total-webseal : 0.000


pdweb.https componentThe pdweb.https statistics component gathers information related to WebSEALHTTPS communication. The following table describes the types of informationavailable:

Type Description

reqs The total number of HTTPS requests received

max-worker The maximum time used by a single worker thread to process an HTTPSrequest

total-worker The total time used by all worker threads that process HTTPS requests

max-webseal The maximum time used to process a single HTTPS request - measuredinside the worker thread, after the request headers have been read, andeliminating connection setup overhead

total-webseal The total time used to process all HTTPS requests - measured inside theworker threads, after the request headers have been read, and eliminatingconnection setup overhead

Example:pdadmin> server task webseald-<instance> stats get pdweb.httpsreqs : 0max-worker : 0.000total-worker : 0.000max-webseal : 0.000total-webseal : 0.000

pdweb.threads componentThe pdweb.threads statistics component gathers information related to WebSEALworker thread activity. This component is always enabled by default and cannot bedisabled. The following table describes the types of information available:

Type Description

active The total number active worker threads handling requests

total The total number of configured worker threads

Example:pdadmin> server task webseald-<instance> stats get pdweb.threadsactive : 0total : 50

pdweb.jmt componentThe pdweb.jmt statistics component gathers information related to the WebSEALjunction mapping table. This component is always enabled by default and cannotbe disabled. The following table describes the types of information available:

Type Description

hits The total number of requests that required URL mapping via the junctionmapping table

Example:pdadmin> server task webseald-<instance> stats get pdweb.jmthits : 5


pdweb.sescache componentThe pdweb.sescache statistics component gathers information related to theWebSEAL session/credential cache activity. The following table describes the typesof information available:

Type Description

hit The number of requests that resulted in a session cache hit - that is, theuser had a session cache entry and it was successfully referenced

miss The number of requests that missed a session cache hit

add The number of entries that have been added to the session cache

del The number of entries that have been deleted from the cache

inactive The number of entries removed from the cache because the inactivitytimeout value had expired

lifetime The number of entries removed from the cache because the lifetimetimeout value had expired

LRU expired The number of times a “Least Recently Used” cache entry is expired orremoved to make room for a new entry.

Example:pdadmin> server task webseald-<instance> stats get pdweb.sescachehit : 0miss : 0add : 0del : 0inactive : 0lifetime : 0LRU expired : 0

pdweb.doccache componentThe pdweb.doccache statistics component gathers information related to WebSEALdocument caching activity. This component reports statistics for all MIME typesenabled in the [content-cache] stanza of the webseald.conf configuration file. Thiscomponent is always enabled by default and cannot be disabled.

The following table describes the types of global information available for allMIME types:

Type Description

General Errors The number of errors reported by the pdweb.doccachecomponent when the there are memory allocation failures,initialization failures, and invalid MIME type header values

Uncachable The number of instances when there is no cache defined for theMIME type of the document to be cached

Pending Deletes The number of entries marked for deletion, but are still in use

Pending Size The number of bytes used by entries marked for deletion but arestill in use

Misses The number of times a URL is looked up in the document cacheand not found. A found cached document eliminates the need toaccess the real document again.

Cache MIME type The MIME type of documents stored in this cache.


Cache MIME type statistics:

Type Description

Max size The maximum combined byte size of all documents in the cache.

Max entry size The maximum byte size for any single cached document. If thedocument size exceeds this internally calculated value, it is notcached.

Size The total byte count for all documents currently residing in thecache

Count The current number of entries in the cache.

Hits The number of successful lookups (documents successfully foundin the cache)

Stale hits The number of successful lookups that found an entry that was tooold and was purged instead

Create waits The number of times subsequent requests for a document areblocked (made to wait) while the document content is initiallybeing cached

Cache no room The number of times a document that is valid for caching cannotfit into the cache because there are too many entries being createdat the same time

Additions The number of successful new entries in the cache

Aborts The number of times the creation of a new cache entry is abortedbecause of problems or a header that indicates the entry shouldnot be cached

Deletes The number of cache entries deleted because the entry is stale(expired) or the creation was aborted

Updates The number of entries that have had expiry times updated

Too big errors The number of attempts to cache documents that exceed themaximum entry size (and therefore are not cached)

MT errors The number of times more than one thread tries to create the sameentry in the cache (MT=Multi-Threading)

Example:pdadmin> server task webseald-<instance> stats get pdweb.doccacheGeneral Errors : 0Uncachable : 0Pending Deletes: 0Pending Size : 0Misses : 0Cache MIME type : text/html

Max size : 2048000Max entry size : 128000Size : 0Count : 0Hits : 0Stale hits : 0Create waits : 0Cache no room : 0Additions : 0Aborts : 0Deletes : 0Updates : 0Too big errors : 0MT errors : 0


pdweb.jct.# componentThe pdweb.jct.# statistics component gathers information related to WebSEALjunctions. The following table describes the types of information available:

Type Description

[/] The actual junction name (listed as a number in the command)

reqs The total number of requests routed across this junction

max The maximum time consumed in a single request across this junction

total The total time consumed by requests across this junction

Example:pdadmin> server task webseald-<instance> stats get pdweb.jct.1[/]reqs : 0max : 0.000total : 0.000

Enabling statistics statically using event loggingStatistics can be statically configured in the [aznapi-configuration] stanza of thewebseald.conf configuration file by using the stats parameter to enable thestatistics interface and using the logcfg event logging parameter to direct thestatistics information to a destination:[aznapi-configuration]stats = <component> [interval [count]]logcfg = stats.<component>:<destination>

Refer to “Enable statistics dynamically” on page 70 for information on the intervaland count arguments.

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

Example 1:

In this example, the stats parameter enables the component and any interval andcount arguments. The logcfg parameter specifies the destination for thisinformation. Refer to the “Using event logging” chapter of the IBM Tivoli AccessManager Base Administrator’s Guide for complete configuration details.[aznapi-configuration]stats = pdweb.jmt 20logcfg = stats.pdweb.jmt:file path=/tmp/jmt.log,rollover_size=-1,flush=20

Example 2:

In this example, multiple stats parameters enable multiple components. Multiplelogcfg parameters specify multiple destinations. Note that, unlike the dynamicstats on command, you can specify several destination files for the samecomponent. Refer to the “Using event logging” chapter of the IBM Tivoli AccessManager Base Administrator’s Guide for complete event logging configuration details.[aznapi-configuration]stats = pdweb.jmt 20stats = pdweb.authn 40stats = pdweb.jct.1 50logcfg = stats.pdweb.jmt:file path=/tmp/jmtA.log,rollover_size=-1,flush=20


logcfg = stats.pdweb.jmt:file path=/tmp/jmtB.log,rollover_size=-1,flush=20logcfg = stats.pdweb.authn:file path=/tmp/an.log,rollover_size=-1,flush=20logcfg = stats.pdweb.jct.1:file path=/tmp/jct.log,rollover_size=-1,flush=20

Using the trace utility to capture WebSEAL actionsThe trace utility allows you to capture information about error conditions andprogram control flow in Access Manager Base and Access Manager WebSEAL. Thisinformation is stored in a file and used for debugging purposes. The trace utility isprovided primarily to assist support personnel in diagnosing problems occurringwith the functioning of the Access Manager software.

As a user, you may find some of the WebSEAL tracing components useful.However, the majority are of little benefit unless you are diagnosing complexproblems with the assistance of technical support personnel.

Note: Use trace with caution. It is intended as a tool to use under the direction oftechnical support personnel. Messages from trace are sometimes cryptic, arenot translated, and can severely degrade system performance.

Basic trace command syntaxpdadmin> server task webseald-<instance> trace <command>

You can perform the following tasks with the pdadmin trace command:

trace set Enable the trace level and trace message destination for a component andits subordinates

trace show Show the name and level for all enabled trace components or for thespecified component

trace list List all available trace components

Enable traceUse the pdadmin trace set command to enable the gathering of trace informationfor the specified component and level.trace set <component> <level> [<log-agent>]


component The trace component name. Required. WebSEAL-specific componentsare prefixed with “pdweb”.

level Reporting level. Required. The level argument specifies the amount ofdetail gathered by the trace utility. The range is 1 to 9. Level 1 specifiesthe most detailed output and level 9 specifies the least detailed output.

logagent Optionally specifies a destination for the trace information gathered forthe specified component. Refer to the “Using event logging” chapter ofthe IBM Tivoli Access Manager Base Administrator’s Guide for completeconfiguration details.

Show enabled trace componentsList all enabled trace components or a specific enabled component. If a specifiedcomponent is not enabled, no output is displayed.trace show [<component>]

Example:


pdadmin> server task webseald-<instance> trace set pdweb.debug 2pdadmin> server task webseald-<instance> trace showpdweb.debug 2

List all available trace componentsList the specified component or all components available to gather and report traceinformation.trace list [<component>]

WebSEAL trace components

pdweb.debugNote: The pdweb.debug component only operates at level 2.

The following command invokes the trace utility for the pdweb.debug componentat level 2, and directs the output to a file, using the event logging mechanism tospecify a file log agent.pdadmin> server task webseald-<instance> trace set pdweb.debug 2 \file path=/opt/pdweb/log/debug.log

The sample output of this command as it appears in the debug.log file:/src/wand/wand/log.c:277: -------------- Browser ===> PD --------------Thread_ID:17GET /test/index.html HTTP/1.1Host: bevanUser-Agent: Mozilla/5.0 (Windows; U; Windows NT 5.0; en-US; rv:0.9.4)Gecko/20011128 Netscape6/6.2.1Accept: text/xml, application/xml, application/xhtml+xml, text/html;q=0.9,image/png, image/jpeg, image/gif;q=0.2, text/plain;q=0.8, text/css,*/*;q=0.1Accept-Language: en-usAccept-Encoding: gzip, deflate, compress;q=0.9Accept-Charset: ISO-8859-1, utf-8;q=0.66, *;q=0.66Keep-Alive: 300Connection: keep-alive---------------------------------------------------

/src/wand/wand/log.c:277: -------------- PD ===> BackEnd --------------Thread_ID:17GET /index.html HTTP/1.1via: HTTP/1.1 bevan:443host: mokum.santacruz.na.tivoli.comuser-agent: Mozilla/5.0 (Windows; U; Windows NT 5.0; en-US; rv:0.9.4)Gecko/20011128 Netscape6/6.2.1accept: text/xml, application/xml, application/xhtml+xml, text/html;q=0.9,image/png, image/jpeg, image/gif;q=0.2, text/plain;q=0.8, text/css,*/*;q=0.1accept-language: en-usaccept-charset: ISO-8859-1, utf-8;q=0.66, *;q=0.66accept-encoding: gzip, deflate, compress;q=0.9keep-alive: 300connection: close---------------------------------------------------

/src/wand/wand/log.c:277: -------------- PD <=== BackEnd --------------Thread_ID:17content-type: text/htmldate: Mon, 25 Mar 2002 19:48:32 GMTcontent-length: 7017etag: "0-1b69-3b688e48"last-modified: Thu, 02 Aug 2001 00:18:32 GMT


server: IBM_HTTP_SERVER/1.3.19 Apache/1.3.20 (Win32)connection: closeaccept-ranges: bytes---------------------------------------------------

/src/wand/wand/log.c:277: -------------- Browser <=== PD --------------Thread_ID:17HTTP/1.1 200 Document followscontent-type: text/htmldate: Mon, 25 Mar 2002 19:48:32 GMTcontent-length: 7017etag: "0-1b69-3b688e48"last-modified: Thu, 02 Aug 2001 00:18:32 GMTserver: IBM_HTTP_SERVER/1.3.19 Apache/1.3.20 (Win32)connection: closeaccept-ranges: bytes---------------------------------------------------


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 82v “Password strength policy” on page 84v “Authentication strength POP policy (step-up)” on page 86v “Network-based authentication POP policy” on page 92v “Quality of protection POP policy” on page 94v “Handling unauthenticated users (HTTP / HTTPS)” on page 94

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 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 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 useris locked out for “x” seconds (or the account is disabled).

The three strikes login policy is used to prevent computer password attacks. Thepolicy creates a condition where a user must wait a period of time before making


more login attempts that fail. For example, a policy could dictate 3 failed attemptsfollowed by a 180 second penalty. This type of login policy can prevent randomcomputer-generated login attempts occurring many times 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 over-head. You may observe delays in replicating accountvalid information to the WebSEAL server. This situation depends on yourLDAP environment. In addition, certain LDAP implementations mightexperience performance degradation as a result of the account valid updateoperation. For these reasons it is recommended that you use a time outinterval.

Command syntaxThe following pdadmin commands are appropriate only for use 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 default setting is 10 attempts.

policy set disable-time-interval {<number>|unset|disable} [-user <username>]

policy get disable-time-interval [-user <username>]

Chapter 4. WebSEAL security policy 83

Command Description

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 default setting is 180 seconds.

Password strength policyPassword strength policy, available for LDAP-based Access Manager installations,refers to the stipulations placed on the construction of a password by passwordpolicy rules. Access Manager provides two means of controlling password strengthpolicy:v Five pdadmin password policy commandsv A plugable authentication module (PAM) that allows you to customize a

password policyRefer 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 only appropriate for use 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>]


Command Description

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

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 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 re-authenticate using the requiredmethod (level).

Step-up authentication means that a user is not immediately shown a “denied”message when they try to access a resource that requires a “higher” authenticationlevel that 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 90.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 97 for detailedinformation about setting up the required authentication mechanisms.

Enabling step-up authenticationStep-up authentication is implemented via 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 used to create a default entry whichcould 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 92.

Step-up login formWebSEAL presents a special form when the step-up POP policy on the requestedresource forces the client to re-authenticate. 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 templatefile 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.

Figure 18. Customized login form for user name and password step-up


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 only be specified 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.

Figure 19. Customized login form for SecurID token passcode step-up


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 authenticationAccess Manager step-up authentication and multi-factor authentication are twodifferent and distinct mechanisms for controlling access to resources. AccessManager only provides step-up authentication functionality, as described in thischapter.

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.

Access Manager step-up authentication relies on a pre-configured hierarchy ofauthentication levels and enforces a specific level of authentication according to thepolicy 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 87.

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 only want to allowor deny access based 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 used to create a default entry whichcould either deny all unmatched IP addresses or allow anyone access who meetthe 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 87 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.

Currently, this attribute is only appropriate in a WebSEAL environment.

The quality of protection POP attribute is the replacement for the “P” and “I” ACLpermission bits that activated privacy and integrity requirements in previousversions of Access Manager. This older implementation of quality of protection wasinefficient and impacted system performance.

The quality of protection POP attribute permits a single transaction where the“yes” response to the ACL decision also includes the required quality of protectionlevel. If the resource manager (such as WebSEAL) cannot guarantee the requiredlevel of protection, the request is denied.pdadmin> pop modify <pop-name> set qop {none|integrity|privacy}

QOP level Description

Privacy Data encryption is required (SSL).

Integrity Use some mechanism to ensure that the data has not changed.

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 over 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 only

requires 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. Since unauthenticated dependson any-authenticated, it makes little sense for an ACL to containunauthenticated without any-authenticated. If an ACL does containunauthenticated without any-authenticated, the default response is togrant 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 94.


Chapter 5. WebSEAL authentication

This chapter discusses how WebSEAL maintains session state and handles theauthentication process. Successful authentication results in an 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 97v “Managing session state” on page 99v “Authentication configuration overview” on page 107v “Configuring Basic Authentication” on page 111v “Configuring forms authentication” on page 112v “Configuring client-side certificate authentication” on page 113v “Configuring HTTP header authentication” on page 116v “Configuring IP address authentication” on page 118v “Configuring token authentication” on page 118v “Supporting multiplexing proxy agents” on page 119v “Configuring reauthentication based on security policy” on page 122v “Configuring reauthentication based on session inactivity policy” on page 125

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 an 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:1. SSL ID (defined by the SSL protocol)2. Server-specific session cookie3. BA header data4. HTTP header data5. 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 Method Supported ConnectionType

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 99v “GSKit and WebSEAL session cache overview” on page 99v “Configuring the GSKit SSL session ID cache” on page 100v “Configuring the WebSEAL session/credentials cache” on page 101v “Maintaining state with session cookies” on page 101v “Determining valid session ID data types” on page 103v “Configuring failover cookies” on page 104

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:1. SSL ID2. Server-specific session cookie3. BA header data4. HTTP header data5. 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 99

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.

There are several configuration parameters available for each cache that allow youto tune the performance of the cache. These parameters are summarized in thefollowing figure:

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.

WebSEAL

Client

GSK CacheConfiguration Parameters- ssl-v2-timeout- ssl-v3-timeout- ssl-cache-max-sessions

Maintains:- SSL session ID

Maintains:

- WebSEAL session ID

- Credential information

- timeout- inactive-timeout- max-entries

GSK SSL SessionCache

WebSEALSession/Credentials Cache

WebSEAL CacheConfiguration Parameters

Figure 20. Session cache configuration parameters


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

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

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 information


for 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 only provides re-authentication of a client 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 which generated the cookie.

In addition, the session cookie contains only a random number identifier that isused to index into the server’s session cache. There is no other informationexposed in the session cookie. The session cookie cannot compromise securitypolicy.

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 = no

A “no” configuration setting for this parameter results in the following conditionsfor clients accessing over HTTPS:1. The SSL session ID is never used as session ID data.2. 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.

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

4. The HTTP header is used as session ID data for clients authenticating withHTTP headers

5. The IP address is used as session ID data for clients authenticating with IPaddresses.

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 some


environments, 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:1. Session cookies are used to identify the following client types for subsequent

logins over another transport:a. Failover cookiesb. Client-side certificatesc. CDSSO ID tokend. Token passcodee. Forms username and passwordf. Basic Authentication

2. The HTTP header is used for clients accessing with HTTP headers.3. The IP address is used for clients accessing with IP addresses.4. 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.

5. 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 clientswitches 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 = yes ssl-id-sessions = nouse-same-session = no

use-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 only accepted 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.

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

Client


WS1

WS2

WS3

Replicated Front-endWebSEAL Servers

Back-endResources

Figure 21. Failover cookie scenario


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. Since 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 whichsupplies 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 include 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:

UNIX:# cdsso_key_gen <pathname>

Windows:MSDOS> cdsso_key_gen <pathname>

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

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 authenticators


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

CDSSO ID Token Authentication

cdsso Cross Domain Single Sign-on authentication.

You use the [authentication-mechanisms] stanza to configure the authenticationmethod and the implementation in the following format:<authentication-method-parameter> = <shared-library>

External custom CDAS authentication parametersThe following parameters are available to specify custom shared libraries forexternal CDAS servers:


passwd-cdas Client access with username and password for a third-partyregistry.

token-cdas Client access with username and token passcode.

cert-cdas Client access with client-side certificate over SSL.

http-request Client access via special HTTP header and / or IP address.

cred-ext-attrs Used by CDAS to supply extended attribute data to usercredential.

Refer to the IBM Tivoli Access Manager WebSEAL Developer’s Reference fordetails on building and configuring a custom shared library that implements aCDAS 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 configuremultiple authentication methods:1. All authentication methods can function independently from each other. It is

possible to configure a shared library for each supported method.2. The cert-cdas method overrides the cert-ssl method when both are configured.

You must enabled one of these to support client-side certificates.3. 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:a. passwd-cdas

b. passwd-ldap

4. It is possible to configure the same custom library for two differentauthentication methods. For example, you could write a custom shared libraryto process 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 thedeveloper to maintain session state and avoid conflicts between the twomethods.

Prompting for loginWebSEAL prompts a client for a login under the following conditions:1. An unauthenticated client that fails an authorization check2. A forms or Basic Authentication client that fails an authorization check

The following client types are presented a “403 failure” error:1. When an authorization check fails:

a. Client-side certificateb. Failover cookiec. CDSSOd. IP addresse. HTTP header

2. When a client authenticates with a method that is disabled by WebSEAL


Logout and change password commandsAccess Manager provides the following commands for supporting clients whoauthenticate 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 or IP address authentication. In this case, you must close thebrowser to log out.

The pkmslogout command is appropriate for authentication via client-sidecertificate, token passcode, forms authentication, and certain implementations ofHTTP 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.


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

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.

Figure 22. BA login prompt


v On Windows, the file that provides the built-in mapping function is a DLLcalled 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 authenticationAccess Manager provides forms authentication as an alternative to the standardBasic Authentication mechanism. This method produces a custom HTML loginform from Access Manager instead of the standard login prompt resulting from aBasic 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 example:

For detailed information on the available HTML forms you can customize, see“Managing custom account management pages” on page 33.

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 an Access Manager identity.

Figure 23. Sample WebSEAL login form


Background: Mutual authentication via certificatesThe exchange of server-side and client-side certificates over SSL results in a trustrelationship between 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 via 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. Access Manager authenticates the client by using the built-in shared library to

exactly match the Distinguished name (DN) in the Subject field of theclient-side certificate with an existing DN entry in the LDAP registry, or byusing a custom CDAS to perform an alternative identity matching.

Request

Client

Response

WebSEAL Server

"I can trust who you are."

verisign

www.tivoli.com

Server'sDigital ID

belsigncertisignentrustverisign

...

Browser's CARoot Certificates

Figure 24. Client validates the WebSEAL certificate


The result of successful authentication is an Access Manager identity that isthen used to build a credential for that user. It is the credential that is requiredfor the client to participate in the Access Manager secure domain.

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 also use iKeyman to install and label the new site certificate. Usethe webseal-cert-keyfile-label parameter in the [ssl] stanza of the webseald.confconfiguration file to designate the certificate as the active WebSEAL server-sidecertificate (this setting overrides any certificate designated as “default” in thekeyfile 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” on page 36.

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 lists 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 DLLcalled 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 Access Manageruser by exactly matching the Distinguished name (DN) in the Subject field of theclient-side certificate with an existing DN entry in the LDAP registry

Configuration conditionsIf client-side certificate handling is set to “required”, all other authenticationsettings are ignored for HTTPS clients.

Configuring HTTP header authenticationAccess Manager supports authentication via custom HTTP header informationsupplied by the client or a proxy agent.

This mechanism requires a mapping function (a shared library) that maps thetrusted (pre-authenticated) header data to an Access Manager identity. WebSEALcan 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 an Access Manager identity. Refer to the IBM TivoliAccess Manager WebSEAL Developer’s Reference for API resources.

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 Access Manager identity. You must customize this file toauthenticate other types of special header data and, optionally, map this data to anAccess 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 conditions1. Session ID cookies are not used to maintain state if ssl-id-sessions = no. The

unique header value is used to maintain state.


2. If the client encounters an authorization failure, the client receives a“Forbidden” page (HTTP 403).

3. Cookie headers cannot be passed to the HTTP header authenticationmechanism.

Configuring IP address authenticationAccess Manager supports authentication via an IP address supplied by the client.

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 via an IP address requires a custom shared library. Use http-requestparameter for this shared library.

Configuring token authenticationAccess Manager supports authentication via a token passcode supplied by theclient.

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 tokenpasscode data. You can customize this file to authenticate other types of specialtoken data and, optionally, map this data to an Access Manager identity. Refer tothe IBM Tivoli Access Manager WebSEAL Developer’s Reference for API resources.

You can 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

Supporting multiplexing proxy agentsAccess Manager provides solutions for securing networks that use a MultiplexingProxy 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 via 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.


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

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 25. 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 111. 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 an 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 Administration Guide for information onmanaging groups.

MPA authentication limitationsThis release of Access Manager only supports one MPA per WebSEAL server.

Configuring reauthentication based on security policyAccess 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 WebSEAL session cache inactivity timeout value.

This section discusses reauthentication based on security policy as dictated by aPOP extended attribute.

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. AccessManager preserves the user’s original session information, including the credential,during reauthentication. 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 63.

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 WebSEAL session cache lifetime timer. Inaddition, a grace period can be configured to allow sufficient time for thereauthentication process to complete before the session cache lifetime timeoutexpires.

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 lifetime reset and extension

Resetting the session cache lifetime valueThe user’s session cache has a limited lifetime, as specified by the timeoutparameter in the [session] stanza of the webseald.conf configuration file. hedefault value, in minutes, is 3600 (1 hour):[session]timeout = 3600

Regardless of session activity or inactivity, the session cache is removed when thelifetime value is reached, at which point the user is logged off.


However, you can configure the session cache lifetime to be reset wheneverreauthentication occurs. With this configuration, the user session no longer has asingle maximum lifetime value. Each time reauthentication occurs, the sessioncache lifetime value is reset.

You can configure session cache 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 thesession cache inactivity timeout value. See “Configuring reauthentication based onsession inactivity policy” on page 125.

Extending the session cache lifetime valueIt is possible for the session cache lifetime value to expire while the user isperforming a reauthentication. This situation occurs under the followingconditions:v The user requests a resource protected by a reauthentication POPv The user’s session cache lifetime value is very near expiration

The session cache lifetime can expire after the reauthentication login form is sent tothe user and before the completed login form is returned. When the session cachelifetime value expires, the session cache entry is deleted. When the login form isreturned to WebSEAL, there is no longer a session for that user. In addition, allcached user request data is lost.

You can configure a time extension, or “grace period”, for the session cachelifetime should the session cache lifetime expire during reauthentication. Thereauth-extend-lifetime parameter in the [reauthentication] stanza of thewebseald.conf configuration file provides this time extension, in seconds. Forexample:[reauthentication]reauth-extend-lifetime = 20

The default value, “0”, provides no extension to the session cache timeout value.

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 inactivity timeout value. See “Configuring reauthentication based onsession inactivity policy” on page 125.


Configuring reauthentication based on session inactivity policyAccess 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 WebSEAL session cache inactivity timeout value.

This section discusses reauthentication based on the expiration of the WebSEALsession cache inactivity timeout value.

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 session cacheinactivity timeout value.

Reauthentication is supported by the following supported WebSEAL authenticationmethods: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 63.

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 is “flagged” whenever the session inactivitytimeout value expires. The session cache (containing the user credential) is notremoved. The user can proceed to access unprotected resources. However, if theuser requests a protected resource, WebSEAL sends a login prompt.

Upon successful reauthentication, the inactive session “flag” is removed and theinactivity timer is reset. However, the session cache lifetime value ultimatelydetermines the maximum session length. When this lifetime value expires, thesession is terminated regardless of activity.

If reauthentication fails, WebSEAL returns the login prompt again. The sessioncache remains “flagged” and the user can proceed as unauthenticated until thesession cache 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.


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

Configuration is available to reset the WebSEAL session cache lifetime timer. Inaddition, a grace period can be configured to allow sufficient time for thereauthentication process to complete before the session cache lifetime timeoutexpires.

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” inthe [reauthentication] stanza of the webseald.conf configuration file:[reauthentication]reauth-for-inactive = yes

The default value for this parameter is “no”.

Configuring session cache lifetime reset and extension

Resetting the session cache lifetime valueThe user’s session cache has a limited lifetime, as specified by the timeoutparameter in the [session] stanza of the webseald.conf configuration file. hedefault value, in minutes, is 3600 (1 hour):[session]timeout = 3600

Regardless of session activity or inactivity, the session cache is removed when thelifetime value is reached, at which point the user is logged off.

However, you can configure the session cache lifetime to be reset wheneverreauthentication occurs. With this configuration, the user session no longer has asingle maximum lifetime value. Each time reauthentication occurs, the sessioncache lifetime value is reset.

You can configure session cache 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 security (POP) policy.See “Configuring reauthentication based on security policy” on page 122.

Extending the session cache lifetime valueIt is possible for the session cache lifetime value to expire while the user isperforming a reauthentication. This situation occurs under the followingconditions:v The user requests a resource protected by a reauthentication POPv The user’s session cache lifetime value is very near expiration

The session cache lifetime can expire after the reauthentication login form is sent tothe user and before the completed login form is returned. When the session cache


lifetime value expires, the session cache entry is deleted. When the login form isreturned to WebSEAL, there is no longer a session for that user. In addition, allcached user request data is lost.

You can configure a time extension, or “grace period”, for the session cachelifetime should the session cache lifetime expire during reauthentication. Thereauth-extend-lifetime parameter in the [reauthentication] stanza of thewebseald.conf configuration file provides this time extension, in seconds. Forexample:[reauthentication]reauth-extend-lifetime = 20

The default value, “0”, provides no extension to the session cache timeout value.

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 security (POP) policy.See “Configuring reauthentication based on security policy” on page 122.



Chapter 6. Cross-domain 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. This chapter discusses two cross-domain single sign-on solutions.

Topic Index:v “Configuring CDSSO authentication” on page 129v “Configuring e-community single sign-on” on page 133

Configuring CDSSO authenticationThe Access Manager Cross-Domain Single Sign-on (CDSSO) provides a mechanismfor transferring user credentials across multiple secure domains. CDSSO allowsWeb users to perform a single sign-on and move seamlessly between two separatesecure domains. The CDSSO authentication mechanism does not rely on a MasterAuthentication Server (see e-Community SSO).

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 second domain now has the user’s identity (as authenticatedin the first domain) and the user is not forced to perform another login.

Integrating a custom CDMF shared libraryIn many CDSSO scenarios, the default one-to-one mapping between users indifferent domains may 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.

Authentication process flow for CDSSO with CDMFThe following process flow description is illustrated in Figure 26.1. Any user who wants to participate in multiple domains must have a valid user

account in the primary 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 expression:


/pkmscdsso?<destination-URL>

For example:/pkmscdsso?https://www.domainB.com/index.html

3. The request is first processed by the WebSEAL server in domain A. WebSEALbuilds an authentication token that contains the user’s Access Manager identity(short name), the current domain (“A”), additional user information, and a timestamp.The additional user information is obtained by a call out to the customizedCDMF shared library (cdmf_get_usr_attributes). This library has the ability tosupply user attributes that can be used by domain B during the user mappingprocess.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.

4. The domain A WebSEAL server re-directs the request plus the encrypted tokenback to the browser and then to the domain B WebSEAL server (HTTPredirection).

5. The domain B WebSEAL server uses its version of the same key file to decryptand validate the token as coming from the referring domain.

6. The domain B WebSEAL server now calls out to a CDSSO authenticationmechanism library. This CDSSO library in turn calls out to the customizedCDMF library which performs the actual user mapping (cdmf_map_usr).The CDMF library passes the user’s identity, and optionally additional userattribute information, back to the CDSSO library. The CDSSO library uses thisinformation to build a credential.

7. The domain B authorization service permits or denies access to protectedobjects based on the user’s credential and the specific ACL permissionsassociated with the requested objects.


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.v To enable the CDSSO authentication method, enter “http”, “https”, or “both”.v To disable the CDSSO authentication method, enter “none”.

For example:[cdsso]cdsso-auth = https

Configuring the CDSSO authentication mechanismThe cdsso configuration parameter specifies the hard-coded shared library formapping authentication information.v On UNIX, the file that provides the built-in mapping function is a shared library

called libcdssoauthn.v On Windows, the file that provides the built-in mapping function is a DLL

called cdssoauthn.


Shared Library


cdsso libcdssoauthn.so libcdssoauthn.a cdssoauthn.dll libcdssoauthn.sl

You can configure the CDSSO authentication mechanism by entering the cdssoparameter with the platform-specific name of the shared library file in the[authentication-mechanism] stanza of the webseald.conf configuration file.

For example:

Solaris:

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 26. Cross-domain single sign-on process with CDMF

Chapter 6. Cross-domain sign-on solutions 131

[authentication-mechanisms]cdsso = libcdssoauthn.so

Windows:[authentication-mechanisms]cdsso = cdssoauthn.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 WebSEAL server in each participating domain. Eachparticipating WebSEAL server in each domain needs to use the same key.

Note: The creation and distribution of key files is not a part of the Access ManagerCDSSO process.

The cdsso_key_gen utility requires that you specify the location (absolutepathname) of the key file when you run the utility:

UNIX: # cdsso_key_gen <absolute-pathname>

Windows: MSDOS> cdsso_key_gen <absolute-pathname>

Enter this key file location in the [cdsso-peers] stanza of the webseald.confconfiguration file of the participating WebSEAL server in each domain. The formatincludes the WebSEAL machine name and the key file location:[cdsso-peers]<webseal-machine-name> = <keyfile-location>

Domain A Configuration Example:[cdsso-peers]www.domainB.com = <pathname>/A-B.key

Domain B Configuration Example:[cdsso-peers]www.domainA.com = <pathname>/A-B.key

In the above example, the A-B.key file would be generated on one machine(WebSEAL A, for example) and manually (and securely) copied to the othermachine (WebSEAL B, for example).

Configuring the token time stampThe token contains a configurable time stamp that defines the lifetime of theidentity token. Once 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 between the participating domains.


Expressing CDSSO HTML linksHTML links to resources on a secondary secure domain must contain a specialCDSSO expression:/pkmscdsso?<destination-URL>

For example:/pkmscdsso?https://www.domainB.com/index.html

Protecting the authentication tokenWhile the authentication token does not contain authentication information (suchas username 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, a malicious user 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.

Configuring e-community single sign-onE-community single sign-on is another implementation of cross-domainauthentication in an 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 (Access Manager or DNS) thatparticipate 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 Access Manager Web portal manager to delegate themanagement 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.

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

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 “Configuring CDSSO authentication” on page 129).

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 27. The e-community model


v The e-community implementation requires a consistent configuration across allWebSEAL servers in all domains participating in the e-community.

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, this mapping functionis not required.

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 tohandle 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 theuser’s first request, the “vouch for” server is always the MAS. The MAS continuesto serve as the “vouch for” server for resources located in the home domain. Asthe user continues with resource requests across the e-community, an individualserver in each remote domain can build its own credential for the user (based onuser identity information from the MAS) and assume the role of “vouch for” serverfor resources in its domain.

The verification requested of the “vouch for” server takes the form of a “vouchfor” token. The “vouch for” server creates the token and returns it to therequesting WebSEAL server. The user identity information in the token isencrypted. The token 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

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 first

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 28. e-community process flow


server 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 Access: WebSEAL 1 (Domain A)

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

v WebSEAL 1 configuration has e-community authentication enabled and specifiesthe location of the MAS. WebSEAL 1 re-directs the browser to a special “vouchfor” URL on the MAS.

v The MAS receives the “vouch for” request and, failing to find credentials forthat user, prompts the user to login.

v Upon successful login, the MAS builds a credential for the user, stores it in thecache, and re-directs 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 from asuccess status “vouch for” token. The requesting server reacts to a failure statustoken as if the user had failed local authentication.

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

v The authorization service permits or denies the request.

(2) FIRST e-Community Access: WebSEAL 3 (Domain B)

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

v WebSEAL 3 configuration has e-community authentication enabled and specifiesthe location of the MAS. WebSEAL 3 re-directs the browser to a special “vouchfor” URL on the MAS.

v The MAS receives the “vouch for” request and, failing to find credentials forthat user, prompts the user to login.

v Upon successful login, the MAS builds a credential for the user, stores it in thecache, and re-directs 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 from asuccess status “vouch for” token. The requesting server reacts to a failure statustoken as if the user had failed local authentication.

v WebSEAL 3 decrypts the token and builds its own credential for the user.


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


(3) NEXT e-Community Access: WebSEAL 2 (Domain A)

v 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 2 hasno cached credentials for the user.

v WebSEAL 2 configuration has e-community authentication enabled and specifiesthe location of the MAS. The presence of the domain A e-community cookieoverrides the WebSEAL 2 configuration for the MAS location. The cookieprovides WebSEAL 2 with the identity of the “vouch for” server. (If scenario 2occurred first, there would also be a domain B cookie maintained on the browserthat would not be sent to a domain A server.)

v WebSEAL 2 re-directs 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).

v The MAS receives the “vouch for” request and finds credentials for that user inthe cache (this occurred in scenario 1 and 2).

v The MAS re-directs the browser back to the originally requested URL onWebSEAL 2 with an encrypted “vouch for” token.

v WebSEAL 2 decrypts the token and builds its own credential for the user.v The authorization service permits or denies the request.

(4) NEXT e-Community Access: WebSEAL 4 (Domain B)

v User requests a resource protected by WebSEAL 4 (remote domain B). If scenario2 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.

v WebSEAL 4 configuration has e-community authentication enabled and specifiesthe location of the MAS. The presence of a domain B e-community cookieoverrides the WebSEAL 4 configuration for the MAS location. The cookieprovides WebSEAL 4 with the identity of the “vouch for” server. (If scenario 1occurred first, there would only be a domain A cookie maintained on thebrowser that would not be sent to a domain B server. The configured MASlocation would be used instead. WebSEAL 4 would then become the “vouch for”server for domain B.)

v If scenario 2 occurred first, WebSEAL 4 re-directs 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).

v WebSEAL 3 receives the “vouch for” request and finds credentials for that userin the cache (this occurred in scenario 2).

v WebSEAL 3 re-directs the browser back to the originally requested URL onWebSEAL 4 with an encrypted “vouch for” token.

v WebSEAL 4 decrypts the token and builds its own credential for the user.v The authorization service permits or denies the request.

(5) ANOTHER e-Community Access: WebSEAL 2 (Domain A)

v User connects to WebSEAL 2 (domain A) with a request. If scenario 3 occurred,WebSEAL 2 has cached credentials for the user.



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. These URLs are constructed during the e-community “vouch for” HTTPre-directs based on the configuration information in webseald.conf.

The “vouch for” Request

The “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 an HTTP re-direct to the “vouch for” server (either theMAS or a 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 tore-direct 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” Reply


The “vouch for” reply is the response from the “vouch for” server to the targetserver.

The “vouch for” reply contains the following information:https://<target-URL>?PD-VFHOST=<vouch-for-server>&PD-VF=<encrypted-token>

The PD-VFHOST parameter 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 (PD-VF). The PD-VF parameterrepresents the encrypted “vouch for” token.

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 are-direct 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) at 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 only passed 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.

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 creation and distribution of key files is not a part of the 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:

UNIX:# cdsso_key_gen <absolute-pathname>

Windows:MSDOS> cdsso_key_gen <absolute-pathname>


The location of the key used to secure tokens sent between servers within the samedomain (home and remote) is entered as the value of the intra-domain-keyparameter in the [e-community-sso] stanza of the webseald.conf configuration file.[e-community-sso]intra-domain-key = <absolute-pathname>

The location of the key files used to secure tokens sent between the MAS andservers in remote domains is entered in the [inter-domain-keys] stanza. Otherservers in the same domain as the MAS do not require inter-domain-keys. TheMAS is the only server that needs to communicate with servers in remote domains.[inter-domain-keys]<domain-name> = <absolute-pathname><domain-name> = <absolute-pathname

Configuring an e-communityThis section reviews all the configuration parameters required for an e-communityimplementation. These parameters are located in the webseald.conf file. You mustcarefully configure this file for each participating server in the e-community.

e-community-sso-auth

This parameter enables or disables e-community authentication. Values include“http”, “https”, “both”, or “none”. For example:[e-community-sso]e-community-sso-auth = both

The values “http”, “https”, and “both” specify the type of communication used bye-community participants. The value “none” disables e-community for that server.The default setting is “none”.

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

e-community-name

This parameter identifies the unifying name of the e-community for allparticipating 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.

intra-domain-key

This parameter identifies the location of the key file used to encrypt and decrypttokens that are exchange within this server’s domain. For example:[e-community-sso]intra-domain-key = /abc/xyz/key.file

You must generate this key file in one location and then manually (and securely)copy the file to the specified location in all other WebSEAL servers within thedomain.

is-master-authn-server

This parameter identifies whether this server is the MAS or 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.

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

vf-token-lifetime

This parameter sets the lifetime timeout value (in seconds) of the “vouch for”token. This value is checked against the creation time stamped on the cookie. Thedefault value is 180 seconds. You must take into account clock skew betweenparticipating servers. For example:[e-community-sso]vf-token-lifetime = 180

vf-url

This 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 = /ecommA/pkmsvouchfor

ec-cookie-lifetime

This parameter specifies the maximum lifetime (in minutes) of the e-communitydomain cookie. The default value is 300 minutes. For example:


[e-community-sso]ec-cookie-lifetime = 300

Inter Domain Keys

The location of the key files required for encrypting and decrypting tokensbetween the MAS and participating servers in remote domains is specified in the[inter-domain-keys] stanza. You must specify fully qualified domain names for theservers 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:[inter-domain-keys]dB.com = /abc/xyz/key.fileBdC.com = /abc/xyz/key.fileC

In this example, key.fileB identifies the key file used between domain A anddomain B. key.fileC identifies the key file used between domain A and domain C.

Each remote server would need to have a copy of the appropriate key file used bythe MAS. To exchange tokens with the MAS (domain A), all servers in domain Brequire copies of key.fileB.[inter-domain-keys]dA.com = /efg/hij/key.fileB

To exchange tokens with the MAS (domain A), all servers in domain C requirecopies of key.fileC.[inter-domain-keys]dA.com = /efg/hij/key.fileC

Configuring the CDSSO authentication mechanismThe e-community configuration requires that you enable the cdsso authenticationmechanism. This mechanism is required when the requesting server builds usercredentials from the identity information contained in the “vouch for” token. Thecdsso configuration parameter specifies the hard-coded shared library for mappingauthentication information.v On UNIX, the file that provides the built-in mapping function is a shared library

called libcdssoauthn.v On Windows, the file that provides the built-in mapping function is a DLL

called cdssoauthn.


Shared Library


cdsso libcdssoauthn.so libcdssoauthn.a cdssoauthn.dll libcdssoauthn.sl

You can configure the CDSSO authentication mechanism by entering the cdssoparameter with the platform-specific name of the shared library file in the[authentication-mechanism] stanza of the webseald.conf configuration file.

For example:

Solaris:[authentication-mechanisms]cdsso = libcdssoauthn.so


Windows:[authentication-mechanisms]cdsso = cdssoauthn.dll


Chapter 7. WebSEAL junctions

The connection between a WebSEAL server and a back-end Web application serveris known as a WebSEAL junction, or junction. A WebSEAL junction is a TCP/IPconnection between a front-end WebSEAL server and a back-end Web applicationserver. Junctions allow WebSEAL to protect Web resources located on back-endservers.

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 145v “Using pdadmin to create junctions” on page 147v “Configuring a basic WebSEAL junction” on page 148v “Mutually authenticated SSL junctions” on page 150v “Creating TCP and SSL proxy junctions” on page 153v “WebSEAL-to-WebSEAL junctions over SSL” on page 153v “Modifying URLs to back-end resources” on page 154v “Additional junction options” on page 160v “Technical notes for using WebSEAL junctions” on page 168v “Using query_contents with third-party servers” on page 169

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 store 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 backupjunction 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 supportedAccess 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 Access Manager authorization model cannot guarantee secure accesscontrol 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 225 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 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:

Chapter 7. WebSEAL junctions 147

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>

The default port value for a TCP junction (if not specified) is 80.

JunctionWebSEAL

Client

Secure Domain

WebApplication

Server

HTTP

/

/mnt

TCP

Figure 29. Non-secure TCP (HTTP) junction


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

Access Manager uses the IBM Global Security Kit (GSKit) implementation of SSL.You must use the GSKit iKeyman utility to add the root certificate of the CA whosigned 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:pdadmin> server task webseald-<instance-name> create –t ssl –p 4443 \–h travel_svr /travel

JunctionWebSEAL

Client

Secure Domain

WebApplication

Server

HTTPS

/

/mntSSLTCP

Figure 30. Secure SSL (HTTPS) junction


Adding additional back-end servers to a junctionTo increase high availability of the resources protected by Access Manager, you canjunction 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 server certificate from the back-end server See“WebSEAL validates back-end server certificate”.

v WebSEAL verifies the Distinguished Name (DN) contained in the certificate(–D) (optional, but highly recommended) See “Distinguished name (DN)matching” on page 151.

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 151.v Back-end server validates WebSEAL identity information in Basic

Authentication (BA) header (–B, –U, –W) See “WebSEAL authenticates withBA header” on page 151.

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 method 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 152

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 only appropriate when used with the –K or –B option.

WebSEAL authenticates with client certificateUse the –K option to enable WebSEAL authentication to the junctioned back-endserver via 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 WebSEAL is configured (webseald.conf) to use a specific client certificate to

authenticate to the back-end server (ssl-keyfile-label).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. Use the ssl-keyfile-label parameter in thewebseald.conf configuration file to configure the key-label.

You must surround the key-label argument with quotation marks. For example:–K “cert1_Tiv”

See “Configuring key database parameters” on page 36.

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

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 Access Manager-specificHTTP 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 toidentity 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 SSLAccess Manager supports SSL junctions between a front-end WebSEAL server anda back-end WebSEAL server. Use the –C option with the create command tojunction the two WebSEAL servers over SSL and provide mutual authentication.

Example:pdadmin> server task webseald-<instance-name> create –t ssl –C –h serverA /jctA

Mutual authentication occurs in the following two stages:

Client WebSEALWeb

Server

www.ibm.com

Secure Domain

-H and -P

ProxyServer

Clipper Internet

-h and -pjunction at /ibm

Figure 31. Example proxy junction


v The SSL protocol allows the back-end WebSEAL server to authenticate to thefront-end WebSEAL server through its server certificate.

v The –C option enables the front-end WebSEAL server to pass its identityinformation 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 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 161.

The following conditions apply to WebSEAL-to-WebSEAL junctions:v The junction is only appropriate with the –t ssl or –t sslproxy junction type.v Both WebSEAL servers must share a common LDAP or DCE registry. This

allows the back-end WebSEAL server to authenticate the front-end WebSEALserver identity information.

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

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 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 155v “Filtering URLs in responses” on page 156v “Processing URLs in requests” on page 158

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

URLs expressed in relative format never require any manipulation by WebSEAL.By default, the browser handles relative URLs by prepending the correct scheme,server, and directory information (including the junction) to the relative URL. Theprepended information comes from the existing page on which the link resides.

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

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 32. Summary: Modifying URLs to back-end resources


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 156v “Modifying absolute URLs with script filtering” on page 157v “Filtering changes the Content-Length header” on page 158

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 only filters 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. However,WebSEAL must add the junction name to the path of absolute and server-relativeURLs 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

These URLs are modified to reflect the junction point of the junctioned server,for example:/jct/dir/file.html

v Absolute URLs indicate a URL position in relation to a host name or IP address,and a network port, for example:http://<host-name>[:<port>]/file.html, orhttps://<host-name>[:<port>]/file.html

These URLs are modified according to the following set of rules:1. 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

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

3. Only URLs in content types defined in the [filter-content-types] stanza of thewebseald.conf configuration file are filtered.

4. META tags are always filtered for refresh requests, for example:<META HTTP-EQUIV=”Refresh” CONTENT=”5;URL=http://server/url”>


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

Note: You must also use the –j option to create the junction to the back-end server.

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./junction-name/resource

This solution parses script embedded in HTML code and therefore requiresadditional processing overhead that can negatively impact performance. Limit youruse of the script-filter parameter only to junctions that require support for filteringof embedded absolute URLs.

The following diagram illustrates this URL filtering solution:

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

/jctAwith -j option

Figure 33. Filtering absolute URLs


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.

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 once 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 158v “Handling server-relative URLs with junction mapping” on page 159

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 variable and value:


IV_JCT_<backend-server-name> = </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

WebSEAL provides an alternative, non-cookie-based solution for handlingdynamically generated server-relative URLs. See “Handling server-relative URLswith junction mapping” on page 159.

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.

Access Manager provides an alternative to the cookie-based solution for filteringdynamically generated server-relative URLs. You can create and activate a junctionmapping 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:

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 34. Processing server-relative URLs


#jmt.conf#<junction-name> <resource-location-pattern>/jctA /documents/release-notes.html/jctA /travel/index.html/jctB /accounts/*/jctB /images/weather/*.jpg

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

Additional junction optionsYou can provide the following additional WebSEAL junction functionality withadditional options:v “Forcing a new junction (–f)” on page 160v “Supplying client identity in HTTP headers (–c)” on page 161v “Supplying client IP addresses in HTTP headers (–r)” on page 162v “Limiting the size of WebSEAL-generated HTTP headers” on page 163v “Passing session cookies to junctioned portal servers (–k)” on page 163v “Supporting case-insensitive URLs (–i)” on page 164v “Stateful junction support (–s, –u)” on page 164v “Specifying back-end server UUIDs for stateful junctions (–u)” on page 165v “Junctioning to Windows file systems (–w)” on page 167

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 Access Manager-specific client identity andgroup 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 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.



CGI EnvironmentVariable Equivalents

Description

iv-creds = HTTP_IV_CREDS = Encoded opaque data structure representing anAccess Manager credential. Supplies credentials toremote servers so mid-tier applications can use theauthorization API to call the authorization service.Refer to the IBM Tivoli Access Manager AuthorizationC API Developer’s Reference.

The Access Manager-specific HTTP header entries are available to CGI programs asthe 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 Access Manager-specific HTTP header data is sent tothe back-end application server.–c <header-types>

The header-types arguments include: all, iv_user, iv_user_l, iv_groups, andiv_creds.


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

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 express 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 Access Manager session cookie(originally established between the client and WebSEAL) to a back-end portalserver. This option currently exists to directly support the integration of WebSEALwith 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 supporting


application 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, Access Manager treats URLs as case-sensitive when performing checkson access controls. The –i option is used to specify that WebSEAL treat URLs ascase-insensitive when performing authorization checks on a request to a junctionedback-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 junction


to 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, Access Manager balances back-end server load by distributing requestsacross all available replicated servers. Access Manager uses a “least-busy”algorithm. This algorithm directs each new request to the server with the fewestconnections 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 once the initialjunction is created as stateful, the add command is used without the –s option tojunction the remaining replicated back-end servers to the same junction point.

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 generates

WebSEAL

ApplicationServer 1

(UUID1)

ApplicationServer 2

(UUID2)

ClientStateful

JunctionsCookiewith

UUID2

Figure 35. Stateful junctions use back-end server UUIDs


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

A “state” established between a client and back-end server 2, via WebSEAL server1 will fail if a subsequent request from the client is routed through WebSEALserver 2.

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.

WebSEAL-1

ApplicationServer 2

StatefulJunctions

WebSEAL-2

UUID B

ApplicationServer 1UUID A

Figure 36. Dissimilar UUIDs


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.

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:

WebSEAL-1

ApplicationServer 2

(UUID 2)

StatefulJunctions

LoadBalancing

Mechanism

WebSEAL-2

Client

Cookiewith

UUID 2

ApplicationServer 1

(UUID 1)

Figure 37. Specifying back-end server UUIDs for stateful junctions


1. Prevents the use of the 8.3 file name formatWhen 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 nameentered.

2. Disallows trailing dots in directory and file namesIf a file or directory contains trailing dots, a 403 “Forbidden” error is returned.

3. Enforces case-insensitivity by setting the –i optionThe –w option automatically invokes the –i option. This option specifies thatspecify that WebSEAL treat URLs as case-insensitive when performingauthorization checks on a request to a junctioned back-end server. After asuccessful ACL check, the original case of the URL is restored when the requestis sent to the back-end server.

Note: If you only require control over case-insensitivity 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 168v “Exceptions to enforcing permissions across junctions” on page 169v “Certificate authentication across junctions” on page 169

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 Access Manager server Web space, access pages belonging to thejunctioned server(s). You should be able to access these pages (subject to


permissions, 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 Access Manager permissions are not enforceable across a junction. Youcannot control, for example, the execution of a CGI script with the x permission, ora directory listing with the l permission. WebSEAL has no means of accuratelydetermining whether or not a requested object on a back-end server is, forexample, a CGI program file, a dynamic directory listing, or a regular HTTP object.

Access to objects across junctions, including CGI programs and directory listings, isonly controlled 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 150

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.

Using query_contents with third-party serversIf you want to protect the resources of the third-party application Web space usingthe Access Manager security service, you must provide WebSEAL with informationabout 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 based on 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 Access Manager server to the third-party server and editing aconfiguration file.

The following 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 which 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.3. 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 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 Access Manager server. Entries that indicatesubdirectories 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 may 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 may 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 Access Manager.

Additional functionality can be added to this program to support special featuresof some third-party Web servers. These features include:1. Directory mapping — where a sub-directory not below the document root is

mapped into the Web space.2. 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 Access Manager to display junctionedWeb server object spaces in the Web portal manager. It is very important to securethis 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. Web 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 Web resources. This chapter discusses single sign-on solutions for the Web spaceof a WebSEAL proxy configuration. Examples include specially configuredjunctions, Global Sign-on, and LTPA.

Topic Index:v “Configuring BA headers for single sign-on solutions” on page 175v “Using global sign-on (GSO)” on page 179v “Configuring single sign-on to IBM WebSphere (LTPA)” on page 182v “Configuring single sign-on forms authentication” on page 184

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 175v “Supplying client identity in BA headers” on page 176v “Supplying client identity and generic password” on page 176v “Forwarding original client BA header information” on page 177v “Removing client BA header information” on page 178v “Supplying user names and passwords from GSO” on page 179

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 allowsthe user to access a resource, regardless of the resource’s location, using only oneinitial login. Any further login requirements from back-end servers are handledtransparent to the user.

Client WebSEALWeb

ApplicationServer

Junction

Login #1 Login #2

Figure 38. Multiple logins


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 allow 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 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 an AccessManager identity. By mapping a client user to a known Access Manager user,WebSEAL manages authentication for the back-end server and provides a simpledomain-wide single sign-on solution.

The following conditions exist for this solution:

Client WebSEALWeb

ApplicationServer

New BA header withWebSEAL-supplied

authenticationinformation

Initial authentication resultsin Policy Director

credentials

junction

request request

Figure 39. Supplying authentication information to back-end servers


v WebSEAL is configured to supply the back-end server with the user namecontained 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 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 Access Manager “dummy” password is used for all requests; all usershave the same password in the back-end server registry. The use of the common“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.

Since 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 Access Manager identity inorder 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.

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:

Client WebSEALSSL junction Web

ApplicationServer

WebSEAL supplies PolicyDirector identity and "dummy"

password

anyauthentication

mechanism

Registry Registry

Figure 40. BA Header contains identity and ″dummy″ password

Chapter 8. Web single sign-on solutions 177

v The back-end server requires client identity information via BAThe 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 only be accessed 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 41. 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 Access Manager client identityinformation into HTTP header fields. See “Supplying client identity in HTTPheaders (–c)” on page 161.

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 setup 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)Access Manager supports a flexible single sign-on solution that features the abilityto provide alternative user names and passwords to the back-end Web applicationserver.

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 “GSO aware” junctions between WebSEALand back-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 42. 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. An Access Manager identity is obtained.

Note: The single sign-on process is independent of the initial authenticationmethod.

2. WebSEAL passes the 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 43), 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 only becreated for registered users.

The registry contains a database for Michael that maps the resource: travel-app toa specific 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 43. 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.

It is recommended that you always use SSL junctions with GSO to ensureencryption of credentials and all data.

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.

gso-cache-entry-idle-timeout Maximum time (in seconds) an inactive cacheentry can remain in the cache.

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, Upon 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 items: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 a LTPAjunction. A high value uses more memory butresults in faster information access. Each cacheentry consumes approximately 50 bytes. Defaultvalue 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.

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 Access Manager user in to a back-end junctioned application serverthat 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 directly

from 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

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.

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 44. Forms single sign-on process flow


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 WebSEALaborts forms single sign-on processing and returns an error to the browser.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 using the authentication data supplied byWebSEAL 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:1. The login page or pages for the application must be uniquely identifiable via a

single regular expression or several regular expressions.2. 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 ofeach of the login forms, or the login form is the first form in the login page.Note that when using the “action” attribute to identify the login form, the“action” attribute has not passed through WebSEAL’s HTML filtering. Theregular expression should match the action URI prior to being filtered.

3. Client-side scripting may be used to validate input data, but it must not modifythe input data. This includes the use of Javascript to set cookies in the user’sbrowser.

4. Login data is submitted at only one point in the authentication process.5. 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 190. 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 which 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 (lower case letter)

[^0-9] Matches any character not between 0 and 9 (not a number)

[a-zA-Z] Matches any character between a and z (lower case) or A and Z(upper case)

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” attributeof the 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 AccessManager user name and DN. To use the user’s Access Manager user name as theinput 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 193v “Supporting back-end server-side applications” on page 194v “Junction best practises for application integration” on page 195v “Building a custom personalization service” on page 197v “Enabling dynamic business entitlements (tag/value)” on page 198v “Maintaining session state between client and back-end applications” on page

201v “Providing access control to dynamic URLs” on page 204v “Dynamic URL example: The Travel Kingdom” on page 210

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 Access Manager-specific user,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 Access Manager-specific header information in HTTP requests destinedfor a back-end server.

See also“Supplying client identity in HTTP headers (–c)” on page 161.

Additional Access Manager-specific environment variables:

CGI Environment Variables Description

HTTP_IV_USER The Access Manager user account name of the requester.

HTTP_IV_GROUPS The Access Manager groups to which the requesterbelongs. Specified as a comma-separated list of groups —each group is surrounded by double-quote marks.

HTTP_IV_CREDS Encoded opaque data structure representing an AccessManager credential. Supplies credentials to remote serversso mid-tier applications can use the authorization API tocall the authorization service. Refer to the IBM Tivoli AccessManager Authorization C API Developer’s Reference.


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 AccessManager 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 Access Manager-specific client identity and group membership informationinto the HTTP headers of requests destined for that server.


The Access Manager-specific HTTP header information enables applications onjunctioned third-party servers to perform user-specific actions based on the client’sAccess Manager identity.

WebSEAL provides the following Access Manager-specific HTTP headers:


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 an Access Managercredential. Supplies credentials to remote servers so mid-tierapplications 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 161.

Junction best practises for application integrationThis section includes “best practises” recommendations when using WebSEALjunctions.v “Supplying complete HOST header information with -v” on page 195v “Supporting standard absolute URL filtering” on page 196

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 arequest 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 practises”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>]

Chapter 9. Application integration 195

For example:-v xyz.ibm.com:7001

Note: The port designation should only be supplied 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 154.

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 may 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 practises”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 an Access Managerenvironment.

The process flow for building a custom WebSEAL portal service includes thefollowing items: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 only selects 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), AccessManager provides a flexible mechanism that allows you to include entitlementinformation in user credentials at the point of authentication. Applications canextract this data from the credential directly using the authorization API. Forfurther information on implementing this CDAS extension, refer to the IBM TivoliAccess 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:v User-defined supplemental data from any field of a user’s LDAP registry

account is added as extended attribute data in the user’s Access Managercredential.

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


v The back-end application can extract the data from the header without requiringspecial 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:1. 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 this section.

2. 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 use the [ldap-ext-cred-tags] stanza of the pd.conf configuration file to mapspecific data from the LDAP inetOrgPerson object class to a user-defined extendedattribute in the user credential. The parameters in this stanza have the followingformat:<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[ldap-ext-cred-tags] stanza:

ldap-employee-number = employeeNumber

Attribute name and value as theyappear in the user credential:

tagvalue_ldap-employee-number:09876

v This functionality requires that the user authenticate via an LDAP user nameand password. The passwd-ldap authentication mechanism must be enabled.The libldapauthn (ldapauthn) shared library is coded to look in the[ldap-ext-cred-tags] stanza of the pd.conf configuration file for supplementaluser-defined credential information.

v The LDAP data can come from a standard or custom field in the inetOrgPersonobject class.

v You can place multiple entries in the [ldap-ext-cred-tags] stanza.v All extended attributes specified in stanza entries are placed in the credential

upon a user login.v The LDAP data names are not case-sensitive.v The credential extended attribute names are case-sensitive.


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 Access Manager objects, you can configure a junction toprovide this User Session ID information to the back-end server. An application onthis back-end server can take advantage of the user session information to managethe 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

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 encoded


string 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. Since 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 198.

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 203v “Using pdadmin to terminate all user sessions” on page 203

Using Administration API to terminate single user sessionsA back-end application can use the 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.

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.

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 specificoperation and its parameter values. The query string portion of the URL providesoperations, parameters, and values to the Web application interface.

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 45. Terminate all userA sessions


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. Access Manager solves thisproblem by providing a mechanism where many dynamic URLs can be mapped toa 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>

Access Manager uses a subset of UNIX shell pattern matching (including wildcards) to define the set of parameters that constitute one object in the object space.Any dynamic URL that matches those parameters is mapped to that object.

Access Manager supports the following UNIX shell pattern-matching characters:

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.acme.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 46. Passing data to a CGI gateway via 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 wild card 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.acme.com/sales/web/db.cgi?service=SoftWear&catalog=clothing&product=shirt&color=red

www.acme.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.acme.com/sales/web/fortecgi.cgi/redshirt"

Figure 47. 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 which correspond to the most restrictive ACLs higher up inthe list. For example, if the book.sales procedure of a sales order application is tobe restricted to just a book club group, but the rest of the sales order applicationcan be accessed by all users, then the mappings should be in the order shown inthe following 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 EvaluationOnce the dynamic URL has been resolved to an object space entry, the standardACL/POP inheritance model is used to determine if the request should beprocessed 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 an 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 upper-case characters in the object name. Use lower-case 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 which offers clients a travel booking serviceover the Internet. The business intends to operate two Oracle database applicationson their 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 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, etc.

/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 a staff member the ability to view or changetheir 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:1. Travel agent staff have complete control over all bookings.2. Authenticated customers can make and change their own bookings, but cannot

interfere with the travel data of other authenticated customers.3. Administration staff have complete access to all of the administration

information.4. Travel Kingdom staff other than the Administration department can change

their own resume information and view partial information of other membersof 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 wish to make their travelbookings across the Internet.

Each user is given an account in the secure domain so that they can beindividually identified by the WebSEAL server. The user’s identity is also passedto the Oracle Web Servers to provide a single sign-on solution to all of the Webresources.


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. webseald.conf reference

webseald.conf configuration file

Categories and stanzas:v WEBSEAL GENERAL

[server]v LDAP

[ldap]v ACTIVE DIRECTORY

[uraf-ad]v DOMINO

[uraf-domino]v SSL

[ssl]v JUNCTION

[junction][filter-url][filter-schemes][filter-content-types][script-filtering][gso-cache][ltpa-cache]

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


[ssl-qop-mgmt-default]v SESSION

[session]v CONTENT

[content][acnt-mgt][cgi][cgi-types][cgi-environment-variables][content-index-icons][icons][content-cache][content-mime-types][content-encodings]

v LOGGING[logging]

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

v POLICY DIRECTOR[policy-director]

WEBSEAL GENERAL


[server] stanza

SYSTEM

unix-user UNIX user account for WebSEAL server.

unix-group UNIX group account for WebSEAL server.

unix-pid-file Location of PID file.

server-root Root directory for the WebSEAL server.

server-name WebSEAL server instance name.

THREADS AND CONNECTIONS

worker-threads Number of WebSEAL worker threads.

client-connect-timeout Initial client connection timeout.

persistent-con-timeout HTTP/1.1 persistent connection timeout.

HTTPS CLIENT

https Allow HTTPS access.

https-port Port to use for secure HTTPS requests.

HTTP CLIENT

http Allow unsecure HTTP (TCP) access.

http-port Port to use for unsecure HTTP requests.

REQUEST BODIES AND CACHING

request-body-max-read Maximum number of bytes to read in as contentfrom the body of POST requests.


WEBSEAL GENERAL


request-max-cache Maximum amount of data cached per request.

DYNURL

dynurl-map Location of URL-to-protected object mapping file.

dynurl-allow-large-posts Limit WebSEAL’s ability to read POST requestslarger than that specified by post-max-read.

URI HANDLING

utf8-url-support-enabled Controls how WebSEAL interprets URLs sent frombrowsers.

SUPPRESSING SERVER IDENTITY

suppress-server-identity Suppress WebSEAL server identity in HTTP serverresponses.

LDAP


[ldap] stanza

ldap-server-config Location of the ldap.conf configuration file (setduring configuration).

cache-enabled Enable and disable the local LDAP cache.

prefer-readwrite-server Allow selection of writeable LDAP server, whenavailable.

auth-using-compare Allows faster authentication checks using ancompare password operation rather than an LDAPbind.

default-policy-override-support Check default policy or user-specific policy.

user-and-group-in-same-suffix Search performance. Indicates that groups aredefined in the same LDAP suffix as the user.

ssl-enabled Enable and disable SSL for WebSEAL-to-LDAPcommunication.

ssl-keyfile Location of the SSL key file.

ssl-keyfile-dn The certificate label in the SSL key file, if any.

ssl-keyfile-pwd SSL key file password.

bind-dn The Distnguished Name of the WebSEAL daemon(set during configuration).

bind-pwd The password for the WebSEAL daemon (set duringconfiguration).

ACTIVE DIRECTORY


[uraf-ad] stanza

ad-server-config Location of the Active Directory configuration file(set during configuration).

bind-id Identity for the current server.

bind-pwd Password for the current server.

Appendix A. webseald.conf reference 215

DOMINO


[uraf-domino] stanza

domino-server-config Location of the Domino configuration file (set duringconfiguration).

bind-id Identity for the current server.

bind-pwd Password for the current server.

SSL


[ssl] stanza

webseal-cert-keyfile Location of the keyfile that contains the servercertificate sent to browsers by WebSEAL whennegotiating SSL sessions.

webseal-cert-keyfile-pwd WebSEAL certificate private key password.

webseal-cert-keyfile-stash Location of WebSEAL private key passwordstashfile.

webseal-cert-keyfile-label Name of WebSEAL certificate to use other than thedefault.

ssl-keyfile Location of the WebSEAL certificate keyfile used forinternal communication.

ssl-keyfile-pwd WebSEAL certificate private key password (forinternal communication).

ssl-keyfile-stash Location of WebSEAL private key password stashfile(for internal communication).

ssl-keyfile-label Name of certificate to use other than the default (forinternal communication).

disable-ssl-v2 Selectively disable SSL V2 support.

disable-ssl-v3 Selectively disable SSL V3 support.

disable-tls-v1 Selectively disable TLS V1 support.

ssl-v2-timeout GSKit cache session ID timeout for SSL V2connections.

ssl-v3-timeout GSKit cache session ID timeout for SSL V3connections.

ssl-max-entries Maximum number of concurrent entries in GSKitSSL session ID cache.

gsk-crl-cache-size CRL cache configuration. Maximum number ofentries in the GSKit CRL cache.

gsk-crl-cache-entry-lifetime CRL cache configuration. Lifetime timeout forindividual entires in the GSKit CRL cache.

ssl-ldap-server LDAP server used for CRL checking.

ssl-ldap-server-port Port number this LDAP server is listening on forCRL checking.

ssl-ldap-user Administration user for LDAP server.

ssl-ldap-user-password Password of administration user for LDAP server.


JUNCTION


[junction] stanza

junction-db Location of the junction database.

jmt-map Location of the junction-to-request mapping table(JMT).

http-timeout Timeout for sending to and reading from aTCP-based junction.

https-timeout Timeout for sending to and reading from anSSL-based junction.

ping-time Interval for WebSEAL-to-junctioned servers pingroutine.

basicauth-dummy-passwd Global password when supplying basicauthentication data over “-b supply” junctions.

worker-thread-hard-limit Percent of total worker threads processingrequests for a particular junction.

worker-thread-soft-limit Percent of total worker threads processingrequests for a particular junction.

io-buffer-size Buffer size for reading from and writing to ajunction.

max-webseal-header-size Maximum size, in bytes, of WebSEAL generatedHTTP headers.

DOCUMENT FILTERING

[filter-url] stanza

<tag> = <attribute> URL attributes that WebSEAL filters in responsesfrom junctioned servers.

[filter-schemes] stanza

scheme = <scheme-name> List of URL schemes that WebSEAL filters inresponses from junctioned servers.

[filter-content-types] stanza

type = text/html> Document content type that WebSEAL filters inresponses from junctioned servers.

type = text/vnd.wap.wml Document content type that WebSEAL filters inresponses from junctioned servers.

[script-filtering] stanza

script-filter Enable and disable filtering of absolute URLsfrom scripts on junctioned servers.

GSO CACHE

[gso-cache] stanza

gso-cache-enabled Enable and disable the GSO cache.

gso-cache-size Number of entries in the GSO cache.

gso-cache-entry-lifetime Maximum lifetime for a GSO cache entry.

gso-cache-entry-idle-timeout Maximum lifetime for an inactive GSO cacheentry.

LTPA CACHE

[ltpa-cache] stanza


JUNCTION


ltpa-cache-enabled Enable and disable the LTPA cache.

ltpa-cache-size Number of entries in the LTPA cache.

ltpa-cache-entry-lifetime Maximum lifetime for a LTPA cache entry.

ltpa-cache-entry-idle-timeout Maximum lifetime for an inactive LTAPA cacheentry.

AUTHENTICATION


BASIC AUTHENTICATION

[ba] stanza

ba-auth Enable and disable the Basic Authenticationmechanism.

basic-auth-realm Realm name displayed in the browser BA loginprompt.

FORMS

[forms] stanza

forms-auth Enable and disable authentication using Forms.

TOKEN

[token] stanza

token-auth Enable and disable authentication using tokenpasscodes.

CERTIFICATE

[certificate] stanza

accept-client-certs Configure WebSEAL client-side certificates handling.

HTTP HEADERS

[http-headers] stanza

http-headers-auth Enable and disable authentication using HTTPheaders.

[auth-headers] stanza

header Specific HTTP headers used for authentication.

IP ADDRESS

[ipaddr] stanza

ipaddr-auth Enable and disable authentication using IP addressinformation.

STEP UP

[authentication-levels] stanza

level = unauthenticatedlevel = password

Step-up authentication configuration.

MULTIPLEXING PROXY AGENTS

[mpa] stanza

mpa Enable and disable support for authentication viamultiplexing proxy agents.


AUTHENTICATION


CDSSO

[cdsso] stanza

cdsso-auth Enable and disable authentication using CDSSOtokens.

authtoken-lifetime Maximum lifetime value for CDSSO authenticationtoken.

[cdsso-peers] stanza

<machine-name> =<keyfile-location>

Domain peers that are participating in CDSSO.

FAILOVER

[failover] stanza

failover-auth Enable and disable accepting failover cookies.

failover-cookies-keyfile Location (absolute pathname) of the cookieencryption key generated by cdsso_key_gen.

failover-cookie-lifetime Time limit for when failover cookie content is valid.

enable-failover-cookie-for-domain Change failover cookie type from server-specificcookie to domain-specific cookie.

e-COMMUNITY SSO

[e-community-sso] stanza

e-community-sso-auth Enable and disable e-community SSO.

e-community-name The e-community name that appears in “vouch for”tokens and requests.

intra-domain-key Location of keyfile used to secure communicationbetween WebSEAL instances in a DNS domain.

is-master-authn-server Designates local machine as the master WebSEALauthentication server.

master-authn-server Name of master WebSEAL authentication server (ifnot the local machine).

master-http-port Non-standard HTTP port for master authenticationserver to listen on.

master-https-port Non-standard HTTPSport for master authenticationserver to listen on.

vf-token-lifetime The “vouch for” token lifetime value.

vf-url The “vouch for” URL.

ec-cookie-lifetime The e-community cookie lifetime value.

[inter-domain-keys] stanza

<domain-name> = <keyfile> The keyfiles for other domains participating in thee-community.

REAUTHENTICATION

[reauthentication] stanza

reauth-for-inactive Enable reauthentication due to session cache entryinactivity timeout.

reauth-reset-lifetime Reset session cache entry lifetime timer aftersuccessful reauthentication


AUTHENTICATION


reauth-extend-lifetime Extend session cache entry lifetime timer tocomplete reauthentication process.

AUTHENTICATION MECHANISMS AND LIBRARIES

[authentication-mechanisms] stanza

passwd-cdaspasswd-ldappasswd-uraftoken-cdascert-sslcert-cdashttp-requestcdssopasswd-strengthcred-ext-attrssu-passwordsu-token-cardsu-certificatesu-http-requestsu-cdssofailover-passwordfailover-token-cardfailover-certificatefailover-http-requestfailover-cdsso

List of supported authentication mechanisms andassociated shared libraries.

SSL QUALITY OF PROTECTION MANAGEMENT

[ssl-qop] stanza

ssl-qop-mgmt Enable and disable quality of protectionmanagement.

[ssl-qop-mgmt-hosts] stanza

<ip-address> QOP encryption level for individual hosts.

[ssl-qop-mgmt-networks] stanza

<ip-address/mask> QOP encryption level for individual networks.

[ssl-qop-mgmt-default] stanza

default Default QOP encryption level for all otherunmatched IP addresses.

SESSION


[session] stanza

max-entries Maximum number of concurrent entries inWebSEAL credentials/session cache.

timeout Maximum lifetime for an entry in the WebSEALcredentials/session cache.

inactive-timeout Lifetime of inactive entries in the WebSEALcredentials cache.

SSL CLIENT SESSIONS

ssl-id-sessions Use the SSL ID to maintain HTTPS login sessions.


SESSION


SHARING SESSIONS

use-same-session Use the same session ID for clients who switchbetween HTTP and HTTPS.

SENDING SESSION COOKIES

resend-webseal-cookies Send any configured session and failover cookieswith every response to the client.

USER SESSION IDS

user-session-ids Enable/disable the creation and handling of usersession IDs for session management.

CONTENT


[content] stanza

LOCAL DIRECTORIES AND FILES

doc-root Root directory of the Web document tree.

directory-index Name of directory index file.

delete-trash-dir Temporary trash directory for files deleted by theadministrator.

LOCAL USER DIRECTORIES

user-dir Directory is user’s home tree containing publicHTML documents.

ERROR PAGES

error-dir Director containing WebSEAL error description files.

ACCOUNT MANAGEMENT PAGES

[acnt-mgt] stanza

mgt-pages-root Root of account management pages.

login Name of standard login form.

login-success Name of login success form.

logout Name of page displayed after successful logout.

account-locked Name of page displayed if authentication failed dueto a locked account.

passwd-expired Name of page displayed if authentication fails dueto an expired password.

passwd-change Name of change password form.

passwd-change-success Name of page displayed if password change requestis successful.

passwd-change-failure Name of page displayed if password change requestis unsuccessful.

help Name of page containing links to validadministration pages.

token-login Name of token login form.

next-token Name of next token form.

stepup-login Name of step-up authentication login form.


CONTENT


switch-user Name of switch user management form.

LOCAL CGI

[cgi] stanza

cgi-timeout Timeout value for writing to and reading from childCGI processes.

[cgi-types] stanza

bat = cmdcmd = cmdpl = perlsh = shtcl = tclsh76

Designates - for Win32 servers - what program toexecute for a particular CGI file extension.

[cgi-environment-variables] stanza

ENV = <variable-name> Environment variables to be inherited by CGIprograms.

ICONS

[content-index-icons] stanza

image/*video/*audio/*text/htmltext/*application/x-tarapplication/*

Specifies the graphic icons to use when a directoryindex is generated by WebSEAL (this occurs whenthere is no index.html).

[icons] stanza

diricon Icon to use for sub-directories.

backicon Icon to use for the parent directory.

unknownicon Icon to use for unknown file types.

DOCUMENT CACHING

[content-cache] stanza

text/htmlimage/**/*

Define cache type and size for specific documentMIME types that WebSEAL stores in memory.

MIME TYPES

[content-mime-types] stanza

<extension> = <type> Defines MIME type for specific documentextensions.

deftype Default MIME type to use when the document typeis not listed in the mapping table.

CONENT ENCODINGS

[content-encodings] stanza

gzZ

Maps document extension to an encoding type forbrowsers that support content encoding.


LOGGING


[logging] stanza

server-log Location of server error log file.

max-size Log file rollover threshold for HTTP logs.

flush-time Frequency for flushing HTTP log file buffers.

requests Enable and disable the HTTP request log.

requests-file Location of the HTTP request log.

referers Enable and disable the HTTP referer log.

referers-file Location of the HTTP referer log.

agents Enable and disable the HTTP agent log.

agents-file Location of the HTTP agent log.

gmt-time Log requests with GMT time instead of local timezone.

AUTHORIZATION API


[aznapi-configuration] stanza

db-file Location of the local client’s policy database cachefile.

cache-refresh-interval Defines the interval between checks for updates(poll) to the master authorization server.

listen-flags Enale and disable flags for the reception of policycache update notifications.

AUTHORIZATION API LOGGING

logclientid=webseald

logsize Log file rollover threshold for management auditlog.

logflush Frequency for flushing management audit log filebuffers.

logaudit Enable and disable auditing.

auditlog Location of audit log.

auditcfg = azn Capture authorization events.

auditcfg = authn Capture authentication events.

auditcfg = http Capture WebSEAL events.

AUTHORIZATION API SERVICE DEFINITIONS

<service-id>

[aznapi-entitlement-services] stanza

AZN_ENT_EXT_ATTR

POLICY DIRECTOR


[policy-director] stanza


POLICY DIRECTOR


config-file Location of the pd.conf configuration file.


Appendix B. WebSEAL junction reference

The pdadmin utility provides an interactive command-line prompt from whichyou can perform WebSEAL junction tasks.

Topic Index:v “Using pdadmin to create junctions” on page 225v “The junction commands” on page 226v “Create a new junction for an initial server” on page 227v “Add an additional server to an existing junction” on page 229

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>

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.


Command Description

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, –W, and –b filteroptions.

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


Supplying BA header information

Appendix B. WebSEAL junction reference 227

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

–L <percent-value> Defines the hard limit for consumption of workerthreads.

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 an additional server to an existing junctionOperation: Adds an additional 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.

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

Appendix B. WebSEAL junction reference 229

–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. 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 C. Notices 233


Index

Aabsolute URL filtering, best practises 196accept-client-certs 115access control list (ACL) 4account management pages 33account-locked 33acct_locked.html 34ACL 4ACL policies

defining 4explicit 5inherited 5valid characters for ACL names 82WebSEAL-specific 81

acnt-mgt stanza 33, 59agent.log 39

event logging format 42example 41

agents 39agents-file 39application support, back-end 194argument-stanza 187authentication

authenticated access to resources 10basic authentication 111CDSSO 129certificate 113configuration overview 107configuring multiple methods 109custom CDAS parameters 108default configuration 108e-community 133forms 112forms single sign-on 184goals 10HTTP header 116IP address 118local parameters 108login prompt 109multiplexing proxy agents (MPA) 119overview 9reauthentication 122, 125supported methods 98supported session data types 98switch user 57token 118unauthenticated access to resources 10understanding process 97

authentication methods, summary 98authentication stength POP policy 92authentication strength POP policy 86authentication-levels stanza 87, 92authentication-mechanisms stanza 61authorization database replica location 47authorization database updates and polling 46authorization service 7authtoken-lifetime 132aznapi-configuration stanza 42, 47, 77

Bba-auth 111back-end application support 194backicon 27basic authentication

configuring 111basic-auth-realm 111basicauth-dummy-passwd 176best practises

absolute URL filtering 196supplying HOST header information (-v) 195

business entitlements (dynamic) 198

Ccache

GSKit (SSL) 99WebSEAL credentials 99

cache-refresh-interval 47CDMF shared library 129cdsso 108, 131CDSSO authentication 129cdsso_key_gen 107, 132, 140cdsso-auth 131cdsso-peers stanza 132cdssoauthn 131cert-cdas 108cert-ssl 108, 115certificate authentication 113certificates

GSKit 35iKeyman 35key database file types 35managing 35

CGI programmingsupporting 193supporting WIN32 environment variables 194

cgi-environment-variables stanza 194cgi-timeout 25cgi-types stanza 27client-connect-timeout 24common log format (request.log) 40content-caches stanza 28Content-Length header 158cookies

junction 158session 101, 163

cred-ext-attrs 108credentials

extended attributes 198, 202inserting data in HTTP headers 199inserting LDAP data 198inserting user session id in HTTP header 202overview 12

credentials cache 99configuring 101inactivity timeout 101lifetime timeout 101maximum entries 101overview and structure 11


CRL cache, configuring 38gsk-crl-cache-entry-lifetime 38gsk-crl-cache-size 38

CRL checking 38cross-domain sign-on

CDSSO 129e-community 133

cross-site scriptingillegal-url-substrings stanza 68preventing vulnerability 68

Ddb-file 47default-webseal ACL policy 82directory index icons 27directory-index 27diricon 27disable-ssl-v2 24disable-ssl-v3 24disable-tls-v1 24doc-root 26document caching 28

document-cache-control POP 29flush caches 29

document filtering 30document root directory

change location 26document-cache-control POP extended attribute 29dynamic business entitlements 198dynamic URLs

dynurl-allow-large-posts 208dynurl-map 205example 210GET and POST methods 207mapping ACL objects 205overview 204placing limitations on POST requests 207providing access control 204request-body-max-read 207resolving 207summary and technical notes 209updating, dynurl update 206

dynurl update 206dynurl-allow-large-posts 208dynurl-map 205dynurl.conf 205

Ee-community authentication 133

″vouch for″ request and reply 139″vouch for″ token 140configuring 141e-community cookie 139encrypting ″vouch for″ token 140features 134process flow 135

e-community cookie 139e-community-name 141e-community-sso-auth 141ec-cookie-lifetime 142enable-failover-cookie-for-domain 107entitlements, dynamic business 198entrust-client 117

error messagesHTTP 30macro support for HTTP 32serviceability 43

error.log 43event logging

HTTP logging 42statistics 77

event poolhttp 42http.agent 42http.clf 42http.cof 42http.ref 42

explicit ACL policy 5extended attributes

document-cache-control (POP) 29HTTP-Tag-Value (junction) 199, 202in user credentials 199reauth (POP) 123

Ffailover cookies

configure cookie lifetime 107configuring 104enable domain-wide cookies 107enabling 105encrypting/decrypting cookie data 107

failover-auth 106failover-cdsso 106failover-certificate 106failover-cookie-lifetime 107failover-cookies-keyfile 107failover-http-request 106failover-password 106failover-token-card 106fatal.log 43filter URLs

Content-Length header 158processing URLs in requests 158script filtering for absolute paths 157standard filtering rules 156

filter-content-types stanza 30filter-schemes stanza 30filter-url stanza 157filtering

absolute URLs 156best practises for absolute URLs 196Content-Length header

X-Old-Content-Length 158document MIME types 30filter absolute URLs with script filtering 157processing URLs in requests 158server-relative URLs 156standard URL filtering rules for WebSEAL 156static documents 156text/html 156text/vnd.wap.wml 156

flush caches 29flush-time 40forms authentication 112

single sign-on solution 184forms-auth 112forms-sso-login-pages stanza 187front-end WebSEAL servers

replicate 50


fsso.conf.template 187

GGET method 207global sign-on (GSO) 179gmt-time 40gsk-crl-cache-entry-lifetime 38gsk-crl-cache-size 38GSKit 35

CRL cache 38file types 35

GSKit (SSL) session cache 99configuring 100

GSO 179configure GSO cache 182

GSO cache, configure 182gso-cache-enabled 182gso-cache-entry-idle-timeout 182gso-cache-lifetime 182gso-cache-size 182gso-resource 187

Hheader 117help 33help.html 34HOST header, best practises for junctions 195HTML account management pages

macro support 34HTML custom pages 33http 23HTTP common log format 40HTTP error messages 30

macro support 32http event pool 42HTTP header

limiting size 163PD-USER-SESSION-ID 202

HTTP header authentication 116HTTP logging

default 39using event logging 42

HTTP server identity, suppressing 69HTTP_IV_CREDS 161, 193, 195HTTP_IV_GROUPS 161, 193, 195HTTP_IV_REMOTE_ADDRESS 162HTTP_IV_USER 161, 193, 195HTTP_PD_USER_SESSION_ID 200HTTP_PD-USER-SESSION-ID 203http-headers-auth 116http-port 23http-request 108, 117HTTP-Tag-Value junction attribute 200, 202http-timeout (junctions) 25HTTP/1.1 responses 20http.agent event pool 42http.clf event pool 42http.cof event pool (NCSA) 42http.ref event pool 42httpauthn 117https 24https-port 24https-timeout (junctions) 25

IiKeyman 37

mutually authenticated SSL junctions 150overview 37SSL type junctions 149WebSEAL test certificate 115

illegal-url-substrings stanza 68inactive-timeout 101inherited ACL policy 5inter-domain-keys stanza 140, 143intra-domain-key 140, 142IP address authentication 118ipaddr-auth 118is-master-authn-server 142iv-creds 161, 195iv-groups 161, 195iv-remote-address 162iv-user 161, 195ivweb_setup 53ivweb_uninst 55

Jjmt load 159jmt-map 159jmt.conf 159junction cookies 158junction fairness 48junction mapping table 159junction stanza 48junction-db 145junctions

-b filter 178-b gso 179-b ignore 177-b supply 176authenticate with BA header (-B, -U, -W) 151best practises 195case-insensitive URLs (-i) 164certificate authentication 169client certificate (WebSEAL) (-K) 151command reference 225Distinguished Name (DN) matching (-D) 151enforcing permissions 169filter absolute URLs with script filtering 157filter URLs in responses 156forcing new junction (-f) 26, 160forms single sign-on (-S) 190global sign-on (GSO) 179gso options (-b gso, -T) 181guidelines for creating 146HOST header best practises (-v) 195host option (-h) 148HTTP-Tag-Value attribute 202HTTP/1.0 and 1.1 responses 20impact of -b options on mutually authenticated

junctions 152junction mapping table 159LTPA (-A, -F, -Z) 183modifying URLs from back-end applications 154mount multiple servers 168mutually authenticated (-D, -K, -B, -U, -W) 150overview 12, 145pdadmin server task 147process server-relative URLs with cookies 158process server-relative URLs with junction mapping 159

Index 237

junctions (continued)processing URLs in requests 158proxy junctions (-H, -P) 153query_contents 169required options 148scalability 14session cookie to portal server (-k) 163specify back-end UUID (-u) 165stateful junction support (-s, -u) 164supply client identity in HTTP headers (-c) 161supply IP address in HTTP headers (-r) 162type option (-t) 148virtual host name (-v) 195WebSEAL client certificate (-K) 151WebSEAL-to-WebSEAL (-C) 153Windows file systems (-w) 167worker thread allocation (-l) 49worker thread allocation (-L) 49

Kkey database file types 35

LLDAP data in HTTP headers 198ldap-ext-cred-tags stanza 199, 200ldapauthn 111, 112libcdssoauthn 131libfailoverauthn shared library 106libhttpauthn 117libldapauthn 111, 112libsslauthn 115libsuauthn 61libtokenauthn 118listen-flags 47log file, WebSEAL 21logcfg 42, 77logging

default HTTP 39HTTP (event logging) 42

logging stanza 21login 33

prompt conditions 109login prompt

conditions 109login_success.html 34login-form-action 187login-page 187login-page-stanza 187login.html 34, 113logout 33, 110logout.html 34LTPA (WebSphere) 182

configure junction 183configure LTPA cache 183

LTPA cache, configure 183ltpa-cache stanza 183ltpa-cache-enabled 183ltpa-cache-entry-idle-timeout 183ltpa-cache-entry-lifetime 183ltpa-cache-size 183

Mmacro support

HTML account management pages 34HTTP error messages 32

management objects 3master-authn-server 142master-http-port 141master-https-port 141max-entries 101max-size 40max-webseal-header-size 163messages 43

error.log 43fatal.log 43notice.log 43routing file 43warning.log 43

mgt-pages-root 33, 59mpa 122MPA authentication 119multi-factor authentication 91multiple WebSEAL instances

configuration overview 50configuring on UNIX 51configuring on Windows 53server start, stop, restart, status commands 56syntax in pdadmin commands 147, 225unconfiguring 55

multiplexing proxy agents (authentication) 119mutually authenticated junctions 150

NNCSA combined format 42net command (Windows) 56network-based authentication POP policy 92next-token 33nexttoken.html 34notice.log 43

Ppasswd_exp.html 34passwd_rep.html 34passwd-cdas 108passwd-change 33passwd-change-failure 33passwd-change-success 33passwd-expired 33passwd-ldap 108, 111, 112passwd.html 34password strength policy 84PD_PORTAL header 197pd_start status command 56PD-USER-SESSION-ID HTTP header 202pd.conf 199pdadmin policy

disable-time-interval 82max-login-failures 82max-password-repeated-chars 84min-password-alphas 84min-password-length 84min-password-non-alphas 84password-spaces 84

pdadmin server taskterminate all_sessions 203


pdadmin server task (junctions) 147pdweb command 20, 56PDWeb_config 51PDWeb_unconfig 55pdweb.authn statistics 72pdweb.authz statistics 73pdweb.debug (trace) 79pdweb.doccache statistics 75pdweb.http statistics 73pdweb.https statistics 74pdweb.jct.# statistics 77pdweb.jmt statistics 74pdweb.sescache statistics 75pdweb.threads statistics 74persistent-con-timeout 24personalization service

configuring WebSEAL 197example 198overview 197

ping-time (junctions) 25pkmscdsso 133pkmslogout 110pkmspasswd 110pkmsvouchfor 139, 142policy enforcer 7polling 46polling authorization database 47POP 5POP policy

authentication strength (step-up) 86defining 4document-cache-control extended attribute 29network-based authentication 92quality of protection 94reauth extended attribute 123

portal-map stanza 197POST method 207

configuring limitations 207POST request caching 63protected 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 45hosts 46networks 46POP policy 94

query_contents 169customizing 172installing 170securing 173

query_contents.c 170query_contents.cfg 170query_contents.exe 170query_contents.html 170query_contents.sh 170

Rreauth POP extended attribute 123reauth-extend-lifetime 124, 127reauth-for-inactive 126reauth-reset-lifetime 124, 126reauthentication

based on security (POP) policy 122based on session inactivity 125reauth POP extended attribute 123reauth-extend-lifetime 124, 127reauth-for-inactive parameter 126reauth-reset-lifetime 124, 126

referer.log 39event logging format 42example 41

referers 39referers-file 39regular expressions

for dynamic URLs 205for forms single sign-on 189list of 189

REMOTE_USER 193replica authorization database location 47replicating front-end WebSEAL servers 50request caching 63request-body-max-read 65, 207request-max-cache 65request.log 39

event logging format 42example 41

requests 39requests-file 39resend-webseal-cookies 102resource manager 7root directory, WebSEAL installation 19routing file 43

Sscalability 14

replicated back-end servers 16replicated front-end servers 15

script-filter 157script-filtering stanza 157security policy

identifyingcontent types 8levels of protection 8planning and implementing 8

securitygroup 58, 59, 60server identity (HTTP), suppressing 69server root directory 23server-log 21server-name 20, 50server-root 23, 59server-side application support 194server-side request caching 63serviceability messages 43

error.log 43fatal.log 43notice.log 43routing file 43warning.log 43

session cacheconfiguring 100, 101GSKit (SSL) 99inactivity timeout 101

Index 239

session cache (continued)lifetime timeout 101overview and structure 11WebSEAL credentials 99

session cookies 101enable 102

session data types 98session ID data types 103session ID management 201session state

between client and back-end 201configuring GSKit SSL session ID cache 100configuring WebSEAL credentials cache 101enable session cookies 102failover cookies 104managing 99session cookies 101terminate all user sessions 203terminate single user session 203user session ID management 201valid session ID data types 103

single sign-on-b filter 178-b gso 179-b ignore 177-b supply 176CDSSO 129concepts 175configure GSO cache 182e-community 133forms authentication 184global sign-on (GSO) 179LTPA (WebSphere) 182supply client identity in BA headers 176

SSL connectivity 24SSL session ID 102ssl-id-sessions 102ssl-keyfile 37ssl-keyfile-label 37ssl-keyfile-pwd 37ssl-keyfile-stash 37ssl-ldap-server 38ssl-ldap-server-port 38ssl-ldap-user 38ssl-ldap-user-password 38ssl-max-entries 100ssl-qop-mgmt 45ssl-qop-mgmt-default stanza 45ssl-qop-mgmt-hosts stanza 46ssl-qop-mgmt-networks stanza 46ssl-v2-timeout 100ssl-v3-timeout 100sslauthn 115starting WebSEAL 20stateful junctions 164, 165statistics 69

activity types 72components 72disable (stats off) 71display (stats get) 72enable (stats on) 70enable using event logging 77list (stats list) 72logcfg parameter 77pdweb.authn 72pdweb.authz 73pdweb.doccache 75

statistics (continued)pdweb.http 73pdweb.https 74pdweb.jct.# 77pdweb.jmt 74pdweb.sescache 75pdweb.threads 74reset (stats reset) 72show (stats show) 71stats command syntax 69stats commands 70stats parameter 77

stats 77stats, commands 70step-up authentication 86stepup-login 33, 89stepuplogin.html 34, 89stopping WebSEAL 20su-admin extended attribute 63su-admins group 57, 58, 59, 60su-excluded group 58, 59, 60suauthn 61suppress-server-identity 69switch user 57

authentication mechanism 61built-in shared library 61CDAS shared library 62enabling 58excluding users 60impact on WebSEAL functionality 62process flow 57securitygroup 58su-admin extended attribute 63su-admins group 57, 58su-excluded group 58valid authentication methods 60

switch-user 59system resource 3

Ttag value 198, 202tagvalue_user_session_id 202tcp-port 47terminate all user sessions 203terminate single user session 203three strikes login policy 82timeout 101, 123, 126timeout parameters

GSKit SSL session cache 100HTTP and HTTPS 24WebSEAL credentials/session cache 101

TLS connectivity 24token authentication 118token-auth 118token-cdas 108, 118token-login 33tokenauthn 118tokenlogin.html 34trace utility 78

pdweb.debug component 79trace list 79trace set 78trace show 78

Transport Layer Security (TLS) 24type, MIME 30


Uudp-port 47unauthenticated users, controlling 94unknownicon 27update notification listening 46, 47URL

about absolute paths 155about relative paths 155about server-relative paths 155filtering options 156handling UTF-8 66modifying URLs to back-end resources 154understanding path types 155using junction cookies 158using junction mapping table 159

use-same-session 102, 103user session ID management 201

tagvalue_user_session_id 201user-session-ids 201

user-defined objects 3user-session-ids 201UTF-8 encoded characters 66utf8-url-support-enabled 67

Vvf-token-lifetime 142vf-url 142vouch for request and reply 139

Wwarning.log 43web objects 3Web portal manager 6WebSEAL

configuring multiple instances 50HTTP/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 69webseald.conf configuration file 21

WebSEAL credentials/session cacheconfiguring 101overview 99overview and structure 11

WebSEAL junctions, See junctions 145webseal-cert-keyfile 36webseal-cert-keyfile-label 36, 115, 169webseal-cert-keyfile-pwd 36webseal-cert-keyfile-stash 36webseal-mpa-servers group 121, 122webseald.conf

location 21overview 21reference 213

WebSphere LTPA 182WIN32 environment variables, supporting 194worker threads

global allocation 48

worker threads (continued)junction fairness 48junctions 48managing 47per junction allocation 49WebSEAL 47

worker-thread-hard-limit 49worker-thread-soft-limit 48worker-threads 48

Index 241


Printed in the United States of Americaon recycled paper containing 10%recovered post-consumer fiber.

GC23-4682-00

Date post:	14-Mar-2018
Category:	Documents
Upload:	dinhdang
View:	234 times
Download:	7 times

WebSEAL Administrator’s Guide - IBM...

Documents