am51 webservers guide

7/28/2019 Am51 Webservers Guide

http://slidepdf.com/reader/full/am51-webservers-guide 1/256

IBM Tivoli Access Manager for e-business

Plug-in for Web ServersIntegration Guide

Version 5.1

SC32-1365-00



IBM Tivoli Access Manager for e-business

Plug-in for Web ServersIntegration Guide

Version 5.1

SC32-1365-00



Note

Before using this information and the product it supports, read the information in Appendix F, “Notices,” on page 215.

First Edition (November 2003)

This edition applies to version 5, release 1, modification 0 of IBM Tivoli Access Manager (product number 5724-C08)and to all subsequent releases and modifications until otherwise indicated in new editions.

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



Overview of ADI retrieval . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165Retrieving ADI from the plug-in client request . . . . . . . . . . . . . . . . . . . . . . . 166

Example: Retrieving ADI from the request header . . . . . . . . . . . . . . . . . . . . . 166Example: Retrieving ADI from the request query string . . . . . . . . . . . . . . . . . . . 167Example: Retrieving ADI from the request POST body . . . . . . . . . . . . . . . . . . . 167

Retrieving ADI from the user credential . . . . . . . . . . . . . . . . . . . . . . . . . 168Supplying a failure reason . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168Configuring dynamic ADI retrieval . . . . . . . . . . . . . . . . . . . . . . . . . . . 169

Configuring the plug-in to use the AMWebARS Web service . . . . . . . . . . . . . . . . . 170

Appendix A. Using pdbackup to backup plug-in data . . . . . . . . . . . . . . . 171Functionality . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171

Backing up plug-in data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171Restoring plug-in data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172

Syntax. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173

UNIX examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173Windows examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173Contents of pdinfo-pdwebpi.lst . . . . . . . . . . . . . . . . . . . . . . . . . . . 174Additional backup data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174

Appendix B. pdwebpi.conf reference . . . . . . . . . . . . . . . . . . . . . . 175General configuration parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . 175Authentication configuration parameters . . . . . . . . . . . . . . . . . . . . . . . . . 178Sessions configuration parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . 188LDAP configuration parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189Proxy configuration parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189Authorization API configuration parameters . . . . . . . . . . . . . . . . . . . . . . . . 190Web server specific configuration parameters . . . . . . . . . . . . . . . . . . . . . . . . 192

Appendix C. Module quick reference . . . . . . . . . . . . . . . . . . . . . . 197

Appendix D. Command quick reference . . . . . . . . . . . . . . . . . . . . . 203pdwebpi_start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204

pdwebpi . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206pdwpi-version . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207pdwpicfg –action config . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208pdwpicfg –action unconfig . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210

Appendix E. Special characters allowed in regular expressions . . . . . . . . . . . 213

Appendix F. Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215Trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216

Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225

Contents vii



viii IBM Tivoli Access Manager for e-business: Plug-in for Web Servers Integration Guide



Figures

1. Plug-in and Tivoli Access Manager component interaction. . . . . . . . . . . . . . . . . . . 22. Plug-in process flow for determining authentication module. . . . . . . . . . . . . . . . . . 47

3. Authentication challenge process logic. . . . . . . . . . . . . . . . . . . . . . . . . 484. Plug-in process flow for determining session module. . . . . . . . . . . . . . . . . . . . 505. Typical server architecture for failover cookies. . . . . . . . . . . . . . . . . . . . . . . 796. User access to secure applications using GSO.. . . . . . . . . . . . . . . . . . . . . . 1317. Forms single sign-on process flow. . . . . . . . . . . . . . . . . . . . . . . . . . 1348. CDSSO process flow. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1429. Logging into an e-community. . . . . . . . . . . . . . . . . . . . . . . . . . . . 148

10. e-Community single sign-on configuration example . . . . . . . . . . . . . . . . . . . . 15511. Attribute retrieval service process flow. . . . . . . . . . . . . . . . . . . . . . . . . 169

© Copyright IBM Corp. 2000, 2003 ix



x IBM Tivoli Access Manager for e-business: Plug-in for Web Servers Integration Guide



Tables

1. Tivoli Access Manager EPAC fields . . . . . . . . . . . . . . . . . . . . . . . . . . 52. pdwebpi.conf section summary . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

3. Supported Macro Substitutions . . . . . . . . . . . . . . . . . . . . . . . . . . . 104. [proxy] error page configuration parameters. . . . . . . . . . . . . . . . . . . . . . . 125. Web-server-specific configuration parameters . . . . . . . . . . . . . . . . . . . . . . 166. [p3p-header] parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267. Authentication audit record field definitions. . . . . . . . . . . . . . . . . . . . . . . 298. Auditing configuration parameter definitions . . . . . . . . . . . . . . . . . . . . . . 309. Plug-in supported languages with supported directory. . . . . . . . . . . . . . . . . . . . 36

10. Local Built-in Authenticators . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5611. External CDAS Server Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . 5612. Equivalent SPNEGO configuration between version 4.1 and 5.1. . . . . . . . . . . . . . . . . 7013. Failover authentication library file names . . . . . . . . . . . . . . . . . . . . . . . 8714. IV header field descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9415. Valid session data types for MPA . . . . . . . . . . . . . . . . . . . . . . . . . . 10416. Valid MPA authentication types . . . . . . . . . . . . . . . . . . . . . . . . . . 105

17. Plug-in ACL permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11118. Plug-in WebDAV permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . 11119. pdadmin LDAP logon policy commands . . . . . . . . . . . . . . . . . . . . . . . 11320. pdadmin LDAP password strength commands . . . . . . . . . . . . . . . . . . . . . 11421. Password examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11522. QOP level descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12223. IV header field descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12624. LTPA configuration parameters . . . . . . . . . . . . . . . . . . . . . . . . . . 12825. IV header field descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12826. General configuration parameters . . . . . . . . . . . . . . . . . . . . . . . . . . 17527. Authentication configuration parameters . . . . . . . . . . . . . . . . . . . . . . . 17828. Sessions configuration parameters . . . . . . . . . . . . . . . . . . . . . . . . . 18829. LDAP configuration parameters . . . . . . . . . . . . . . . . . . . . . . . . . . 18930. Proxy configuration parameters . . . . . . . . . . . . . . . . . . . . . . . . . . 189

31. Authorization API configuration parameters . . . . . . . . . . . . . . . . . . . . . . 19032. Web server specific configuration parameters . . . . . . . . . . . . . . . . . . . . . . 19233. Plug-in authentication method/module reference . . . . . . . . . . . . . . . . . . . . 19734. Windows-specific authentication modules . . . . . . . . . . . . . . . . . . . . . . . 19935. Plug-in session module reference . . . . . . . . . . . . . . . . . . . . . . . . . . 19936. Plug-in pre-authorization module reference . . . . . . . . . . . . . . . . . . . . . . 20037. Plug-in post-authorization module reference . . . . . . . . . . . . . . . . . . . . . . 20138. Response module reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202

© Copyright IBM Corp. 2000, 2003 xi



xii IBM Tivoli Access Manager for e-business: Plug-in for Web Servers Integration Guide



Preface

IBM® Tivoli® Access Manager Plug-in for Web Servers manages the security of your Web-based resources by acting as the gateway between your clients and

secure Web space. The plug-in implements the security policies that protect yourWeb object space. The plug-in can provide single sign-on, support, Web serversrunning as virtual hosts, and incorporate Web application server resources into itssecurity policy.

Note: For details on: supported platforms, disk and memory requirements,software prerequisites and installation instructions for the plug-in, refer tothe Tivoli Access Manager for e-business Web Security Installation Guide.

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

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

The IBM Tivoli Access Manager for e-business Plug-in for Web Servers Integration Guideprovides administrative procedures and technical reference information forsecuring your Web domain using the Plug-in for Web Servers application.

Who should read this bookThis guide is for system administrators responsible for the installation, deploymentand administration of Access Manager Plug-in for Web Servers.

Readers should be familiar with the following:

v PC and UNIX® operating systems.

v Database architecture and concepts.

v Security management.

v Internet protocols, including HTTP, HTTPS and TCP/IP.

v Lightweight Directory Access Protocol (LDAP) and directory services.

v A supported user registry.

v Authentication and authorization.

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

What this book contains

This book contains the following sections:

v Chapter 1, “Introducing IBM Tivoli Access Manager Plug-in for Web Servers”

© Copyright IBM Corp. 2000, 2003 xiii



Provides an introduction to the Access Manager Plug-in for Web Serversapplication giving details of system architecture, functionality and operatingenvironment.

v Chapter 2, “IBM Tivoli Access Manager Plug-in for Web Servers configuration”

Provides information on the configuration requirements for Access ManagerPlug-in for Web Servers.

v

Chapter 3, “IBM Tivoli Access Manager Plug-in for Web Servers authenticationand request processing”

Discussion of how the plug-in maintains session state, handles the authenticationprocess, and performs any post authorization processing required on authorizedsessions.

v Chapter 4, “IBM Tivoli Access Manager Plug-in for Web Servers security policy”

Information on the configuration and customization of the Access Managerplug-in for Web Servers security policy.

v Chapter 5, “Web single sign-on solutions”

Discussion of single signon solutions for the Web space protected by AccessManager Plug-in for Web Servers.

v

Chapter 6, “Cross-domain sign-on solutions”Discussion of the Access Manager Plug-in for Web Servers’ cross-domain singlesignon solutions.

v Chapter 7, “Application integration,” on page 159

Discussion of third-party application integration through the plug-in’s extendedrange of environment variables and HTTP headers, and dynamic URL capability.

v Chapter 8, “Authorization decision information retrieval,” on page 165

Discussion of how the plug-in can provide, or acquire, authorization decisioninformation (ADI) required to evaluate authorization rules that protect resourcesin the Tivoli Access Manager domain.

v Appendix A, “Using pdbackup to backup plug-in data,” on page 171

Information on using the pdbackup utility.v Appendix B, “pdwebpi.conf reference”

A listing of the Access Manager Plug-in for Web Servers configurationparameters with associated descriptions.

v Appendix C, “Module quick reference”

A listing of all plug-in authentication, session and post-authorization methodswith associated descriptions.

v Appendix D, “Command quick reference”

A listing of the available plug-in utilities with a description of the actions theyperform.

v Appendix E, “Special characters allowed in regular expressions,” on page 213

A listing of the special characters allowed in regular expressions used in thepdwebpi.conf configuration file.

Publications

Review the descriptions of the Tivoli Access Manager library, the prerequisitepublications, and the related publications to determine which publications youmight find helpful. After you determine the publications you need, refer to theinstructions for accessing publications online.

xiv IBM Tivoli Access Manager for e-business: Plug-in for Web Servers Integration Guide



Additional information about the IBM Tivoli Access Manager for e-businessproduct itself can be found at:

http://www.ibm.com/software/tivoli/products/access-mgr-e-bus/

The Tivoli Access Manager library is organized into the following categories:

v “Release information”

v “Base information”

v “Web security information”

v “Developer references” on page xvi

v “Technical supplements” on page xvi

Release informationv IBM Tivoli Access Manager for e-business Read This First (GI11-4155-00)

Provides information for installing and getting started using Tivoli AccessManager.

v IBM Tivoli Access Manager for e-business Release Notes (GI11-4156-00)

Provides late-breaking information, such as software limitations, workarounds,and documentation updates.

Base informationv IBM Tivoli Access Manager Base Installation Guide (SC32-1362-00)

Explains how to install and configure the Tivoli Access Manager base software,including the Web Portal Manager interface. This book is a subset of IBM Tivoli Access Manager for e-business Web Security Installation Guide and is intended foruse with other Tivoli Access Manager products, such as IBM Tivoli AccessManager for Business Integration and IBM Tivoli Access Manager for OperatingSystems.

v IBM Tivoli Access Manager Base Administration Guide (SC32-1360-00)

Describes the concepts and procedures for using Tivoli Access Manager services.Provides instructions for performing tasks from the Web Portal Managerinterface and by using the pdadmin command.

Web security informationv IBM Tivoli Access Manager for e-business Web Security Installation Guide

(SC32-1361-00)

Provides installation, configuration, and removal instructions for the TivoliAccess Manager base software as well as the Web Security components. This

book is a superset of IBM Tivoli Access Manager Base Installation Guide.

v IBM Tivoli Access Manager Upgrade Guide (SC32-1369-00)

Explains how to upgrade from Tivoli SecureWay Policy Director Version 3.8 orprevious versions of Tivoli Access Manager to Tivoli Access Manager Version5.1.

v IBM Tivoli Access Manager for e-business WebSEAL Administration Guide(SC32-1359-00)

Provides background material, administrative procedures, and technicalreference information for using WebSEAL to manage the resources of yoursecure Web domain.

v IBM Tivoli Access Manager for e-business IBM WebSphere Application ServerIntegration Guide (SC32-1368-00)

Preface xv





Provides installation, removal, and administration instructions for integratingTivoli Access Manager with IBM WebSphere® Application Server.

v IBM Tivoli Access Manager for e-business IBM WebSphere Edge Server IntegrationGuide (SC32-1367-00)

Provides installation, removal, and administration instructions for integratingTivoli Access Manager with the IBM WebSphere Edge Server application.

v

IBM Tivoli Access Manager for e-business Plug-in for Web Servers Integration Guide(SC32-1365-00)

Provides installation instructions, administration procedures, and technicalreference information for securing your Web domain using the plug-in for Webservers.

v IBM Tivoli Access Manager for e-business BEA WebLogic Server Integration Guide(SC32-1366-00)

Provides installation, removal, and administration instructions for integratingTivoli Access Manager with BEA WebLogic Server.

v IBM Tivoli Access Manager for e-business IBM Tivoli Identity Manager ProvisioningFast Start Guide (SC32-1364-00)

Provides an overview of the tasks related to integrating Tivoli Access Manager

and Tivoli Identity Manager and explains how to use and install theProvisioning Fast Start collection.

Developer referencesv IBM Tivoli Access Manager for e-business Authorization C API Developer Reference

(SC32-1355-00)

Provides reference material that describes how to use the Tivoli Access Managerauthorization C API and the Tivoli Access Manager service plug-in interface toadd Tivoli Access Manager security to applications.

v IBM Tivoli Access Manager for e-business Authorization Java Classes DeveloperReference (SC32-1350-00)

Provides reference information for using the Java™

language implementation of the authorization API to enable an application to use Tivoli Access Managersecurity.

v IBM Tivoli Access Manager for e-business Administration C API Developer Reference(SC32-1357-00)

Provides reference information about using the administration API to enable anapplication to perform Tivoli Access Manager administration tasks. Thisdocument describes the C implementation of the administration API.

v IBM Tivoli Access Manager for e-business Administration Java Classes DeveloperReference (SC32-1356-00)

Provides reference information for using the Java language implementation of the administration API to enable an application to perform Tivoli Access

Manager administration tasks.v IBM Tivoli Access Manager for e-business Web Security Developer Reference

(SC32-1358-00)

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 for e-business Command Reference (SC32-1354-00)

xvi IBM Tivoli Access Manager for e-business: Plug-in for Web Servers Integration Guide



Provides information about the command line utilities and scripts provided withTivoli Access Manager.

v IBM Tivoli Access Manager Error Message Reference (SC32-1353-00)

Provides explanations and recommended actions for the messages produced byTivoli Access Manager.

v IBM Tivoli Access Manager for e-business Problem Determination Guide

(SC32-1352-00)Provides problem determination information for Tivoli Access Manager.

v IBM Tivoli Access Manager for e-business Performance Tuning Guide (SC32-1351-00)

Provides performance tuning information for an environment consisting of TivoliAccess Manager with the IBM Tivoli Directory server as the user registry.

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

The Tivoli Software Library provides a variety of Tivoli publications such as whitepapers, datasheets, demonstrations, redbooks, and announcement letters. The TivoliSoftware Library is available on the Web at:

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

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

IBM Global Security KitTivoli Access Manager provides data encryption through the use of the IBM GlobalSecurity Kit (GSKit) Version 7.0. GSKit is included on the IBM Tivoli Access ManagerBase CD for your particular platform, as well as on the IBM Tivoli Access ManagerWeb Security CDs, the IBM Tivoli Access Manager Web Administration Interfaces CDs,and the IBM Tivoli Access Manager Directory Server CDs.

The GSKit package provides the iKeyman key management utility, gsk7ikm, whichis used to create key databases, public-private key pairs, and certificate requests.The following document is available on the Tivoli Information Center Web site inthe same section as the IBM Tivoli Access Manager product documentation:

v IBM Global Security Kit Secure Sockets Layer and iKeyman User’s Guide(SC32-1363-00)

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

IBM Tivoli Directory ServerIBM Tivoli Directory Server, Version 5.2, is included on the IBM Tivoli Access

Manager Directory Server CD for the desired operating system.

Note: IBM Tivoli Directory Server is the new name for the previously releasedsoftware known as:

v IBM Directory Server (Version 4.1 and Version 5.1)

v IBM SecureWay Directory Server (Version 3.2.2)

IBM Directory Server Version 4.1, IBM Directory Server Version 5.1, and IBM TivoliDirectory Server Version 5.2 are all supported by IBM Tivoli Access ManagerVersion 5.1.

Preface xvii







Additional information about IBM Tivoli Directory Server can be found at:

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

IBM DB2 Universal DatabaseIBM DB2® Universal Database™ Enterprise Server Edition, Version 8.1 is providedon the IBM Tivoli Access Manager Directory Server CD and is installed with the IBM

Tivoli Directory Server software. DB2 is required when using IBM Tivoli DirectoryServer, z/OS™, or OS/390® LDAP servers as the user registry for Tivoli AccessManager.

Additional information about DB2 can be found at:

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

IBM WebSphere Application ServerIBM WebSphere Application Server, Advanced Single Server Edition 5.0, isincluded on the IBM Tivoli Access Manager Web Administration Interfaces CD for thedesired operating system. WebSphere Application Server enables the support of

both the Web Portal Manager interface, which is used to administer Tivoli Access

Manager, and the Web Administration Tool, which is used to administer IBM TivoliDirectory Server. IBM WebSphere Application Server Fix Pack 2 is also required byTivoli Access Manager and is provided on the IBM Tivoli Access Manager WebSphereFix Pack CD.

Additional information about IBM WebSphere Application Server can be found at:

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

IBM Tivoli Access Manager for Business IntegrationIBM Tivoli Access Manager for Business Integration, available as a separatelyorderable product, provides a security solution for IBM MQSeries®, Version 5.2,and IBM WebSphere® MQ for Version 5.3 messages. IBM Tivoli Access Manager for

Business Integration allows WebSphere MQSeries applications to send data withprivacy and integrity by using keys associated with sending and receivingapplications. Like WebSEAL and IBM Tivoli Access Manager for OperatingSystems, IBM Tivoli Access Manager for Business Integration, is one of theresource managers that use the services of IBM Tivoli Access Manager.

Additional information about IBM Tivoli Access Manager for Business Integrationcan be found at:

http://www.ibm.com/software/tivoli/products/access-mgr-bus-integration/

The following documents associated with IBM Tivoli Access Manager for BusinessIntegration Version 5.1 are available on the Tivoli Information Center Web site:

v IBM Tivoli Access Manager for Business Integration Administration Guide(SC23-4831-01)

v IBM Tivoli Access Manager for Business Integration Problem Determination Guide(GC23-1328-00)

v IBM Tivoli Access Manager for Business Integration Release Notes (GI11-0957-01)

v IBM Tivoli Access Manager for Business Integration Read This First (GI11-4202-00)

xviii IBM Tivoli Access Manager for e-business: Plug-in for Web Servers Integration Guide











IBM Tivoli Access Manager for WebSphere Business IntegrationBrokersIBM Tivoli Access Manager for WebSphere Business Integration Brokers, availableas part of IBM Tivoli Access Manager for Business Integration, provides a securitysolution for WebSphere Business Integration Message Broker, Version 5.0 andWebSphere Business Integration Event Broker, Version 5.0. IBM Tivoli AccessManager for WebSphere Business Integration Brokers operates in conjunction with

Tivoli Access Manager to secure JMS publish/subscribe applications by providingpassword and credentials-based authentication, centrally-defined authorization,and auditing services.

Additional information about IBM Tivoli Access Manager for WebSphereIntegration Brokers can be found at:


The following documents associated with IBM Tivoli Access Manager forWebSphere Integration Brokers, Version 5.1 are available on the Tivoli InformationCenter Web site:

v

IBM Tivoli Access Manager for WebSphere Business Integration Brokers AdministrationGuide (SC32-1347-00)

v IBM Tivoli Access Manager for WebSphere Business Integration Brokers Release Notes(GI11-4154-00)

v IBM Tivoli Access Manager for Business Integration Read This First (GI11-4202-00)

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

Additional information about IBM Tivoli Access Manager for Operating Systemscan be found at:

http://www.ibm.com/software/tivoli/products/access-mgr-operating-sys/

The following documents associated with IBM Tivoli Access Manager forOperating Systems Version 5.1 are available on the Tivoli Information Center Website:

v IBM Tivoli Access Manager for Operating Systems Installation Guide (SC23-4829-00)

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

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

v IBM Tivoli Access Manager for Operating Systems Release Notes (GI11-0951-00)

v IBM Tivoli Access Manager for Operating Systems Read Me First (GI11-0949-00)

IBM Tivoli Identity ManagerIBM Tivoli Identity Manager Version 4.5, available as a separately orderableproduct, enables you to centrally manage users (such as user IDs and passwords)and provisioning (that is providing or revoking access to applications, resources, oroperating systems.) Tivoli Identity Manager can be integrated with Tivoli Access

Preface xix







Manager through the use of the Tivoli Access Manager Agent. Contact your IBMaccount representative for more information about purchasing the Agent.

Additional information about IBM Tivoli Identity Manager can be found at:

http://www.ibm.com/software/tivoli/products/identity-mgr/

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

To locate product publications in the library, click the Product manuals link on theleft side of the library page. Then, locate and click the name of the product on theTivoli software information center page.

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

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

Accessibility

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

Contacting software supportBefore contacting IBM Tivoli Software Support with a problem, refer to the IBMTivoli Software Support site by clicking the Tivoli support link at the followingWeb site: http://www.ibm.com/software/support/

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

The guide provides the following information:

v Registration and eligibility requirements for receiving support

v Telephone numbers, depending on the country in which you are located

v A list of information you should gather before contacting customer support

Conventions used in this book

This reference uses several conventions for special terms and actions and foroperating system-dependent commands and paths.

Typeface conventionsThe following typeface conventions are used in this reference:

xx IBM Tivoli Access Manager for e-business: Plug-in for Web Servers Integration Guide



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

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

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

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





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

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

Monospace

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

Operating system differencesThis book uses the UNIX convention for specifying environment variables and fordirectory notation. When using the Windows command line, replace $variable with%variable% for environment variables and replace each forward slash (/) with a

backslash (\) in directory paths. If you are using the bash shell on a Windowssystem, you can use the UNIX conventions.

Preface xxi



xxii IBM Tivoli Access Manager for e-business: Plug-in for Web Servers Integration Guide



Chapter 1. Introducing IBM Tivoli Access Manager Plug-in forWeb Servers

IBM Tivoli Access Manager (Tivoli Access Manager) Plug-in for Web Servers is anintegration solution that facilitates the implementation and management of thesecurity policy for your protected Web space. Installed as part of the same processas your Web server, the plug-in acts as the security gateway between your clientsand your protected Web space.

This introductory chapter gives an overview of Tivoli Access Manager Plug-in forWeb Servers technology, identifies the technical requirements for the product andprovides an introduction to the processes for ensuring the security of your Webspace using the plug-in.

Note: For details on supported platforms, disk and memory requirements,software prerequisites and installation instructions for the plug-in, refer to

the Tivoli Access Manager for e-business Web Security Installation Guide. Fordetails on upgrading Tivoli Access Manager Plug-in for Web Servers toversion 5.1 refer to the IBM Tivoli Access Manager Upgrade Guide.

This introductory chapter contains the following topics:

v “Tivoli Access Manager Plug-in for Web Servers technology”

v “Protecting your Web space with Tivoli Access Manager Plug-in for WebServers” on page 3

v “Tivoli Access Manager Plug-in for Web Servers authentication” on page 4

v “Credential acquisition” on page 5

Tivoli Access Manager Plug-in for Web Servers technologyTivoli Access Manager Plug-in for Web Servers can be integrated with the TivoliAccess Manager application to provide a complete security solution for your Webresources. The plug-in operates as part of the same process as your Web server,intercepting each request that arrives, determining if an authorization decision isrequired and providing a means for user authentication if necessary. The plug-incan provide single sign-on solutions and incorporate Web application resourcesinto its security policy.

Basic operational components and architectureTwo basic architectural components make up Tivoli Access Manager Plug-in forWeb Servers – the plug-in component and the Authorization Server. The plug-in

component operates with Web server threads, sending details of each request usingan Inter-Process Communication (IPC) interface to the Authorization Server. TheAuthorization Server performs the authentication and authorization of incomingrequests. The Authorization Server is a local mode AZNAPI application thataccepts and processes requests from the plug-in and responds, telling the plug-inhow to handle each request.

© Copyright IBM Corp. 2000, 2003 1



Client Browser

SD

User Registry

ACL DBMaster

ACL DBReplica

Plug-in

Web Server

AuthorizationServer

R u n T i m e

E n v i r o n m e n t

R u n T i m e

E n v i r o n m e n t

AccessManager

PolicyServer

The Authorization server determines which virtual host the request is addressed to(if virtual hosts are present on the Web server) and determines if the requestrequires authorization. Requests that do not require authorization are passeddirectly to the Web server for processing. Requests that require authorization areprocessed by the Authorization server in the following way:

1. Session and authentication information is extracted from requests that have been previously authenticated.

2. If required, an authentication interaction is initiated with the user.

3. A Tivoli Access Manager credential is created.

4. The resources the user can access are identified and these resources are thenmapped to the corresponding Tivoli Access Manager protected object name. Aprotected object name represents an electronic entity such as a secure part of aWeb site or an application that only certain users are permitted to access.

5. Whether the request or response requires modification is determined.

6. Responses required by the plug-in or the host Web server are generated byadding cookies or headers to the request or response, or by generating aresponse (for example, an authenticated response or an unauthorized response).

Support for virtual hosts

Virtual hosting capability of a Web server allows it to appear as more than onehost to the Internet. The Web servers supported by Tivoli Access Manager Plug-infor Web Servers all provide virtual hosting capability.

Tivoli Access Manager Plug-in for Web Servers provides the capability toimplement security policy on a per virtual-host-basis. The application setuprequired to implement this ability is covered later in this document.

Figure 1. Plug-in and Tivoli Access Manager component interaction.

2 IBM Tivoli Access Manager for e-business: Plug-in for Web Servers Integration Guide



Protecting your Web space with Tivoli Access Manager Plug-in for

Web Servers

Tivoli Access Manager Plug-in for Web Servers provides the following features:

v Supports multiple authentication methods, including basic authentication, IPaddress, token, certificates, and forms, among others.

v Accepts HTTP and HTTPS requests.v Protects Web server resources by authenticating and authorizing user requests

that are dependant on organizational policy.

v Supports the authentication and authorization of requests in a virtual hostenvironment.

v Manages access control to the Web server space. Supported resources includeURLs, URL-based regular expressions, CGI programs, HTML files, Java servlets,and Java class files.

v Caches session and credential information to eliminate repetitive queries to theuser registry database during authorization checks.

v Provides single sign-on capabilities

A corporate security policy identifies the Web resources requiring protection andthe level of protection required for each of those Web resources. Tivoli AccessManager uses a virtual representation of these Web resources, called the protectedobject space. The protected object space contains objects that represent actualphysical resources in your network. You implement security policy by applying theappropriate security mechanisms to the 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 for each user type.

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

Authorization rules are conditions contained in an authorization policy that areused to make access decisions based on attributes such as user, application, andenvironment context.

v Extended attributes

Extended attributes are additional values placed on an object, ACL, or POP thatcan influence an authorization decision.

It is the Authorization Server component of Tivoli Access Manager Plug-in for Web

Servers that permits or denies access to protected resources based on the user’scredentials and the access controls placed on the objects. To successfully implementsecurity policy, you must logically organize the different content types and applythe appropriate ACL and POP policies. Access control management can be complexand is made easier by careful categorization of the content types. Comprehensiveinformation on Tivoli Access Manager including details of setting policy can befound in the IBM Tivoli Access Manager Base Administrator’s Guide.

Chapter 1. Introducing IBM Tivoli Access Manager Plug-in for Web Servers 3



Tivoli Access Manager Plug-in for Web Servers authentication

Authentication is the method of identifying an individual process or entityattempting to log on to a secure domain. Authorization is the method of determining whether an authenticated user has the right to perform an operationon a specific resource. Authentication ensures that the individual is who they claimto be, but says nothing about the ability to perform operations on a resource.

Tivoli Access Manager Plug-in for Web Servers enforces a high degree of securityin a secure domain by requiring each client to provide proof of identity.Comprehensive network security can be provided by having Tivoli AccessManager Plug-in for Web Servers control the authentication and authorization of clients.

The following conditions apply to Tivoli Access Manager Plug-in for Web Serversauthentication:

v The plug-in supports a standard set of authentication methods. You cancustomize the plug-in to support other authentication methods.

v The plug-in process is independent of the authentication method.

v The plug-in requires only a client identity. From this identity, the plug-in obtainsan authenticated (or unauthenticated) credential that can be used by theAuthorization Server to permit or deny access to resources.

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

The Tivoli Access Manager Plug-in for Web Servers authentication process resultsin the following actions:

1. Client authentication results in a client identity.

Client authentication is only successful if the user has an account defined in theTivoli Access Manager user registry. Otherwise the user is designated as

unauthenticated.2. Tivoli Access Manager Plug-in for Web Servers uses the client identity to

acquire credentials for that client.

The plug-in matches the authenticated client identity with a registered TivoliAccess Manager user. The plug-in then obtains the appropriate user credentials.This is known as credentials acquisition.

Credentials include the user name and any groups where the user hasmembership. These credentials are available to the plug-in which permits ordenies access to requested objects in the Tivoli Access Manager protected objectspace.

Credentials can be used by any Tivoli Access Manager service that requiresinformation about the client. Credentials allow Tivoli Access Manager to

securely perform a multitude of services such as authorization, auditing, anddelegation.

See Chapter 3, “IBM Tivoli Access Manager Plug-in for Web Serversauthentication and request processing,” on page 39 for further informationabout support for specific authentication methods.




Credential acquisition

The primary goal of the authentication process is to acquire credential informationdescribing the client user. The user credential is a key requirement for participatingin the secure domain.

Tivoli Access Manager distinguishes the authentication of the user from the

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

The authentication process results in method-specific user identity information.This information is checked against user account information that resides in theTivoli Access Manager user registry (LDAP by default). Tivoli Access ManagerPlug-in for Web Servers maps the user name and group information to a commondomain-wide representation and format known as the Extended Privilege AttributeCertificate (EPAC).

Method-specific identity information, such as passwords, tokens, and certificates,represent physical identity properties of the user. This information can be used toestablish a secure session with the server.

The resulting credential, which represents a user’s privileges in the secure domain,describes the user in a specific context and is valid only for the lifetime of thatsession.

Tivoli Access Manager credentials contain the user identity and groups where thisuser has membership.

Credentials are used by any Tivoli Access Manager service that requiresinformation about the client. For example, the Tivoli Access Manager Authorization

Server uses credentials to determine whether a user is authorized to performspecific operations on a protected resource in the secure domain. Credentials arealso used in other tasks such as logging and auditing.

EPACs contain the Unique Universal Identifiers (UUIDs) that Tivoli AccessManager needs to work with access control lists (ACLs).

The following EPAC fields are appropriate to Tivoli Access Manager:

Table 1. Tivoli Access Manager EPAC fields

Attribute Description

Secure Domain ID Principal’s home secure domain identifier

Principal UUID UUID of the principal

Group UUIDs UUID(s) of groups to which the principal belongs

Tivoli Access Manager Plug-in for Web Servers can be configured to refreshcredential information for a user while keeping their session current. This is usefulfunctionality in cases when a user requires extra access to certain secureapplications or when you want to restrict a user’s access without having the userlogout of their current session. For more information on configuring the plug-in forcredential refresh see “Credential refresh” on page 33.

Chapter 1. Introducing IBM Tivoli Access Manager Plug-in for Web Servers 5



Chapter 2. IBM Tivoli Access Manager Plug-in for WebServers configuration

This chapter describes general administration and configuration tasks you canperform to customize IBM Tivoli Access Manager (Tivoli Access Manager) Plug-infor Web Servers.

Topics in this chapter include:

v “General plug-in information”

v “Configuring the Authorization Server” on page 11

v “Configuring for virtual host servers” on page 13

v “Web-server-specific configuration” on page 15

v “Customizing object listings” on page 18

v “Configuring switch user (SU) for administrators” on page 19

v

“Configuring fail-over for LDAP servers” on page 24v “Supporting Platform for Privacy Preferences (P3P) headers” on page 25

v “Configuring plug-in auditing, logging, tracing, and the cache database” on page28

v “Configuring the authorization API service” on page 33

v “Credential refresh” on page 33

v “Configuring HTTP request caching” on page 34

v “Language support and character sets” on page 35

General plug-in information

The following sections describe general information about Tivoli Access ManagerPlug-in for Web Servers configuration:

v “Root directory of the Tivoli Access Manager Plug-in for Web Serversinstallation”

v “The pdwebpi.conf configuration file” on page 8

v “The pdwebpimgr.conf configuration file” on page 9

v “Starting and stopping Tivoli Access Manager Plug-in for Web Servers” on page9

v “HTTP error messages” on page 9

v “Macro support” on page 10

v “Forms related macros” on page 10

Root directory of the Tivoli Access Manager Plug-in for WebServers installation

The Tivoli Access Manager Plug-in for Web Server’s program files are installed inthe following root directory:

UNIX:

/opt/pdwebpi/

Windows:

C:\Program Files\Tivoli\PDWebPI\




You can configure this path during a Windows installation of the plug-in. Youcannot configure this path on UNIX installations. This guide uses the install_pathvariable to represent this root directory.

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

/var/pdwebpi/

Log files are written to the common Tivoli Directory if this was selected during theconfiguration of the Tivoli Access Manager runtime.

The pdwebpi.conf configuration fileYou can customize the operation of the plug-in by configuring the parameterslocated in the pdwebpi.conf configuration file. The file is located in the followingdirectory:

UNIX:

install_path/etc/

Windows:

install_path\etc\

The following table categorizes the configuration file’s stanzas.

Table 2. pdwebpi.conf section summary

Sections Stanzas

GENERAL [module-mgr] [modules] [wpiconfig] [pdweb-plugins][performance]

AUTHENTICATION [common-modules] [authentication-levels][authentication-mechanisms] [user-agent] [acctmgmt][BA] [failover] [failover-add-attributes][failover-restore-attributes] [forms] [login-form-1] [ltpa]

[tag-value] [token-card] [http-hdr] [iv-headers][login-redirect] [ntlm] [spnego] [boolean-rules][switch-user] [dynurl] [cred-refresh] [ext-auth-int][auth-data] [http-method-perms] [web-server-authn]

SINGLE SIGNON [fsso] [ecsso] [ecsso-domain-keys] [ecsso-token-attributes] [ecsso-incoming-attributes] [cdsso][cdsso-domain-keys] [cdsso-token-attributes][cdsso-incoming-attributes]

VIRTUAL HOSTS [virtual-host-name]

SESSIONS [sessions] [session-cookie]

LDAP [ldap]

LOGGING [web-log]

AUTHORIZATION SERVER [proxy-if] [proxy]

P3P [p3p-header]

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

WEB SERVER [ihs] [iis] [iplanet] [apache]

See Appendix B, “pdwebpi.conf reference,” on page 175 for a description of theconfigurable parameters within the pdwebpi.conf configuration file.




Note: Anytime you make a change to the pdwebpi.conf file, you must manuallyrestart Tivoli Access Manager Plug-in for Web Servers so that the newchanges are recognized. See “Starting and stopping Tivoli Access ManagerPlug-in for Web Servers” for information on starting and stopping theapplication.

The pdwebpimgr.conf configuration fileUNIX installations of the plug-in include the configuration file pdwebpimgr.conf.This configuration file contains parameters that are used to automatically re-startthe authorization daemon if it has failed.

The file is located in the directory:

install_path/etc/

There is no reason why you should need to change the parameters in this file.

Starting and stopping Tivoli Access Manager Plug-in for WebServers

To start and stop the plug-in process, use the pdwebpi_start command on UNIXand use the Services Control Panel on Windows.

UNIX:

pdwebpi_start {start|stop|restart|status}

For example, to stop the plug-in and then restart it, use:

# pdwebpi_start restart

The pdwebpi_start command is located in the following directory:

install_path/sbin/

Windows:Identify the plug-in process in the Services Control Panel and use the appropriatecontrol buttons.

Note: pdwebpi is the authorization server process. On UNIX installations, theprocess pdwebpimgrd automatically restarts the authorization server if itfails. On Windows, the authorization server is automatically restarted byWindows services.

HTTP error messagesSometimes Tivoli Access Manager Plug-in for Web Servers attempts to service arequest and fails. There can be many causes for this failure. Two common causes of failure are:

v A file does not exist

v Permission settings forbid access

When a failure to service a request occurs, the plug-in returns an error code to theWeb server, which interprets the error code and displays a corresponding errorpage.

Customizing the display of IIS error messagesIIS provides the ability to customize the format and content of error pagesdisplayed to clients. This is useful for displaying more detailed error informationto clients. The plug-in can utilize this error customization facility within IIS.

Chapter 2. IBM Tivoli Access Manager Plug-in for Web Servers configuration 9



Using the use-error-pages parameter within the [iis] stanza of the pdwebpi.confconfiguration file you can choose whether IIS configured error pages or thestandard error code pages are returned to the client browser. Set to yes, theuse-error-pages parameter causes the plug-in to utilize any customized IIS errorpages. Set to no, standard error pages are displayed for errors encountered by theAuthorization Server. By default the use-error-pages parameter is set to no.

Note: Setting use-error-pages to yes, thus allowing the display of customized IISerror pages for Authorization Server errors, results in a significantdegradation in plug-in performance.

Macro supportThe following macros are available for use in customizing HTML error pages.Macros dynamically substitute appropriate information that is available.

Table 3. Supported Macro Substitutions

Macro Description

%USERNAME% The name of the logged-in user

%ERROR_CODE% A numeric error code associated with an error

%ERROR_TEXT% Error text associated with an error

%URL% The URL requested by the client

%HOSTNAME% Fully qualified hostname

%HTTP_BASE% Base HTTP URL of the server:http://host:tcpport/

%HTTPS_BASE% Base HTTPS URL of the server:https://host:sslport/

%HTTP_BODY% The body of the request, if one exists.

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

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

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

%POST_URL% The configured POST URL for any of the Tivoli AccessManager supplied forms.

%COOKIES% Any cookies that are found in the request.

Forms related macrosTivoli Access Manager Plug-in for Web Servers provides the following forms,located in the /opt/pdwebpi/nls/html/lang/charset directory:

v switchuser,

v token,

v forms login,

v change password.

These forms have been configured with the %POST_URL% macro. The%POST_URL% macro allows the plug-in to resend any POST data which might




have been included in the original request. Without the %HTTP_BODY% macroany POST data provided with the original request is lost once the plug-in hasfinished processing the form.

The default forms have also been configured to cache any necessary session datawithin the form itself. This session data includes, the originally requested URL, thereferer for the originally requested URL and the body of the original request.

Configuring the Authorization Server

The majority of authorization and authentication processing is handled by theAuthorization Server. The Authorization Server provides a pool of worker threadsthat:

v Accept requests from the plug-in,

v Send results of each request back to the plug-in.

The plug-in communicates with the Authorization Server through an IPCmechanism implemented using shared memory. The [proxy-if] stanza in thepdwebpi.conf configuration file specifies configuration parameters that pertain to

communication between the plug-in and the Authorization Server.

Configuring Worker ThreadsThe number-of-workers and the worker-size parameters in the [proxy-if] stanza of the configuration file, specify values that can be tuned to provide optimal plug–inAuthorization Server performance. Consider the quantity and type of traffic onyour network when setting these values.

[proxy-if]number-of-workers = 10worker-size = 10000cleanup-interval=300

The number-of-workers parameter specifies the number of concurrent incoming

requests that can be serviced by the plug-in. Requests that arrive when all workerthreads are busy are buffered until a worker thread becomes available. Thisparameter simply specifies the number of threads made available to service apotentially unlimited work queue. The parameter should be increased according tothe maximum number of requests you expect the Web server to acceptsimultaneously. On UNIX platforms the operating system may impose limits onthis value.

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

The worker-size parameter defines the amount of memory (in bytes) that ispre-allocated for each worker thread.

The cleanup-interval is the time in minutes between successive clean-ups of theAuthorization Server’s shared memory.

Note: Change the cleanup-interval and worker-size parameters only totroubleshoot performance problems.




Setting the Maximum Session Lifetime for IPC requestsThe max-session-lifetime parameter in the [proxy-if] stanza of the pdwebpi.confconfiguration file sets the time in seconds that the plug-in will wait for a responsefrom the Authorization Server before timing out. This parameter relates only to theshort-lived ″session″ that is established between the plug-in and the AuthorizationServer for request handling. If such a timeout occurs, an error page is sent to the

client. Such timeouts are highly unlikely.[proxy-if]max-session-lifetime = 300

Note: The max-session-lifetime parameter does not control the lifetime of authenticated sessions. Authenticated session lifetime is controlled by thetimeout parameter in the [sessions] stanza.

Configuring error pagesLocated in the [proxy] stanza of the pdwebpi.conf configuration file are parametersfor specifying the HTML pages to be displayed when errors occur in the proxy.The parameters set within the [proxy] stanza are: error-page, acct-locked-page,retry-limit-reached-page and login-success. Default files exist for these parameters.

The files can be be edited or a new file can be specified to suit your organization’srequirements. The following table summarizes the parameters.

Table 4. [proxy] error page configuration parameters.

Parameter Description

error-page The path to the page displayed on the users browserwhen an unexpected server error occurs.

acct-locked-page The path to the page displayed when a user attemptsto access a locked account.

retry-limit-reached-page The path to the page displayed when the allowedmaximum number of failed logon attempts has beenreached. The maximum number of allowed logon

failures is set in LDAP - refer to, “Three strikes logonpolicy” on page 112 for details on setting this value.

login-success Specifies the page to be displayed when the plug-indoes not have a page to redirect the user back to aftera successful forms or token login. This situation canoccur when you build a login form that sends thelogin POST data back to the plug-in directly.

By default, the sample HTML pages are located in the following directory:install_path/nls/html/lang/charset.

Where:

v lang is taken from the NLS configuration. In a U.S. English installation, lang will be set to C.

v charset is the character set in which the page is encoded. The default is utf-8.

For details on plug-in language support refer to “Language support and charactersets” on page 35.




Configuring for virtual host servers

Virtual hosts are identified to Tivoli Access Manager Plug-in for Web Servers by anarbitrary name that is set in the [pdweb-plugins] stanza of the pdwebpi.confconfiguration file.

The plug-in can apply distinct security policy according to two characteristics of a

request:v an ID for the virtual host to which the request was addressed,

v the protocol (http or https) over which the request arrived.

The virtual host ID is derived from the host Web server’s configurationinformation and is Web-server specific. It is determined as follows:

IHS and Apache The configuration algorithm used to construct virtual host IDs is asfollows:

1. If a ServerName directive exists inside a <VirtualHost {hosta}:{port}{hostb}:{port}...> block, that name is used for constructing the objectspace for every host in the virtual host list. No attempt is made toresolve the supplied servername into a fully qualified hostname.

2. If there is no ServerName directive inside the VirtualHost block andthe host names in the list are not numeric IP addresses, an attempt ismade to fully qualify each name and then create object spaces foreach distinct host name.

3. If there is no ServerName directive inside the VirtualHost block andthe host names in the list are numeric IP addresses, an attempt ismade to resolve each IP address to a fully qualified hostname.

4. If there is still no host name and there is a name specified in a globalServerName directive, that name is used (without resolving).

5. If there is no global ServerName directive, the fully qualified versionof the system’s hostname is used.

IIS 5.0 and 6.0 The ID corresponds exactly to the Web site name as shown in the Internet

Information Services management snap-in. For example, the default Website created when IIS is configured is named ″Default Web Site″, this isthe ID used by Tivoli Access Manager Plug-in for Web Servers.

Sun ONE WebServer (formerlyiPlanet)

The ID corresponds exactly to the virtual host name specified whencreating the virtual host in the Sun ONE Web Server configuration GUI.This name is stored in the <VS id= > element of the server.xml file.

Tivoli Access Manager Plug-in for Web Servers defines security policy in terms of virtual hosts. A Tivoli Access Manager Plug-in for Web Servers virtual host isidentified by a virtual host ID as defined above and the set of protocols (http, httpsor both) that it should protect. The virtual host defines the set and precedence of authentication schemes, session identification schemes and post-authorizationhandling that should be applied to requests to the Web server virtual host over one

of the matching protocols. The virtual host also defines the mapping of URIs toTivoli Access Manager Protected Object Space names.

Tivoli Access Manager Plug-in for Web Servers virtual hosts are defined in the[pdweb-plugins] stanza of the configuration file. They may be defined as eitherprotected or unprotected. An unprotected virtual host will have no Tivoli AccessManager security policy applied to it. If a request is received that does not matchone of the defined protected or unprotected virtual hosts then a warning messageis generated in the Authorization Server’s log file indicating the virtual host ID andthe protocol of the request and the request is granted access. This facilitatesdiagnosis of configuration problems.




Protected virtual hosts are defined by the virtual-host parameter of the[pdweb-plugins] stanza. Unprotected virtual hosts are defined by theunprotected-virtual-host parameter of the [pdweb-plugins] stanza. The virtualhost name used, typically corresponds to the virtual host ID that this virtual hostmatches but this is not necessarily always the case. It is the virtual host namesdefined in the [pdweb-plugins] stanza that are used to define virtual host-specificsecurity policy.

The security policy for a particular virtual host is defined by the configurationparameters specified in a stanza with the name of the virtual host. All of theparameters that may be defined in the virtual host stanza have appropriate defaultvalues so it is not necessary to have a stanza for each virtual host. It is necessary tohave such a stanza only if the security policy for the virtual host differs from thedefault.

Two parameters of the virtual host are used to match an incoming request to thevirtual host that defines the security policy that should be applied to the request.These parameters are id and protocols.

The id parameter is defined to be the virtual host ID that this virtual host will

match. The default value for the id parameter is the virtual host name itself.

The protocols parameter defines the set of protocols that the virtual host willmatch. This value may be http, https or both. The default value is both.

The remaining parameters of the virtual host define the security policy that should be applied to requests matching this virtual host.

Virtual hosts are associated with a particular sub-branch of the protected objectspace. A request’s URI is prefixed with this sub-branch to construct a protectedobject space name. This protected object space name is used for makingauthorization decisions. The branch configuration parameter defines the name of

this protected object space.[virtual_host_name]branch = virtual_host_id

If the virtual host ID value has no leading backslash (/), the entry is prefixed with/PDWebPI/.

The branch parameter defaults to the value of the id parameter resulting in adefault object name prefix of /PDWebPI/virtual-host-id.

Virtual host branches explainedDuring plug-in configuration an objectspace is created called /PDWebPI. Withinthis objectspace, entries are created for each of the virtual hosts protected by the

plug-in. The objectspace under a virtual host object is owned by the plug-inAuthorization Server that performs authorization decisions for resources in thevirtual host object space. By default, the branch of the objectspace used for avirtual host takes its name from the virtual host ID. If a different branch of the/PDWebPI objectspace is to be used then the branch extension is used to specifythis. Branches may be shared between virtual hosts. This may happen when virtualhosts are aliases of each other.

Note: When a branch is changed, an object needs to be created with the newname. Any ACLs attached under the old branch stay attached to the nownon-existent objects.




Following is an example showing the configuration parameters required for a Webserver that has four virtual hosts:

v ibm.com,

v lotus.com-HTTP,

v lotus.com-HTTPS,

v domino.com.

The virtual hosts lotus.com-HTTP and lotus.com-HTTPS are really the same virtualhost as they share the same branch; however they are distinguished by the type of access (HTTP or HTTPS). In this case, authentication configuration can be setdifferently depending on the type of access. domino.com is not protected by theplug-in and ibm.com is another virtual host on the same server.

[pdweb-plugins]virtual-host = ibm.comvirtual-host = lotus.com-HTTPSvirtual-host = lotus.com-HTTPunprotected-virtual-host = domino.com

web-server = iplanet

[lotus.com-HTTPS]id = lotus.comprotocols = httpsbranch = lotus.com

[lotus.com-HTTP]id = lotus.comprotocols = httpbranch = lotus.com

[ibm.com]id = ibm.comprotocols = http, httpsbranch = ibm.com

Be sure to restart the Web Server each time you make a change to theconfiguration for virtual hosts in the pdwebpi.conf configuration file.

Further configuration on a per virtual host basis is necessary to set theauthentication parameters for each individual virtual host. Refer to “Configuringauthentication for virtual hosts” on page 42 for details on configuringauthentication methods for virtual hosts.

Web-server-specific configuration

Some of the plug-in’s actions are specific to the Web server and therefore requireparticular configuration, depending on the Web server type on which the plug-in isoperating. Use the web-server parameter in the [pdweb-plugins] stanza of the

pdwebpi.conf configuration file to define your Web server type. Valid values areihs, iplanet, iis or apache. For example:

[pdweb-plugins]web-server = ihs

Web-server-specific configuration items exist in the [iis], [ihs], [apache] and[iplanet] stanzas of the pdwebpi.conf configuration file.




Some Web server configuration parameters can be set on a per branch basis byappending the full virtual host branch to the stanza. For example,[iplanet:/PDWebPI/lotus.com] . Parameters related to browsing the Web space can

be configured this way.

The following table explains the configurable parameters for specific Web servertypes.

Table 5. Web-server-specific configuration parameters


[ihs]

query-contents Specifies the query contents program to use for browsing the IBM HTTP Server Web space by the’pdadmin> object list’ command. This parametercan be overridden on a per branch basis byspecifying a value for it in a stanza named[ihs:branch] for example [ihs:/PDWebPI/lotus.com]

query-log-file Location of log file for errors encountered by thequery contents program.

doc-root Specifies the documentation root that provides theWeb space browse capability needed forperforming ’pdadmin> object list’ commands. Thisparameter is set by the configuration utility whensetting up virtual hosts - it is specified on aper-policy branch basis in an [ihs:branch] stanza,for example [ihs:/PDWebPI/lotus.com]

[apache]

query-contents Specifies the query contents program to use for browsing the Apache Web space by the ’pdadmin>object list’ command. This parameter can beoverridden on a per branch basis by specifying avalue for it in a stanza named [apache:branch] for

example [apache:/PDWebPI/lotus.com]


doc-root Specifies the documentation root that provides theWeb space browse capability needed forperforming ’pdadmin> object list’ commands. Thisparameter is set by the configuration utility whensetting up virtual hosts - it is specified on aper-policy branch basis in an [apache:branch]stanza, for example [apache:/PDWebPI/lotus.com]

[iis]

query-contents Specifies the query contents program for browsing

the IIS Web space by pdadmin. This parameter can be overridden on a per branch basis by specifyinga value for it in a stanza named[iis:branch], forexample, [iis:/PDWebPI/lotus.com]





Table 5. Web-server-specific configuration parameters (continued)


log-file Defines the log file for error and trace messagesfrom the IIS plug-in, that are kept separate fromthe Authorization Server’s log file in order toensure consistency of the files. If specified as arelative path, the location is relative to the logsub-directory of the installation directory. If specified as an absolute path, the absolute path isused.

[iplanet]

query-contents Specifies the query contents program for browsingthe Sun ONE (iPlanet) Web space by pdadmin.This parameter can be overridden on a per branch basis by specifying a value for it in a stanzanamed [iplanet:branch], for example,[iplanet:/PDWebPI/lotus.com]


doc-root Specifies the documentation root that provides theWeb space browse capability needed forperforming ’pdadmin> object list’ commands. Thisparameter is set by the configuration utility whensetting up virtual hosts - it is specified on aper-policy branch basis in an [iplanet:branch]stanza, for example, [iplanet:/PDWebPI/lotus.com]

In the example below, the virtual hosts ibm.com and lotus.com both have acorresponding stanza in the configuration file: [iplanet:/PDWebPI/ibm.com] and[iplanet:/PDWebPI/lotus.com] where specific configuration parameters aredefined.

[pdweb-plugins]virtual-host = ibm.comvirtual-host = lotus.comweb-server = iplanet

[iplanet]query-contents = /opt/pdweb/bin/wpi_iplanet_ls

[iplanet:/PDWebPI/ibm.com]doc-root = /usr/local/ibm.com/doc/root

[iplanet:/PDWebPI/lotus.com]doc-root = /usr/local/lotus.com/doc/root

Web server considerationsIISWhen configuring IIS security settings using the Directory Security tab in the Webserver Properties dialog, it is important to remember that some of the configurablesecurity settings are inheritable through the Web space hierarchy.

The plug-in dynamically creates ″virtual″ Web space objects to handle variousfunctions. The security settings on these objects are often important. It is essentialthat the security properties on these objects are not changed.




After IIS security settings have been modified within the Directory Security tab of the Properties dialog, the Inheritance Overrides dialog is displayed. The InheritanceOverrides dialog lists Child Nodes that override the value you have just set. Youhave the option to choose which nodes should use the new value. PDWebPI nodesmust not be selected in this dialog.

Apache and IHS

Disabling Multiviews: When using Apache or IHS Web servers the MultiViewsdirective on the root directory should be disabled. Having the MultiViews directiveenabled bypasses the authentication checking by Tivoli Access Manager Plug-in forWeb Servers thereby compromising Web server security.

The Multiviews directive is enabled on the document root directory by default inApache.

Configuration for PHP scripts: Tivoli Access Manager Plug-in for Web Serversonly works correctly when PHP scripts are handled internally to the Web server,using PHP support configured as a module implementation.

Customizing object listingsTivoli Access Manager Plug-in for Web Servers supplies a binary file for eachsupported Web server used to determine the output for a pdadmin administrationobject list or an object show command. The following table indicates the standard

binary names, and their locations:

v iPlanet — install_path/bin/wpi_apache_ls

v IHS — install_path/bin/wpi_ihs_ls

v IIS — install_path/bin/wpi_iis_ls

If you require object browsing capabilities that are not part of the standardfunctionality you will need to develop your own customized binary to replace thatsupplied with the plug-in.

When developing a customized binary the following guidelines apply:

Command Line ArgumentsiPlanet,IHS,Apache

directory virtual_host log_file [-d]

Where:

directory The absolute path to the directory or file to list or show.

virtual_host The virtual host for the directory or file.

log_file The absolute path to a file which will contain any error informationproduced by the action.

-d When the -d option is specified an object show is executed insteadof an object list.

IIS

[-log log_file] -path directory -vhost virtual_host [-d]




Where:

log_file The absolute path to a file which will contain any error informationproduced by the action.

directory The absolute path to the directory or file to list or show.

virtual_host The virtual host for the directory or file.

-d When the -d option is specified an object show is executed insteadof an object list.

OutputFor each entry listed the format of the output will be:

<Object Type=[type] Description=[description] Attachable=[yes/no]> [name] </Object>

Where:

type A number which indicates the object type. Current values include:

v 0 Unknown

v 1 Domain

v 2 File

v 3 Program

v 4 Directory

v 5 Junction

v 9 HTTP Server

v 10 Non-existent object

v 11 Container

v 12 Leaf

v 14 Application Container

v 15 Application Leaf

description A textual description of the object.attachable Whether policy can be attached to the object.

name The object name for the object. This object name should not contain anyleading directory names.

For example:

<Object Type=2 Description="File" Attachable="yes"> apache.gif </Object>

Configuring switch user (SU) for administrators

The Plug-in for Web Servers switch user functionality allows specific

administrators to assume the identity of a user who is a member of the TivoliAccess Manager secure domain. The switch user implementation is similar to thesu command in UNIX environments. In the plug-in environment, the administratoracquires the user’s true credentials and interacts with resources and back-endapplications with the exact same abilities as the actual user.

Switch user is a useful Help Desk tool for troubleshooting and diagnosingproblems. 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. Anadministrator cannot switch user to any other member of this group.

v Tivoli Access Manager processes, sec_master, and other selected users can beexcluded from the switch user capabilities through membership in an exclusion

group.v 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. The process begins with an authenticated administrator who is a member of thesu-admins group.

2. The administrator connects to a pre-configured switch user HTML form. This

form is accessible only to members of the su-admins group. If the user is not amember of the su-admins group, a ″Not Found″ page is returned.

3. The switch user form is completed and returned with the followinginformation: user name (administrator is ″switched to″ this user), a destinationURL, and an authentication method. This action results in a POST request

being sent to /pkmssu.form.

4. Two checks are done before the switch is authorized.

a. The plug-in checks if the ″switched to″ user is a member of the su-adminsgroup. A user cannot ″ become″ another user who is a member of thesu-admins group.

b. The plug-in checks if the ″switched to″ user is a member of the su-excludedgroup. No users are allowed to ″ become″ a member of the su-excluded

group. An error is returned if either of these two checks fail. All subsequentrequests are made as though they were made by the ″switched to″ user.

5. The administrator remains as the ″switched to″ user until the standard TivoliAccess Manager /pkmslogout utility is called at which time the ″switched to″user is logged out and the administrator returns to their original session.

Enabling switch userThe [common-modules] stanza in the pdwebpi.conf configuration file defines theuse of all authentication methods. To enable switch user functionality, theswitch-user module needs to be configured as a pre-authorization module. Thisallows the switch user function to access a user before authorization is performed.

[common-modules]

...pre-authzn = switch-user

...

Note: If the acctmgmt module is configured as a pre-authorization module alongwith the switch-user module then the switch-user module must appear inthe list before the acctmgmt module.

Ensure that the entry for switch user exists in the [modules] stanza of thepdwebpi.conf configuration file. For example:




[modules]...switch-user = pdwpi-su-module...

Configuring the switch user HTML formThe switch user form is defined in the [switch-user] stanza of the pdwebpi.conf

configuration file.v The switch-user-form parameter specifies the name of the file. By default the file

name is switchuser.html and is located in the directoryinstall_path/nls/html/lang/charset. On US English systems, the lang directoryis called C and charset is utf-8.

[switch-user]switch-user-form = switchuser.html

v The switch-user-uri parameter contains the URI which is used to invoke theswitch user function. Note that the standard authorization policy is not appliedto this URI. Group-based authorization checking is conducted instead of ACLchecking.

[switch-user]

switch-user-uri = /switchuser.htmlv The switch-user-post-uri parameter specifies the URI which the switch user

form is submitted to:

[switch-user]switch-user-post-uri = /pkmssu.form

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, securitygroup, or su-admins.

v Destination URL

This page is displayed after a successful switch user operation. You can

configure this as hidden input containing an appropriate home page or asuccessful switch user 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 notes

below for a list of the valid authentication method parameters.

v The macro, %CUSTOM%, is included in the default form and can be used toautomatically include in the form all configured switch-user authenticationmechanisms.

Switch user form notes:

v The form is only available to members of the su-admins group. An ACL is notrequired on this file. The plug-in performs an internally hard-coded groupmembership check. The plug-in 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 The plug-in verifies that all required data is present in the submitted form. If data is missing, the form is returned to the administrator with a descriptivemessage.

v Valid values for the authentication method include:




su-passwordsu-token-cardsu-certificatesu-http-requestsu-cdsso

These authentication method parameters specify which authenticationmechanism the plug-in is to use.

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 Tivoli Access Manager account, except those belonging to certain groups. You can exclude other Tivoli Access Manager usersfrom switch user through membership in the su-excluded group. In addition,members of the Tivoli Access Manager securitygroup group are excluded fromswitch user functionality. Typically, sec_master and the Tivoli Access Manager

processes are members of securitygroup.

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

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 pdwebpi.conf configuration file. Thefollowing authentication 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

Tivoli Access Manager supplies a single switch user library that can be used toenable any of the above authentication mechanisms in a default, non-customized

environment. 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 Tivoli Access Manager iscalled:

UNIX libsuauthn

Windowssuauthn




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 the behavior of your existing CDAS while supporting the requirement of returning acredential without requiring the user password for input.

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

Example:

In the following example (for a Solaris platform), an existing environment hasthree authentication methods enabled:

1. Forms authentication using the built-in libldapauthn library

2. Certificates authentication using the built-in libsslauthn library

3. Token authentication using a custom CDAS mechanism

The environment is now expanded to support switch user functionality for any of those three authentication methods. Three additional authentication parameters forswitch user must be enabled in the pdwebpi.conf configuration file. In addition, anew 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

Impacting other plug-in functionality

Impact on session cache timeout configurationThe functionality of the configured plug-in session cache inactivity and lifetimetimeout values are not affected by the switch user operation. The inactivity andlifetime timers are associated with the administrator’s session cache entry and notthe session data that changes during a switch user operation.

The session inactivity timer continues to be reset while the administrator performsrequests as the ″switched-to″ user. When the administrator ends the switch usersession, the inactivity is still valid for the re-established administrator session.

The session lifetime value is not extended by a switch user operation. It is possible

for the lifetime timeout of the administrator session to expire during a switch useroperation. If this timeout occurs, the sessions are deleted, logging off both theadministrator and the ’switched-to’ user. The administrator must reauthenticateand begin the switch user operation 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 Tivoli Access Manager, the administrator must know theuser’s password to successfully perform step-up authentication.

Support for reauthenticationThe plug-in reauthentication functionality is recognized by the switch useroperation. If reauthentication is required during a switch user operation, theadministrator must authenticate as the ″switched-to″ user.

Note: For this version of Tivoli 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 usersession task and the terminate all user sessions tasks operate as in the following:

v

the″

switched-to″

user session is terminated when the″

switched-to″

session IDor user session ID is specified.

v both the administrator session and the ″switched to″ user session are terminatedwhen the administrator session ID or the user session ID are specified.

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, as stored in the credential, is

called tag_value_prefix_su-admin:tag_value_prefix_su-admin = su-admin-name

Where tag_value_prefix_ represents the tag_value_prefix parameter valueconfigured in the [pdwebpi-plugins] stanza of the plug-in configuration file. Thisextended attribute is available to any auditing mechanism.

Configuring fail-over for LDAP servers

Tivoli Access Manager plug-in for Web servers connects to any available LDAPserver—master or replica depending on priority—when it starts up. If the LDAPmaster server is down for any reason, the plug-in must be able to connect to anavailable LDAP replica server for any read operations. This is the standard Tivoli

Access Manager LDAP replica configuration. For further details refer to the IBMTivoli Access Manager Base Administrator’s Guide.

IBM Directory (LDAP) supports the existence of one or more read-only replicaLDAP servers. Sun ONE (formerly iPlanet) Directory Server (LDAP) supports theexistence of one or more read-only replica LDAP servers referred to as″consumers″. You must add lines to the [ldap] stanza of the pdwebpi.confconfiguration file to identify any replica servers available to the plug-in. Use thefollowing syntax for each replica:

replica =ldap_server, port,type, preference




where:

ldap-server The network name of the LDAP replica server.

port The port this server listens on. Generally, use 389 for unencryptedcommunications or 636 for communicating over SSL.

type The functionality of the replica server - either ″read-only″ or ″read-write″.Normally, use ″read-only″. A ″read-write″ type would represent a master

server.

preference A number from 1 - 10. The server with the highest preference value ischosen for LDAP connections. See ″Setting preference values for replicaLDAP servers″ in the IBM Tivoli Access Manager Base Administrator’sGuide.

Example:

replica =replica1.ldap.tivoli.com,389,readonly,5replica =replica2.ldap.tivoli.com,389,readonly,5

Supporting Platform for Privacy Preferences (P3P) headers

The Platform for Privacy Preferences Project (P3P), is a World Wide WebConsortium standard that provides a way to describe user privacy preferences andWeb server privacy policy information in a uniform way. Using P3P, a user canconfigure privacy preferences that determine what information is divulged to aWeb server and how that information is used. With P3P, a Web server can specifywhat user privacy policy information it gathers and what it will use thisinformation for. A Web server’s privacy policy is made available in amachine-readable format to clients that P3P enabled browsers can ″read″ andcompare with the user’s own privacy preferences. The user is alerted when theWeb server’s privacy policy and the user’s privacy configuration do not match.

A common use for P3P is to enable browsers to make intelligent decisions about

whether to accept cookies received from a Web server. Support for this is enabled by default within Internet Explorer 6.0. If Internet Explorer 6.0 receives a cookiefrom a site that doesn’t send a P3P policy, or sends a policy that does not matchthe user’s privacy preferences, then the browser may decide to automatically blockthe cookie.

The plug-in relies on cookies to maintain session information as well as, forinstance, to retain fail-over information. Internet Explorer, using its default settings

blocks cookies and so will not store plug-in cookies, effectively limiting plug-infunctionality. The plug-in provides P3P configuration options that specify acompact P3P policy statement sent with pages when a plug-in cookie is set. Theplug-in P3P configuration options allows you to create a compact P3P policy thatmatches your organization’s privacy policy. It is then up to the client to decide if

they will allow Tivoli Access Manager cookies to be set.

Note: You should not configure a P3P policy that doesn’t match yourorganization’s privacy policy just to allow Internet Explorer to acceptcookies. Before enabling P3P policies for plug-in cookies, ensure you arefamiliar with the P3P specification and understand exactly what it is you areclaiming as your organization’s privacy policy.




Configuring P3P headersThe plug-in provides configuration parameters that match the definition of thecompact policy syntax of the W3C P3P recommendations. These should beconfigured to allow plug-in cookies while still maintaining the integrity of yourorganization’s privacy policy.

The first step in configuring P3P headers is to set the send-p3p-header parameterin the [pdweb-plugins] in the pdwebpi.conf configuration file. This entry can beset on a per virtual host basis by defining it within a user defined[virtual_host_name] stanza. Set to true the send-p3p-header parameter specifieswhether the plug-in adds a P3P header containing a compact policy statement toany HTTP response in which it has set cookies. The sending of a P3P policy isdisabled by default.

If you have enabled the sending of P3P headers, the parameters in the[p3p-header] or [p3p-header:virtual_host] stanza should then be set. Theseparameters define the compact policy that applies to all HTTP cookies set.

The default settings in this stanza allow session cookies to be stored in an Internet

Explorer 6 browser — even if they appear as third-party cookies.Table 6. [p3p-header] parameters

Parameter Use

p3p-element This parameter can be used to specify a reference to a full XMLpolicy in addition to the compact policy configured using the otherparameters in this stanza.

Uncommenting the line,p3p-element = policyref="/w3c/p3p.xml", directs the browser to

send the specified reference to the full XML policy.Note: An ACL that allows unauthenticated access needs to be seton the /w3c directory to allow access to the policy. This is requiredas Internet Explorer does not send authentication information with

the request that permits the viewing of policy.

access Specifies the access the user has to the information contained withinand linked to by the cookie. Possible values:noneallnonidentcontact-and-otherident-contactother-ident

disputes Specifies whether the full P3P policy contains some informationregarding disputes over the information contained within thecookie. Valid values are true or false. This parameter is set to false bydefault.

remedies Specifies the possible remedies for disputes. Possible values are:correctmoneylaw

If not specified, no remedy information is included in the policy.

non-identifiable When set to true, this parameter specifies that no information in thecookie, or information linked to by the cookie, personally identifiesthe user in any way. Valid values are true or false. This parameter isset to false by default.




Table 6. [p3p-header] parameters (continued)

Parameter Use

purpose Specifies the purpose of the information in the cookie and linked to by the cookie. Possible values are:currentadmindeveloptailoring pseudo-analysis pseudo-decisionindividual-analysisindividual-decisioncontacthistoricaltelemarketingand other-purpose.

For all values except current, an additional specifier may beconfigured. The possible values are:alwaysopt-in

opt-out.

For purposes not specified, the default value is always. This value isspecified after the purpose, separated by a colon, for example:

purpose = contact:opt-in

recipient Specifies the recipients of the information in the cookie, and theinformation linked to by the cookie. Possible values are:oursdeliverysameunrelated publicother-recipient.

retention Specifies how long the information in the cookie or the informationlinked to by the cookie is to be retained.

Possible values are:no-retentionstated-purposelegal-requirementbusiness-practicesindefinitely.




Table 6. [p3p-header] parameters (continued)

Parameter Use

categories Specifies the type of information stored in the cookie or linked to bythe cookie.

If the non-identifiable parameter is set to true, then no categoriesneed be configured. Possible values are:

physicalonlineuniqueid purchase financialcomputernavigationinteractivedemographiccontentstate politicalhealth preference

location governmentother-category

Example P3P configuration:

[pdweb-plugins] or [virtual_host_name]send-p3p-header = true...[p3p-header] or [p3p-header:virtual_host_name]# p3p-element = policyref="/w3c/p3p.xml"access = nonedisputes = falsenon-identifiable = false

purpose = currentpurpose = other-purpose:opt-inrecipient = oursretention = no-retentioncategories = uniqueid

Configuring plug-in auditing, logging, tracing, and the cache database

Logging and auditing can provide you with information that will help inidentifying any problems you might have with the plug-in. If you find you arehaving trouble and need a real-time view of error messages, then start the plug-inin the foreground using the -foreground option:

pdwebpi -foreground

Note: For installations on IIS, restart IIS before starting the plug-in in foregroundmode to release any existing shared memory.

Status and error messages are logged in the file configured in the log-file, logs andlog-entries parameters in the [pdweb-plugins] stanza of the pdwebpi.confconfiguration file.

Plug-in auditing and basic cache database configuration is performed using theparameters in the [aznapi-configuration] stanza of the pdwebpi.conf configurationfile.




Audit recordsThe basic services of the authorization API allow capture of authentication (authn)and authorization (azn) audit events.

The standard ’authn’ audit events do not however encapsulate sufficientinformation about an authentication attempt to allow the correlation of these

events to a specific virtual host, where a plug-in is protecting more than a singlehost. For this reason, the plug-in implements its own audit event category tocapture virtual-host-specific authentication information.

Standard ’azn’ audit events do capture plug-in relevant virtual host information byvirtue of the protected object name being constructed with the/PDWebPI/virtual_host_name prefix.

Plug-in-specific authentication audit events are recorded in virtual-host-specificaudit event pools constructed as follows:

wpi.virtual_host_name.authn.authentication_module_name

Plug-in-specific authentication audit events conform to the DTD definition

described in the IBM Tivoli Access Manager Base Administrator’s Guide.

Elements of the XML style ’wpi’ audit records are described in the table below.

Table 7. Authentication audit record field definitions.

XML Tag Description

<event> Encapsulates tag for the audit record. The element includesan attribute describing the doc type definition revision of therecord.

<date> Record of the date and time the event occurred.

<outcome> The tag element includes a status parameter that identifiesthe Tivoli Access Manager or plug-in error code. The

element describes the broad outcome of the event. Thepossible values are:

v 0 = Success

v 1 = Failure

v 2 = Pending

v 3 = Unknown

<originator> Header tag for the originator section of the audit record. Thetag element includes the blade parameter that identifies theTivoli Access Manager blade responsible for the event.

<component> The tag identifies the component that captured the auditrecord. The component is recorded in the form:wpi.virtual_host_name.type_of_event.module_name




Table 7. Authentication audit record field definitions. (continued)

XML Tag Description

<action> Identifies the authentication method attempted. Action codesand their corresponding authentication mechanisms are:

16961 - BA17236 - Client side certificate17731 - Ecsso17999 - Failover cookie17997 - Forms18504 - Http Header18768 - IP address4806211 - IV header: PAC credential4806229 - IV header:Username4806220 - IV header:Distinguished name300609 - IV header:IP address21579 - Token

<location> Defines the server name that initiated the event.

<accessor> Header tag for the accessor section of the audit record. Tagelement can include the name of the accessor.

<principal> The principal tag includes the parameter auth that identifiesthe authenticating directory service. The tag defines thevalidated user name.

<target> The target tag includes the parameter resource that can beone of the following values:

v 0 = authorization

v 1 = process

v 2 = TCB

v 3 = credential

v 4 = general

Authentication audit records always set this this value to 3 -credential.

<object> Holds audit data that has little meaning for theauthentication process.

<data> Extra authentication failure information. For example, failureduring an authentication attempt using HTTP headerinformation will result in an audit log record recording thefailed HTTP header in this field.

Auditing configurationThe following table displays the auditing configuration parameters and explainstheir function.

Table 8. Auditing configuration parameter definitions


logsize The size (in bytes) at which the log files rollover to a new file.If set to 0 the log files will not rollover. A negative numberwill roll the logs over daily regardless of size.

logflush The interval in seconds at which the logs are flushed.Maximum of 6 hours and a default of 20 seconds.

logaudit Enables or disables auditing.

auditlog Specifies the name of the audit file




Table 8. Auditing configuration parameter definitions (continued)


auditcfg Enables or disables authorization and/or authenticationauditing.

For example:[aznapi-configuration]logsize = 2000000logflush = 20logaudit = noauditlog = audit.logauditcfg = azn#auditcfg = authnauditcfg = wpi

Tracing Plug-in actionsTivoli Access Manager Plug-in for Web Servers provides the ability to trace actionsand store the results on file for the purposes of debugging. Primarily, tracing is ananalysis and problem diagnosis tool used by application support to gain acomplete view of actions causing errors. As a user, you might find some of theplug-in tracing facilities useful though the majority of facilities will be of little

benefit unless you are diagnosing complex problems.

It is possible to trace the HTTP messages at the plug-in. This can be very useful because it shows exactly what is received from the user and what is returned tothe user - even if the communication is over HTTPS. Trace is turned on and off using the standard pdadmin tracing commands.

The inputs to and results of authorization decisions can be traced to facilitatediagnosis of authorization policy configuration problems. This tracing shows usercredential information including names, UUIDs, session ID, and attributes. This

tracing also shows the name of the Tivoli Access Manager protected object beingused to make the decision and the permissions required. The result of the decisionis also shown along with any returned decision attributes.

pdadmin trace commands

Listing trace components: The list command produces a list of all the plug-inactions that can be traced.

Syntax:

pdadmin> server task PDWebPI-server-name trace list [component]

The majority of trace tasks listed are specific to Tivoli Access Manager.

Plug-in-specific trace items are prefixed with pdwebpi.

Setting trace components: There are three main trace items that you might finduseful for debugging:

v pdwebpi.request

v pdwebpi.plugin

v pdwebpi.azn

When pdwebpi.request is set to two, tracing occurs on every request that passesthrough the plug-in. When pdwebpi.request is set to nine, the request header is




included in the trace. pdwebpi.plugin activates trace in the plug-in server. Allmessages are sent to the Web server’s log file or, in the case of IIS, to a logdifferent from that used for the authorization server. pdwebpi.azn set to one traces

brief information about every authorization decision including protected objectname, permission string, user name, session ID, HTTP method, HTTP URI anddecision result. When pdwebpi.azn is set to two, tracing occurs for additionalcredential attribute information and both input and output decision attributes.

When pdwebpi.azn is set to five, included is additional information about step-upand reauthentication processing.

The trace set command has the following syntax:

pdadmin> server task PDWebPI-server-name trace set componentlevel [file path= file|other-log-agent-config]

Where component is the name of the trace component as shown by the listcommand. A trace is set for this component. level is the amount of detail gatheredfor the trace. The range is 1 to 9, with 1 being the least detailed and 9 being themost detailed. The optional file path parameter specifies the location for traceoutput. Trace output by default is sent to the standard configured plug-in log file(except when using the component pdwebpi.plugin). For IIS installations, the

name of the file to which the plug-in component trace is sent to is alwaysconfigured using the log-file parameter under the [iis] stanza in the configurationfile.

Output can be sent to the screen using the -foreground option. That is:

pdwebpi -foreground

Showing trace components: To show trace components use the show commandin the following form:

pdadmin> server task PDWebPI-server-name trace show [component]

Cache database settingsYou can configure the plug-in to regularly poll the master authorization databasefor update information. The cache-refresh-interval parameter can be set to″default″, ″disable″, or a specific time interval in seconds. The ″default″ setting isdisable.

[aznapi-configuration]cache-refresh-interval = 60

The db-file parameter defines the full path to the ACL cache database. By defaultthis parameter is not set.

[aznapi-configuration]db-file = /var/pdwebpi/db/pdwebpi.db

The listen-flags parameter enables or disables the reception of policy cache updatenotifications. A ″disable″ value disables the notification listener. This parameter isset by the svrsslcfg utility.

[aznapi-configuration]listen-flags = disable




Configuring the authorization API service

The [aznapi-entitlement-services] stanza of the pdwebpi.conf configuration fileassigns service IDs to services. Each stanza entry defines different types of aznAPIservice. For more information refer to the IBM Tivoli Access Manager AdministrationC API Developer’s Reference.

Each entry is in the form:service_id = path_to_dll [ & params ... ]

Service IDs are used by the aznAPI client to identify the services. You can specifyparameters to pass to the service when it is initialized by the aznAPI. Parametersfollow the ″&″ symbol in the entry.

Credential refresh

The information gathered at the time of user authentication is cached in thecredential for the duration of the session — see “Credential acquisition” on page 5for more details on plug-in user credentials.

Unless configured for credential refresh, changes made to the source of the usercredential information, such as adding or removing the user from a group, are notreflected in the user’s session until a new user session is created.

Some reasons why credential refresh is useful:

v You are able to refresh a user’s credential without requiring them to log-out andre-login to an application. This improves the user experience.

v It provides an administrator with the ability to supply extra access to secureWeb objects for a user during their current session.

v It improves security by allowing an administrator to restrict a user’s accesspermissions during a current session if the administrator has reason to believe

that the user is not behaving appropriately.

Configuring credential refreshThe [common-modules] stanza in the pdwebpi.conf configuration file defines theuse of all authentication methods. To enable credential refresh functionality, thecred-refresh module needs to be configured as a pre-authorization module.

[common-modules]...pre-authzn = cred-refresh...

Ensure that the entry for credential refresh exists in the [modules] stanza of thepdwebpi.conf configuration file; that is:

[modules]...cred-refresh = pdwpi-cred-refresh-module...

When refreshing credentials you may find it necessary to preserve someinformation about the user from the original credential. For example, a customattribute may record the user’s login time which would be of value to keepunchanged when the credential is refreshed. The plug-in allows you to configureattributes to keep when a refresh is performed. These are configured based on theattribute name.




The [cred-refresh] or [cred-refresh:virtual-host] stanza specifies the attributes topreserve from the original credential and which attributes to refresh into the newcredential when a credential refresh operation takes place. The values are specifiedin the form preserve = attribute_pattern for attributes to preserve from the original.Values to refresh are specified in the form refresh = attribute_pattern. The standardplug-in pattern matching rules apply to the attribute patterns, with the exceptionthat character comparisons are case insensitive. Refer to Appendix E, “Special

characters allowed in regular expressions,” on page 213 for more information onthe allowed matching rules.

The following rules apply to the attribute list:

v Rules that appear earlier in the stanza have precedence over those that appearlater.

v Rules that do not match any attributes are refreshed by default.

v Certain attributes are always preserved, regardless of how the [cred-refresh]stanza is configured. These attributes being:

– AZN_CRED_AUTHNMECH_INFO,

– AZN_CRED_BROWSER_INFO,

– AZN_CRED_IP_ADDRESS,– AZN_CRED_PRINCIPAL_NAME

– AZN_CRED_QOP_INFO

v Attributes marked by the aznAPI as read-only are always preserved, regardlessof the contents of the [cred-refresh] stanza.

v If an attribute is not present in the original credential, it will not be preserved,regardless of the configuration of this stanza.

Note: A credential is only refreshed from the registry when the credential does notexist in the credential cache.

Once credential refresh functionality is configured you can use the pdadmin

command line utility to refresh the credential of a particular user. The example below shows the commands for adding a user to a new group and refreshing thecredential while the user is still logged on, effectively giving the user accesspermissions of the new group.

pdadmin> group modify group_name add user_namepdadmin> server task server_name refresh all_sessions user_name

Note: On UNIX platforms a restart of the plug-in is not required after adjustingcredential refresh configuration. On Windows, as with all changes made topdwebpi.conf, a restart of the plug-in is required for credential refreshconfiguration changes to take effect.

Configuring HTTP request cachingThe plug-in caches request data and uses this cached data to rebuild a requestduring a HTTP redirect, if a re-authentication requirement interrupts thecompletion of the request processing. This functionality benefits POST and PUTrequests, because these requests types can include a variety of information fields.

When an authentication requirement interrupts a request, the plug-in caches allinformation necessary to rebuild the request during the HTTP redirect that followsafter re-authentication. Cached request data includes URL, METHOD, Message




Body, query strings, and all HTTP headers (including cookies). This data istemporarily stored in the plug-in credentials/session cache.

Upon successful authentication (or re-authentication), the plug-in sends a HTTPredirect to the browser. The browser follows the redirect to the original URLcontained in the redirect. The plug-in intercepts the redirect and rebuilds therequest using the cached data. The rebuilt request is delivered to the URL

destination.

Configuring server-side caching parametersThe max-cached-http-body parameter in the [pdweb-plugins] stanza of the plug-inconfiguration file specifies the maximum amount of HTTP body data that is cachedfor any given request. When the amount of body data exceeds the configuredmaximum, all of the body data is discarded.

The worker-size parameter within the [proxy-if] stanza controls the amount of memory allocated for any given request. The max-cached-http-body size, at aminimum, should conform to the following algorithm:

max-cached-http-body * 4/3 * 2 + 3000 <= worker-size # #

This algorithm assumes that 3000 bytes is enough memory to hold the request lessany POST data, and the returned form, less the cached POST data. If the size of the request plus the size of the returned form is likely to exceed 3000 bytes youshould either increase the worker-size entry or decrease the max-cached-http-bodyvalue.

Language support and character sets

Tivoli Access Manager Plug-in for Web Servers can display Tivoli Access Managergenerated HTML pages in the preferred language of the customer. The languageused for the display in HTML pages is taken from the standard Accept-Language

header found within the HTTP request. Language values are represented by twocharacters. Location-specific values are expressed in a two part format, indicatingthe language and the country where this version of the language is used. Examplesinclude:

v es (Spanish)

v de (German)

v en (English)

v it (Italian)

v en-US (English/United States)

v en-GR (English/United Kingdom)

v es-ES (Spanish/Spain)

v es-MX (Spanish/Mexico)

v pt-BR (Portuguese/Brazil)

If the plug-in finds no appropriate language code in the HTTP request, it retriesthe language list without the qualifying dialect (e.g. es-MX is retried as es). If anappropriate language is still not found, the server uses English.

Only the Tivoli Access Manager generated pages, contained withininstall_path/nls/html/lang/charset, are served in multiple languages. Examples




of these pages include all Tivoli Access Manager authentication forms and theTivoli Access Manager account management pages.

The languages specified within the Accept Language field in the HTTP header aremapped directly to directories found within the install_path/nls/html directory.A server can be modified to cater for language specifier variations by copyinglanguage directories. To modify a server, the actual language directories that

should be copied are :am base install directory/nls/msg/langam webpi install directory/nls/html/lang/charsetam webpi install directory/nls/msg/lang/charset

The following table lists the languages supported by the plug-in, with theassociated sub-directory name:

Table 9. Plug-in supported languages with supported directory.

Language System Directory

English (default) C

Czech cs

German de

Spanish es

French fr

Hungarian hu

Italian it

Japanese ja

Korean ko

Polish pl

Portuguese, Brazil pt_BR

Russian ru

Chinese, China zh_CN

Chinese, Taiwan zh_TW

Up to ten language specifications in the Accept Language field of the HTTP headerare recognized.

Different character sets for a given language are located in a directory below thatfor language support. The character set directory used is selected based on thevalue of the accept-charset header received from the client. If no match is found(or if the header is not set) then the utf-8 directory is used.

You can enable and disable the support for different languages and character sets based on the accept-language and accept-charset headers. The default settings forthese parameters are configured in the [pdweb-plugins] stanza but can beoverridden on a virtual host basis by defining them in a stanza with the name of the virtual host ID.

[pdweb-plugins] or [virtual-host]...use-accept-langauge-header = true...use-accept-charset-header = false




By default, the use of the accept-charset header is disabled.

The use-accept-language-header parameter enables or disables the use of theaccept-language HTTP header when attempting to locate the language for thegenerated HTML response.

The use-accept-charset-header parameter enables or disables the use of the

accept-charset HTTP header when attempting to locate the charset in which todecode elements of a HTTP request, or generate a HTML response. The defaultvalue (if not found within this configuration file) is false.

The user-agent header can be used as an alternative to the accept-language andaccept-charset headers for selecting a language and character set. The user-agentheader contains device-specific information that can be used to provide languageand character information when the requirements of the device are known. Theuser-agent header is only used when either or both accept-language and accept-charsetheaders are not found, or if the use of those headers is disabled.

The default mapping from user-agent to language and character set is configured inthe [user-agent] stanza and can be overridden on a per virtual-host basis. The

stanza includes a list of patterns that are matched, in the order specified, to thecontents of the user-agent header. For a list of the available wildcard charactersrefer to Appendix E, “Special characters allowed in regular expressions,” on page213. If a match is found then the directory for the corresponding language andcharset is used. In addition to specifying a language and character set for a givenuser-agent pattern, it is also possible to specify a directory. In this case the directoryname specified is used rather than the one for the charset when sending TivoliAccess Manager pages. This directory must be located under the specifiedlanguage directory.




Chapter 3. IBM Tivoli Access Manager Plug-in for WebServers authentication and request processing

This chapter discusses how IBM Tivoli Access Manager (Tivoli Access Manager)Plug-in for Web Servers maintains session state, handles the authentication process,and performs any post authorization processing required on authorized sessions.

This chapter includes the following topics:

v “The request handling process”

v “Configuring authentication” on page 41

v “Managing session state” on page 49

v “Authentication configuration overview” on page 55

v “Configuring Basic Authentication” on page 59

v “Configuring forms authentication” on page 61

v

“Configuring certificate authentication” on page 64v “Configuring token authentication” on page 65

v “Configuring SPNEGO authentication” on page 69

v “Configuring NTLM authentication (IIS platforms only)” on page 76

v “Configuring Web server authentication (IIS platforms only)” on page 77

v “Configuring Failover authentication” on page 78

v “Configuring IV header authentication” on page 93

v “Configuring HTTP header authentication” on page 95

v “Configuring IP address authentication” on page 97

v “Configuring LTPA Authentication” on page 98

v “Configuring the redirection of users after logon” on page 99

v “Adding extended attributes for credentials” on page 99

v “Adding LDAP extended attributes to the HTTP header (tag value)” on page 102

v “Supporting Multiplexing Proxy Agents (MPA)” on page 104

The request handling process

Tivoli Access Manager Plug-in for Web Servers processes each Web request as itarrives at the Web server. There are eight steps to the request handling process:

1. Virtual host identification

The first step in request processing is the identification of the virtual host forwhich the request is intended. Virtual host identification is discussed in

“Configuring for virtual host servers” on page 13.2. Session identification

Once the virtual host has been determined the request is examined for existingauthenticated session information. This information may by either a sessioncookie or SSL session ID. The information that is used for identifying thesession is determined by the configured session modules. “Managing sessionstate” on page 49 discusses each of the available session modules.

3. Authentication

If no existing session is identified, the request is examined for authenticationinformation. This may be information such as a Basic Authentication user name




and password, a submission to a login form, or a client certificate. Theinformation that is used for authenticating the client is determined by theconfigured authentication modules. “The authentication process” on page 41discusses each of the available authentication modules.

If valid authentication information exists in the request, a new authenticateduser session is created. If no authentication information is present, the requestis treated as unauthenticated. If invalid authentication information is present in

the request and the authentication method supports re-entry (for example, BasicAuthentication) of authentication information then the user is challenged toprovide their authentication again. If the authentication method does notsupport re-entry (for example, client certificate) an error is returned to theclient.

4. Pre-authorization

In some cases, initial request processing maybe required before access to arequested resource is authorized. This processing is performed by anyconfigured pre-authorization module. Pre-authorization modules providefunctions that do not require authorization or they support capabilities thatrequire access to the request prior to the authorization decision.

5. Authorization

During the authorization, Tivoli Access Manager policy is consulted using thecredential information associated with the session to determine whether or notaccess should be granted to the requested resource and if so under whatconditions. The policies that may be defined to control access to resources aredefined in Chapter 4, “IBM Tivoli Access Manager Plug-in for Web Serverssecurity policy,” on page 109.

6. Authentication upgrade

In cases where the user’s authentication level is inappropriate for accessing arequested resource or a request is unauthenticated, the request is examinedagain for authentication information that would authenticate the user at therequired authentication level. If no such information exists, and anauthentication module that supports the ability to challenge the user for

information at the required authentication level is configured, then the user ischallenged to provide such information. If there is no means to upgrade theauthenticated user session to a sufficient level to access the resource then accessis denied.

7. Post-authorization

Occasionally, after the authorization decision has occurred, certain processingmay be required to:

v modify the Web request before it is handled by the Web server, for example,to insert a header,

v modify the Web response generated by the Web server, for example, to set acookie,

v

generate a complete response without the Web server handling the request,for example, to redirect the user to a particular page after a successful logon.

These operations occur after the result of the authorization process is knownsince the decision may affect how the request should be handled. Thesecapabilities are provided by post-authorization modules.

8. Response handling

Functions such as Forms Single Sign-on (FSSO) and External AuthenticationInterface (EAI) processing require the response generated by the Web server to

be processed by the plug-in rather than being sent to the client. Generally, with




response handling, the plug-in processes responses from the Web server beforepassing an alternative response to the user. Modules that require this capabilityare called response modules.

The authentication process

Authentication is the method of identifying an individual process or entity that is

attempting to log on to a secure domain. Successful authentication results in aTivoli Access Manager identity that represents the user. The plug-in uses thisidentity to acquire credentials for that user. Credentials are used by theAuthorization Server to permit or deny access to protected resources when afterevaluating the ACL permissions, POP conditions and authorization rules governingthe policy for each resource.

Note: ACL = access control list policyPOP = protected object policy

Tivoli Access Manager Plug-in for Web Servers supports several authenticationmethods by default and can be customized to use other methods.

Configuring authenticationAll available authentication methods with their associated shared library names aredefined in the [modules] stanza of the pdwebpi.conf configuration file. The[modules] stanza also lists the modules used for session identification andpost-authorization handling. These modules are described later. The sharedlibraries must exist in the pdwebpi/lib directory. Shared library names are specifiedwithout any operating-system-specific prefix (such as lib) and anyoperating-system-specific suffix (such as dll). For example:

BA = pdwpi-ba-module

In the preceding example, the BA module library is given as pdwpi-ba-module. OnWindows, the plug-in looks for a file called pdwpi-ba-module.dll, on Solaris it will

look for a file called libpdwpi-ba-module.so, and on AIX it will look for a filecalled libpdwpi-ba-module.a.

Note: An alternative to the default searching path for library files can be definedin the [module-mgr] stanza.

Each label defined in the [modules] stanza has a corresponding stanza of its own,for example [BA], [cert], and [token]. Specific configuration information for eachauthentication method is specified in these stanzas and applies to thatauthentication method independent of which virtual-host it is called from. If special configuration is required on a per virtual-host basis then the defaultconfiguration can be overridden by using a stanza that qualifies the module labelwith a virtual-host label. For example:

[BA]basic-auth-realm = "Access Manager"

[BA:ibm.com]basic-auth-realm = "ibm.com"

In the above example, users accessing virtual host ibm.com using BasicAuthentication will be subject to the configuration parameters specified in thestanza [BA:ibm.com].

Chapter 3. IBM Tivoli Access Manager Plug-in for Web Servers authentication and request processing 41



A standard configuration of modules permits only one instance of a module libraryto be specified for a given authentication method, for example:

[modules]BA = pdwpi-ba-module

Some installations may require multiple instances of an authentication library to bespecified. This might be done when different behavior of a module is required for

different authentication levels. The following example shows the configuration fortwo instances of the forms authentication module.

[modules]BA = pdwpi-ba-moduleforms-authn-level1 = pdwpi-forms-moduleforms-authn-level2 = pdwpi-forms-module

[common-modules]authentication = forms-authn-level1authentication = forms-authn-level2authentication = BA

[forms-authn-level1]login-form = level1-form

[forms-authn-level2]login-form = level2-form

[BA]...

The last step in configuring authentication methods is to specify the authenticationmethods. These are set in the [common-modules] stanza of the configuration file intheir order of preference. For example:

[common-modules]session = ssl-idsession = BAsession = session-cookie

authentication = certauthentication = BA

post-authzn = ltpa

In the above example, the configuration settings ensure that:

v SSL session IDs are used to maintain session information as a first choice.

v BA headers (if available) are used to maintain session information when an SSLsession ID is not available.

v Session cookies are used as a last resort to maintain session information whenneither SSL session IDs or BA headers are available.

v Certificates are used as the authentication method as a first choice.

v BA is used for authentication when a certificate is not available.

v LTPA cookies are to be added to the request as part of post-authorizationprocessing.

Configuring authentication for virtual hostsConfiguration of authentication methods can be achieved on a per virtual host

basis by specifying the methods directly in each virtual host stanza. For example:

[pdweb-plugins]virtual-host = ibm.com




[ibm.com]....session = ssl-idsession = BAsession = session-cookie

authentication = certauthentication = BA

post-authzn = ltpa

An alternative way to specify the authentication methods for virtual hosts is todefine a stanza for authentication method configuration. This allows multiplevirtual-hosts to share a module configuration. The module configuration stanza isspecified by the modules parameter in the virtual-host stanza. For example:

[pdweb-plugins]virtual-host = ibm.comvirtual-host = lotus.com

[ibm.com]modules = ibm-lotus-module-stanza

[lotus.com]modules = ibm-lotus-module-stanza

[ibm-lotus-module-stanza]authentication = BAsession = BApost-authzn = ltpa

When separate stanzas for authentication method configuration on a per-virtualhost basis are not defined in the configuration file, all virtual hosts use theparameters configured in the [common-modules] stanza; that is, the default valuefor the modules parameter is common modules.

The following example sets up a virtual host called ibm.com that is configured to

use SSL session IDs where it can, BA headers where it can’t use an SSL ID and hasBA headers, and uses session cookies as a last resort to maintain sessioninformation. It supports certificate authentication ahead of basic authentication andon successful authentication adds an LTPA cookie to the request to be handled bythe Web server. The example only shows the parameters defined here.

[pdweb-plugins]virtual-host = ibm.com

[modules]ssl-id = pdwpi-ssl-idsession-cookie = pdwpi-session-cookieBA = pdwpi-bacert = pdwpi-certltpa = pdwpi-ltpa

[ibm.com]session = ssl-idsession = BAsession = session-cookie

authenitcation = cert

post-authzn = ltpa

Further configuration of the authentication parameters can be achieved on a pervirtual host basis by creating virtual host specific authentication configuration




stanzas. The example below shows the configuration for two virtual hosts:ibm.com and lotus.com. Each virtual host has module specific authenticationconfiguration.


[modules]...

[ibm.com]session = BAsession = session-cookie

authenitcation = BAauthentication = forms

[lotus.com]session = session-cookie

authenitcation = BAauthentication = cert

[BA:ibm.com]basic-auth-realm = "Access Manager - ibm.com"

[BA:lotus.com]basic-auth-realm = "Access Manager - lotus.com"

Configuring the order of authentication methodsThe order in which configured authentication methods are displayed in theconfiguration file is essential to the correct operation of your plug-in software. Thetype of authentication methods you choose needs to be carefully considered andimplemented in a way that is fail safe and achieves your security objectives.

Tivoli Access Manager Plug-in for Web Servers supports a variety of authentication

methods in a way that can be tailored to different customer requirements fordifferent security needs.

As seen in previous sections of this document, the [common-modules] stanza of the pdwebpi.conf configuration file is where you specify the authenticationmethods you want to use. The [authentication-levels] stanza of the configurationfile defines step-up authentication levels (refer to, “Authentication-strengthProtected Object Policy (Step-up)” on page 116) as well as the ordering of authentication methods configured in the [common-modules] stanza.

An authentication method defaults to a level of 1 when no entry for it is defined inthe [authentication-levels] stanza. Authentication order is then determined as thehighest authentication level down to the lowest authentication level for theauthentication methods defined in the [authentication-levels] stanza. If anauthentication level is shared by several modules the sub-order is then determined

by the order in which the modules appear within the [common-modules] stanza.

To understand plug-in authentication it is useful to think of the plug-in asking twoquestions for each request it processes:

1. Can I authenticate this request using the configured method of authentication?

If the answer to this question is no, then the plug-in asks the next question.

2. Can I generate an authentication request using the configured method of authentication?




Consider the following configuration.

[common-modules]authentication = BA

For an incoming request, authentication of the user is required if the ACL does notpermit unauthenticated users. The plug-in seeing BA as the only authenticationmethod configured, asks; ″can I authenticate this request using basic

authentication?″ If the request is new then the answer is no—the plug-in does notknow of this user. The plug-in then asks; ″can I generate an authentication requestusing basic authentication?″ If basic authentication has been configured correctly,the answer is yes. The plug-in prompts the user for an ID and password.

This is a simple example of authentication using Basic Authentication. It is likelythat you will want to configure more than one authentication method dependingon the security requirements of your object space.

Following is a more detailed example of the logic that the plug-in uses to givepriority to particular authentication methods.

The authentication logic discussed in the following paragraphs assumes that

unauthenticated users are not permitted to access the resource and that thefollowing configurations have been made to the pdwebpi.conf configuration file.

[common-modules]authentication = BAauthentication = failoverauthentication = forms

post-authzn = failover

[authentication-levels]1 = BA2 = failover

The preceding configuration specifies three authentication methods: BA, failover

cookies, and forms with failover cookies used for post-authorization processing.The levels set in the [authentication-levels] stanza determine the order in whichthe authentication methods are called to authenticate requests. Formsauthentication defaults to a level of 1 as no level has been defined for it in the[authentication-levels] stanza.

Using the above configuration, the plug-in, when receiving a request, looks for afailover cookie in the request header. The plug-in looks for a failover cookie beforeBA data because failover is specified at level 2 in the [authentication-levels]stanza. The [authentication-levels] stanza takes precedence over the order of theauthentication modules definitions in the [common-modules] stanza.

The plug-in asks the question; ″can I authenticate this request using a failovercookie?″ If the request has not been previously authenticated then the answer isno, as the plug-in will have not previously constructed a failover cookie for therequest. The plug-in asks the second question, ″can I generate an authenticationrequest using the failover cookie?″ The answer is no, as the failover cookie modulehas no way of generating requests for authentication.

The plug-in moves to the next configured authentication method in the[authentication-levels] stanza, which in the example is BA. The plug-in asks thequestion; ″can I authenticate this request using the BA header?″ The answer is no,as the request has not been previously authenticated. The plug-in then asks the




question; ″can I generate an authentication request using BA?″ The answer is likelyto be yes, and the user is prompted to enter a user ID and password. A successfulauthentication produces an authorized session and a failover cookie is inserted intothe request header and used as the first method of authentication for subsequentrequests during the same session.

Should the BA module be unable to generate a method for authenticating the user,

the plug-in would default to the ordering of methods listed in the[common-modules] stanza of the configuration file. In the configuration exampleabove, the plug-in would assign the priority of authentication methods thus:

level 1 = BA, formslevel 2 = failover cookie

If failover cookies and BA fail to provide a method for user authentication, theplug-in would authenticate using forms.




The flow chart below shows the plug-in logic used to select an authenticationmodule.

Call first authentication

module in list

incoming request

User ID returned?

Call next authentication

module in list

Other configured

authentication modules to

try?

Authenticated user

Yes No

Yes

No authenticationinformation available.

Send user anauthentication

challenge.

No

The plug-in calls each authentication module in the order it was configured untilone of the modules returns a credential for the user. If none of the configuredauthentication modules is able to generate a credential, an authentication challengeis sent to the user to prompt them to provide authentication information.

If an authentication challenge is required, then the first suitable authenticationmodule from the configured list is called to generate the commands needed toproduce the challenge. Not all authentication modules can generate a challenge.For example, there is no challenge to request HTTP Headers — these are eitherpresent in the request or not. In addition, an authentication module might beunavailable because it is already being used to identify a proxy agent that isforwarding requests to the plug-in. The most common authentication mechanismsthat can generate a challenge for the user are Basic Authentication (a BA challengeis sent to the user) and forms-based authentication (a logon form is sent to theuser). If no authentication method is available, the user cannot be authenticatedand the plug-in returns a forbidden page.

The flowchart in figure 2 shows the process for selecting an authentication methodto send a challenge to the user.

Each configured authentication method is examined in the order in which it isconfigured until one is found that satisfies the required level of authentication. If amodule is found that satisfies the authentication criteria, it is called to build thechallenge that is sent to the user. If none of the configured authentication methodsis suitable, then no authentication is possible. The plug-in returns a ″Forbidden″page to the user because the user does not have the permissions required to accessthe requested resource and there is no possibility to send them a challenge toauthenticate at the required level.

Figure 2. Plug-in process flow for determining authentication module.




Examine first

authentication module in

the list

request

Is the level high enough?

Examine next

authentication

module in list.

Does the authentication

method support a

challenge?

Are there other

authentication

modules to try?

Call module to build

challenge

Yes

Yes

No

Yes

No No authentication

possible

No

Is the authentication

method already used?

No Yes

Configuring post-authorization processing

Configured post-authorization modules are called after a request has beenauthorized. Post-authorization modules determine if any other action needs to betaken before a request is passed back to the plug-in for processing by the Webserver. All configured post-authorization modules are called to determine if anyneed to take action on the request.

Post Authorization modules can be categorized as either:

v Modifying Requests for SSO — These post-authorization modules addinformation (cookies or headers) that are used by the Web application to identifythe user without requiring a second authentication.

v Modifying Responses — These post-authorization modules modify responsesusually by adding headers or cookies to it. For example, the failover module

adds a failover cookie to responses.v Special Functions — These post-authorization modules recognize the URI being

requested as the trigger for some special function. A special function indicatesthat the request is handled by the plug-in. An example is eCSSO ″vouch for″requests.

Post-authorization modules are called in the order they appear in the configurationfile. Post-authorization modules specified ″later″ in the list have the ability to undoor overwrite changes made by prior post-authorization modules.

Figure 3. Authentication challenge process logic.




For example; the following configuration will result in different plug-in behaviordepending on the order that BA and forms are specified in the [common-modules]stanza.

[common-modules]...post-authzn = BApost-authzn = forms

[BA]...strip-hdr = always

[forms]...create-ba-hdr = yes

The configuration above is a simple example of how a great deal of flexibility can be achieved through the ordering of post-authorization modules and moduleconfiguration.

Managing session state

Session state information is used by the plug-in to identify the source of incomingrequests. The plug-in uses the identity of the request source to maintain the sessionstate between client and server when the client performs numerous requests withinthe one session. Without an established session state between client and server, thecommunication between the client and the server must be renegotiated for eachsubsequent request. Session state information improves performance by eliminatingthe need for repeated authentication. The client can log on once and makenumerous requests without performing a separate log on for each request.

Tivoli Access Manager Plug-in for Web Servers handles both HTTP and HTTPScommunication. The plug-in is designed to use any of the following informationtypes to maintain session state with a client:

1. SSL Session ID

2. Basic Authentication

3. Server-specific session cookie

4. HTTP header data

5. IP address

6. LTPA cookies

7. IV headers

The plug-in calls each configured session module in turn. The plug-in continues tosearch the configured session module types until one returns a credential. Theplug-in then determines if the application references a Multiplexing Proxy Agent. If

it is a Proxy Agent, then another session must exist for the real end user. To findthis other session, the plug-in continues to call the rest of the configured sessionmodules. A user credential is returned when an existing session is found for whichuser authentication has already taken place. This credential is used to authorize therequest. If none of the configured session modules returns a user credential, the




session is either new or is a session for which no credential has been established.

Call first Session modulein list

incoming request

Credential returned?

Call next Sessionmodule in list

Flagged as MPA?

Other Session modules totry?

Return Credential

Yes

Yes

No

Yes

No No Sessioncredential available

No

Configuring the plug-in session/credentials cacheThe plug-in session cache allows a server to store the session ID information frommultiple clients. The session cache accommodates both HTTPS and HTTP sessionstate information.

The plug–in cache stores session ID information plus the credential informationobtained for each client. Credential information is cached to eliminate repetitive

queries to the user registry database during authorization checks. The plug-incache also maintains session state information for SSL connections between theplug-in and the LDAP user registry.

There are several configuration parameters available for the plug-in cache thatallow you to tune the performance of the cache.

Note: The values configured in the [sessions] stanza of the pdwebpi.confconfiguration file may be overridden in the [module_name] stanza, and somemay be further overridden in the [module_name:virtual_host_name] stanza ona per-virtual host basis.

Setting the maximum concurrent entries value

The max-entries parameter, located in the [sessions] stanza of the pdwebpi.confconfiguration file, sets the maximum number of concurrent entries in each sessionmodule’s session/credentials cache.

This value corresponds to the number of concurrent logon sessions for a particularsession module. When the cache size reaches this value, entries are removed fromthe cache according to a least recently used algorithm to allow new incominglogons.

The default number of concurrent logon sessions is 4096:

Figure 4. Plug-in process flow for determining session module.




[sessions]max-entries = 4096

Setting the cache entry timeout valueThe timeout parameter, located in the [sessions] stanza of the pdwebpi.confconfiguration file, sets the maximum lifetime timeout for an entry in the plug-insession/credentials cache.

The plug-in caches credential information internally. The session cache timeoutparameter dictates the length of time authorization credential information remainsin memory.

The parameter is not an inactivity timeout. The value maps to a ″credentiallifetime″ rather than a ″credential timeout″. Its purpose is to enhance security byforcing the user to re-authenticate when the specified timeout limit is reached.

The default logon session timeout (in seconds) is 3600:

[sessions]timeout = 3600

You can configure the session cache lifetime to be reset whenever reauthenticationoccurs. Each time reauthentication occurs, the session cache timeout value is reset.To configure session cache lifetime reset, use the reauth-lifetime-reset parameter inthe [sessions] stanza of the pdwebpi.conf configuration file:

[sessions]reauth-lifetime-reset = yes

The default value is no.

It is possible for the session cache lifetime value to expire while the user isperforming a reauthentication. The session cache lifetime can expire after thereauthentication logon form is sent to the user and before the completed logonform is returned. When the session cache lifetime value expires, the session cache

entry is deleted. When the logon form is returned to the plug-in, there is no longera session for that user. In addition, all cached user request data is lost. You canconfigure a time extension, or grace period, for the session cache lifetime if thesession cache lifetime expire during reauthentication.

The reauth-grace-period parameter in the [sessions] stanza of the pdwebpi.confconfiguration file provides this time extension, in seconds. For example:

[reauthentication]reauth-grace-period = 20

The default value, 0, provides no extension to the session cache timeout value. Thereauth-grace-period parameter applies to users with existing session cache entriesand who are required to reauthenticate. For example:

v Users performing reauthentication resulting from POP security policy,

v Users performing reauthentication resulting from session cache inactivity,

v Users performing step-up authentication.

The reauth-grace-period option is intended to be used in conjunction with thereauth-lifetime-reset = yes option.

Setting the cache entry inactivity timeout valueThe inactive-timeout parameter, located in the [sessions] stanza of thepdwebpi.conf configuration file, sets the timeout value for logon session inactivity.




The default logon session inactivity timeout (in seconds) is 600:

[sessions]inactive-timeout = 600

To disable this timeout feature, set the parameter value to 0.

Maintaining session state with the SSL session IDTivoli Access Manager Plug-in for Web Servers can track sessions using the SSLsession ID of incoming HTTPS requests. This facility is not available on IIS, as IISdoes not make SSL session IDs available to the plug-in.

Note: SSL session IDs are not used for authenticating requests.

The [common-modules] stanza in the pdwebpi.conf configuration file defines theuse of all session, authentication, and post-authorization methods using the formatmodule_type = module-name. To maintain session state using SSL session ID’s, assignthe word ssl-id to the session parameter as in the following:

[common-modules]session = ssl-id

Ensure the shared library for ssl-id is configured in the [modules] stanza of thepdwebpi.conf configuration file. That is:

[modules]ssl-id = pdwpi-sslsessid-module

Maintaining session state using Basic AuthenticationBasic Authentication (BA) is a method for authenticating users and maintainingsession state through the input of a username and password. BA is defined by theHTTP protocol and can be implemented over HTTP and HTTPS.

Basic Authentication maintains session state by caching a record of the content of

the Basic Authentication header.

To configure the plug-in to maintain session state using Basic Authentication, usethe [common-modules] stanza in the pdwebpi.conf configuration file. Enter theparameter session with the value as BA, as in the following:

[common-modules]session = BA

If BA is used to maintain session state, it needs to be also used for userauthentication. The [common modules] stanza of the configuration file should alsoset BA for authentication.

[common-modules]session = BAauthentication = BA

Security Warning:Using the Basic Authentication authorization header to identify sessions can exposeusers of the Web server to unlimited password guessing attacks.

This is a limitation of the HTTP Basic Authentication scheme that includes theuser’s password in the authorization header.




Tivoli Access Manager Plug-in for Web Servers is not enabled by default. The BasicAuthentication session identification capability is provided for thoseAdministrators aware of all the security risks associated with Basic Authenticationincluding this one.

Basic Authentication session identification can be securely used when a plug-insecured Web server operates behind a multiplexing proxy agent (for example

behind a WebSEAL junction) using Basic Authentication to authenticate itself to theplug-in. In such a situation the multiplexing proxy agent does not forward BasicAuthentication authorization headers from users to the plug-in, making the attackimpossible.

Maintaining session state with Session CookiesUsing session cookies to hold session information is a method for maintainingplug-in session state. The server packages the state information for a particularclient in a cookie and sends it to the client’s browser. For each new request, the

browser re-identifies itself by sending the cookie (with the session identifier) backto the server.

Session cookies offer a possible solution for situations when the client uses a browser that renegotiates its SSL session after very short periods of time. Forexample, some versions of the Microsoft Internet Explorer browser renegotiate SSLsessions every two or three minutes.

A session cookie provides re-authentication of a client only to the server the clientauthenticated to within a short time period (around ten minutes). The mechanismis based on a ″server cookie″ that cannot be passed to any machine other than theone that generated the cookie.

In addition, the session cookie contains a random number identifier that is used toindex the cookie in the server’s session cache — no other information is exposed inthe session cookie. The session cookie cannot compromise security policy.

Tivoli Access Manager Plug-in for Web Servers uses a secure server-specific sessioncookie. The following conditions apply to this cookie mechanism:

v Cookie contains session information only; it does not contain identityinformation.

v Cookie is located only in the browser memory (it is not written to the browsercookie jar on the disk).

v Cookie has a limited lifetime (configurable).

v Cookie has path and domain parameters that prohibit its use by other servers.

To configure the plug-in to use session cookies to maintain session state, use the[common-modules] stanza in the pdwebpi.conf configuration file. Enter the

parameter session with the value as session-cookie, as in the following:

[common-modules]session = session-cookie

The resend-pdwebpi-cookies parameter, located in the [sessions] stanza of thepdwebpi.conf configuration file, enables or disables the sending of the sessioncookie to the browser with every response. This action helps to ensure that thesession cookie remains in the browser memory. The resend-pdwebpi-cookiesparameter has a default setting of no:

[sessions]resend-pdwebpi-cookies = no




Change the default setting to yes to send plug-in session cookies with everyresponse.

Maintaining session state using HTTP headersTivoli Access Manager Plug-in for Web Servers can be configured to use HTTPheader information to identify sessions and maintain session state.

The plug-in can use HTTP headers for tracking sessions as well as authenticatingusers. If the plug-in is configured to use HTTP headers to track sessions then itmust also be configured to use HTTP headers to authenticate users. However,having the plug-in configured to authenticate incoming requests using HTTPheaders does not require the plug-in to be configured to track sessions. Refer to,“Configuring HTTP header authentication” on page 95 for details on configuringthe plug-in to use HTTP headers for client authentication.

When using HTTP headers to maintain session state, the [common-modules]stanza of the pdwebpi.conf configuration file must be configured with thefollowing values:

[common-modules]

authentication = http-hdrsession = http-hdr

A standard configuration of HTTP headers permits only one header to be specified,for example:

[modules]http-hdr = pdwpi-httphdr-module

To specify multiple HTTP headers, multiple instances of the HTTP header modulemust be configured.

For example:

[modules]

entrust-client-header = pdwpi-httphdr-modulesome-other-header = pdwpi-httphdr-module

[entrust-client-header]header = entrust-client

[some-other-header]header = some-other

Maintaining session state using IP addressesTivoli Access Manager Plug-in for Web Servers can use IP addresses to identifyand track sessions.

To configure the plug-in to use IP addresses to track sessions, use the[common-modules] stanza in the pdwebpi.conf. Enter the parameter session withthe value as ip-addr. That is:

[common-modules]session = ip-addr

Ensure the shared library for IP address authentication is configured in the[modules] stanza of the pdwebpi.conf configuration file. That is:

[modules]ip-addr = pdwpi-ipaddr-module




If IP addresses are used to maintain session state they must also be used toauthenticate incoming requests. See “Configuring IP address authentication” onpage 97 for details on configuring Tivoli Access Manager Plug-in for Web Serversto use the IP address as the method for client authentication. The usage of IPaddresses for authenticating clients, however, does not require them to be used asthe method for identifying sessions.

Maintaining session state using LTPA cookiesLTPA authentication can be used to accept and authenticate based on an LTPAcookie. LTPA Authentication can maintain session state using the LTPA cookiefound within each HTTP request.

To configure the plug-in to maintain session state using LTPA Authentication, usethe [common-modules] stanza in the pdwebpi.conf configuration file. Enter theparameter session with the value as ltpa, as in the following:

[common-modules]session = ltpa

If LTPA is used to maintain session state, it also needs to be configured for user

authentication. The [common-modules] stanza of the configuration file also shouldset LTPA for authentication.

[common-modules]authentication = ltpasession = ltpa

Maintaining session state using iv-headersTivoli Access Manager Plug-in for Web Servers can cache iv-header information toimprove system performance.

The [common-modules] stanza in the pdwebpi.conf configuration file defines theuse of all session, authentication, and post-authorization methods using the formatmodule_type = module-name. To cache iv-headers information assign the value

iv-headers to the session parameter as in the following:[common-modules]session = iv-headers

Ensure the shared library for iv-headers is configured in the [modules] stanza of the pdwebpi.conf configuration file. That is:

[modules]iv-headers = pdwpi-iv-headers-module

Authentication configuration overview

As seen in the section “Configuring authentication” on page 41, it is theauthentication modules that perform the process of extracting authenticationinformation from requests. The actual authentication of requests is performed byauthentication mechanisms which validate authentication information. Theseparation of roles between authentication modules and authenticationmechanisms allows custom CDAS libraries written for WebSEAL to be used withthe plug-in.

The mechanisms for all authentication methods supported by Tivoli AccessManager Plug-in for Web Servers are configured in the [authentication-mechanisms] stanzas of the pdwebpi.conf configuration file. Supportedauthentication 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

The plug-in provides template server code that you can use to build and specifya custom external Cross Domain Authentication Service (CDAS) server.

An external CDAS authenticator specifies the appropriate custom shared library.

Note: Unlike the configuration for the [modules] stanza, add the full file namewhen configuring mechanisms in the [authentication-mechanisms] stanza.That is, include the file prefix and the operating-system-specific extension.

Local authentication mechanismsThe following authentication mechanism parameters specify local built-inauthenticators:

Table 10. Local Built-in Authenticators .


Forms and Basic Authentication

passwd-ldap Client access with LDAP username and password.

Client-side Certificate Authentication

cert-ssl Client access using a client-side certificate over SSL.

HTTP Header, IP Address Authentication, IV Header with iv-remote-address activated.

http-request Client access via special HTTP header, IP address, or IV Headerwith iv-remote-address activated.

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:

Table 11. External CDAS Server Parameters .


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

token-cdas Client access with LDAP username and token passcode.

cert-cdas Client access using a client-side certificate over SSL.

In addition to the authentication libraries there are two other standard TivoliAccess Manager libraries that can be used in the plug-in:

v passwd-strength

This library checks new passwords entered on the password change form.

v cred-ext-attrs

This library allows custom attributes (name/value pairs) to be specified forinclusion in the credential.




Refer to the IBM Tivoli Access Manager for e-business Web Security Developer Referencefor details on building and configuring a custom shared library that implements aCDAS server.

Default configuration for plug-insBy default the plug-in is set to authenticate clients using Basic Authentication (BA)

usernames and passwords (LDAP registry).

The plug-in 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 on Solaris:

[authentication-mechanisms]passwd-ldap = libldapauthn.socert-ssl = pdwpi-sslauthn.so

To configure other authentication methods, add the appropriate parameter with itsshared library (or CDAS module).

Configuring multiple authentication methodsYou modify the [authentication-mechanisms] stanza of the pdwebpi.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 ispossible 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 enable one of these to support client-side certificates.

3. Only one password type authenticator is actually used when more than one isconfigured. The plug-in 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.

Logout, change of password and help commandsTivoli Access Manager provides the following commands for supporting clientswho authenticate over HTTP or HTTPS.

pkmslogoutClients can use the pkmslogout command to log out from the current sessionwhen they use an authentication method that does not supply authentication datawith each request. When using an authentication method that suppliesauthentication data with each request, the pkmslogout command clears the session




cache though credential information is still contained in the request header. In thiscase, the user must close the browser to fully logout of the session.

The pkmslogout command is appropriate for authentication using tokenpasscodes, Forms authentication, and certain implementations of HTTP headerauthentication.

Run the command as follows:https://www.tivoli.com/pkmslogout

The browser displays a logout form defined in the pdwebpi.conf configuration file:

[acctmgmt]logout-success = logout_success.html

The logout-success entry can specify either a pre-defined HTML file (containedwithin the base install_path/nls/html/C directory) or a URI. The specified URIcould be either a relative URI or an absolute URI.

The pkmslogout utility also supports multiple logout response pages when thenetwork architecture requires different exit screens for users logging out of distinctly different virtual hosts.

pkmspasswdYou can use this command to change your logon password when using BasicAuthentication (BA) or Forms authentication. This command is appropriate overHTTP or HTTPS.

For example:

https://www.tivoli.com/pkmspasswd

The browser displays a change of password form defined in the pdwebpi.confconfiguration file:

[acctmgmt]password-change-form-uri = /pkmspasswd.formpassword-change-uri = /pkmspasswdpassword-change-success = password_change_success.htmlpassword-change-failure = password_change_failure.html

You can modify the password_change_success.html andpassword_change_failure.html files to suit your requirements.

pkmshelpYou can use this command to access help pages. This command is appropriate overHTTP or HTTPS.

The name and location of help pages are defined in the pdwebpi.conf configuration

file:[acctmgmt]help-uri = /pkmshelphelp-page = help.html

You can modify the help.html file to suit your requirements.




Configuring Basic Authentication

Basic Authentication (BA) is a standard method for providing a username andpassword to the authentication mechanism. BA is defined by the HTTP protocoland is implemented over HTTP and over HTTPS.

Enabling Basic AuthenticationBy default, the plug-in is configured for BA username and password. The[common-modules] stanza in the pdwebpi.conf configuration file defines the use of BA for authenticating requests. That is:

[common-modules]authentication = BA

The [modules] stanza in the pdwebpi.conf configuration file defines all availableauthentication mechanisms and their associated shared library name. Ensure thatthe entry for basic authentication exists; that is:


By default the BA authentication mechanism is given a level of 1 in the[authentication levels] stanza of the configuration file. This setting relates to thepriority of authentication mechanisms for incoming requests.

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

v On Windows, the file that provides the built-in mapping function is a DLLcalled ldapauthn.

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-mechanisms] stanza of the pdwebpi.confconfiguration file – as in the following:

Solaris:

[authentication-mechanisms]passwd-ldap = libldapauthn.so

Windows:

[authentication-mechanisms]passwd-ldap = ldapauthn.dll

Setting the realm nameThe realm is displayed in the dialog presented by a browser to the user forrequesting a username and password. The realm name is assigned to thebasic-auth-realm parameter in the [BA] stanza of the pdwebpi.conf configurationfile.

[BA]basic-auth-realm = realm_name




Manipulating BA headersYou can configure the plug-in to supply protected applications with original ormodified client identity information by controlling the contents of the BA headersthat are sent to the Web server. The existing header that is sent from the client can

be:

v stripped off all requests,

v stripped off unauthenticated requests,v passed unchanged for all requests.

For clients that do not provide a BA header or for existing client headerinformation passed to the Web server, the header information can be:

v set to a fixed username and password,

v have a fixed password sent (with the username passed as the name of theauthenticated user),

v be set using information from Tivoli Access Manager GSO lockbox.

To manipulate the BA headers of incoming requests, the plug-in must beconfigured to allow post-authorization processing using Basic Authentication. To

do this, add the parameter post-authzn and set it to the value BA in the[common-modules] stanza of the pdwebpi.conf configuration file. That is:

[common-modules]post-authzn = BA

The strip-hdr parameter instructs the plug-in to either:

Value Result

ignore Leave the header as is. The plug-in passes the original client BAheader to the resource without interference. This basically constitutesa direct login to the resource, transparent to the plug-in for instanceswhen you want to bypass plug-in authentication.

Notes:

1. This option potentially allows unauthenticated users to send BAheaders to the Web server. You should only use this option if youare sure you need it and you understand the security implications.

2. When BA authentication is configured at the plug-in and theprotected resource attempts to authenticate the client with its ownBA challenge, the user’s credentials will not be accepted by theprotected resource. Other authentication mechanisms such asForms, configured at the plug-in, will pass the original client BAheader to the resource without interference.

always Always remove the Basic Authentication header information from anyclient requests before forwarding the requests to the Web server. Inthis case, the plug-in becomes the single security provider. If youneed to supply the Web server with some client information, you can

combine this option with IV header authentication to put TivoliAccess Manager client identity information into HTTP header fields.Note: If the protected server sends a BA challenge with this optionenabled, the client sees an authentication pop-up window but cannotlog in because their response is always removed.

unauth The BA header received from the client is removed from all requestsexcept those from users that have been authenticated by the plug-inusing Basic Authentication. This permits authenticated users to sendauthenticated BA headers to the web server but prevents anunauthenticated user from doing so.




The add-hdr parameter in the [BA] stanza of the configuration file allows you tosupply client identity information in HTTP Basic Authentication (BA) headers.Supplying client identity information in HTTP BA headers using the add-hdrparameter, occurs after any processing by the strip-hdr parameter functionality.The add-hdr parameter can be set as: none, gso, or supply.

v Set as none, a BA header is not added to the request.

v

Set as gso, a GSO BA header is added to the request — refer to “Using Globalsingle sign-on (GSO)” on page 130 for detailed information on configuringplug-in GSO functionality.

v Set as supply, a static password and username are added to the BA header. Thesestatic password and usernames are defined in the supply-password andsupply-username parameters in the [BA] stanza of the configuration file. Thesupply-username parameter can be set to a fixed username value. If thesupply-username parameter is not set, the username in the BA header is createdusing the Tivoli Access Manager authenticated username. In this case the plug-inprotected resource requires authentication from a Tivoli Access Manager identity.

When the add-hdr parameter is set to supply and the supply-password andsupply-username parameters are set, the specified username and password areused for all requests. The use of a common username and password offers no

basis for the application server to prove the legitimacy of the client logging inwith that username. If clients always go through the plug-in to access resources,this solution does not present any security problems. However, it is important tophysically secure resources from other possible means of access. Since thisscenario has no password-level security, plug-in protected resources mustimplicitly trust the plug-in to verify the legitimacy of the client. The user registrymust also recognize the Tivoli Access Manager identity in order to accept it.

If supply-username is not set and the user is unauthenticated then no BA header isadded to the request.

Specify UTF-8 encoding of BA headers

Edit the plug-in configuration file. Specify whether or not the plug-in should useUTF-8 encoding for BA headers.

[BA]use-utf8 = true

The default value is true.

For more information on plug-in support for UTF-8 encoding, see “Languagesupport and character sets” on page 35.

Configuring forms authentication

Tivoli Access Manager provides Forms authentication as an alternative to thestandard Basic Authentication mechanism. This method produces a custom HTMLlogon form from Tivoli Access Manager instead of the standard logon promptresulting from a Basic Authentication challenge.

When you use Forms-based logon, the browser does not cache the username andpassword information as it does with Basic Authentication.




Enabling forms authenticationThe [common-modules] stanza in the pdwebpi.conf configuration file defines theuse of all authentication methods. To enable authentication using forms, assign theword forms to the authentication parameter; that is:

[common-modules]authentication = forms

When using forms for authentication, the plug-in must also be configured to useforms for post-authorization processing. Using forms allows the plug-in to redirectthe authenticated user back to the original request URL. In the [common-modules]stanza of the pdwebpi.conf configuration file, add the parameter pre-authzn as inthe following:

[common-modules]authentication = formspre-authzn = forms

The [modules] stanza in the pdwebpi.conf configuration file defines all availableauthentication mechanisms and their associated shared library name. Ensure thatthe entry for forms authentication exists; that is:

[modules]forms = pdwpi-forms-module

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

v On Windows, the file that provides the built-in mapping function is a DLLcalled ldapauthn.

You can configure the username and password authentication mechanism by

entering the passwd-ldap parameter with the platform-specific name of the sharedlibrary file in the [authentication-mechanisms] stanza of the pdwebpi.confconfiguration file, as in the following:

Solaris:

[authentication-mechanisms]passwd-ldap = libldapauthn.so

Windows:

[authentication-mechanisms]passwd-ldap = ldapauthn.dll

Customizing HTML response formsForms authentication requires you to use a custom logon form. By default, thesample login.html form is located in the following directory:install_path/nls/html/lang/charset.

Where lang is taken from the NLS configuration. On US English systems, the langdirectory is called C and charset is utf-8.




The login-form parameter in the [forms] stanza of the configuration file definesthe file name of the form presented to the user during log on. The path of the fileshould be relative to the translated pdwebpi HTML directory (for example pdwebpi/nls/html/lang/charset).

[forms]login-form = login.html

Note: Removal of the wpi_url field from the login.html form, will cause POSTdata, submitted with the login form, to be available in the HTTP request asPOST data variables. This includes the user name and password used tologin to Tivoli Access Manager. Also, removing the wpi_url field from aform disables all POST data caching functionality and macros such as%POST_URL% will no longer be supported.

Customizing the forms login URIIt is possible to have multiple instances of the forms login module used within asingle virtual host. In such instances it is necessary to change the URI POSTed towhen the login form is submitted for each separate instance of the forms loginmodule. The login-uri parameter in the [forms] stanza controls this URI. If

changed from the default, the form specified by the login-form parameter (see“Customizing HTML response forms” on page 62) must be updated to reflect thechange.

Creating a BA HeaderForms authentication provides the ability to create a BA header based on the username and password provided in the login form. Creation of the header providesan easy single sign-on mechanism that can be used when the back-end applicationrequires basic authentication, and the user name and password match that whichTivoli Access Manager uses.

BA header creation is handled by the forms post-authorization module. Add anentry for forms post-authorization processing to the [common-modules] stanza of the plug-in configuration file:

[common-modules]post-authzn = forms

The create-ba-hdr parameter within the [forms] stanza of the configuration fileenables or disables the creation of BA headers, for example:

[forms]create-ba-hdr = yes

By default forms authentication does not create the BA header - create-ba-hdr isset to no. Regardless of how the parameter is set, a BA header is not created whenthe user is not successfully authenticated and a header is not created when theuser’s password has expired.

Note: If another module after the forms module in the post-authzn list overwritesthe BA header (or removes it) then this function does not work. It isadvisable to have the forms module specified as the last in the post-authznlist.

Specify UTF-8 encoding on BA headersEdit the plug-in configuration file. Specify whether or not the plug-in should useUTF-8 encoding for BA headers.




[forms]use-utf8 = true



Configuring certificate authentication

Tivoli Access Manager Plug-in for Web Servers supports secure communicationwith clients using client-side digital certificates over SSL. In this authenticationmethod, certificate information (such as the Distinguished Name or DN) ismapped to a Tivoli Access Manager identity.

Mutual authentication using certificatesAuthentication using digital certificates takes place in two stages:

v The Web server where the plug-in is located identifies itself to SSL clients withits server-side certificate.

v The Web server uses its database of Certificate Authority (CA) root certificates tovalidate clients accessing the server with client-side certificates. The followingprocess takes place:

1. An SSL client requests a connection with a Web server through the plug-in.

2. In response, the Web server sends its public key using a signed server-sidecertificate. This certificate has been previously signed by a trusted third-partycertificate authority (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 the Web server’s certificate matches one of these root 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 Web server.

The end result of this process is a secure channel over which the client canauthenticate (for example, using a username and password). After successfulauthentication, the client and server can continue to communicate securelyover this channel.

6. Now the client sends its public key certificate through the plug-in to the Webserver.

7. The Web server attempts to match the signature on the client certificate to a

known CA using the Web server’s certificate store.8. If there is no match for the signature, an SSL error code is generated and sent

to the client.

9. If there is a match for the signature, then the client can be trusted.Authentication of the client takes place, resulting in a Tivoli Access Manageridentity.

10. Session keys are securely negotiated between the client and the Web server.The end result of this process is a secure and trusted communication channel

between the mutually authenticated client and server.




Enabling certificate authenticationThe [common-modules] stanza in the pdwebpi.conf configuration file defines theuse of all authentication methods. To enable authentication using certificates,assign the word ’cert’ to the authentication parameter:

[common-modules]authentication = cert

The [modules] stanza in the pdwebpi.conf configuration file defines all availableauthentication mechanisms and the associated shared library name. Ensure that theentry for certificate authentication exists:

[modules]cert = pdwpi-certificate-module

Note: For installations on IHS, you must configure the Web server to requestcertificates from clients.

Configuring the certificate authentication mechanismThe cert-ssl parameter specifies the shared library for mapping certificateauthentication information.

On UNIX, the file that provides the built-in mapping function is a shared librarycalled libpdwpi-sslauthn. On Windows, the file that provides the built-in mappingfunction is a DLL called sslauthn.

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-mechanisms] stanza of the pdwebpi.conf configuration file.

Solaris:

[authentication-mechanisms]cert-ssl= libpdwpi-sslauthn.so

Windows:

[authentication-mechanisms]cert-ssl = pdwpi-sslauthn.dll

Note: The pdwpi-sslauthn CDAS requires the subject DN in the user’s certificate toexactly match the LDAP DN of the user. If you need to use a morecomplicated mapping, a customized CDAS will need to be developed. Referto the IBM Tivoli Access Manager for e-business Web Security Developer Referencefor instructions on building CDAS modules, these instructions also apply tothe Plug-in for Web Servers.

Configuring token authentication

Tivoli Access Manager Plug-in for Web Servers supports authentication using atoken passcode supplied by the client.

SecurID Token authenticationThe plug-in token authentication process requires the RSA SecurID client, installedand configured on server where the plug-in is installed, to communicate with aremote RSA server. The supported SecurID client version is 5.1.




RSA’s ACE/Servers authenticate several different tokens, including software tokensand hand-held microprocessor-controlled devices. SecurID Software Tokens are

binary programs running on a workstation, installed on a smart-card, or runningas a plug-in to a Web browser. SecurID Software Tokens can run as an application.The application displays a window into which a user enters a PersonalIdentification Number (PIN), and the Software Token computes the passcode. Theuser can then authenticate to the plug-in by entering the passcode into a login

form.

The most typical form of SecurID Token is the hand-held device. The device isusually a key fob or slim card. The token can have a PIN pad, onto which a userenters a PIN, in order to generate a passcode. When the token has no PIN pad, thepasscode is created by concatenating the user’s PIN and tokencode. A tokencode ischanging number displayed on the key fob. The tokencode is a number generated

by the SecurID token at one minute intervals. A user then enters the PIN andtokencode to authenticate to the ACE/Server.

The plug-in supports both RSA token modes:

v Next tokencode mode

This mode is used when the user enters the correct PIN but an incorrecttokencode. Typically, the tokencode must be entered incorrectly three times in arow to send the tokencard into next tokencode mode. When the user inputs thecorrect passcode, the tokencode is automatically changed. The user waits for thenew tokencode, and then enters the passcode again.

v New PIN mode

The token can be in New PIN mode when the old PIN is still assigned. Thetoken is placed in this mode when the administrator wants to enforce amaximum password age policy. The token is also in New PIN mode when thePIN is cleared or has not been assigned. Newly assigned tokens might not yethave a PIN. A PIN can be cleared by an administrator when the user hasforgotten it or suspects that it has been compromised.

SecurID PINs can be created in different ways:v User-defined

v System-generated

v User-selectable

PINs modes are defined by the method of creation, and by rules that specifyparameters for password creation and device type.

The plug-in supports the following types of user-defined PINs:

v 4-8 alphanumeric characters, non-PINPAD token

v 4-8 alphanumeric characters, password

v 5–7 numeric characters, non-PINPAD token

v 5-7 numeric characters, PINPAD token

v 5-7 numeric characters, Deny 4-digit PIN

v 5-7 numeric characters, Deny alphanumeric

The plug-in does not support the following types of new PINs:

v System-generated, non-PINPAD token

v System-generated, PINPAD token

v User-selectable, non-PINPAD token

v User-selectable, PINPAD token




Token users cannot reset their PIN without an ACE administrator first clearing thetoken or putting it in new PIN mode. This means users with valid PINs cannotpost to pkmspassword.form. Attempts to access this form return an error message.

Authentication workflow for tokens in new PIN modeThe following process occurs for Authentication of tokens in new PIN mode:

1. A client (browser) requests a protected Web object requiring token

authentication.2. The plug-in returns an authentication page, requesting username and

passcode.

3. The user fills in their username and tokencode and submits form to theplug-in’s authentication library. When the user has no PIN, either because thetokencard is new or the administrator reset the PIN, the tokencode is the sameas the passcode. When the user has a PIN, but the tokencard is in New PINmode, the user enters the PIN plus the tokencode.

4. The plug-in’s token authentication library sends the authentication request tothe ACE/Server.

5. The ACE/Server processes the request as follows:

a.If the authentication is unsuccessful, the result is returned to the plug-intoken authentication library, which displays an error page to the client(return to step 2).

b. If the token was not in new PIN mode, the user is authenticated. Theplug-in token authentication library returns success to the plug-in, whichserves the requested protected Web object. (End of authenticationworkflow).

c. If the token is in new PIN mode, the ACE/Server returns the NEW_PINerror code to the plug-in token authentication library.

6. The plug-in presents to the user the password expired form.

7. User enters tokencode or passcode and the new PIN and posts it to theplug-in.

8. The plug-in checks to see if a password strength server is deployed.a. If a password strength server is not deployed, the plug-in continues to

step 9.

b. If a password strength server is deployed, the plug-in checks the new PIN.If the PIN is valid, the plug-in continues to step 9. If the PIN is not valid,he plug-in returns to step 6.

9. The plug-in authentication library sends the tokencode and new PIN to theACE/Server.

10. The ACE/Server returns a response code.

11. If the PIN set call to the ACE/Server is successful, the plug-in returns theoriginally requested protected Web object to the client. If the PIN set call fails,authentication workflow returns to step 6.

Using token authentication with a password strength serverThe plug-in also supports a password strength server that is specific to anauthentication mechanism. This support enables security architects to developdifferent password strength policies for different authentication methods whileusing only the plug-in authentication mechanisms. A four-digit, numeric PIN, forexample, may qualify for the ACE/Server but would fail against a more stringentpassword strength server.




Enabling token authenticationThe [common-modules] stanza in the pdwebpi.conf configuration file defines theuse of all authentication methods. To enable authentication using tokens, assign theword ’token’ to the authentication parameter.

When authentication using tokens is enabled then tokens must also be configured

for post-authorization processing. In the [common-modules] stanza of theconfiguration file, construct a post-authzn parameter and assign it the value’token’. The [common-modules] stanza should include the following two entries:

[common-modules]authentication = tokenpost-authzn = token

The [modules] stanza in the pdwebpi.conf configuration file defines all availableauthentication mechanisms and the associated shared library name. Ensure that theentry for token authentication exists:

[modules]token = pdwpi-token-module

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

v On Windows, the file that provides the built-in mapping function is a DLLcalled xtokenauthn.

The token shared library is installed as part of the Tivoli Access Manager WebSecurity Runtime (PDWebRTE) package. The location of this shared library is:

UNIX /opt/pdwebrte/lib

Windowsc:\Program Files\Tivoli\PDWebRTE\bin

By default, this built-in shared library is hard-coded to map SecureID tokenpasscode data. You can customize this file to authenticate other types of specialtoken data and, optionally, map this data to a Tivoli Access Manager identity. Referto the IBM Tivoli Access Manager for e-business Web Security Developer Reference forAPI 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-mechanisms] stanza of the pdwebpi.conf configuration file.

For example:

Solaris:

[authentication-mechanisms]token-cdas = libxtokenauthn.so

Windows:

[authentication-mechanisms]token-cdas = xtokenauthn.dll




Customizing token response pagesThe token-login-form parameter in the [token-card] stanza of the configuration filedefines the file name of the form presented to the user client during a token logon.The path of the file should be relative to the translated plug-in HTML directory(for example, pdwebpi/nls/html/lang/charset). Where lang is taken from the NLSconfiguration. On US English systems, the lang directory is called C and charset is

utf-8.

The next-token-form parameter in the [token-card] stanza defines the formdisplayed to the user client to request the next token. The client is requested toenter another token when the server cannot successfully authenticate the user fromthe first. Inability to authenticate the user can be caused by a number of reasons.Most commonly, though, the error occurs because the client and server clocks arenot synchronized. When authentication cannot succeed using the first token, thepage specified in the next-token-form parameter is displayed to prompt for thenext token.

The token-card stanza has the following format:

[token-card]

token-login-form = tokenlogin.htmlnext-token-form = nexttoken.html

Configuring SPNEGO authentication

SPNEGO authentication provides a Single Signon (SSO) capability for Windowsuser accounts when protected objects are accessed using Internet Explorer. WithSPNEGO authentication the plug-in performs the server-side of the negotiation,Internet Explorer performs the client side.

When a user requests access to a secure Web server, Internet Explorer employs theuser’s Windows login credentials to participate in a negotiation with the Webserver to prove the user’s authenticity. Once the server has confirmed the user’s

identity, they are granted access if:v the user is a member of the domain,

v SPNEGO has been enabled in the Authorization Server,

v the Authorization Server permits access.

Users accessing resources protected by plug-in SPNEGO authentication who arenot members of the domain or are using browsers other than Internet Explorermust authenticate using another method, for example Basic Authentication orforms.

Note: SPNEGO authentication module functionality can only operate correctly if the Web server is configured to allow anonymous access. In the case of IIS,

Integrated Login must be unchecked, and Anonymous Access checked. In thecase of other Web servers, the standard configuration should be used.

Platform and user registry supportThe SPNEGO authentication mechanism is available on all supported Webserver/platform/user-registry combinations.

When Active Directory is not the Tivoli Access Manager user registry, users must be replicated between the Active Directory registry and the Access Manager userregistry.




Upgrading SPNEGO configuration from version 4.1 to 5.1Tivoli Access Manager Plug–in for Web Servers version 4.1 provided the spnegomodule. In version 5.1 of the plug-in, the functionality of this module has beenincorporated into three separate modules: spnego, ntlm and web-server-authn.There is no automatic process for moving your 4.1 SPNEGO configuration to 5.1 —you will need to reconfigure manually. The following table shows equivalent 5.1

configuration settings against those of version 4.1.

There are two situations:

v With the web-server-does-authn parameter in the [spnego] stanza of the version4.1 configuration file set to true.

v With the web-server-does-authn parameter in the [spnego] stanza of the version4.1 configuration file set to false.

Table 12. Equivalent SPNEGO configuration between version 4.1 and 5.1.

Plug-in Version 4.1 Plug-in Version 5.1

[common-modules]authentication = spnegoauthentication = BA

session = spnegosession = session-cookie

[spnego]web-server-does-authn = true

[common-modules]authentication = web-server-authn

session = session-cookie

Refer to “Configuring Web serverauthentication (IIS platforms only)” on page77 for further configuration options.

[common-modules]authentication = spnegoauthentication = BA

session = spnegosession = session-cookie

[spnego]

web-server-does-authn = false

[common-modules]authentication = spnegoauthentication = ntlmauthentication = BA

session = session-cookie

Refer to “Configuring NTLM authentication

(IIS platforms only)” on page 76 for furtherconfiguration options.

LimitationsThe following plug-in features are not supported with SPNEGO authentication:

v POP or session timer based reauthentication of SPNEGO authenticated clients.

v Password change using pkmspasswd for user registries other than ActiveDirectory.

v Mapping of a username through a CDAS.

v SPNEGO clients cannot log out of the plug-in. Clients must log out from the

workstation. Clients that access plug-in pkms command pages (excepting switchuser) receive the PKMS help page.

v Reauthentication when the inactive session timer expires for SPNEGO clients.The user cache entry is deleted but the session ID is retained. Information in theheader received from the SPNEGO client is used to reauthenticate. The clientdoes not have to log in again, but the client receives a new session cache entry.

v Reauthentication when a user accesses an object with a reauthentication policyattached. In this case access is denied, and user receives a message stating thatreauthentication is required.




Windows desktop single signon configurationThis section contains the configuration steps that must be completed to implementWindows desktop single signon using SPNEGO authentication with the plug-in.Not all steps are required on each platform. To configure SPNEGO authentication,complete each of the following steps:

Step 1: Configure the plug-in server into Active Directory domainTo participate in a Kerberos exchange with Internet Explorer, the plug-in servermust have an identity in the Active Directory Kerberos domain. This requires thatthe plug-in be registered with the Active Directory domain controller. The InternetExplorer browser can then employ the user’s Windows login credential to accessthe plug-in enhanced server.

See the Microsoft documentation for instructions on how to add an identity for theplug-in server host into an Active Directory domain.

Notes:

1. On Windows, the default plug-in server (first server instance) uses the LocalService Account identity when contacting the Active Directory domaincontroller.

2. On UNIX, ensure that the user name matches the host name of the plug-inserver host. Do not use the full domain name. For example, for the systemdiamond.subnet2.ibm.com, create a user diamond. Do not require the user tochange password at next log in. Do not set the password to expire.

Step 2: Map Kerberos principal to Active Directory userThe Internet Explorer client request to the Active Directory domain controllerrequests access to a Kerberos principal of name:

HTTP/DNS_name_of_plug-in_server@Active_Directory_domain_name

This name must be mapped to the Active Directory user that represents the plug-inenhanced server instance, as created in Step 1 above.

This mapping requires the Windows ktpass utility. The ktpass utility might not beloaded on the Windows system by default. It can be obtained from the WindowsSupport Tools package on the Windows CDs.

Windows: Register the service principal name for the plug-in server. On theActive Directory domain controller, run the ktpass command. For example, whenthe plug-in host is diamond.subnet2.ibm.com, and the Active Directory domain isIBM.COM the command is:

ktpass -princ HTTP/[email protected] -mapuser diamond

UNIX: Complete the following steps:

1. On UNIX systems, in addition to mapping the user, you must create a keytab

file for use when signing in to the Kerberos domain. The syntax is (entered asone line):

ktpass -princ HTTP/DNS_name_of_WebPI_server@ Active_Directory_domain_name-pass your_password -mapuser WebPI_server_instance-out full_path_to_keytab_file -mapOp set

The user identity specified by the -mapuser option in the above command isthe Active Directory user. The password specified here resets the password forthe Active Director user. A highly secure password, such as a randomlygenerated password, is preferred. The location of the keytab file is arbitrary.




Retain this password, for use in a later step to test your Kerberos configuration(when testing authentication from a UNIX machine to the Active Directory KeyDistribution Center).

2. Transfer the keytab file to the UNIX system. Ensure that a secure transfermethod is used. The recommended location is:

/opt/pdwebpi/etc/key_tab_filename

3. For best security practice, delete the keytab file from the Windows system.4. On the UNIX system, assign ownership of the file to pdwebpi, and restrict

permissions on the keytab file so that only the owner can access it. Forexample:

# chown pdwebpi keytab_file# chgrp pdwebpi keytab_file# chmod 600 keytab_file

5. For UNIX servers, repeat the above steps for each plug-in instance.

Step 3: Install Kerberos runtime client (UNIX only)The server where the plug-in is installed must have a Kerberos runtime installed.On Windows systems, the Kerberos runtime client is part of the operating system.No additional packages are required.

On UNIX systems, install the appropriate package:

v AIX

IBM Network Authentication Service Client.

This client can be found in the AIX expansion pack.

v Solaris

– IBM Network Authentication Service Client.

This client is included on the Tivoli Access Manager Web Security CD. Usepkgadd to install.

– SUN Kerberos Client SUNWkr5cl.

This is required by the IBM Network Authentication Service Client.

This package is part of the SEAM package, and can be downloaded from theSun Web site.

v Linux

MIT Kerberos v1.2.5

Step 4: Configure Kerberos client (UNIX only)The Kerberos client installed in the previous step must be configured. This requirescreation or modification of a Kerberos configuration file. On Solaris and AIX thefile is, /etc/krb5/krb5.conf, on Linux the file is, /etc/krb5.conf. Complete theinstructions that apply to your operating system:

AIX

Use the mkkrb5clnt utility. This utility creates and completes /etc/krb5/krb5.conf.

1. Run mkkrb5clnt. The syntax is:

mkkrb5clnt -r Active_Directory_domain -c Active_Directory_controller_DNS-s Active_Directory_controller_DNS -d local_DNS_domain

For example:

mkkrb5clnt -r IBM.COM -c dc1.ibm.com -s dc1.ibm.com -d dns.com

2. Manually edit krb5.conf to remove any cryptographic settings not supported by Active Directory.




[libdefaults]default_tkt_enctypes = des-cbc-md5 des-cbc-crcdefault_tgs_enctypes = des-cbc-md5 des-cbc-crc

This step removes des3-cbc-sha1.

Solaris and Linux

Manually edit krb5.conf. Customize the following information for your domain:

v Realm. For example: IBM.COM

v Active Directory controller server name. For example, dc1.

v Domain name. For example, ibm.com.

v DNS name. For example, ibm.com. Using the example values above, the contentsof the Kerberos configuration file would include the following entries:

A partial listing of krb5.conf:

[libdefaults]default_realm = IBM.COMdefault_tkt_enctypes = des-cbc-md5 des-cbc-crcdefault_tgs_enctypes = des-cbc-md5 des-cbc-crc

[realms]IBM.COM = {kdc = dc1.ibm.com:88admin_server = dc1.ibm.com:749default_domain = ibm.com}

[domain_realm]dc1.ibm.com = IBM.COM.ibm.com = IBM.COM

The last line in the example file above ( .ibm.com = IBM.COM ) represents the DNSdomain in which the plug-in enhanced server operates and to which the userconnects. Note the dot (.) in front of the IBM domain in the last line. This acts as awildcard for all subdomains and hosts in the ibm.com domain.

Note: On United Linux which uses a version of Kerberos called Heimdal, it may be necessary to add the following lines to the [libdefaults] stanza tofacilitate testing.

[libdefaults]default_etypes = des-cbc-md5 des-cbc-crcdefault_etypes_des = des-cbc-md5 des-cbc-crc

Step 5: Verify authentication of Web server principal (UNIX only)Use the kinit program to verify that the Kerberos principal for the plug-inenhanced server can authenticate. Use the password specified when you ranktpass in Step 2:

# /usr/krb5/bin/kinit [email protected] for [email protected]: server_password# klist

You should see some output from klist showing the credentials [email protected]

Note: The location of the kinit utility might vary depending on the operatingsystem platform.




Step 6: Verify plug-in authentication using the keytab file (UNIXonly)Verify that the plug-in can authenticate using the keytab file created in Step 2.Enter the following kinit command as one continuous line:

# kinit -k -t /var/pdweb/keytab-diamond/diamond_HTTP.keytabHTTP/[email protected]# klist

You should see some output from klist showing the credentials forHTTP/[email protected]

Step 7: Enabling SPENGO authentication within the plug-inTo enable SPNEGO authentication within the plug-in:

1. Assign the value, spnego, to the authentication parameters in the[common-modules] stanza of the plug-in configuration file, pdwebpi.conf.

[common-modules]authentication = spnego

2. Within the [authentication-mechanisms] stanza, set the kerberosv5 parameterto the absolute path of the Security Translation Layer Interface (stli) sharedlibrary. For example:

AIX: kerberosv5 = /opt/PolicyDirector/lib/libstliauthn.a

Other UNIX:kerberosv5 = /opt/PolicyDirector/lib/libstliauthn.so

Windows:kerberosv5 = C:\PROGRA~1\Tivoli\POLICY~1\bin\stliauthn.dll

3. Within the [spnego] stanza, set:

v spnego-krb-service-name to either HTTP orHTTP@ fully_qualified_host_domain_name.

v spnego-krb5-keytab-file to the full pathname of the keytab file that is to beused by the plug-in. This value is only required on UNIX platforms. On

Windows platforms, the option is ignored.

Step 8: Enabling SPENGO authentication within the Web serverTo enable SPNEGO for IIS ensure the access policy of the Web server — set in theDirectory Security tab — is set to anonymous. For other Web servers the defaultconfiguration is acceptable.

To enable SPNEGO within the Internet Explorer client:

1. If the plug-in is installed on UNIX, configure the Local Intranet zone to includethe name of the UNIX server:

a. Select Tools → Internet options.

b. From the Security tab select either Local Intranet → Sites → Advanced orTrusted Sites → Sites.

c. Enter the UNIX server on which the plug-in is running.

2. Configure the integrated login behavior:

a. Select Tools → Internet Options.

b. From the Security tab click Custom Level.

c. Scroll down to the Logon section in the Security Settings dialog, and selecteither Automatic... or Prompt... depending on the functionality you require.

Note: If the Trusted Sites option was selected in step 1 above, then the userwill never be prompted to enter username and password information.




3. If the client is version 6 of Internet Explorer then you need to configure theIntegrated Windows login. To do this:


b. From the Advanced tab, check Enable Integrated Windows Login.

c. Restart the browser for the change to take effect.

Troubleshooting tipsKerberos configuration

v Problem: When testing the keytab created for a UNIX server using kinit, you getthe error ″Clock skew too great while getting initial credentials.″

Solution: You must keep clocks synchronized when using Kerberos. For apermanent solution, deploy some kind of time synchronization service on yourmachines. For a temporary solution, adjust the clocks on the machines so theyare within one minute of each other.

v Problem: When testing the keytab created for a UNIX server using kinit, you getthe error ″Preauthentication failed while getting initial credentials″ or ″Passwordincorrect while getting initial credentials″.

Solution: The key in the keytab file is incorrect. Make sure you generated thekeytab file correctly, with the correct principal name, Active Directory username, and path.

v Problem: kinit crashes when running kinit -k -t

Solution: Some versions of kinit don’t deal properly with problems when anentry is not found in a keytab file. Double-check that the keytab file has theexact same entry you are passing to kinit.

Tivoli Access Manager Plug-in for Web Servers configuration

v When a problem occurs, consider enabling trace for SPNEGO. Add an entry tothe routing file. The routing file is located under the installation directory, inetc/routing. Example entry:

bst:*.9:TEXTFILE:install_path/log/spnegotrace.log

On UNIX, the default plug-in installation directory is /opt/pdwebpi. Substitutethe path for your installation directory. Stop and restart the plug-in. Look forerror messages in the trace file.

v Problem: The plug-in server will not start. The log file contains an error saying″Authentication method (kerberosv5) is not configured.″

Solution: Enable the kerberosv5 authentication method in the[authentication-mechanisms] stanza in the plug-in configuration file.

v Problem: The plug-in will not start. The error message is ″The security servicefunction gss_import_name returned major error code 131072 and minor errorcode -1765328168.″

Solution: The principal name specified in the configuration file was invalid. Itshould have the form ″HTTP@host_name″ where host_name is the fully qualifiedDNS name of a computer which is configured into the Kerberos realm.

v Problem: The plug-in server does not start. The error message is: ″The securityservice function gss_acquire_cred returned major error code 851968 and minorerror code 39756033″.

Solution: The principal name in the configuration file does not match any of thekeys in the specified keytab file. The keys in the keytab file have names likeHTTP/host_name@REALM. The principal name should have the formatHTTP@host_name




v Problem: When a user attempts to access the plug-in they receive an errorsaying ″HPDIA0100E An internal error has occurred.″ The plug-in trace log filecontains a message saying ″The security service function gss_accept_sec_contextreturned major error code 851968 and minor error code -1765328347.″

Solution: The system clock on the client machine is out of sync with the systemclock on the plug-in server. You must keep clocks synchronized when usingKerberos. For a permanent solution, deploy a time synchronization service on

your machines. For a temporary solution, adjust the clocks on the machines sothey are within one minute of each other.

Other configuration items to check when problems occur

v Check that the file permissions and ownership of the keytab file allow access bythe plug-in authorization server as mentioned in “Step 2: Map Kerberosprincipal to Active Directory user” on page 71.

v Check that the keytab file contains valid data and keys for the correct principalname by using the ktutil utility to display information contained in the keytabfile.

v Check that the DNS configuration for the entire domain (domain controller andclients) is correct and that names resolve correctly and match the values in the

service principal name configuration items in various locations (keytab file,plug-in configuration file, etc.).

v Check that system clocks are synchronized and that a distributed time service ismaintaining clock synchronization on all systems in the domain.

v Check that the network configuration is correct and that there are no issues suchas congestion, incorrect routing, name collision, and so on. Ensure that thelatency is within tolerable limits. Be sure that firewalls, NAT, and other networksecurity services do not interfere with the operation of the domain.

Configuring NTLM authentication (IIS platforms only)

Legacy versions of the Windows platform provided a rudimentary Single Signon

(SSO) mechanism known as NT Lan Manager (NTLM) authentication. This methodof authentication is based on hashing algorithms providing a similar level of security and operation as that of Basic Authentication. The plug-in supports NTLMauthentication to facilitate backwards compatibility between modern Windowsplatforms (XP, 2000) and older systems such as Windows NT. The plug-in supportsNTLM on the Windows IIS platform only, UNIX platforms are not supported.

To enable NTLM authentication, assign the value, ntlm, to the authenticationparameter in the [common-modules] stanza of the plug-in configuration file,pdwebpi.conf.

[common-modules]authentication = ntlm

To enable NTLM authentication ensure the access policy of the IIS Web server isset to anonymous.

To configure Internet Explorer for participation in NTLM (and SPNEGO)exchanges:







c. Scroll down to the Logon section in the Security Settings dialog, and selecteither Automatic... or Prompt... depending on the functionality you require.



a. Select Tools → Internet Options


c. Restart the browser for the change to take effect.

The use-pre-windows-2000-logon-name parameter in the [ntlm] stanza of theplug-in configuration file can be used to configure either the Windows 2000 or thepre-Windows 2000 username formats. By default, the ntlm module uses theWindows 2000 logon name to represent the authenticated user in Tivoli AccessManager. This is the username portion of the [email protected] logon name.The use-pre-windows-2000-logon-name parameter allows the pre-Windows 2000logon name to represent the authenticated user in Tivoli Access Manager. This isthe username portion of the DOMAIN\USERNAME logon name. This parameter is

ignored if Tivoli Access Manager uses Active Directory as its user registry. WithActive Directory, the user’s Tivoli Access Manager user name is always theusername portion of the [email protected] logon name.

Configuring Web server authentication (IIS platforms only)

Some Web servers provide the ability to perform authentication natively. Oneexample of this is the capability of IIS to perform Integrated Windows Login(SPNEGO, NTLM or BA). The plug-in can be configured to utilize this native Webserver authentication trusting that the Web server has performed adequately secureauthentication checks. Currently Web server authentication for the plug-in is onlysupported on IIS.

To enable Web server authentication in the plug-in, assign the value, web_svr_authn,to the authentication parameter in the [common-modules] stanza of the plug-inconfiguration file,pdwebpi.conf.

[common-modules]authentication = web_svr_authn

To configure Internet Explorer for participation in NTLM (and SPNEGO)exchanges:




c. Scroll down to the Logon section in the Security Settings dialog, and select

either Automatic... or Prompt... depending on the functionality you require.





c. Restart the computer for the change to take effect.




The web-server-authn authentication module can be configured to use either theWindows 2000 or the pre-Windows 2000 username formats by setting theuse-pre-windows-2000-logon-name parameter in the plug-in configuration fileunder the [web-server-authn] stanza.

By default, the web-server-authn module uses the Windows 2000 logon name torepresent the authenticated user in Tivoli Access Manager. This is the username

portion of the [email protected] logon name. The use-pre-windows-2000-logon-name parameter allows the pre-Windows 2000 logon name to represent theauthenticated user in Tivoli Access Manager. This is the username portion of theDOMAIN\USERNAME logon name. This parameter is ignored if Tivoli AccessManager uses Active Directory as its user registry. With Active Directory, the user’sTivoli Access Manager user name is always the username portion of [email protected] logon name.

Configuring Failover authentication

This section contains the following topics:

v “Failover authentication concepts”

v“Failover authentication configuration” on page 85

Failover authentication conceptsThe plug-in provides an authentication method that enables an authenticatedsession between a client and a plug-in enhanced Web server to be preserved whenthe plug-in enhanced server becomes unavailable. The method is called failoverauthentication. Failover authentication enables the client to connect to anotherplug-in enhanced Web server, and create an authentication session containing thesame user session data and user credentials.

The failover cookie feature is typically used for clients connecting to a replicatedfront-end Web server through a load-balancing mechanism. A failover cookie

prevents forced re-authentication when the original session between server andclient becomes unavailable.

With failover cookies configured for post-authorization processing, the plug-inencrypts credential data in either a server-specific or domain-wide cookie. Thecookie is placed on the browser when the client first connects. If the initial Webserver session is lost, the cookie is presented to the next server that the client isredirected to. The cookie is used for automatic re-authentication so the client isspared the task of re-authenticating manually. The plug-ins on replicated serversshare a common key that decrypts the credential information held in the cookieand establishes a new session.




Client Browser Load Balancer

www.ibm.cominstance 1



SD

The diagram above shows a typical architecture that would benefit from the use of failover cookies. Three identical instances of the same Web server are located

behind a load balancing server that directs requests to one of the three serversdepending on load and availability. For example, assume that each instance of www.ibm.com is configured to authenticate client accesses using failover cookiesand also configured to use failover cookies for post-authorization processing. Aclient accesses www.ibm.com and is directed to instance 1 of the server andauthenticates successfully. The client’s credential is encrypted and stored in adomain wide cookie that is stored at the client browser. If, during the session, the

client needs to accesses either instance 2 or instance 3 of www.ibm.com (forexample, if instance 1 fails or demand becomes too great) then the failover cookiestored in the client’s browser is used for automatic re-authentication without theneed for user intervention. The original session start time is kept with the cookieso that the integrity of the session lifetime remains valid when an automaticredirection to a failover server takes place.

Failover authentication scenarioAs part of the failover capability, the plug-in supports user authentication usingthe failover cookie. The failover cookie is a server-specific cookie or a domain cookie.The failover cookie contains client-specific data, such as user name, cookie-creationtime stamp, original authentication method, and an attribute list. The attribute listcontains by default the user’s authentication level. The plug-in can be configured

to add specific extended attributes to the attribute list.

The plug-in encrypts this client-specific data. The replicated plug-in enhanced Webservers share a common key that decrypts the cookie information. When thereplicated plug-in server receives this cookie, it decrypts the cookie, and uses theuser name and authentication method to regenerate the client’s credential. Theplug-in can also be configured to copy any extended attributes from the cookie tothe user credential. The client can now establish a new session with a replicaplug-in enhanced server without being prompted to log in.

Note: Failover cookies can be used over either HTTP or HTTPS.

Figure 5. Typical server architecture for failover cookies.




The sequence of events for a failover authentication event is:

1. The client (browser) attempts to access a protected resource. The client requestgoes to a load balancer that controls access to the replicated servers.

2. The load balancer selects a target server and forwards the user request.

3. The client successfully authenticates to the server through the plug-in using oneof the supported authentication methods.

4. The plug-in creates a failover authentication cookie that contains clientauthentication information, and sends the cookie to the client.

5. The client sends the cookie through the load balancer to the plug-in with eachsubsequent request. The plug-in processes each request.

6. If the load balancer finds that the plug-in enhanced server is not accessible, theclient request is directed to another replicated plug-in enhanced server.

7. The plug-in on the replicated server is configured to check for the existence of afailover authentication cookie every time it attempts to authenticate a user.

8. The plug-in uses the information in the cookie to establish a session with theclient, without requiring the client to manually log in again. The client’s sessiondata and user credential are built, and the request for the protected resource isprocessed.

9. The change of session from one plug-in enhanced server to another istransparent to the client. Because the plug-in enhanced servers contain identicalresources, the client session continues uninterrupted.

Failover authentication libraryThe plug-in provides a built-in failover authentication shared library for each of the supported authentication methods. Each failover shared library mimics theshared library for the corresponding authentication method and, additionally,recovers any extended attributes that were originally placed in the user’scredential. When a failover authentication event occurs, the plug-in calls thefailover authentication library that matches the last authentication method used bythe user before the original server failed.

The plug-in supplies failover authentication function for the followingauthentication methods:

v Basic or forms authentication (also known as password authentication),

v Token card authentication,

v Certificate authentication,

v HTTP request authentication

v Cross-domain single signon (CDSSO),

v Kerberos authentication (SPNEGO).

The plug-in supplies one standard failover shared library that functions for all theabove authentication methods. This library is called libfailoverauthn on UNIX

systems, and failoverauthn on Windows.

Note: Alternatively, you can supply a custom CDAS library that provides specificauthentication capabilities required by your environment.

For example, the plug-in can be configured to support forms authentication andfailover authentication. When the plug-in starts, both the forms authenticationshared library and the ″failover-forms″ authentication library are loaded. The userauthenticates using forms authentication. The plug-in server sends a failover




authentication cookie to each client (browser). The cookie data specifies that thecookie was created in a forms authentication environment.

When the plug-in enhanced server becomes unavailable, the failover cookie is sentto a second plug-in enhanced server. The second server, which is typically areplicated server, also has both the forms authentication shared library and theforms-failover library loaded in the plug-in. The plug-in instance on the second

server receives the failover cookie, and examines it to determine the user’sprevious authentication method. The plug-in on the second server calls out to thefailover–forms authentication shared library to extract the necessary data from thecookie, and then uses that data to authenticate the user and get a user credential.

For example, when both forms authentication and failover authentication areenabled in a replicated plug-in environment, two separate libraries must beconfigured in the plug-in configuration file. One library specifies the formsauthentication method library. The other library specifies the failoverauthentication method library. Example configuration file entries would be:

[authentication-mechanisms]passwd-ldap = /opt/pdweb/lib/libldapauthn.sofailover-password = /opt/pdweb/lib/libfailoverauthn.so

In this example, the passwd-ldap stanza entry specifies the plug-in’s built-in formsauthentication library. The failover-password stanza entry specifies the plug-in’s

built-in failover authentication library.

Addition of data to a failover cookieThe plug-in automatically adds specific data from the user session to each failoverauthentication cookie. The plug-in can be configured to add additional informationfrom the client data maintained in the credential cache. Also, the plug-in can beconfigured to add user-defined data specific to their deployment. For example,user attributes obtained by a custom cross-domain authentication service can beadded to the cookie.

By default the plug-in adds the following data to each cookie:

v User name

This name corresponds to the name used to identify the user in the user registry

Note: When an authenticated user has used the plug-in’s switch user function toobtain the effective identity of another user, the identity of the other useris not added to the cookie. Only the original authenticated user identity isadded to the cookie.

v Authentication method

The authentication method used to authenticate the user to the plug-in.

v Cookie creation time

The system time when the cookie was created.

The plug-in also creates an attribute list containing additional data. By default, theattribute list contains one value:

v Authentication level

An integer value that corresponds to the plug-in’s authentication strength level(also an integer value) that is assigned on the local plug-in enhanced server tothe authentication method. Authentication strength, also known as step-upauthentication, enables a user to authenticate to a different authenticate methodwithout having to logout.




plug-in configuration file, the administrator can ensure that the attributes areavailable to add to the re-created user credential during failover authentication.

Note: The maximum size of a failover authentication cookie is 4 kilobytes (4096 bytes).

Extraction of data from a failover cookie

When a failover authentication event occurs, the plug-in receives a failoverauthentication cookie and by default extracts the following data from each cookie:

v User name,

v Authentication method,

v Cookie creation time.

The plug-in first determines if the cookie is valid by subtracting the cookie creationtime from the system time, and comparing this value against the plug-inconfiguration file entry for failover cookie lifetime.

If the cookie lifetime has been exceeded, the cookie is not valid, and failoverauthentication is not attempted. If the cookie lifetime has not been exceeded, the

plug-in uses the user name and authentication method to authenticate the user and build a user credential.

The plug-in next checks configuration settings to determine if additional cookiedata should be extracted and evaluated. Note that the plug-in does not by defaultextract any other attributes from the failover authentication cookie. Each additionalattribute to be extracted must be specified in the plug-in configuration file.Wildcard pattern matching can be used to obtain groups of attributes.

The plug-in can be configured to extract the following defined attributes:


When this value is extracted, the plug-in uses it to ensure that the user is

authenticated with the authentication method necessary to maintain the specifiedauthentication level.

Note that the plug-in can obtain authentication levels from several differentplaces:

– Failover cookie

– Failover authentication library

– Cross-domain authentication service

– Entitlement service

The authentication level extracted from the failover cookie takes precedence overlevels obtained from the other places.

v Session lifetime timestamp

The plug-in can use this timestamp to determine if the user’s entry in theoriginal server’s session cache would have expired. If it would have, the plug-indiscards the cookie and all its potential credential attributes. The session lifetimeis not preserved, and the user is prompted to log in.

v Session inactivity timestamp

The plug-in can use this timestamp to determine if the user’s entry in theoriginal server’s session cache would have been inactive for too long. If it wouldhave, the plug-in discards the cookie and all its potential credential attributes.The session lifetime is not preserved, and the user is prompted to log in.




Note: Successful use of these timestamps requires synchronization of clocks between replicated plug-in servers. If clock skew becomes great, sessionswill expire or become inactive at unintended times.

v Additional extended attributes

These include user-defined customized attributes, such as those generated bycross-domain authentication services. The plug-in adds the attributes to the user

credential.

Attributes that are not specified in the plug-in configuration file will be ignoredand not extracted. In addition, administrators can specify that certain attributesmust be ignored during failover cookie extraction. Although ignore is the default

behavior, this specification can be useful, for example, to ensure that user attributesare obtained from the user registry instead of from the failover cookie.

Domain-wide failover authenticationThe plug-in supports an optional configuration that enables failover authenticationcookies to be marked as available for use during failover authentication to any andall other plug-in enhanced servers in the Tivoli Access Manager domain. Thisconfiguration option enables failover authentication cookies to be used in

deployments that do not necessarily have a load balancer and replicated plug-inenhanced servers.

When a client session goes through a failover authentication event to a replicatedplug-in enhanced server, the client continues to access the same set of protectedresources. When a client session goes through a failover authentication event to aplug-in enhanced server that is not replicated, it is possible that a different set of resources will be available to the client. In large deployments, this partitioning of resources within the Tivoli Access Manager domain is common. This partitioningcan be done for performance reasons and for administrative purposes.

Domain-wide failover authentication can be used to redirect a client to anotherserver at a time when the client’s requests have led it to request a resource that is

not available through the local server. In this case, the client (browser) is redirectedto another plug-in enhanced server. The receiving plug-in can be configured tolook for failover authentication cookies. The plug-in attempts to authenticate theclient and recognizes the failover authentication cookie. By using the cookie, theplug-in does not need to prompt the client for login information, but instead canestablish a session with the client and construct a valid set of user credentials.

Backwards compatibilityFailover cookies generated by Version 5.1 of the plug-in can be understood andread (consumed) by plug-ins from versions prior to Version 5.1 . Likewise, failovercookies generated by older (pre-Version 5.1) plug-ins can be understood and read(consumed) by Version 5.1 of the plug-in. CDAS modules written to customizefailover cookies for older (pre-Version 5.1) plug-ins will work with Version 5.1 of

the plug-in.

To ensure complete backwards compatibility, the following features are provided:

v The plug-in can be configured to authenticate a user based on failover cookiecontents when the session lifetime timestamp is not present.

The session lifetime timestamp is not present in failover authentication cookiesprior to Version 5.1.

v The plug-in can be configured to authenticate a user based on failover cookiecontents when the session inactivity timestamp is not present.




The session inactivity timestamp is not present in failover authentication cookiesprior to Version 5.1.

v The algorithm used to encrypt client data in failover authentication cookies wasupdated for Version 4.1 of the plug-in. When using the plug-in with versions of the plug-in prior to Version 4.1, a configuration file setting can be set to enableaccess to the older-style cookies.

v

The plug-in can be configured to not use UTF-8 encoding on strings in thefailover cookie. By not using UTF-8 encoding for cookies created on Version 5.1of the plug-in, the cookies can be understood and read (consumed) by older(pre-Version 5.1) plug-ins.

Upgrading failover authenticationIn the plug-in configuration file, the [failover-add-attributes] and[failover-restore-attributes] stanzas replace the pre-Version 5.1 stanza[failover-attributes].

During an upgrade from Tivoli Access Manager Version 4.1 to the current TivoliAccess Manager version, the stanza [failover-attributes] and its contents aremigrated to the [failover-add-attributes] stanza.

The upgrade is automated, and takes place when the plug-in is installed. There isno need for manual updating of these entries.

Failover authentication configurationThis section describes how to configure failover authentication.

If you are not familiar with failover authentication concepts, review “Failoverauthentication concepts” on page 78.

To configure failover authentication, complete the following tasks:

1. Stop the plug-in server.

2. To enable failover authentication, complete each of the following tasks:a. “Enabling authentication using failover cookies” on page 86

b. “Specify the failover authentication library” on page 86

c. “Create an encryption key for cookie data” on page 87

d. “Specify the cookie lifetime” on page 87

e. “Specify UTF-8 encoding on BA headers” on page 63

3. Optionally, you can configure the plug-in to maintain session state acrossfailover authentication sessions. If this is appropriate for your deployment,complete the following instructions:

a. “Add the session lifetime timestamp” on page 89

b. “Add the session activity timestamp” on page 89

c. “Add an interval for updating the activity timestamp” on page 90

4. Optionally, you can configure the plug-in to add extended attributes to thefailover cookie:

v “Add extended attributes” on page 90

5. When you have configured the plug-in to add attributes to the failover cookie,you must configure the plug-in to extract the attributes when reading thecookie:

v “Specify attributes for extraction” on page 91




6. Optionally, you can enable failover authentication cookies for use on anyplug-in enhanced server within the domain. If this is appropriate for yourdeployment, see

v “Enable domain-wide failover cookies” on page 91

7. If you need to maintain backwards compatibility with failover authenticationcookies generated by plug-in enhanced servers from versions prior to Version

5.1, complete the following instructions:a. “Specify UTF-8 encoding on BA headers” on page 63

b. “Require validation of a lifetime timestamp” on page 92

c. “Require validation of an activity timestamp” on page 92

d. “Enable backwards compatibility for encryption” on page 93

8. After completing all the instructions applicable to your deployment, restart theserver.

Enabling authentication using failover cookiesThe [common-modules] stanza in the pdwebpi.conf configuration file defines theuse of all authentication methods. Failover cookies can be configured to performauthentication and post-authorization tasks.

Plug-ins configured for post-authorization processing using failover cookies,encrypt and store a credential as a failover cookie in the transaction response.

Plug-ins, configured to use failover cookies for performing authentication,re-authenticate clients using the encrypted credential from a failover cookie foundin the transaction request.

To enable authentication and post-authorization using failover cookies, assign thereference ’failover’ to the authentication and post-authzn parameters:

[common-modules]authentication = failoverpost-authzn = failover

The [modules] stanza in the pdwebpi.conf configuration file defines all availableauthentication mechanisms and their associated shared library name. Ensure thatthe entry for failover authentication exists:

[modules]failover = pdwpi-failovercookie-module

Specify the failover authentication libraryEdit the plug-in configuration file. In the [authentication-mechanisms] stanza,uncomment the entry for the authentication type (or types) that must supportfailover cookies. Add the name of the plug-in failover cookie library appropriatefor the operating system type.

The default configuration file entry is:[authentication-mechanisms]#failover-password = failover_password_library_filename#failover-token-card = failover_token_card_filename#failover-certificate = failover_certificate_filename#failover-http-request = failover_http_request_filename#failover-cdsso = failover_cdsso_filename#failover-kerberosv5 = failover_kerberos_library

The plug-in supplies one standard failover shared library that functions for all theabove authentication methods. Refer to the following table for the library names.:




Table 13. Failover authentication library file names

Solaris libfailoverauthn.so

Linux libfailoverauthn.so

AIX libfailoverauthn.a

Windows failoverauthn.dll

For example, to enable failover authentication for clients who originallyauthenticated with forms authentication on Solaris, uncomment thefailover-password entry and add the library name:

[authentication-mechanisms]failover-password = libfailoverauthn.so

Alternatively, when you have developed a CDAS library that implements acustomized version of failover authentication for one or more authenticationmethods, insert the name of the custom CDAS as the value for the configurationfile keyword. For example, if you developed a custom CDAS for formsauthentication, enter the absolute path name:

[authentication-mechanisms]failover-password = /dir_name/custom_cdas_failover_library.so

Create an encryption key for cookie dataUse the cdsso_key_gen utility to secure the cookie data. This utility generates asymmetric key that encrypts and decrypts the data in the cookie.

Attention: If you do not configure the plug-in to encrypt failover authenticationcookies, and you have enabled failover authentication, the plug-in will generate anerror and refuse to start. Failover authentication cookies must be encrypted.

1. Run the utility on one of the replicated servers. From a command line, specifythe location of the key file you want to create. You must specify an absolutepath name.

For example:UNIX:

# /opt/pdwebrte/bin/cdsso_key_gen absolute_pathname_for_keyfile

Windows:

MSDOS> C:\Program Files\Tivoli\PDWebrte\bin\cdsso_key_genabsolute_pathname_for_keyfile

You can give the key file any appropriate name, such as/opt/pdwebrte/lib/wpi.key.

2. Edit the plug-in configuration file. In the [failover] stanza, specify the keyfilelocation.

[failover]failover-cookies-keyfile = absolute_pathname_for_keyfile

3. Manually copy the key file to each of the remaining replicated servers.

4. On each replicated server, edit the plug-in configuration file to supply thecorrect path name to failover-cookies-keyfile in the [failover] stanza.

Specify the cookie lifetimeEdit the plug-in configuration file. Specify the valid lifetime for the failover cookie.

[failover]failover-cookie-lifetime = 30




The default lifetime is 30 minutes.

Specify UTF-8 encoding on cookie stringsEdit the plug-in configuration file. Specify whether or not the plug-in should useUTF-8 encoding on strings within the failover cookies.

[failover]use-utf8 = true


UTF-8 should be used when user names or credential attributes in the cookie arenot encoded in the same code page as the one that the plug-in enhanced server isusing. By default, the plug-in supports UTF-8 encoding. When all servers in theplug-in deployment use UTF-8 encoding, leave this value at the default setting of true.

Backwards compatibility

Plug-in installations prior to Version 5.1 did not use UTF-8 encoding. Thus, cookiescreated by these servers do not have UTF-8 encoding on their strings. When a

plug-in instance is operating with a plug-in from versions prior to Version 5.1, theplug-in should not use UTF-8 encoding.

For backwards compatibility, set use-utf8 to false.

[failover]use-utf8 = false


Specify the authentication levelThe plug-in provides a number of different ways to specify an authentication level.For failover cookies, there are two methods that can be used. One method sets the

authentication level in the failover cookie. The other method sets the level whencalling the failover authentication library.

When both methods are used, the authentication level in the failover cookie takesprecedence over the level set when calling the library.

If neither of the methods are configured, the authentication level is set to theauthentication level associated with the failover method by the[authentication-levels] stanza.

The two methods are:

v Specify authentication level in the failover authentication cookie.

Add the authentication level to the plug-in configuration file. You must use thestanza entry keyword AUTHENTICATON_LEVEL:

[failover-add-attributes] or [failover-add-attributes:virtual-host]AUTHENTICATION_LEVEL = add

The actual value for AUTHENTICATION_LEVEL is an integer that the plug-in tracksinternally. You do not need to specify the integer in this stanza.

To retain the authentication level optionally loaded into the cookie by theoriginator, the value must also be configured to be preserved at the receivingend using the following entry:




[failover-restore-attributes] or [failover-restore-attributes:virtual-host]AUTHENTICATION_LEVEL = preserve

v Specify authentication level when calling the failover authentication library.

When configuring either the built-in plug-in failover authentication library or aCDAS library, you can optionally specify an authentication level to assign to theauthenticated user. The authentication level is an integer that maps to a specificauthentication method, as part of the plug-in’s authentication strength feature.

Add a command line argument to the configuration file entry for theappropriate failover authentication library. The syntax is:

[authentication-mechanisms] failover_authentication_method = failover_authentication_libary& -l level_number

The level_number must correspond to a valid integer, as specified in the[authentication-levels] stanza in the plug-in configuration file.

For example, to activate failover authentication for forms authentication on aSolaris systems, and to assign to the user an authentication level of ″3″, createthe following configuration file entry:

[authentication-mechanisms]

failover-password = libfailoverauthn.so& -l 3

Add the session lifetime timestampThe plug-in calculates the session lifetime timestamp by combining the followingvalues:

v Current system time.

v Maximum lifetime in seconds that an entry is allowed to exist in the plug-incredential cache.

This maximum lifetime in seconds is specified in the plug-in configuration file[session] stanza:

[sessions]timeout = 3600

To add this value to the failover authentication cookie, add the following entry tothe plug-in configuration file:

[failover-add-attributes]session-lifetime-timestamp = add

Note that this attribute cannot be set by wildcard matching. The exact entrysession-lifetime-timestamp must be entered.

Add the session activity timestampThe plug-in calculates the session activity timestamp by adding together thesevalues:

v System time.

v Maximum lifetime of inactive entries in the credential cache.The maximum lifetime for inactive entries is set in the [sessions] stanza in theconfiguration file:

[session]inactive-timeout = 600

The default value is 600 seconds.

v Interval for updating the failover authentication cookie.

This value is set in the [failover] stanza in the plug-in configuration file:




[failover]failover-update-cookie = -1

The default value is -1 seconds. A negative integer means the failover cookie isonly updated when authentication occurs or when the credential is refreshed.For more information, see “Add an interval for updating the activitytimestamp.”

To add this value to the failover authentication cookie, add the following entry tothe plug-in configuration file:

[failover-add-attributes]session-activity-timestamp = add

Note that this attribute cannot be set by wildcard matching. The exact entrysession-activity-timestamp must be entered.

Add an interval for updating the activity timestampOptionally, the session activity timestamp in the failover cookie can be updatedduring the user’s session.

This entry contains an integer value for interval (in seconds) between updating thefailover cookie’s activity timestamp.

The default entry is:

[failover]failover-update-cookie = -1

When failover-update-cookie is set to 0, the last activity timestamp is updatedwith each request.

When failover-update-cookie is set to an integer less than 0 (any negativenumber), the last activity timestamp is never updated.

When failover-update-cookie is set to an integer greater than 0, the sessionactivity timestamp in the cookie is updated at intervals of this number of seconds.

The value chosen for this stanza entry can affect performance. See “Addition of data to a failover cookie” on page 81.

Add extended attributesThe plug-in can optionally be configured to place a copy of specified extendedattributes from a user credential into a failover authentication cookie. No extendedattributes are configured by default.

To add extended attributes, add entries to the [failover-add-attributes] stanzain the plug-in configuration file. The syntax is:

[failover-add-attributes]attribute_pattern = add

The attribute_pattern can be either a specific attribute name, or a case-insensitivewildcard expression that matches more than one attribute name. For example, tospecify all attributes with the prefix tagvalue_, add the following entry:

[failover-add-attributes]tagvalue_* = add

The order of the stanza entries is important. Rules that appear earlier in[failover-add-attributes] take priority over those placed later in the stanza.




Attributes that do not match any of the wildcard patterns, or are not explicitlyspecified, are not added to the failover cookie.

Specify attributes for extractionThe plug-in can optionally be configured to extract attributes from a failoverauthentication cookie and place them into a user credential. No attributes areconfigured for extraction by default.

Attributes to be extracted are declared in the [failover-restore-attributes]stanza in the plug-in configuration file. The syntax is:

[failover-restore-attributes]attribute_pattern = {preserve|refresh}

The value preserve tells the plug-in to extract the attribute and add it to thecredential. Values set by this method overrule attributes of the same name thatmay have been set when the authentication CDAS created the new credential.

The value refresh tells the plug-in to conditionally extract the attribute and add itto the credential only if an attribute of the same name was not added when theauthentication CDAS created the new credential.

The attribute_pattern can be either a specific attribute name, or a case-insensitivewildcard expression that matches more than one attribute name. For example, toextract all attributes with the prefix tagvalue_, add the following entry:

[failover-restore-attributes]tagvalue_* = preserve

Attributes that do not match any patterns specified with the preserve value are notextracted from the failover authentication cookie.

The order of the stanza entries is important. Rules that appear earlier in[failover-restore-attributes] take priority over those placed later in the stanza.

The following attributes cannot be matched by a wildcard pattern, but must beexplicitly defined for extraction:


[failover-restore-attributes]AUTHENTICATION_LEVEL = preserve

v Session lifetime timestamp

[failover-restore-attributes]session-lifetime-timestamp = preserve

v Session inactivity timestamp

[failover-restore-attributes]session-inactivity-timestamp = preserve

Enable domain-wide failover cookiesYou can allow a failover authentication cookie to be used by any plug-in withinthe same domain as the plug-in that creates the cookie. This feature is controlled

by a stanza entry in the [failover] stanza.

By default, domain-wide failover cookie functionality is disabled:

[failover]enable-failover-cookie-for-domain = false

To enable this feature, set enable-failover-cookie-for-domain to true:




[failover]enable-failover-cookie-for-domain = true

For information on the effects of enabling this stanza entry, see “Domain-widefailover authentication” on page 84.

Require validation of a lifetime timestampThe plug-in can optionally be configured to require that each failover authenticationcookie contain a session lifetime timestamp. The session lifetime timestamp is notrequired by default. The default configuration file entry is:

[failover]failover-require-lifetime-timestamp-validation = false

This stanza entry is used primarily for backwards compatibility.

Attention: For backwards compatibility with failover cookies created by plug-insprior to Version 5.1, set this entry to false. Failover authentication cookies created

by plug-ins prior to Version 5.1 do not contain this timestamp.

v When this value is false, and the session lifetime timestamp is missing from the

failover cookie, the receiving server will view the cookie as valid.v When this value is true, and the session lifetime timestamp is missing from the

failover cookie, the receiving server will view the cookie as not valid.

v When this value is either false or true, and the session lifetime timestamp ispresent in the failover cookie, the receiving server evaluates the timestamp. If the timestamp is not valid, the authentication fails. If the timestamp is valid, theauthentication process proceeds.

Note: The session lifetime timestamp is configured separately from the sessionactivity timestamp.

Require validation of an activity timestampThe plug-in can optionally be configured to require that each failover authentication

cookie contain a session activity timestamp. The session activity timestamp is notrequired by default. The default configuration file entry is:

[failover]failover-require-activity-timestamp-validation = false

This stanza entry is used primarily for backwards compatibility.

Attention: For backwards compatibility with failover cookies created by plug-insprior to Version 5.1, set this entry to false. Failover authentication cookies created

by plug-ins prior to Version 5.1 do not contain this timestamp.

v When this value is false, and the session activity timestamp is missing from thefailover cookie, the receiving server will view the cookie as valid.

v

When this value is true, and the session activity timestamp is missing from thefailover cookie, the receiving server will view the cookie as not valid.

v When this value is either false or true, and the session activity timestamp ispresent in the failover cookie, the receiving server evaluates the timestamp. If the timestamp is not valid, the authentication fails. If the timestamp is valid, theauthentication process proceeds.

Note: The session activity timestamp is configured separately from the sessionlifetime timestamp.




Enable backwards compatibility for encryptionFor Tivoli Access Manager Version 4.1, the level of security for the encryption of the failover authentication cookie was increased. This encryption algorithm is not

backward compatible. If you are integrating failover authentication cookies withplug-in enhanced servers using versions of Tivoli Access Manager prior to Version4.1, you must specify a configuration file setting in the plug-in configuration file toenable backwards compatibility.

Backwards compatibility with the older encryption algorithm is not enabled bydefault:

[pdweb-plugins]pre-410-compatible-tokens = false

To enable backwards compatibility, set pre-410-compatible-tokens to true:

[pdweb-plugins]pre-410-compatible-tokens = true

Configuring IV header authentication

Tivoli Access Manager supports authentication using internally generated headerinformation supplied by a compatible client or a proxy agent. For historic reasonsthese are called IV (IntraVerse) headers. When the plug-in enhanced Web serverreceives requests from a trusted application such as WebSEAL or a multiplexingproxy agent, IV headers may be inserted into the requests relayed to the plug-inproxy server.

IV headers contain information that identify the originating client rather than therelaying server. The information in the headers is used to construct an originatingclient credential for authorization purposes. Similarly, if the plug-in enhanced Webserver relays requests to another Tivoli Access Manager server that recognizes IVheaders, the plug-in proxy can insert IV headers to identify the originating client.

The plug-in can be configured to use IV headers for post-authorization processingor for authenticating requests. Configured for post-authorization processing, theplug-in, after a successful authentication, modifies a transaction request byinserting the client’s true identity as IV headers. These headers may then beforwarded on to another server by the originating Web server.

If the plug-in is configured to use IV Headers to perform client authentication, theplug-in creates a client credential using the identity extracted from an IV headerfound in a transaction request. Because it is easy for clients to fake IV headers,such a credential is created only if the request is received via a trustedmultiplexing proxy agent (MPA). See, “Supporting Multiplexing Proxy Agents(MPA)” on page 104.

For authentication, IV headers can be configured to accept one, some, or all of iv-user, iv-user-l, iv-creds, or iv-remote-address headers in the request as proof of authentication when received through a proxy. The iv-remote-address header isused to record the real remote address of the user.

Configured for post-authorization processing, IV headers are inserted with one,some or all of the iv-user, iv-user-l, iv-creds, iv-groups, and/or iv-remote-address,HTTP headers into the request.




Table 14. IV header field descriptions

IV Header Field Description

iv-user The short name of the Access Manger user. Defaults tounauthenticated if the client is unauthenticated (unknown).

iv-user-l The full domain name of the user (long form). For example,LDAP distinguished name.

iv-groups A list of the groups to which the user belongs.

iv-creds Encoded opaque data structure representing the user’s TivoliAccess Manager credential.

iv-remote-address The IP address of the client. This value could represent the IPaddress of a proxy server or a network address translator(NAT).

Note: Access Manager only trusts headers received from trusted frontends. Afrontend is considered trusted if it is recognized as a Multiplexing ProxyAgent (MPA). For details on configuring the plug-in for supporting MPA’srefer to “Supporting Multiplexing Proxy Agents (MPA)” on page 104.

Enabling authentication using IV headersThe [common-modules] stanza in the pdwebpi.conf configuration file defines theuse of all authentication methods. To enable authentication using IV headers,assign the reference iv-headers to the authentication parameter:

[common-modules]authentication = iv-headers

To enable IV headers for post-authorization processing, assign the value iv-headersto the post-authzn parameter in the [common-modules] stanza of thepdwebpi.conf configuration file:

[common-modules]

post-authzn = iv-headers

The [modules] stanza in the pdwebpi.conf configuration file defines all availableauthentication mechanisms and their associated shared library name. Ensure thatthe entry for IV header authentication exists:

[modules]iv-headers = pdwpi-iv-headers-module

Configuring IV header parametersIV header authentication parameters are configured in the [iv-headers] stanza of the pdwebpi.conf configuration file.

The accept parameter specifies the types of IV headers that are accepted forperforming IV header authentication. By default the plug-in accepts all types of IVheaders. The valid options are, all, iv-creds, iv-user, iv-user-l, iv-remote-address. Toenter more than one header type, separate the values with a comma.

For example:

[iv-headers]accept = iv-creds,iv-user

The generate parameter specifies the type of IV headers to generate whenforwarding proxied requests. By default the plug-in generates all types of IV




headers when forwarding proxied requests. The valid options are: all, iv-creds,iv-user, iv-user-l, iv-remote-address. To enter more than one header type, separatethe values with a comma.

Specify UTF-8 encoding of IV headersEdit the plug-in configuration file. Specify whether or not the plug-in should use

UTF-8 encoding for IV headers.[iv-headers]use-utf8 = true



Configuring the IV header authentication mechanism foriv-remote-address

When using iv-remote-address in the IV Header you will need to specify the

shared library for mapping HTTP authentication header information. Thehttp-request authentication mechanism specifies the shared library for mappingHTTP authentication header information.

v On UNIX, the file that provides the built-in mapping function is a shared librarycalled libhttpauth.

v On Windows, the file that provides the built-in mapping function is a DLLcalled httpauthn.dll.

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-mechanisms] stanza of the pdwebpi.conf configuration file, thatis:

Solaris:

[authentication-mechanisms]http-request = libhttpauth.so

Windows:

[authentication-mechanisms]http-request = httpauthn.dll

Configuring HTTP header authentication

Tivoli Access Manager supports authentication through custom HTTP headerinformation supplied by the client or a proxy agent.

This mechanism requires a mapping function (a shared library) that maps thetrusted (pre-authenticated) header data to a Tivoli Access Manager identity. Theplug-in can take this identity and create a credential for the user.

The plug-in assumes that custom HTTP header data has been previouslyauthenticated by a proxy agent. For this reason the module only works if theplug-in is located behind an authenticated Web proxy agent, and the mpa-enabledparameter within the [pdweb-plugins] stanza is set to true.

By default, this shared library is built to map data from Entrust Proxy headers.




Enabling authentication using HTTP headersThe [common-modules] stanza in the pdwebpi.conf configuration file defines theuse of all authentication methods. To enable authentication using HTTP headers,assign the reference http-hdr to the authentication parameter; that is:

[common-modules]authentication = http-hdr

The [modules] stanza in the pdwebpi.conf configuration file defines all availableauthentication mechanisms and their associated shared library name. Ensure thatthe entry for HTTP header authentication exists:


Specifying header typesYou must specify all supported HTTP header types in the [http-hdr] stanza of thepdwebpi.conf configuration file.

[http-hdr]header = header_type

A standard configuration of HTTP headers permits only one header to be specified,for example:


To specify multiple HTTP headers, multiple instances of the HTTP header modulemust be configured.

For example:

[modules]entrust-client-header = pdwpi-httphdr-modulesome-other-header = pdwpi-httphdr-module

[entrust-client-header]header = entrust-client

[some-other-header]header = some-other

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 librarycalled libpdwpi-http-cdas.

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

called pdwpi-http-cdas.

By default, this built-in shared library is hard-coded to map Entrust Proxy headerdata to a valid Tivoli Access Manager identity. You must customize this file toauthenticate other types of special header data and, optionally, map this data to aTivoli Access Manager identity. Refer to the IBM Tivoli Access Manager for e-businessWeb Security Developer 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-mechanisms] stanza of the pdwebpi.conf configuration file.




For example:

Solaris:

[authentication-mechanisms]http-request = libpdwpi-http-cdas.so

Windows:

[authentication-mechanisms]http-request = pdwpi-http-cdas.dll

Configuring IP address authentication

The IP Address of incoming requests can be used to both maintain session stateand to authenticate client requests using values in the client address headers.

Configuring the plug-in to use the IP address for maintaining session state isinvalid without also configuring it to use the IP address to authenticate the clientrequest. However, usage of the IP address to authenticate users is valid if theplug-in does not use the IP address to track user sessions.

Enabling authentication using the IP addressThe [common-modules] stanza in the pdwebpi.conf configuration file defines theuse of all authentication methods. To enable authentication using the IP Address of the request initiator, assign the reference ip-addr to the authentication parameter asin the following:

[common-modules]authentication = ip-addr

To enable the use of the IP Address to track user sessions, assign the referenceip-addr to the session parameter as in the following:

[common-modules]session = ip-addr

The [modules] stanza in the pdwebpi.conf configuration file defines all availableauthentication mechanisms and their associated shared library names. Ensure thatthe entry for IP Address authentication exists, as in the following:

[modules]ip-addr = pdwpi-ipaddr-module

Configuring the IP address authentication mechanismThe IP Address Authentication Mechanism is the same as that for HTTP Headers.The http-request parameter specifies the shared library for the IP Addressauthentication mechanism.

v On UNIX, the file that provides the built-in mapping function is a shared library

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

called pdwpi-http-cdas.

You can configure the IP address authentication mechanism by entering thehttp-request parameter with the platform-specific name of the shared library file inthe [authentication-mechanisms] stanza of the pdwebpi.conf configuration file.

For example:




Solaris:

[authentication-mechanisms]http-request = libpdwpi-http-cdas.so

Windows:

[authentication-mechanisms]http-request = pdwpi-http-cdas.dll

Configuring LTPA Authentication

The plug-in can use LTPA cookies to authenticate users. LTPA cookies can either beprovided by Tivoli Access Manager WebSEAL or by IBM WebSphere server.

Enabling LTPA AuthenticationThe [common-modules] stanza in the pdwebpi.conf configuration file defines theuse of LTPA for authenticating requests.

[common-modules]authentication = ltpa

The [modules] stanza in the pdwebpi.conf configuration file defines all availableauthentication mechanisms and their associated shared library name. Ensure thatthe entry for LTPA authentication exists; that is:

[modules]ltpa = pdwpi-ltpa-module

Setting the Key DetailsThe actual LTPA cookie, which is received, is encrypted by the sender. The cookiemust be decrypted before authentication can take place. The [ltpa] stanza in thepdwebpi.conf configuration file contains the key details required for the decryptionprocess:

[ltpa]

ltpa-keyfile = full path of keyfileltpa-stash-file = password stash file locationltpa-password = password in lieu of the stash file

where:

v The ltpa-keyfile entry specifies the name of the keyfile supplied from theoriginating machine. The keyfile entry is required.

v The ltpa-stash-file entry specifies the name of the file that contains thepassword to the keyfile. This entry is optional, although if it does not exist, theltpa-password entry must exist. This entry takes precedence over any specifiedltpa-password.

v The ltpa-password entry is required only if the ltpa-stash-file entry does notexist. It should contain the clear text password to the specified keyfile.

Configuring LTPA post-authorization processingThe LTPA module is configured for post-authorization processing as part of asingle sign-on solution to a WebSphere application server. Refer to “Single sign-onto WebSphere application server using LTPA cookies” on page 127 forconfiguration details.




Configuring the redirection of users after logon

Using the login-redirect module you can configure the plug-in to redirect users toa specific URL after they have successfully been authenticated. This may be usefulin cases where you want all users to be directed to a portal rather than the Webpage they requested, or for presenting the user with a welcome page or the startpage for an on-line application.

The plug-in logon redirect functionality works independently of the method usedfor authenticating users. A redirection does not occur for a step-up authenticationor for re-authentication.

Enabling user redirectionThe [common-modules] stanza in the pdwebpi.conf configuration file defines theuse of all authentication methods. To redirect the user to a specific URI after theirinitial logon and authentication, assign the reference login-redirect to the pre-authznparameter; as in the following:

[common-modules]pre-authzn = login-redirect

Note: When used, it is recommended that the login-redirect parameter be placedfirst in the pre-authorization module list; otherwise, another authenticationmodule redirect may take precedence.

The [modules] stanza in the pdwebpi.conf configuration file defines all availableauthentication mechanisms and their associated shared library names. Ensure thatthe entry for login-redirect exists, as in the following:

[modules]login-redirect = pdwpi-loginredirect-module

Configuring user redirection parameters

User redirection parameters are configured in the [login-redirect] stanza of thepdwebpi.conf configuration file.

[login-redirect]redirect-uri = redirect uri

Use the redirect-uri parameter to specify the URI you want users directed tofollowing a successful logon. The specified URI can either be a relative URI or anabsolute URI.

Adding extended attributes for credentials

This section contains the following topics:

v “Mechanisms for adding extended attributes to a credential”

v “Entitlement service configuration” on page 100

Mechanisms for adding extended attributes to a credentialThe Tivoli Access Manager Plug-in for Web Servers authentication process accessesthe Tivoli Access Manager user registry and builds a credential for the user. Thecredential contains user information that is needed to make access decisions. Thisincludes information such as user name and list of groups to which the user

belongs.




The plug-in supports several different mechanisms (services) that allowadministrators and application developers to extend the authentication process.When the plug-in conducts the authentication process, it checks to see if anyexternal services have been implemented and configured. When they have, theplug-in calls those services. The services can do their own processing to build a listof extended attributes about the user identity. These extended attributes are addedto the user credential.

The following types of services are supported:

v Credential attribute entitlement service

This entitlement service is built-in to Tivoli Access Manager by default. Thisservice obtains specified user information from a user registry (such as an LDAPuser registry) and inserts the data into an attribute list in the user credential.This built-in credential attribute entitlement service is a generic entitlementservice that can be used by many resource managers. This service takes the placeof a previous method that required administrators to add ″tag/value″ entries tothe [ldap-ext-creds-tag] stanza in the pdwebpi.conf configuration file. In Version5.1, you should use the built-in entitlement service to obtain LDAP user registrydata. For configuration information, see “Entitlement service configuration”

v Customized credential attribute entitlement serviceWhen the built-in credential attribute entitlement service cannot provide all of the information needed for your deployment, you can write your own credentialattribute entitlement service. Tivoli Access Manager supports this as part of theauthorization API. For more information, see the IBM Tivoli Access Manager fore-business Authorization C API Developer Reference.

v Credential extended attributes external authentication service (CDAS)

The plug-in provides an external authentication API interface that can be used todevelop external authentication services. These services are commonly calledCDASs (cross-domain authentication service).

You can use the plug-in’s external authentication API to develop your ownexternal authentication service. This can be used when the need to obtain user

authentication information extends beyond entitlements information. The use of a credential extended attributes CDAS is recommended when an applicationneeds to access information available only at authentication time, or when theapplication needs to map a user ID used at authentication to the Tivoli AccessManager user ID. For more information, see the IBM Tivoli Access Manager fore-business Web Security Developer Reference.

Entitlement service configurationTo configure entitlement service, complete the instructions in the followingsections:

v “Step 1 — Determine the attributes to be added to the credential”

v “Step 2 — Define your use of the entitlement service” on page 101

v “Step 3 — Specify the attributes to be added to the credential” on page 101

Step 1 — Determine the attributes to be added to the credentialEach user attribute that you want to add to the user credential must be defined ina Tivoli Access Manager configuration file. Typically, this is done in the plug-inconfiguration file.

Go to the Tivoli Access Manager user registry (for example, an LDAP userregistry). Make a list of the names of each user registry entry that you want the




credential attributes entitlement service to extract from the registry and place intothe user credential. You will need the user DN and group DN also.

Step 2 — Define your use of the entitlement service1. Verify that the credential attributes entitlement service is configured. The

following default entry should be present in the plug-in configuration file:

[aznapi-entitlement-services]

AZN_ENT_EXT_ATTR = azn_ent_ext_attr

Note that the plug-in automatically takes the value azn_ent_ext_attr and findsthe corresponding shared library. For example, on Solaris, libazn_ent_ext_attr.so

2. Add an authorization API service definition entry to specify your usage of theentitlement service. Add the entry in the [aznapi-configuration] stanza.

The entry must use the parameter cred-attributes-entitlement-services. You canchoose a value, such as TAM_CRED_ATTRS_SVC. For example:

[aznapi-configuration ]cred-attributes-entitlement-services = TAM_CRED_ATTRS_SVC

Step 3 — Specify the attributes to be added to the credential

The attributes to be added to the credential are configured in several stanzas. Addthis information to the plug-in configuration file.

Note: Alternatively, you can define the attributes in a separate file, to be called bythe entitlement service. For more information, see the IBM Tivoli Access Manager for e-business Authorization C API Developer Reference.

Review the following example entry.

[TAM_CRED_ATTRS_SVC]eperson = azn_cred_registry_idgroup = cn=enterprise, o=tivoli

[TAM_CRED_ATTRS_SVC:eperson]tagvalue_credattrs_lastname = sn

tagvalue_credattrs_employeetype = employeetypetagvalue_credattrs_address = homepostaladdresstagvalue_credattrs_email = email

[TAM_CRED_ATTRS_SVC:group]tagvalue_credattrs_businesscategory = businesscategory

The stanza name [TAM_CRED_ATTRS_SVC] is the Service ID. Inside this stanzaare sources of attributes to be retrieved. The source names, such as user and groupare used to identify the source location in the registry. You need to define these.The values for these sources are registry identifiers that exist in the registry. Thevalues can be existing credential attribute names. If this is the case, the serviceautomatically finds and uses the respective values.

Configure the registry attributes for each of the sources under the service stanza ina separate stanza. The syntax of the separate stanza is the service ID library namefollowed by a colon (:) and then the source name. This connection is necessary

because more than one service can be configured in the same file.

The configuration file entries contain mappings of user registry attributes touser-defined credential attributes.

For example, in an LDAP user registry, the DN for a user could be cn=joeuser,o=tivoli




For this user, the LDAP user registry entries could be:

sn=Smithemployeetype=banktellerhomepostaladdress="3004 Mission St Santa Cruz CA 95060"[email protected]=finance

Using the example configuration entries shown above, the attribute list returnedwould have the following entries:

Attribute name Attribute value

credattrs_lastname Smith

credattrs_employeetype bankteller

credattrs_address 3004 Mission St Santa Cruz CA 95060

credattrs_email [email protected]

credattrs_businesscategory finance

Note that the service, source, and attributes can be multi-valued. If you specify thesame attribute name as a stanza entry keyword, then the attributes retrieved will

be added as a multi-valued attribute even when they come from different sources.

For example, more than one entitlement service can be chained together. Thisenables values retrieved from one service. to be used as input values for anotherservice. Likewise, attributes can be retrieved from more than one DN in the userregistry. Thus, using the example above, you could add values from multiple users(DNs) to one credattrs_businesscategory attribute, if you wanted a list of all the

businesscategory entries for a group of users.

For example, if you want to build an attribute called myemployeeinfo to add to thecredential, and you want this attribute to contain the last name and employee typeof everyone that authenticates, you could then define the following:

[myID]

source = azn_cred_authzn_id

[myID:source]myemployeeinfo = lastnamemyemployeeinfo = employeetype

Adding LDAP extended attributes to the HTTP header (tag value)

Often it is useful to attach user-specific information from LDAP (for example,telephone number, e-mail address) to the headers of HTTP authenticated requests.This allows multiple applications to access the attached information withouthaving to constantly query the LDAP server. The nature of this information is thatit is relatively static and is never updated by any of the applications that use it.

This data is placed into the user credential as part of the ivauthn authenticationprocess. This information can also be attached to the users credential through auser-implemented CDAS authentication module.

The following process flow describes the sequence of events:

v User-defined supplemental data from any field of a user’s LDAP registryaccount is added as extended attribute data in the user’s Tivoli Access Managercredential.




v When configured for tag value post-authorization processing, the plug-inextracts the LDAP extended attribute data and places it in the HTTP header of the request.

v The back-end application can extract the data from the header without requiringspecial code or the authorization API.

Configuring the plug-in for inserting LDAP extended attribute information into an

HTTP header involves the following steps:1. Configure tag value post-authorisation in the Web Plug-in. Refer to “Enabling

tag value processing” for details on how to do this.

2. Add the extended attributes to the /PDWebPI/host object in Access Manager.For example (entered as one line):

pdadmin> object modify /PDWebPI/hostset attribute HTTP-Tag-Value ldap-home-phone=homePhone

You can also create a new Tivoli Access Manager extended credential CDAS andspecify this as an authentication mechanism in the plug-in. For example:

1. Set the cred-ext-attrs parameter in the [authentication-mechanisms] stanza tothe new CDAS. For example (entered as one line):

[authentication-mechanisms]cred-ext-attrs = /opt/PolicyDirector/lib/libextcredtags.so& /opt/pdwebpi/etc/pdwebpi.conf

(the default configuration file is pd.conf)

2. Edit pdwebpi.conf add a new stanza: [ldap-ext-attr-cdas-tags] and the LDAPextended attributes required. For example:

[ldap-ext-attr-cdas-tags]ldap-home-phone = homePhone

3. Restart the plug-in

4. Add the extended attributes to /PDWebPI/host object in Tivoli Access Manager.For example (entered as one line):

pdadmin> object modify /PDWebPI/hostset attribute HTTP-Tag-Value ldap-home-phone=homePhone

Enabling tag value processingThe [common-modules] stanza in the pdwebpi.conf configuration file defines theuse of all authentication methods. To enable processing using tag values, assign thereference tag-value to the post-authzn parameter:

[common-modules]post-authzn = tag-value

The [modules] stanza in the pdwebpi.conf configuration file defines all availableauthentication mechanisms and their associated shared library names. Ensure thatthe entry for tag value exists, as in the following:

[modules]tag-value = pdwpi-tag-value-module

Configuring tag value parametersTag value parameters are configured in the [tag-value] stanza of the pdwebpi.confconfiguration file.

[tag-value]cache-definitions = yescache-refresh-interval = 60




The cache-definitions parameter enables or disables caching of tag valuedefinitions that are attached to the object space. The cache-refresh-interval definesthe refresh interval in seconds for the cache of definitions.

If need be, you can configure a prefix to add to credential attribute names used fortag-value HTTP headers. This prefix:

v Is used as a search string by the tag-value module when searching credential

attributes.

v Is added to the session ID credential attribute.

v Is added by the switch-user module to the credential attribute it uses to store theadministrator’s username.

Specify the prefix using the tag-value-prefix parameter in the [pdweb-plugins]stanza of the plug-in configuration file.

This parameter can be overridden for a specific virtual host using a [virtual_host]stanza for that virtual host. The default behavior is to have no prefix.

Supporting Multiplexing Proxy Agents (MPA)

Tivoli Access Manager provides solutions for securing networks that use aMultiplexing Proxy Agent (MPA). Multiplexing Proxy Agents (MPA) are gatewaysthat accommodate multiple client access. Gateways establish a single authenticatedchannel to the secured Web server and ″tunnel″ all client requests and responsesthrough this channel. To the plug-in, the information across this channel initiallyappears as multiple requests from one client. The plug-in must distinguish

between the authentication of the MPA server and the additional authentication of each individual client. A common example of such gateways are Wireless AccessProtocol (WAP) gateways. Tivoli Access Manager WebSEAL also acts as an MPAwhen configured with a junction to the host Web server to allow single signon

between WebSEAL and the plug-in. To configure such a solution, the iv-headerauthentication module can be used. See Chapter 5, “Web single sign-on solutions,”

on page 125 for more details on configuring for SSO.

Valid session data types and authentication methodsBecause Tivoli Access Manager Plug-in for Web Servers maintains an authenticatedsession for the MPA, it must simultaneously maintain separate sessions for eachclient. Therefore, the session data and authentication method used for the MPAmust be different than the session data and authentication method used by theclient. The table below lists the valid session types for the MPA and the client:

Table 15. Valid session data types for MPA

Valid Session Types

MPA-to-plug-in Client-to-plug-in

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, theclient’s choices for session data type include only HTTP header and cookie.




v If the MPA uses a HTTP header for session data, the client can use a differentHTTP header type.

v The server-specific cookie contains session information only; it does not containidentity information.

v If MPA support is enabled, the use of SSL session IDs to maintain session statechanges. Normally, having SSL session IDs configured to maintain session state,

only the SSL session ID is used to maintain sessions for HTTPS clients. To allowthe MPA to maintain a session with an SSL session ID and have clients maintainsessions using another method, this restriction is removed.

The authentication method used by the MPA-to-plug-in must be different than theauthentication method used by the client-to-plug-in. The table below lists the validauthentication methods for the MPA and the client:

Table 16. Valid MPA authentication types

Valid Authentication Types

MPA-to-plug-in Client-to-plug-in

Basic Authentication Basic Authentication

Forms FormsToken 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 particular

transport, Basic Authentication is automatically disabled for that transport. If MPA support is enabled, this restriction is removed. This allows the MPA to logon, for example, with Forms (or token) and clients to log on with BasicAuthentication over the same transport.

Authentication process flow for MPA and multiple clientsThe following process flow occurs for MPA and multiple client authentication.

1. Make the following configuration changes:

v Enable support for Multiplexing Proxy Agents in the configuration file.

v Create a Tivoli Access Manager account for the specific MPA gateway.

v Grant Proxy ([PDWebPI]p) access for this account to the MPA Protected

Object for the virtual host to which proxied requests will be directed. In thedefault configuration, this can be achieved by making the user a member of the pdwebpi-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 the plug-in using the client request.

6. The MPA authenticates to the plug-in (using a method distinct from the client)and an identity is derived for the MPA (that already has a plug-in account).




7. The plug-in verifies the MPA’s membership in the pdwebpi-mpa-serversgroup.

8. A credential is built for the MPA and flagged as a special MPA type in thecache.

Although this MPA credential accompanies each future client request, it is notused for authorization checks on these requests.

9. Now the plug-in needs to further identify the owner of the request.The MPA is able to distinguish the multiple clients for proper routing of logonprompts.

10. The client logs in and authenticates using a method distinct from theauthentication type used for the MPA.

11. The plug-in builds a credential from the client authentication data.

12. The session data type used by each client must be distinct from the sessiondata type used by the MPA.

13. The Authorization Server permits or denies access to protected objects basedon the user credential and the object’s ACL permissions.

Enabling MPA authenticationThe mpa-enabled parameter in the [pdweb-plugins] stanza of the pdwebpi.confconfiguration file enables or disables MPA authentication. The valid settings aretrue and false for enabling and disabling MPA authentication respectively. MPAauthentication is disabled by default. MPA authentication can be set for individualvirtual hosts by specifying the mpa-enabled parameter in the [virtual_host] stanzaof the configuration file.

To identify a new session as being the primary session established by an MPA, anauthorization decision is made, testing for the Proxy ([PDWebPI]p) permission onthe MPA protected object. By default the MPA protected object is defined to be/PDWebPI. To override this default setting, for example to define different sets of principals as representing MPAs for each virtual host, a value can be specified for

the mpa-protected-object configuration parameter. This parameter may beoverridden for each virtual host by specifying a value for it in the [virtual_host]stanza of the configuration file. For example, to enable MPA access for the ibm.comvirtual host but not the lotus.com virtual host, use the following settings in thepdwebpi.conf configuration file:

[pdmweb-plugins]virtual-host = ibm.comvirtual-host = lotus.com

[ibm.com]mpa-enabled = yes

To define members of the ibm-mpa-servers group as being MPAs for requests to

the ibm.com virtual host and lotus-mpa-servers group as being MPAs for requeststo the lotus.com virtual host, use the following configuration:


[ibm.com]mpa-enabled = yesmpa-protected-object = /PDWebPI/ibm.com

[lotus.com]mpa-enabled = yesmpa-protected-object = /PDWebPI/lotus.com




and define the following Tivoli Access Manager policy:

pdadmin> acl create ibm-mpapdadmin> acl modify ibm-mpa set group ibm-mpa-servers T[PDWebPI]ppdadmin> acl create lotus-mpapdadmin> acl modify lotus-mpa set group lotus-mpa-servers T[PDWebPI]ppdadmin> acl attach /PDWebPI/ibm.com ibm-mpapdadmin> acl attach /PDWebPI/lotus.com lotus-mpa

The mpa-protected-object configuration parameter specifies the object againstwhich the authorization decision will be made.

Create a user account for the MPARefer to the IBM Tivoli Access Manager Base Administration Guide and the IBM Tivoli Access Manager Web Portal Manager Administration Guide for information on creatinguser accounts.

Add the MPA account to the pdwebpi-mpa-servers groupTivoli Access Manager Plug-in for Web Servers creates a group for easilyadministering MPA servers. This group is called pdwebpi-mpa-servers. The

default-pdwebpi ACL attached to /PDWebPI grants Proxy ([PDWebPI]p) permissionto members of the pdwebpi-mpa-servers group. When installed in a Tivoli AccessManager secure domain that has at least one WebSEAL configured, thedefault-pdwebpi ACL is configured so that it also grants Proxy permission tomembers of the webseal-servers and webseal-mpa-servers groups. You maychoose your own groups and ACLs used to control identification of principals asMultiplexing Proxy Agents.

Refer to the IBM Tivoli Access Manager Base Administration Guide and the IBM Tivoli Access Manager Web Portal Manager Administration Guide for information onmanaging groups.




Chapter 4. IBM Tivoli Access Manager Plug-in for WebServers security policy

This chapter contains information that describes how you can configure andcustomize IBM Tivoli Access Manager (Tivoli Access Manager) Plug-in for WebServers security policy.


v “Plug-in-specific Access Control List (ACL) policies”

v “Three strikes logon policy” on page 112

v “Password strength policy” on page 113

v “Authentication-strength Protected Object Policy (Step-up)” on page 116

v “Multi-factor authentication” on page 118

v “Reauthentication Protected Object Policy” on page 119

v

“Network-based authentication Protected Object Policy” on page 121v “Quality-of-protection Protected Object Policy” on page 122

v “Handling unauthenticated users (HTTP/HTTPS)” on page 123

Plug-in-specific Access Control List (ACL) policies

The following security considerations apply for the /PDWebPI container in theprotected object space:

v The Tivoli Access Manager Plug-in for Web Servers object begins the chain of ACL inheritance for the plug-in region of the object space.

v If you do not apply any other explicit ACLs, this object defines (throughinheritance) the security policy for the entire Web space.

v The traverse permission is required for access to this object and any object belowthis point.

Refer to the IBM Tivoli Access Manager Base Administrator’s Guide for completeinformation about Tivoli Access Manager ACL policies.

Note: The Microsoft IIS Web server provides the ability to specify a default Webpage within a directory that is displayed when a user request contains aURL that includes only the directory path.

The ACL check performed by the Plug-in for Web Servers only applies tothe directory specified in the request URL and not the default Web pageserved by the IIS server in response to this request.

You should incorporate this ACL check limitation when implementing yoursecurity policy on IIS platforms.

Similarly, due to the nature of the Web Server plug-in architecture, there isnothing stopping you from installing other modules which conflict with thesecurity provided by the plug-in. It is the responsibility of the Web serveradministrator to ensure that no modules are installed onto the Web serverthat conflict with the plug-in.




For example the ″MultiViews″ functionality within Apache and IHS Webservers attempts to dynamically determine the extension of the requestedURL. For example, if a request is made to www.tivoli.com/index then theWeb server would dynamically map this to www.tivoli.com/index.html if such a file existed.

Unfortunately this mapping occurs after authorization has taken place which

means the authorization check is performed on index rather thanindex.html.

In such situations it is recommended that the ″MultiViews″ option isdisabled. or the policy is set up to capture this mapping. For example, anACL could be attached to /PDWebPI/www.tivoli.com, or if greatergranularity was required the ACL could be attached to both,/PDWebPI/www.tivoli.com/index and/PDWebPI/www.tivoli.com/index.html.

/PDWebPI/host or virtual_host The /PDWebPI/host or virtual_host subtree contains the object space of a particular

plug-in instance. The following security considerations apply for this object:v The traverse permission is required for access to any object below this point.

v If you do not apply any other explicit ACLs, this object defines (throughinheritance) the security policy for the entire object space on this machine.




Plug-in ACL permissionsThe following table describes the ACL permissions applicable for the Tivoli AccessManager Plug-in for Web Servers region of the object space:

Table 17. Plug-in ACL permissions

Permission Operation Description

[PDWebPI]r read View any element other than a directory. AnyHTTP GET or POST request requires thispermission. There is no specific ″list″ permissionfor requesting a directory listing (A GET of a URLending in /).

[PDWebPI]d delete Remove the Web object from the Web space. HTTPDELETE commands require this permission.

[PDWebPI]m modify Place/publish a HTTP object in the plug-in objectspace. A HTTP PUT request requires thispermission.

[PDWebPI]p proxy Determines whether a user can act as aMultiplexing Proxy agent. See “Add the MPAaccount to the pdwebpi-mpa-servers group” on

page 107 for more details.

T traverse Required for access to any object below this point.

The plug-in also supports WebDAV operations as shown below.

Table 18. Plug-in WebDAV permissions

Task Permission Required

PROPFIND [PDWebPI]R

PROPPATCH [PDWebPI]M

MKCOL [PDWebPI]N

WebDAV operations are authorized based on the request URI – not on individualmembers of a collection. In addition, some other WebDAV operations are partiallysupported:

v COPY - Requires [PDWebPI]R on the collection so that the ’copy from’ can beread. Permissions for the destination are not checked.

v MOVE - This is considered a copy then a delete. Requires [PDWebPI]Rd on thecollection that you are moving from. Permissions for the destination are notchecked.

Default /PDWebPI ACL policy

Core entries for the Tivoli Access Manager Plug-in for Web Servers ACL,default-pdwebpi, include:

Group iv-admin TcmdbsvaBR[PDWebPI]rR

User sec_master cmdbsvaBR[PDWebPI]rR

Any-other T[PDWebPI]rR

Unauthenticated T

Group pdwebpi-mpa-servers TBR[PDWebPI]p

Chapter 4. IBM Tivoli Access Manager Plug-in for Web Servers security policy 111



Group webseal-servers TBR[PDWebPI]p

Group webseal-mpa-servers TBR[PDWebPI]p

At installation, this default ACL is attached to the /PDWebPI container object in theobject space.

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.

Three strikes logon policy

The three strikes logon policy, available for LDAP-based Tivoli Access Managerinstallations, enables you to prevent computer password attacks by specifying amaximum number of failed log on attempts and a penalty lockout time. The policycreates a condition where a user must wait a period of time before making morelog on attempts that fail. For example, a policy could dictate 3 failed attemptsfollowed by a 180 second penalty. This type of logon policy can prevent random

computer-generated log on attempts occurring many times a second.

The three strikes logon policy requires the joint contribution of two pdadminpolicy command settings:

v Maximum number of failed log on attemptspolicy set max-login-failures

v Penalty for exceeding failed log on attempt settingpolicy set disable-time-intervalThe penalty setting can include an account lockout time interval or a completedisabling of the account.

If a logon policy is set (as an example) for three failed attempts followed by

specific lockout time penalty, a fourth attempt (correct or incorrect) will result in anerror page that states the account is temporarily unavailable because of passwordpolicy.

The time interval is specified in seconds - the minimum recommended timeinterval is 60 seconds.

If the disable-time-interval policy is set to disable, the user is locked out of theaccount and the LDAP account valid attribute for this user is set to no. Anadministrator re-enables the account through the Web Portal Manager.

Note: Setting the disable-time-interval to disable results in additionaladministration overhead. You might observe delays in replicating account

valid information to the plug-in. This situation depends on your LDAPenvironment. In addition, certain LDAP implementations might experienceperformance degradation as a result of the account valid update operation.For these reasons it is recommended that you use a timeout interval.




The following pdadmin commands are appropriate only for use with an LDAPregistry.

Table 19. pdadmin LDAP logon policy commands

Command Description

policy set max-login-failures {number|unset} [-user username]

policy get max-login-failures [-user username]Manages the policy controlling the maximumnumber of failed log on attempts allowed before apenalty is imposed. This command depends on apenalty set in the policy set disable-time-intervalcommand.

As the administrator, you can apply this policy to aspecific user or apply the policy globally to all userslisted 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]Manages the penalty policy controlling the timeperiod an account should be disabled if themaximum number of failed log on attempts isreached.

As the administrator, you can apply this penaltypolicy to a specific user or apply the policy globallyto all users listed in the LDAP registry.

The default setting is 180 seconds.

Password strength policyA Tivoli Access Manager LDAP-based installation provides two means of controlling the construction of passwords:

v Five pdadmin password policy commands

v A plugable authentication module (PAM) that allows you to customize apassword policy

Refer to the Tivoli Access Manager Authorization C API Developer’s Reference

Password strength policy set by the pdadmin utilityThe five password strength attributes implemented through the pdadmin utilityinclude:

vMinimum password length

v Minimum alphabetic characters

v Minimum non-alphabetic characters

v Maximum repeated characters

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




The following pdadmin commands are appropriate for use only with an LDAPregistry. The unset option disables this policy attribute – that is, the policy is notenforced.

Table 20. pdadmin LDAP password strength commands

Command Description

policy set min-password-length {number|unset} [-user username]

policy get min-password-length [-user username]

Manages the policy controlling the minimum lengthof a password.

As the administrator, you can apply this policy to aspecific user or apply the policy globally to all userslisted in the default registry.

The default setting is 8.

policy set min-password-alphas {number|unset} [-user username]

policy get min-password-alphas [-user username]

Manages the policy controlling the minimum

number of alphabetic characters allowed in apassword.

As the administrator, you can apply this penaltypolicy to a specific user or apply the policy globallyto all users listed in the default registry.


policy set min-password-non-alphas {number|unset} [-user username]

policy get min-password-non-alphas [-user username]

Manages the policy controlling minimum number of non-alphabetic (numeric) characters allowed in apassword.

As the administrator, you can apply this policy to aspecific user or apply the policy globally to all userslisted in the default registry.


policy set max-password-repeated-chars {number|unset} [-user username]

policy get max-password-repeated-chars [-user username]

Manages the policy controlling the maximumnumber of repeated characters allowed in apassword.

As the administrator, you can apply this policy to a

specific user or apply the policy globally to all userslisted in the default registry.


policy set password-spaces {yes|no|unset} [-user username]

policy get password-spaces [-user username]




Table 20. pdadmin LDAP password strength commands (continued)

Command Description

Manages the policy controlling whether a passwordcan contain spaces.

As the administrator, you can apply this policy to aspecific user or apply the policy globally to all users

listed in the default registry.

The default setting is unset.

The following table illustrates several password examples and the policy results based on the default values of the five pdadmin parameters:

Table 21. Password examples

Example Result

password Not valid: must contain at least one non-alphabeticcharacter.

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

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 the

unset 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 Protected Object Policy (Step-up)

The authentication-strength Protected Object Policy (POP) makes it possible tocontrol access to objects based on the authentication method that they use.

You can use this functionality – sometimes known as step-up authentication – toensure that users accessing more sensitive resources use a stronger authentication

mechanism. You might want this condition because of the greater threat of improper access.

For example, you can provide greater security to a region of the Web space byapplying a step-up POP policy that requires a stronger level of authentication thanthe client used when initially entering the plug-in domain.

Step-up authentication can also be set for each specific virtual host on a Webserver, allowing individual virtual hosts to carry their own step-up levels of authentication without being subject to server-wide policy implementations.

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. Refer to Chapter 3, “IBMTivoli Access Manager Plug-in for Web Servers authentication and requestprocessing,” on page 39 for details on configuring authentication mechanisms.

Any client accessing a Web server through the plug-in has an authentication level,such as ″unauthenticated″ or ″password,″ which indicates the method by which theclient last authenticated through the plug-in.

In some situations it might be necessary to enforce minimum ″safe″ levels of authentication required to access certain Web space objects. For example, in oneenvironment, authentication by token passcode might be considered more securethan authentication by username and password. Another environment could havedifferent standards.

Rather than forcing clients to restart their sessions when they do not meet therequired level of authentication, the step-up authentication mechanism gives clientsa second chance to re-authenticate using the required method (level).

Step-up authentication means that users are not immediately shown a ″denied″

message when they try to access a resource that requires a ″higher″ authenticationlevel than the one they logged on 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.

You configure authentication levels in the [authentication-levels] or[authentication-levels:virtual_host_label] stanza of the pdwebpi.conf configurationfile. For example:

[authentication-levels]1 = BA2 = iv-headers3 = cert




Based on the order of the methods in the list, each method is assigned a levelindex.

v Unauthenticated is assumed to have a level of 0.

v Subsequent methods can be placed in any order. See “Step-up authenticationnotes and limitations” on page 118

v There must be at least two entries to enable step-up authentication.

v Levels for authentication mechanisms can be set for specific virtual hosts byspecifying the levels using a stanza with the form: [authentication-levels:virtual_host_name].

Note: See Chapter 3, “IBM Tivoli Access Manager Plug-in for Web Serversauthentication and request processing,” on page 39 for detailed informationabout setting up the required authentication mechanisms.

Enabling step-up authenticationStep-up authentication is implemented using a POP policy placed on the objectsrequiring authentication sensitive authorization. You use the IP EndpointAuthentication Method attribute of a POP policy.

The pdadmin pop modify set ipauth command specifies both the allowednetworks and the required authentication level in the IP Endpoint AuthenticationMethod attribute.

The configured authentication levels can be linked to IP address ranges. Thismethod is intended to provide management flexibility. If filtering users by IPaddress is not important, you can set a single entry for anyothernw (any othernetwork). This setting will affect all accessing users, regardless of IP address, andrequire them to be authenticated 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 is 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 testProtected object policy: test

Description: Test POPWarning: no

Audit 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

During step-up authentication, validation of the supplied user ID can be enabled by setting the verify-step-up-user parameter in the [module-mgr] stanza to true.

[module-mgr]verify-step-up-user = true




Enabling the verify-step-up-user parameter ensure that when prompted tore-authenticate using a higher level mechanism, the entered identity matches theidentity originally entered. If the identities don’t match, a ’403 Forbidden’ page isreturned.

Step-up authentication example1. Configure authentication levels in pdwebpi.conf:

[authentication-levels] or [authentication-levels:virtual_host_label]1 = BA2 = token

2. Configure IP Endpoint Authentication Method POP attribute:

pdadmin> pop modify test set ipauth anyothernw 2pdadmin> pop show test

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

Therefore, users accessing objects protected by the test POP require level 2authentication or will be forced to authenticate with the token method.See also “Network-based authentication Protected Object Policy” on page 121.

Step-up authentication notes and limitationsv Step-up authentication is supported over both HTTP and HTTPS.

v You cannot step-up from the HTTP protocol to HTTPS.

v Authentication methods not specified in the [authentication-levels] stanzadefault to level 1.

v Authentication methods can be specified only once in the level list.

vSPNEGO does not step-up to any authentication method that uses POST forms.Configuring step-up behavior using SPNEGO authentication module results inan error page being returned to the client.

v Incorrect configuration of step-up authentication levels results in the disabling of step-up functionality within the plug-in. This situation can lead to unexpectedauthentication behavior, such as the password logon page being issued forobjects protected by a POP that requires the token passcode authenticationmethod.

After configuring step-up authentication mechanisms, check the pdwebpi.log filefor reports of any configuration errors.

Multi-factor authentication

Multi-factor authentication functionality is an extension of step-up authenticationfunctionality that allows you to specify a protected object policy (POP) that forcesthe user to authenticate using all authentication mechanisms with a level lowerthan the configured POP authentication level. That is, the user is required to haveauthenticated at all levels up to, and including, the required level before access isgranted. Multi-factor authentication can also be used in conjunction withre-authentication to force a multi-factor re-authentication.

Standard authentication-level based authentication allows a Policy to be associatedwith an object that sets a minimum required authentication level that must be




achieved before access is granted. The supported authentication mechanisms aregiven an ordering in the configuration that specifies which mechanisms areconsidered stronger than others. When a user first authenticates in order to accessan object they are offered the choice of all authentication methods that meet therequired level for that object. It is up to the user to choose which method they willuse.

To achieve multi-factor authentication, step-up authentication needs to beconfigured as discussed in “Authentication-strength Protected Object Policy(Step-up)” on page 116. Once step-up authentication is configured, you will needto add the extended attribute, MULTI-FACTOR-AUTH, to a protected object policy(POP) for a Tivoli Access Manager Plug-in for Web Servers object or objects.

When the MULTI-FACTOR-AUTH attribute is set, all authentication levels up tothe specified POP authentication level are required before access to the resource isgranted.

As an example, assume the following configuration is set in the configuration file:

[authentication-levels]1 = cert

2 = forms

With the above configuration, when a POP attached to a resource which requiresan authentication level of 2 and the new MULTI-FACTOR-AUTH attribute is set totrue, the user must first supply a valid client certificate before entering aforms-based logon. If the POP attached to the resource does not have theMULTI-FACTOR-AUTH attribute enabled, then only form-based authentication isused.

Enabling multi-factor authenticationMulti-factor authentication is implemented using a POP policy placed on theobjects requiring multi-factor authentication.

Syntax:

pdadmin> pop modify pop_name set attribute MULT-FACTOR_AUTH true

Reauthentication Protected Object Policy

Tivoli Access Manager Plug-in for Web Servers can force a user to perform anadditional log on (reauthentication) to ensure that a user accessing a protectedresource is the same person who initially authenticated at the start of the session.Reauthentication can be activated by a Protected Object Policy (POP) on theprotected object or by expiration of the session cache inactivity timeout value. Thissection discusses reauthentication based on security policy as dictated by a POPextended attribute. Refer to “Configuring the plug-in session/credentials cache” onpage 50 for details on configuring the Session/Credential Cache.

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 plug-inauthentication methods:

v Forms (user name and password) authentication




v Token authentication

In addition, a custom user name/password CDAS can be written to supportreauthentication.

Reauthentication assumes the user has initially logged in to the secure domain andthat a valid credential exists for the user. During reauthentication, the user must

log on using the same identity that generated the existing credential. Tivoli AccessManager preserves the user’s original session information, including the credential,during reauthentication. The credential is not replaced during reauthentication.

During reauthentication, the plug-in also caches the request that prompted thereauthentication. Upon successful reauthentication, the cached data is used torebuild the request.

If reauthentication fails, the plug-in returns the logon prompt again. If reauthentication succeeds, but the ACL check fails for that resource, a 403″Forbidden″ message is returned and the user is denied access to the requestedresource. In either case, the user is never logged off. Using a still valid credential,the user can end the reauthentication process (by requesting another URL) and still

participate in the secure domain by accessing other resources that do not requirereauthentication.

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 provided

by 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 thepdadmin pop create

,pdadmin pop modify

, andpdadmin pop attach

commands. The following example illustrates creating a POP called ″secure″ withthe reauth extended attribute and attaching it to an object:

pdadmin>pop create securepdadmin>pop modify secure set attribute REAUTH truepdadmin>pop attach /PDWebPI/hostA/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. Reauthentication is required for every access to objects protected by areauthentication policy.

In situations when most but not all objects in a directory require reauthentication,it is best to attach a POP to the entire directory including the ″reauth″ extendedattribute. For those objects that do not require reauthentication, attach a POP thatis identical to that for the directory but exclude the ″reauth″ extended attribute.

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




Network-based authentication Protected Object Policy

The network-based authentication Protected Object Policy (POP) makes it possibleto control access to objects based on the IP address of the user. You can use thisfunctionality to prevent specific IP addresses (or IP address ranges) from accessingany resources in your 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 levels

v Allowed networks

For details on specifying configuration levels, refer to “Configuring levels forstep-up authentication” on page 116

Specifying IP addresses and rangesAfter configuring the authentication levels you must specify the IP addresses andIP address ranges permitted by this POP 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 method

is 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 requires them to authenticate atthe specified level.

Syntax:

pdadmin> pop modify pop_name set ipauth anyothernw level_index

Conversely, if you want to ignore the authentication level and want to allow ordeny access based only on IP address, you can use level 0 for ranges that you wantto allow in and ″forbidden″ for ranges you want to deny.

The anyothernw entry is used as a network range that matches any network not

otherwise specified in the POP. This method can be used to create a default entrythat could either deny all unmatched IP addresses or allow access to anyone whomeets the authentication level requirement.

By default, anyothernw appears in a POP with an authentication level index of 0.The entry appears as ″Any Other Network″ in the pop show command:

pdadmin> pop show testProtected object policy: testDescription: Test POPWarning: noAudit level: none




Quality 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 116 for a moredetailed discussion on setting authentication levels.

ExampleRequire 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 addressTo disable step-up authentication by IP address, enter the following command:

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 algorithmTivoli Access Manager Plug-in for Web Servers uses the following algorithm toprocess 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.

Quality-of-protection Protected Object Policy

The quality-of-protection Protected Object Policy (POP) attribute allows you tospecify what level of data protection is required when performing an operation onan object.

pdadmin> pop modify pop_name set qop {none|integrity|privacy}

Table 22. QOP level descriptions

QOP level Description

privacy Data encryption is required (SSL).

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

none No method of data protection is used.

For example:

pdadmin> pop modify test set qop privacy




The quality-of-protection POP attribute permits a single transaction when the ″yes″response to the ACL decision also includes the required quality-of-protection level.If the plug-in cannot guarantee the required level of protection, the request isdenied.

Handling unauthenticated users (HTTP/HTTPS)

Tivoli Access Manager Plug-in for Web Servers accepts requests from bothauthenticated and unauthenticated users over HTTP and HTTPS. The plug-in thenrelies on the Authorization Server to enforce security policy by permitting ordenying 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 the plug-inis encrypted – as it is with an authenticated user.

v An SSL connection between an unauthenticated user and the plug-in requiresonly server-side authentication.

Processing a request from an anonymous client1. An anonymous client makes a request to the Web server through the plug-in

(using HTTP or HTTPS).

2. The plug-in creates an unauthenticated credential for this client.

3. The request proceeds, with this credential, to the protected Web object.

4. The Authorization Server checks the permissions on the unauthenticated entryof the ACL for this object, and permits or denies the requested operation.

5. Successful access to this object depends on the unauthenticated ACL entrycontaining at least the read (r) permission.

6. If the request fails the authorization decision, the client receives a logon form(BA or Forms-based).

Forcing user log onYou can force an unauthenticated user to log on by correctly setting theappropriate permissions on the unauthenticated entry in the ACL policy thatprotects the requested object.

The read [PDWebPI]r permission allows unauthenticated access to an object.

To force an unauthenticated user to log on, remove the read [PDWebPI]rpermission from the unauthenticated entry in the ACL policy that protects theobject.

Applying unauthenticated HTTPS

There are many practical business reasons for supporting unauthenticated access tothe plug-in enhanced Web server over HTTPS. These include:

v Some applications do not require a personal log on, but require sensitiveinformation, 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 business before you can proceed with further transactions. Again, sensitive informationmust be passed over the network.




Controlling unauthenticated users with ACL/POP policiesTo control unauthenticated users with ACL/POP policies:

Note: The ″any-other″ entry type is also known as the ″any-authenticated″ entrytype.

1. To permit unauthenticated user access to public objects, protect the public

content with an ACL that contains at least the read [PDWebPI]r permission forthe unauthenticated and any-other entries:

unauthenticated [PDWebPI]rany-other [PDWebPI]r

Note: The unauthenticated entry is a mask (a bitwise ″and″ operation) againstthe any-other entry when permissions are determined. A permission forunauthenticated is granted only if the permission also appears in theany-other entry. Since unauthenticated depends on any-other, it makeslittle sense for an ACL to contain unauthenticated without any-other. If an ACL does contain unauthenticated without any-other, the defaultresponse is to grant no permissions to unauthenticated.

2. To require encryption (SSL), protect the content with a Protected Object Policy

(POP) that specifies privacy as a condition.See “Quality-of-protection Protected Object Policy” on page 122.




Chapter 5. Web single sign-on solutions

When Tivoli Access Manager Plug-in for Web Servers is implemented as anauthorization service to provide protection to a secure domain, there is often a

requirement to provide solutions for single sign-on to resources within thatdomain. This chapter discusses single sign-on solutions for the Web spaceprotected by Tivoli Access Manager Plug-in for Web Servers.


v “Single sign-on concepts”

v “Automatically signing-on to a secured application” on page 126

v “Single sign-on to the plug-in from WebSEAL or other proxy” on page 128

v “Using the Failover cookie for single sign-on” on page 129

v “Using Global single sign-on (GSO)” on page 130

v “Security Provider NEGOtiation (SPNEGO) single sign-on” on page 133

v “Single sign-on using forms” on page 133

Single sign-on concepts

When a protected resource is located on the plug-in enhanced Web applicationserver, a client requesting that resource can be required to perform multiple logonswhen accessing different secure applications. Each log on is likely to requiredifferent logon identities.

The problem of administering and maintaining multiple logon identities can often be solved with a single sign-on (SSO) mechanism. SSO allows the user to access aresource using only one initial log on. Any further log on requirements for

resources on the Web server are handled transparent to the user.

There are a number of different single sign-on architectures supported by TivoliAccess Manager Plug-in for Web Servers. These are:

1. One plug-in instance providing single sign-on to more than one secureapplication on a server.

2. Single sign-on to the plug-in from WebSEAL or other proxy agent such as aWAP gateway.

3. Use of failover cookies to provide single sign-on between different domains.

4. Use of the Global Single sign-on (GSO) Lockbox module to provide access toapplications using stored user credential information.

5. Use of Security Provider NEGOtiation (SPNEGO) for permitting access to

resources on IIS based Web servers.6. Forms based authentication as a mechanism for SSO.

7. Cross Domain Single Sign On which provides a mechanism for transferringuser credentials across multiple secure domains.

8. e-Community single sign-on, where a user authenticates once and is issued atoken that allows them to access other domains within a virtual community of domains without the need to re-authenticate.

The first six SSO scenarios are discussed in this chapter. The seventh and eighthscenarios are the topic of the next chapter.




Automatically signing-on to a secured application

HTTP headers and LTPA cookies (when the application is WebSphere ApplicationServer) can be used to achieve SSO to applications on a server that are protected

by one plug-in instance.

After initial authentication of the client, the plug-in can build an HTTP header

containing client identity information that can be used for automatic authenticationto secure applications running on the server. In a similar way, an LTPA cookie can

be used to achieve SSO to a Web application server such as WebSphere.

Configuring single sign-on to secure applications using HTTPheaders

The HTTP headers used for signing on to an application are generated by theiv-header post-authorization module. The set of headers that can be generated arecollectively called IV headers.

After the successful authorization of a user request, the plug-in can insert IVheaders that define the client’s identity into the request for processing by the

application. This header information can be used as proof of the user’s identitywhen the request is handled by an application hosted by the secured Web server.The user is spared the need to log on each time a new secure application isaccessed.

Configured for post-authorization processing, IV headers are inserted with one,some, or all of the iv-user, iv-user-l, iv-creds, iv-groups, iv-remote-address HTTPheader types. These header types are described in the following table.

Table 23. IV header field descriptions


iv-user The short name of the Tivoli Access Manager user. Defaults to

unauthenticated if the client is unauthenticated (unknown).iv-user-l The full domain name of the user (long form), for example,

LDAP distinguished name.

iv-groups A list of the groups to which the user belongs.

iv-creds Encoded opaque data structure representing the user’s TivoliAccess Manager credential.


Enabling and disabling generation of IV headersTo enable the plug-in to insert IV headers into authorized requests, the plug-inneeds to be configured to use IV headers for post-authorization processing. The[common-modules] stanza in the pdwebpi.conf configuration file defines the use of all authentication methods. To enable IV headers for post-authorization processing,assign the parameter post-authzn the keyword value iv-headers in the[common-modules] stanza in the pdwebpi.conf configuration file. That is:

[common-modules]post-authzn = iv-headers





The generate parameter specifies the type of IV headers to generate whenforwarding proxied requests. By default, the plug-in generates all types of IVheaders when forwarding proxied requests. The valid options are all, iv-creds,

iv-user, iv-user-l, and iv-remote-address. To enter more than one header type,separate the values with a comma.

For example:

[iv-headers]generate = iv-creds,iv-user,iv-user-1

Single sign-on to WebSphere application server using LTPAcookies

When the plug-in is installed as a protective layer on a WebSphere applicationserver, accessing clients are faced with two potential logon points – the plug-in andsecure applications served by WebSphere. To provide a single point of logon in this

situation the plug-in can be configured to generate and pass the cookie-basedlightweight third party authentication (LTPA) mechanism onto Web applicationservers that support LTPA cookies.

When a user makes a request for a resource on a server, the user must first beauthenticated to the plug-in. After successful authentication, the plug-in generatesan LTPA cookie on behalf of the user. The LTPA cookie, which serves as anauthentication token for the Web application server, contains user identity andpassword information. This information is encrypted using a password-protectedsecret key shared between the plug-in and the application server.

The plug-in inserts the cookie in the HTTP header of the request that is sent to theWeb application server. The application server receives the request, decrypts thecookie, and authenticates the user based on the identity information supplied inthe cookie.

To improve performance, the plug-in stores the LTPA cookie in the session cacheand uses the cached LTPA cookie for subsequent requests during the same usersession. For details on setting the parameters for the session cache refer to,“Configuring the plug-in session/credentials cache” on page 50.

Configuring single sign-on to WebSphere using LTPA cookiesUse of LTPA cookies to achieve single sign-on to application servers supportingLTPA cookies, is part of the plug-in’s post-authorization processing. To enable thisfunctionality, enter the key value ltpa for the parameter post-authzn in the[common-modules] stanza of the pdwebpi.conf configuration file:

[common-modules]post-authzn = ltpa

Chapter 5. Web single sign-on solutions 127



LTPA cookie configuration is performed in the [ltpa] stanza of the pdwebpi.confconfiguration file. The following parameters require configuration.

Table 24. LTPA configuration parameters


ltpa-keyfile The full path name of the key file used to encrypt theidentity information contained in the cookie.

ltpa-stash-file The location of the password stash file. If no passwordstash file exists, this entry should be commented out.

ltpa-password The password to use when a password stash file does notexist.

ltpa-lifetime The lifetime, in seconds, of the LTPA cookie.

Technical notes for LTPA single sign-onv The key file contains information about a specific Web application server. If you

add more than one application server to the same plug-in, all servers will sharethe same key file.

v For single sign-on to succeed, the plug-in and the application server must insome way share the same registry information.

v The application server is responsible for setting up LTPA and the creation of theshared secret key.

Single sign-on to the plug-in from WebSEAL or other proxy

When the plug-in enhanced Web server receives requests from a trustedapplication such as WebSEAL or a multiplexing proxy agent, IV headers may beinserted into the requests relayed to the plug-in. IV headers contain informationthat identify the originating client rather than the relaying server. The informationin the headers is used to construct an originating client credential for authorizationpurposes.

If the plug-in is configured to use IV Headers to perform client authentication, theplug-in creates a client credential using the identity extracted from an IV headerfound in the transaction request. Because it is easy for clients to fake IV headers,such a credential is created only when the ’use secondary authenticator’ flag in theauthenticate request is set.

For authentication, IV headers can be configured to accept one, some, or all of iv-user, iv-user-l, iv-creds or iv-remote-address headers in the request as proof of authentication when received via a proxy. The iv-remote-address header is used torecord the real remote address of the user. These IV header types are recognized byTivoli Access Manager and WebSEAL.

Table 25. IV header field descriptions IV Header Field Description

iv-user The short name of the client. Defaults to unauthenticated if theclient is unauthenticated (unknown).

iv-user-l The full domain name of the user (long form).

iv-groups A list of the groups to which the client belongs.

iv-creds Encoded opaque data structure representing a Tivoli AccessManager credential.




Table 25. IV header field descriptions (continued)



Note: Access Manager only trusts headers received from trusted frontends. Afrontend is considered trusted if it is recognized as a Multiplexing ProxyAgent (MPA). For details on configuring the plug-in for supporting MPA’srefer to “Supporting Multiplexing Proxy Agents (MPA)” on page 104.

In order to be accepted as proof of client identity, WebSEAL or other proxy mustitself be authenticated to the plug-in. This is typically achieved by a mutuallyauthenticated SSL connection between the proxy and the Web server secured bythe plug-in.

Enabling and disabling authentication using IV headersThe [common-modules] stanza in the pdwebpi.conf configuration file defines the

use of all authentication methods. To enable authentication using IV headers,assign the reference ’iv-header’ to the authentication parameter:

[common-modules]authentication = iv-header


The accept parameter specifies the types of IV header that are accepted forperforming IV header authentication. By default the plug-in accepts all types of IVheader. The valid options are all, iv-creds, iv-user, iv-user-l, and iv-remote-address.

To enter more than one header type, separate the values with a comma.

For example:

[iv-headers]accept = iv-creds,iv-user

Using the Failover cookie for single sign-on

With failover cookies configured for post-authorization processing, the plug-inencrypts a client’s credential data in either a server-specific or domain-wide cookie.The cookie is placed on the browser when the client first connects. When the clientattempts to access another secure server within the domain, the cookie is presentedto the next server that the client is redirected to. The cookie is used for automatic

re-authentication so the client is spared the task of re-authenticating manually. Theplug-ins on replicated servers share a common key that decrypts the credentialinformation held in the cookie, establishing a new session.

Note: Token security was improved in the plug–in 4.1 release for failover cookiegeneration. The improvements are not interoperable with the Tivoli AccessManager 3.9 token encoding scheme. To continue to be able to interoperatewith 3.9 Tivoli Access Manager Web Security products set the




pre-410-compatible-tokens configuration parameter in the [pdweb-plugins]stanza to true. This parameter is process-wide and cannot be specified on aper-virtual host basis.

Enabling single sign-on using Failover cookiesFailover cookies can be configured to perform authentication and

post-authorization tasks.

Plug-ins configured for post-authorization processing using failover cookies,encrypt and store a credential as a failover cookie in the transaction response.

Plug-ins configured for using failover cookies for performing authentication,re-authenticate clients using the encrypted credential from a failover cookie foundin the transaction request.

To enable SSO using failover cookies, assign the reference ’failover’ to theauthentication and post-authzn parameters in the [common-modules] stanza of the configuration file:

[common-modules]

authentication = failoverpost-authzn = failover

For further details on configuring failover cookie authentication refer to“Configuring Failover authentication” on page 78.

Using Global single sign-on (GSO)

Tivoli Access Manager Plug-in for Web Servers can be configured to grant usersaccess to the computing resources they are authorized to use through a singlelogin. Designed for large enterprises consisting of multiple systems andapplications within heterogeneous, distributed computing environments, GSOeliminates the need for end users to manage multiple user names and passwords.

Note: GSO is not a suitable single sign-on solution for iPlanet Web servers whenthe iPlanet Web server uses the same LDAP instances as Tivoli AccessManager.

To create a GSO solution, Tivoli Access Manager GSO resources and GSO resourcegroups must first be created using the Web portal manager or the pdadmin utility.For details on creating GSO resources and GSO resource groups refer to the IBMTivoli Access Manager Base Administrator’s Guide.

The Basic Authentication (BA) post-authorization module is called after a requesthas been authorized to determine if a resource credential is available for therequested resource. The resource credential is a username/password combination

that is mapped into each resource and stored in the user registry. The BApost-authorization module retrieves the resource credential appropriate for the userand the requested application resource and creates an HTTP Basic Authenticationheader using the retrieved resource credential and adds this BA header to theHTTP request. The resource credential is retrieved from the user registry for thefirst request only, for all subsequent requests, the resource credential is retrieved assession information.

The following figure illustrates how the GSO mechanism is used to retrieve usernames and passwords for back-end application resources.




Plug-in

User Registry

1

2 3Tivoli Access

Manager identityUsername andpassword

4

5SD

Web server

travel-app

payroll-app

1. User Michael requests access to the protected back-end Web server application,travel-app. Tivoli Access Manager authenticates the client and a Tivoli AccessManager identity is obtained. If the resource requested is unprotected therequest is forwarded to the Web server for handling.

Note: The single sign-on process is independent of the initial authenticationmethod.

2. The plug-in passes the Tivoli Access Manager identity to the user registry

server (LDAP or URAF).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 following table illustrates the structure of the GSO resource credentialdatabase:

Michael Jane

resource: travel-appusername=mikepassword=123

resource: travel-appusername=Janepassword=abc

resource: payroll-appusername=smithpassword=456

resource: payroll-appusername=Jonespassword=xyz

3. The registry returns username ″mike″ and password ″123″ to the plug-in.

4. The plug-in inserts Michael’s username and password information in the HTTPBasic Authentication (BA) header of the request that is sent back to the Webserver.

Figure 6. User access to secure applications using GSO.




5. The Web server authenticates Michael (for the resource he has requested) basedon his credentials in the BA header inserted in the request from Step 4, as if itis from the client.

Configuring Global single sign-onTo enable Global Single sign-on functionality you need to configure pdwebpi.conf.

In the [common-modules] stanza, specify the value BA for the post-authznparameter as in the following:

[common-modules]authentication = ...session = ...post-authzn = BA

Ensure that in the modules stanza the parameter BA is assigned at least the defaultmodule; that is:


Within the [BA] stanza of the pdwebpi.conf configuration file there are a number of parameters used for configuring the BA post-authorization module. These are:

v basic-auth-realm

v strip-hdr

v add-hdr

v gso-resource-name

v supply-password

v supply-username

For achieving GSO to back-end applications, the parameters add-hdr andgso-resource-name need configuring. Other BA parameters are discussed in moredetail in “Configuring Basic Authentication” on page 59.

The add-hdr parameter controls the addition of a new BA header once the requesthas been authenticated. For achieving GSO, set this parameter to the value gso:

[BA:virtual_host1]...add-hdr = gso

The setting of the add-hdr parameter to the value gso means a new BA header isadded to the HTTP request based on resource information that is stored in the userregistry. The gso-resource-name parameter in the [BA] stanza of the configurationfile specifies the name of the Web server resource that is to be GSO enabled. Thiscan be specified on a per virtual host basis. The resource credential stored in theuser registry is mapped to each resource stored in the user registry.

Set the gso-resource-name parameter to the name of the Tivoli Access Managerresource that is to be GSO enabled. For example:

[BA:virtual_host1]...gso-resource-name = payroll-app

Only one GSO resource name can be specified per virtual host. If no value isspecified for gso-resource-name the virtual host name is used as the GSO resourcename.




Note: If you are sharing an LDAP registry between Sun ONE (formerly iPlanet)and Tivoli Access Manager, you cannot create GSO resource credentialswithin Tivoli Access Manager with target user names the same as thoseusernames expecting to authenticate to the Sun ONE Web Server. This is

because the Sun ONE Web Server cannot limit the LDAP search criteriawhen authenticating users to search only for objects of the correct LDAPobject class.

Security Provider NEGOtiation (SPNEGO) single sign-on

Using SPNEGO as an authentication mechanism within the plug-in provides asingle sign-on capability that permits users to access resources on a secure IIS Webserver from a Windows client without the need for authentication other than theinitial logon to the domain. Operational and configuration details of SPNEGOsingle sign-on are included in “Configuring SPNEGO authentication” on page 69.

Single sign-on using forms

Single sign-on forms authentication allows Tivoli Access Manager Plug-in for WebServers to transparently log an authenticated Tivoli Access Manager user in to aplug-in secured Web server that requires authentication using a HTML form.

Single sign-on forms authentication supports existing applications that use HTMLforms for authentication and cannot be modified to directly trust the authenticationperformed by the plug-in. Plug-in form-based single sign-on provides a quickintegration solution that should be regarded as an interim solution to be usedwhile a more trusted and efficient method for authentication is developed.

Enabling single sign-on forms authentication produces the following results:

v The plug-in interrupts the authentication process initiated by the back-endapplication.

v The plug-in supplies data required by the login form and submits the login form

on behalf of the user.

v The user is unaware that a second login is taking place.

v The back-end application is unaware that the login form is not coming directlyfrom the user.

The plug-in must be configured to:

v Recognize and intercept the login form

v Fill in the appropriate authentication data

The administrator enables forms single sign-on by configuring how the login formis to be recognized, completed, and processed.

Forms single sign-on process flowThe following scenario assumes that the plug-in has already authenticated the user.




SD

Client Browser

WebPlug-in Web Server

request for resource login required

redirect tologin page

request for login pageURI

match request for login page

applicationreturns login form

Form fieldsaved

by plug-in

actual login

responsebuilt

by plug-in

request for resource

2

34

5 6

7

8

1

9 10

13

12

redirect to action URI

request for action URI

14

11

1. The user requests a resource on a protected virtual host.

2. The plug-in passes the request to the back-end application.

3. Because the back-end application requires the user to authenticate, a redirectto the application’s login page is sent back to the plug-in.

4. The plug-in passes the redirect to the browser.

5. The browser follows the redirect and requests the login page.

Note: Everything to this point in the process flow is standard plug-infunctionality.

6. The plug-in has been configured for forms single sign-on. The plug-in FSSOmodule recognizes the request as a request for a login page, based oninformation contained in the plug-in configuration file. The request is sent tothe application.

7. The application returns the login page and perhaps application-specificcookies.

8. The plug-in intercepts the response and parses the HTML returned to identifythe login form. When the plug-in finds a HTML form in the document itcompares the action URI in the form to the value of the login-form-actionparameter from the plug-in configuration file. If there is a match, the plug-inuses the form found, otherwise the plug-in keeps searching for other forms. If no form in the page matches the action URI pattern from the configuration filethen the plug-in aborts forms single sign-on processing and passes theunmodified response back to the browser.

Figure 7. Forms single sign-on process flow.. Forms single sign-on process flow.




If a login form is found, the plug-in parses the form HTML in the documentto identify the request method, the action URI, and any other input fields inthe form, saving them for use in step 10. It then sends the browser a redirectto the login form’s action URI with a unique request identifier appended as aquery. Any application specific cookies are also included with the redirect.

9. The browser follows the redirect and requests the action URI.

10.The plug-in recognizes the inbound request by it’s unique query string andgenerates the authentication request using the rules from the argument-stanzaand data saved in step 8. The completed login form (authentication request) isthen sent to the back-end application.

11. The application authenticates using the plug-in supplied authentication data inthe form. The application returns a redirect to the originally requestedresource.

12. The plug-in returns the redirect to the browser.

Note: This completes the forms SSO-specific functionality.

13. The browser follows the redirect and requests the resource.

14. The plug-in passes the request to secure resource.

During this process, the browser makes four requests to the plug-in. From theuser’s perspective, only a single request for the resource is made. The otherrequests occur automatically 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 usinga single regular expression or several regular expressions.

2. The login page can include more than one HTML form. However, the loginform must be identified by applying a regular expression to the action URIs of

each 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 the plug-in’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 precludes support for Web sites using Javascript to buildlogon forms dynamically or to set cookies in the user’s browser.

4. Login data is submitted at only one point in the authentication process.

5. The logon URI to be intercepted in step 8 in the previous section, must beprocessed as a single request by the underlying Web server. PHP scriptshandled as external commands in Apache, for example, spawn multiplesub-request and cannot be intercepted.

Enabling forms single sign-onThe FSSO module handles the forms single sign-on process. The module needs to

be called after the authorization of the request and before the Web server respondsto the request. The FSSO module therefore needs to be configured as a post-authznmodule and as a response module. These are specified in the [common-modules]stanza in the pdwebpi.conf configuration file. That is:

[common-modules]...response = fsso




The response module is used to capture the login form presented by the Webserver so that it can be processed.

The [modules] stanza in the pdwebpi.conf configuration file defines all availableauthentication mechanisms and their associated shared library name. Ensure thatthe entry for fsso exists:

[modules]

fsso = pdwpi-fsso-module

Since the primary role of the plug-in is to protect Web resources fromunauthorized access it must authorize all requests for resources even if they arepart of a form-based single sign-on process. The plug-in checks the ACL database

before allowing access to the back-end application login page and also checks before allowing access to the URI specified in the form action (where thecompleted login form is sent). If the security policy does not give permission forthe current user to access these pages then the form-based single sign-on will fail.

Configuring forms single sign-onThe forms single sign-on configuration information is located in the pdwebpi.conf

configuration file under the [fsso] or [fsso:virtual-host] stanza. The stanza containsone or more login-page-stanza entries which point to other custom-named stanzasthat contain configuration information for the login pages found on the back-endapplication.

The ability to support multiple login pages is important because a server mighthost several applications that each use a different authentication method.

For example:

[fsso]login-page-stanza = login-from-1login-page-stanza = login-form-2

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 regularexpression, that uniquely identifies requests for anapplication’s login page. The configured pattern iscompared against the request URI.

login-form-action This parameter specifies a pattern, using a regularexpression, that identifies which form contained in theintercepted page is the application’s login form. If multipleforms match the pattern then the first is used.

argument-stanza This parameter points to another custom stanza that liststhe fields and data required for completing the login form.

gso-resource This parameter supplies the name of the Tivoli AccessManager resource that is to be used when loading GSOsourced data defined in the arguments-stanza. Only oneGSO resource name can be specified per custom login pagestanza. If no value is specified for gso-resource, the virtualhost name is used as the GSO resource name.

For example:




[login-form-1]login-page = /cgi-bin/getloginpage*login-form-action = *argument-stanza = form1-datagso-resource = payroll-app

About the login-page parameter: The value of the login-page parameter is aregular expression that the plug-in uses to determine if an incoming request is

actually a request for a login page. If this is the case, the plug-in intercepts thisrequest and begins the forms single sign-on processing.

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. In thefollowing example, the URI of a request to a protected virtual host calledmyserver1 might appear as follows:

https://myserver1.mycompany.com/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 usedto identify the login form on the page returned by the back-end server following arequest matching the login-page parameter. Only one login-form-action parameteris 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. Theaction attribute is a URI expressed as a relative, server-relative, or absolute path.The login-form-action parameter must match this path as it comes from the

back-end server - even if it would normally be modified by the plug-in before

being forwarded to the client.

If multiple action attributes on the page match the regular expression, only the firstmatch is accepted as the login form.

If the login-form-action regular expression does not match any form on the page,an error is returned to 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 expressions: The special characters allowed in the regularexpressions used in the forms single sign-on configuration are defined in

Appendix E, “Special characters allowed in regular expressions,” on page 213.

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 stanza: The custom argument stanza contains one or more entriesin the following form:

name = method:value




name

The value of the name parameter is set to equal the value of the name attribute of 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:username

gso:password

The input is the current user’s GSO username and password (from the targetgso-resource specified in the custom login page stanza).

v Value of an attribute in the user’s credential

cred:cred-ext-attr-name

By default, the credential includes information such as the user’s Tivoli AccessManager user name and DN. To use the user’s Tivoli Access Manager user nameas the input value, specify the value as:

cred:azn_cred_principal_name

The user’s DN may be accessed as:cred:azn_cred_authzn_id

Custom credential attributes (added using 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

Notes:

1. The plug-in does not execute script code (Javascript, AxcitveX, etc.) before thefom is submitted which may cause problems if the code is required for thelogin process. Problems will not arise if this code simply checks the input priorto submission but problems may occur if the code modifies the user input.

2. Although forms-based SSO can make use of information in the GSO database itdoes not interfere with the GSO capability supplied by the BA module.

It is possible, if required, to have one GSO target in use to fill in the BasicAuthentication headers sent to the backend server and another specified in theforms-based SSO configuration for use when filling in login forms.




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 bythe HelpNow application

v 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:&nbp;<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 6. Cross-domain sign-on solutions

When Tivoli Access Manager Plug-in for Web Servers is implemented to provideprotection for a secure domain, there is often a requirement to provide solutions

for single sign-on to resources. This chapter discusses two methods for achievingsingle sign-on across different plug-in protected domains; e-Community singlesign-on and cross domain single sign-on (CDSSO). Both solutions use a trustedtoken to pass user authentication information between different domains.

Which solution you choose will depend on the amount of flexibility required.e-Community single sign-on uses a central server which coordinates the singlesign-on process amongst the different domains. With CDSSO, there is no centralauthentication server and no automated re-directs which provides more flexibility.

The following topics are covered:

v “Cross domain single sign-on (CDSSO)”

v “e-Community single sign-on” on page 146

Cross domain single sign-on (CDSSO)

Tivoli Access Manager Cross-Domain Single Sign-on (CDSSO) provides amechanism for transferring user credentials across multiple secure domains.CDSSO supports the goals of scalable network architecture by allowing theintegration of multiple secure domains. For example, a large corporate extranet can

be 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. The CDSSO authentication mechanism does not rely on a MasterAuthentication Server as “e-Community single sign-on” on page 146 does.

With CDSSO, when a user makes a request to a resource located in anotherdomain, the CDSSO mechanism transfers an encrypted user identity token fromthe first domain to the second domain. The second domain now has the user’sidentity (as authenticated in the first domain) and the user is not forced to performanother login.

CDSSO domains are based on DNS domains. All servers in the same DNS domainshare the same symmetric key. In order to perform CDSSO with servers in anotherDNS domain (which may or may not also be in a different Tivoli Access Managerdomain) a different key is needed.

Authentication process flow for CDSSO

The CDSSO process flow is described in the diagram and text below. Any userwho wants to participate in multiple domains must have a valid user account inthe primary domain, in this case domainA, and an identity that can be mappedinto a valid account in each of the participating remote domains. A user cannotinvoke the CDSSO functionality without initially authenticating to an initial securedomain (A) that contains the user’s account.




1

2

3

SD

user initiallyauthenticated to

domainA

page with CDSSO link

GET /pkmscdsso?http://webpi.domainB.com/page.htm

user IDREDIRECT http://webpi.domainB.com/page.htm?

PD-REFERER=webpi.domainA.com&PD-ID=

www.domainA.com

user ID

p l u g -

i n

www.domainB.com

user ID

p l u g -

i n

GET /page.htm?PD-REFERER=webpi.domainA.com&PD-ID=user ID

page.html

4

5

1. The user makes a request to access a resource in domain B using a custom linkon a Web page in Domain A.

2. The link contains a special CDSSO expression specified by the uri parameter inthe [cdsso] stanza of the pdwpi.conf configuration file. The default vaue is pkmscdsso:

/pkmscdsso?destination-URL

For example:

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

The request is first processed by the plug-in server in domain A. The plug-in builds an authentication token that contains the user’s Tivoli Access Manageridentity (short name), the current domain (″A″), additional user information,and a time stamp.

The additional user information (extended attributes) is obtained by a call outto the customized CDMF shared library (cdmf_get_usr_attributes). This libraryhas the ability to supply user attributes that can be used by domain B duringthe user mapping process.

Plug-in triple-DES encrypts this token data with the symmetric key generated by the cdsso_key_gen utility. This key file is shared and stored in the[cdsso-domain-keys] stanza of the pdwebpi.conf configuration file on bothdomain A and domain B plug-in enhanced Web 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.

3. The domain A plug-in server re-directs the request plus the encrypted token back to the browser and then to the domain B plug-in server (HTTPredirection).

4. The domain B plug-in server uses its version of the same key file to decryptand validate the token as coming from the referring domain.

The domain B plug-in 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).

Figure 8. CDSSO process flow..




The CDMF library passes the user’s identity, and any extended attributeinformation, back to the CDSSO library. The CDSSO library uses thisinformation to build a credential.

5. 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 [common-modules] stanza in the pdwebpi.conf configuration file defines theuse of all authentication methods. To enable CDSSO authentication, assign the termcdsso to the authentication parameter:

[common-modules]authentication = cdsso

When using CDSSO authentication, the plug-in must also be configured for CDSSOpost-authorization processing. In the [common-modules] stanza of thepdwebpi.conf configuration file, add the parameter post-authzn as in the following:

[common-modules]authentication = cdsso

post-authzn = cdsso

The [modules] stanza in the pdwebpi.conf configuration file defines all availableauthentication mechanisms and their associated shared library name. Ensure thatthe entry for forms authentication exists:

[modules]cdsso = pdwpi-cdsso-module

Encrypting the authentication token dataThe plug-in 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 plug-in enhanced Web server in each participating

domain. Each participating plug-in server in each domain needs to use the samekey.

Note: The creation and distribution of key files is not a part of the Tivoli AccessManager CDSSO 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-domain-keys] stanza of the pdwebpi.confconfiguration file of the participating plug-in server in each domain. The[cdsso-domain-keys] stanza derives its name from the pdwpi-cdsso-module namedefined in the [modules] stanza. It takes the form [cdsso-module-name-domain-keys]. The domain keys can be specified on a per virtual host basis by creating a[cdsso-module-name-domain-keys:virtual-host-name] stanza. The format of the entryincludes the domain name and the key file location:

[cdsso-domain-keys]domain-name = keyfile-location

Domain A Configuration Example:

Chapter 6. Cross-domain sign-on solutions 143



[cdsso-domain-keys]www.domainB.com = pathname/A-B.key

Domain B Configuration Example:

[cdsso-domaina-keys]www.domainA.com = pathname/A-B.key

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

Configuring the token time stampThe token contains a configurable time stamp that defines the lifetime of theauthentication token. Once the time stamp has expired, the token is consideredinvalid and is not used. The time stamp is used to help prevent replay attacks bysetting a value short enough to prevent the token from being stolen and replayedwithin its lifetime.

The authtoken-lifetime parameter, located in the [cdsso] stanza of thepdwebpi.conf

configuration file, sets the token lifetime value. The value isexpressed in seconds. The default value is 180:

[cdsso]authtoken-lifetime =180

This value may be overriden on a per-virtual host basis. You must take intoaccount any clock skew between the participating domains.

Including credential attributes in the authentication tokensYou can include credential attributes in the CDSSO tokens by specifying them inthe [cdsso-token-attributes] stanza of the plug-in configuration file. The attributesto be included can be specified on a peer-to-peer or per-domain basis. Thecredential attributes listing in this stanza is only relevant when the default SSO

token creation and consumption libraries are in use. If you do not requirecredential attributes in CDSSO vouch-for tokens, then you can leave this stanzaempty.

The default name of this stanza is derived from the module name for thepdwpi-cdsso-module defined in the [modules] stanza. It is of the form[cdsso_module_name-token-attributes].

The values in the [cdsso-token-attributes] stanza are default across all virtual hostsand can be overridden on a per virtual-host basis by creating a[cdsso_module_name-token-attributes:virtual_host] stanza.

The format of the entries is: domain_name = pattern1, pattern2, ... pattern n.

Credential attributes matching the specified patterns for a target host or domainare included in CDSSO vouch-for tokens constructed for that target host ordomain. Only a single value for each attribute is used, and only string values aresupported. Other types of credential attribute values are ignored. Patterns can bespecified using the pattern matching characters explained in Appendix E, “Specialcharacters allowed in regular expressions,” on page 213.

For example:




[cdsso-token-attributes]ibm.com = attrprefix_*, *name*tivoli.com = *_attrsuffix, some_exact_attribute

A default set of attributes can be configured using a <default> entry in this stanza.Such a default set of attributes is used when there is no other entry matching aparticular target host. If the <default> entry is not present, then no attributes will

be included by default.

Accepting and rejecting credential attributes from CDSSOauthentication tokensYou can specify the credential attributes to accept and those to reject fromincoming CDSSO authentication tokens by specifying the values in the[cdsso-incoming-attributes] stanza. Unlike the outgoing attributes configuration,incoming attributes cannot be configured on a per-peer or per-domain basis. Onlyone set of attribute patterns can be configured, and these patterns will be appliedto incoming tokens regardless of source. This processing only takes place if thedefault SSO token creation and consumption libraries are in use. The default nameof this stanza is derived from the module name for the pdwpi-cdsso-moduledefined in the [modules] stanza. It is of the form [cdsso_module_name-incoming-

attributes]. The values in this stanza are default across all virtual hosts. However,they may be overridden on a per virtual-host basis by configuring a[cdsso_module_name-incoming-attributes:virtual_host] stanza.

The format of entries in this stanza is:

attribute_pattern = preserve|refresh

Attributes in CDSSO tokens that match a refresh entry are removed from the token before the CDMF library is called to map the remote user into the local domain.Attributes matching a preserve entry, or matching none of the entries, are retained.If no entries are configured, then all attributes are retained.

Specify the sso-create and sso-consume librariesTo specify sso-create and sso-consume libraries, edit the plug-in configuration file.In the [authentication-mechanisms] stanza, uncomment the entry for sso-createand sso-consume and add the name of the plug-in failover cookie libraryappropriate for the operating system type.

The default configuration file entry is:

[authentication-mechanisms]sso-create = /opt/pdwebrte/lib/ibssocreate.sosso-consume = /opt/pdwebrte/lib/libssoconsume.so

Alternatively, when you have developed a CDAS library that implements acustomized version of sso-create and sso-consume functionality, insert the name of the custom CDAS as the value for the configuration file keyword. For example, if you developed a custom CDAS for sso-create, enter the absolute path name:

[authentication-mechanisms]sso-create = /dir_name/custom_cdas_sso-create.so

Expressing CDSSO linksLinks to resources on a secondary secure domain must contain a special CDSSOexpression which is configured using the uri parameter in the [cdsso] stanza onthe configuration file. The default value is /pkmscdsso:

/pkmscdsso?destinationURL




When configured as a post-authorization module, requests to /pkmscdsso?remote-uri will redirect the client to, remore-uri?PD-REFERER=this-host&argument=authentication-token

The name of the query string argument specifying the authentication token isconfigured using the cdsso-argument parameter in the [cdsso] stanza of thepdwebpi.conf configuration file. The default value is PD-ID. This may be overriden

on a per-virtual host basis.

The default value, PD-ID, of the cdsso-argument parameter should only bechanged when a custom SSO create/consume library is in use. When using theshipped SSO create/consume libraries, the default, PD-ID, must be used.

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 plug-in enhanced Web servers and the users. Thetoken could conceivably be stolen from the user’s browser history. The time stampon the token should be short enough to make it unlikely that the token could bestolen and replayed 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 plug-in serversparticipating in the CDSSO domain. For this reason, the keys used to protect the

tokens must also be carefully managed, and changed on a regular basis.

e-Community single sign-on

Tivoli Access Manager Plug-in for Web Servers e-community single sign-onfunctionality allows users to access resources across multiple servers in multipledomains without requiring re-authentication.

An ″e-community″ is a group of distinct domains (Tivoli Access Manager or DNS)that participate in a business relationship. These participating domains can beconfigured as part of one business (and perhaps using different DNS names forgeographic reasons) or as different 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) is




maintained in the home domain. This arrangement allows a single point of reference for administration issues, such as help desk calls within the e-communitythat all refer to the home domain.

Alternatively, you can use the Tivoli Access Manager Web Portal Manager todelegate the management of this information such that participating domains haveresponsibility for the administration of their own users.

The 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 be authenticated.

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 duty of the MAS should be restricted to providingauthentication services. The MAS should not contain resources that are available tousers.

After a user has successfully authenticated to the MAS, the MAS generates avouch-for token. This token is passed back to the server where the user is making

the request. The server treats this vouch-for token as proof that the user hassuccessfully 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 single sign-on process flow” on page 148.

e-Community single sign-on features and requirementse-Community single sign-on has the following features and requirements:

v e-Community functionality supports access using direct URLs (bookmarks) toresources.

v e-Community implementation requires a consistent configuration across all

plug-ins in all domains participating in the e-community.v All users who are participating in the e-community authenticate against a single

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

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)vouch-for the user’s authenticated identity.

v Domain-specific cookies are used to identify the server that can providevouch-for 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 identities. Thevouch-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 Configuration for e-community is set in the pdwebpi.conf file of eachparticipating plug-in.




e-Community single sign-on process flowAn e-community consists of a plug-in-enhanced master authentication server(MAS) and additional plug-in-enhanced servers acting as an e-community. Thee-community single sign-on solution can also interoperate with WebSEAL protectedresources.

The e-community implementation is based on a vouch-for system. Normally, whenunauthenticated users request a resource through the plug-in they are promptedfor authentication information. In an e-community configuration, the plug-in serveridentifies a vouch-for server and requests verification from this vouch-for serverthat the user has authenticated. The vouch-for server stores valid credentialinformation for the user.

For the user’s first request, the vouch-for server is always the MAS. The MAScontinues to serve as the vouch-for server for resources located in the homedomain. As the user continues with resource requests across the e-community, anindividual server in each remote domain can build its own credential for the user(based on user identity information from the MAS) and assume the role of vouch-for server for resources in its domain.

1

plug-in

Tivoli-IBM-Lotuse-community

p l u

g - i n ww1.ibm.com

p l u

g - i n

ww2.ibm.com

IBM Domain

MA S

p l u

g - i n ww1.lotus.com

p l u

g - i n

ww2.lotus.com

Lotus Domain

2 3

www.tivoli.com

SD

Client Browser

The example above shows two domains, IBM domain and Lotus domain, that existwithin an e-community. The following processes take place the first time a userlogs on to a secure Web site within the e-community:

1. The user requests access to a resource on the Web server ww1.ibm.com. Theplug-in intercepts the request and confirms that ww1.ibm.com is configured aspart of the Tivoli-IBM-Lotus e-community. The MAS server in the e-communityis identified from the ww1.ibm.com configuration.

Figure 9. Logging into an e-community.




2. The request is passed to the MAS - www.tivoli.com. The MAS authenticates therequest on behalf of ww1.ibm.com and issues a vouch-for token that becomesthe user’s e-community identity. The user identity information in the token isencrypted.

3. The MAS sends the vouch-for token to ww1.ibm.com. ww1.ibm.com treats thisvouch-for token as proof that the user has successfully authenticated to theMAS and can now access the requested resource based on normal authorization

controls.

The e-community cookiev The e-community cookie is a domain-specific cookie set by one plug-in, stored in

the memory of the user’s browser, and transmitted to other plug-in instances (inthe 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 and functionality,and a lifetime value. The cookie contains no user information.

v The e-community cookie allows servers in participating domains to requestvouch-for information locally. The e-community cookie for the domain where the

MAS is located plays a less significant role.v The cookie has a lifetime (timeout) value that is set in the pdwebpi.conf

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

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

reply. These URLs are constructed during the e-community vouch-for HTTPre-directs based on the configuration information in pdwebpi.conf.

The vouch-for requestThe vouch-for request is triggered when a user requests a resource from a targetserver (configured for e-community) that contains no credential information forthat user. The server sends 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-community

identity. The receiving server uses the target_url in the vouch-for reply to re-directthe browser back to the originally requested page.

The pkmsvouchfor vouch-for URL is configurable.

For example:

https://www.tivoli.com/pkmsvouchfor?companyABC&https://ww2.lotus.com/index.html




The vouch-for replyThe vouch-for reply is the response from the vouch-for server to the target server.

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://ww2.lotus.com/index.html?PD-VFHOST=www.tivoli.com&PD-VF=3qhe9fjkp...ge56wgb

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 passed only once. The receiving server uses this information to build user credentials in its own cache. The server uses these credentials for

future requests by that user during the same session.v The token has a lifetime (timeout) value that is set in the pdwebpi.conf

configuration file. This value can be very short (seconds) to reduce the risk of are-play attack.

Note: Token security has been improved in the plug–in 4.1 release. Theimprovements are not interoperable with the Tivoli Access Manager 3.9token encoding scheme. To continue to be able to interoperate with 3.9Tivoli Access Manager Web Security products set the pre-410-compatible-tokens configuration parameter in the [pdweb-plugins] stanza to true. Thisparameter is process-wide and cannot be specified on a per-virtual host

basis.

Encrypting the vouch-for tokenTivoli Access Manager Plug-in for Web Servers must encrypt the authenticationdata placed in the token using a key generated by the cdsso_key_gen utilitylocated in the pdwebrte/bin directory. You must ″synchronize″ this key by sharingthe key file with each plug-in server in each participating domain. Eachparticipating plug-in server in each domain needs to use the same key.

Note: The creation and distribution of key files is not a part of the Tivoli AccessManager e-community process. You must manually and securely copy keysto each participating server.




The cdsso_key_gen utility requires that you specify the full path to the utility andthe location (absolute pathname) of the key file when you run the utility:

UNIX:

# /opt/pdwebrte/bin/cdsso_key_gen absolute_pathname

Windows:

MSDOS> install_path/pdwebrte/bin/cdsso_key_gen absolute_pathname

The encryption keys are configured in the [ecsso-domain-keys] stanza of thepdwebpi.conf configuration file. Details of this configuration are covered in thenext section, “Configuring an e-community.”

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

Enabling and Disabling e-Community MembersThe [common-modules] stanza in the pdwebpi.conf configuration file defines the

use of all authentication methods. To enable a plug-in server to operate within ane-community, assign the term ecsso to the authentication and pre-authznparameters as in the following:

[common-modules]authentication = ecssopre-authzn = ecsso

When configuring for non-MAS e-community members, ecsso authentication musttake precedence over other authentication schemes; that is, ecsso must be specified

before other authentication schemes in the list of authentication modules. Also, if the ecsso module is to take precedence over an authentication module specifiedwith a higher authentication level than the default of 1, then the ecsso moduleitself must be configured with at least the same authentication level.

The [modules] stanza in the pdwebpi.conf configuration file defines all availableauthentication mechanisms and their associated shared library names. Ensure thatthe entry for e-community SSO exists:

[modules]ecsso = pdwpi-ecsso-module

e-community-nameThe e-community-name parameter identifies the name of the e-community theserver belongs to. For example:

[ecsso]e-community-name = companyABC

The e-community-name value must be the same for all members of ane-community.

is-master-authn-serverThis parameter identifies whether this server is the MAS or not. Possible values are yes or no. The parameter would be set as follows for the e-community MAS:

[ecsso]is-master-authn-server = yes




Multiple plug-ins 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 plug-in servers in the e-community.

If is-master-authn-server is set to yes, then this server will accept vouch-forrequests from other plug-in instances whose e-community-name is the same andwhose domain keys are listed in the [ecsso-domain-keys] stanza.

master-authn-serverIf the is-master-authn-server parameter is set to no, then the master-authn-serverparameter must be uncommented and specified. The parameter identifies the fullyqualified domain name of the e-community MAS. For example:

[ecsso]master-authn-server = www.tivoli.com

master-http-portAssign the port number that the master authentication server uses to receive HTTPrequests. If the port number is not the standard port 80 then the non-standard portnumber must be specified here.

[ecsso]master-http-port = port_number

master-https-portAssign the port number that the master authentication server uses to receiveHTTPS requests. If the port number is not the standard port 443 then thenon-standard port number must be specified here.

[ecsso]master-https-port = port_number

vf-token-lifetimeThis 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. The default

value is 180 seconds. You must take into account clock skew between participatingservers. By default the parameter is set as:

[ecsso]vf-token-lifetime = 180

vf-urlThis parameter specifies the vouch-for URL The value must begin with aforward-slash (/). The default setting value is:

[ecsso]vf-url = /pkmsvouchfor

You can also express an extended URL:

vf-url = /ecommA/pkmsvouchfor

vf-argumentThe value of the vf-argument parameter is the argument name of the vouch-fortoken as it appears in the vouch-for reply. The default value of PD-VF should only

be changed if custom create and consume modules are in use and a differentargument name is used to represent the vouch-for token.

The value is used to construct vouch-for replies by the MAS and to distinguishincoming requests as ones with couch-for information by participating ECSSOservers.




[ecsso]vf-argument = PD-VF

allow-login-retryA MAS that employs a username/password-based authentication scheme has twooptions when a user has performed an unsuccessful logon: it can prompt the usersto input their credentials again, or it can immediately redirect users back to the

server they originally attempted to access without vouching for the user. In thelater case, users are forced to authenticate directly to the subordinate server. Theallow-login-retry parameter controls this behavior at the MAS. This parameter isapplicable only to the configuration of the MAS within an ecsso community.

Note: Users can attempt to reset an expired password.

Other login failures occurring at the MAS, such as account locked, cause animmediate redirection back to the subordinate server irrespective of the value of the allow-login-retry parameter. By default the parameter is set as:

[ecsso]allow-login-retry = true

use-utf8This parameter controls the string encoding within the ECSSO vouch-for tokensand e-community cookies. The value of this parameter only affects vouch-fortokens created and consumed by the default SSO create and consume libraries.

[ecsso]use-utf8 = true

ecsso Domain KeysDefined in the [ecsso-domain-keys] stanza of the configuration file are thelocations of the key files required for encrypting and decrypting tokens betweenthe MAS and participating servers in remote domains. Configuration of the MASinvolves defining the keys for each domain for which it is the master.Configuration of e-community members other than the MAS involves defining the

key for the domain and for the MAS. You must specify the fully qualified domainnames for the servers and the absolute path names for the key file locations.

The following MAS configuration example provides the MAS, located within thetivoli.com domain, with key files for communicating with two remote domains:

[ecsso-domain-keys]ibm.com = /abc/xyz/ibm-tivoli.keylotus.com = /abc/xyz/lotus-tivoli.keytivoli = /abc/xyz/tivoli.key

Note: In the above example, it is crucial to have tivoli.key for data exchange between servers in the tivoli domain.

Configuration for servers in the domains involves specifying the MAS domain andthe corresponding key used to exchange information with the MAS. A key is alsorequired for data exchange between servers in the domain. For example the[ecsso-domain-keys] stanza for a server in a domain participating in ane-community may look like this:

[ecsso-domain-keys]#the key for data exchange between the MAS (tivoli.com)#and the ibm.com domain serverstivoli.com = /abc/xyz/ibm-tivoli.key#the key for data exchange between servers in the ibm.com domainibm.com = /abc/xyz/ibm.key




Including credential attributes in the vouch-for tokensYou can include credential attributes in the eCSSO vouch-for tokens by specifyingthem in the [ecsso-token-attributes] stanza of the plug-in configuration file. Theattributes to be included can be specified on a peer-to-peer or per-domain basis.The credential attributes listing in this stanza is only relevant when the defaultSSO token creation and consumption libraries are in use. If you do not requirecredential attributes in eCSSO vouch-for tokens, then you can leave this stanza

empty.

The default name of this stanza is derived from the module name for thepdwpi-ecsso-module defined in the [modules] stanza. It is of the form[ecsso_module_name-token-attributes].

The values in the [ecsso-token-attributes] stanza are default across all virtual hostsand can be overridden on a per virtual-host basis by creating a[ecsso_module_name-token-attributes:virtual_host] stanza.

The format of the entries is: domain_name = pattern1, pattern2, ... pattern n.

Credential attributes matching the specified patterns for a target host or domain

are included in eCSSO vouch-for tokens constructed for that target host or domain.Only a single value for each attribute is used, and only string values aresupported. Other types of credential attribute values are ignored. Patterns can bespecified using the pattern matching characters explained in Appendix E, “Specialcharacters allowed in regular expressions,” on page 213.

For example:

[ecsso-token-attributes]ibm.com = attrprefix_*, *name*tivoli.com = *_attrsuffix, some_exact_attribute

A default set of attributes can be configured using a <default> entry in this stanza.Such a default set of attributes is used when there is no other entry matching aparticular target host. If the <default> entry is not present, then no attributes will

be included by default.

Accepting and rejecting credential attributes from vouch-fortokensYou can specify the credential attributes to accept and those to reject fromincoming vouch-for tokens by specifying the values in the [ecsso-incoming-attributes] stanza. Unlike the outgoing attributes configuration, incoming attributescannot be configured on a per-peer or per-domain basis. Only one set of attributepatterns can be configured, and these patterns will be applied to incoming tokensregardless of source. This processing only takes place if the default SSO tokencreation and consumption libraries are in use. The default name of this stanza isderived from the module name for the pdwpi-ecsso-module defined in the[modules] stanza. It is of the form [ecsso_module_name-incoming-attributes]. Thevalues in this stanza are default across all virtual hosts. However, they may beoverridden on a per virtual-host basis by configuring a [ecsso_module_name-incoming-attributes:virtual_host] stanza.

The format of entries in this stanza is:

attribute_pattern = preserve|refresh

Attributes in eCSSO vouch-for tokens that match a refresh entry are removed fromthe token before the CDMF library is called to map the remote user into the local




domain. Attributes matching a preserve entry, or matching none of the entries, areretained. If no entries are configured, then all attributes are retained.

Specify the sso-create and sso-consume librariesTo specify sso-create and sso-consume libraries, edit the plug-in configuration file.In the [authentication-mechanisms] stanza, uncomment the entry for sso-createand sso-consume and add the name of the plug-in failover cookie library

appropriate for the operating system type.

The default configuration file entry is:

[authentication-mechanisms]sso-create = /opt/pdwebrte/lib/ibssocreate.sosso-consume = /opt/pdwebrte/lib/libssoconsume.so

Alternatively, when you have developed a CDAS library that implements acustomized version of sso-create and sso-consume functionality, insert the name of the custom CDAS as the value for the configuration file keyword. For example, if you developed a custom CDAS for sso-create, enter the absolute path name:

[authentication-mechanisms]sso-create = /dir_name/custom_cdas_sso-create.so

Failure to configure ecsso keys correctly generates warnings within the plug-in logfile.

Configuring e-community single sign-on - an exampleIn the following example there are two e-communities configured – lotus-dominoand ibm-db2 – with a single MAS authenticating the requests for bothcommunities.

MAS

p l u

g - i n

www.tivoli.com

plug-in

lotus-domino

e-community

ibm-db2

e-community

p l u

g - i n

p l u

g - i n

p l u

g - i n

p l u

g - i n

www.domino.com www.lotus.com ww1.ibm.com www.db2.com

ww2.ibm.com

The following conditions apply for this example:

v www.tivoli.com is the MAS for both e-communities.

Figure 10. e-Community single sign-on configuration example




v Two distinct domains (one server in each domain for simplicity) exist within thelotus-domino e-community – domino.com and lotus.com. Users accessing one of these domains can access the other without the need to re-authenticate as allaccess is granted via the MAS.

v The ibm-db2 e-community contains two distinct domains – ibm.com anddb2.com. Users accessing one of these domains can access the other without theneed to re-authenticate.

v Users accessing one of the ibm.com servers can access the other using avouch-for token. Single sign-on in this case is achieved without the need for theMAS to grant access.

In the above example, the following configuration options apply:

Configuration of the MAS – www.tivoli.comAs the MAS is the control center for more than one e-community, twodistinct instances of the ecsso module need to be configured and thee-community names that the MAS controls need to be defined. The MASneeds to have specified all the keys of the main domains within all thecommunities it controls. Configuration is set as follows:

[modules]ecsso1 = pdwpi-ecsso-moduleecsso2 = pdwpi-ecsso-module

[common-modules]authentication = ecsso1authentication = ecsso2

pre-authzn = ecsso1pre-authzn = ecsso2

[ecsso1]e-community-name = lotus-dominois-master-authn-server = yes.....etc

[ecsso2]e-community-name = ibm-db2is-master-authn-server = yes.....etc

[ecsso1-domain-keys]# one key for each domain the MAS controlsdomino.com = /abc/tivolikeys/tivoli-domino.keylotus.com = /abc/tivolikeys/tivoli-lotus.keydb2.com = /abc/tivolikeys/tivoli-db2.keyibm.com = /abc/tivolikeys/tivoli-ibm.key

Configuration of www.domino.com


[common-modules]authentication = ecsso

pre-authzn = ecsso

[ecsso]e-community-name = lotus-dominois-master-authn-server = nomaster-authn-server = www.tivoli.com.....etc

[ecsso-domain-keys]




#key for encrypting/decrypting data#between servers in the domino.com domaindomino.com = /abc/domino-keys/domino.key#key for encrypting/decrypting data between#servers in the domino.com domain and the MAStivoli.com = /abc/domino-keys/tivoli-domino.key

Configuration of www.lotus.com

The configuration parameters for achieving single sign-on towww.lotus.com will be identical to those configured for www.domino.comexcept the domain keys will be different. Domain keys configuration forwww.lotus.com would be as follows:

[ecsso-domain-keys]#key for encrypting/decrypting data#between servers in the lotus.com domainlotus.com = /abc/lotus-keys/lotus.key#key for encrypting/decrypting data#between servers in the lotus.com domain and the MAStivoli.com = /abc/lotus-keys/tivoli-lotus.key

Configuration of www.db2.com


[common-modules]authentication = ecsso

pre-authzn = ecsso

[ecsso]e-community-name = ibm-db2is-master-authn-server = nomaster-authn-server = www.tivoli.com.....etc

[ecsso-domain-keys]#key for encrypting/decrypting data#between servers in the db2.com domain

db2.com = /abc/db2-keys/db2.key#key for encrypting/decrypting data between#servers in the db2.com domain and the MAStivoli.com = /abc/db2-keys/tivoli-db2.key

Configuration of ww1.ibm.comThe e-community single sign-on configuration for ww1.ibm.com isidentical to that of www.db2.com. Two keys are required, one forencrypting/decrypting data between the MAS and the ibm.com domainand a key for encrypting/decrypting data between servers within theibm.com domain (i.e. ww1.ibm.com and ww2.ibm.com in this example).

[ecsso-domain-keys]ibm.com = /abc/ibm-keys/ibm.keytivoli.com = /abc/ibm-keys/tivoli-ibm.key

Configuration of ww2.ibm.comThe definition of keys for ww2.ibm.com will be identical to that forww1.ibm.com.

[ecsso-domain-keys]ibm.com = /abc/ibm-keys/ibm.keytivoli.com = /abc/ibm-keys/tivoli-ibm.key




Chapter 7. Application integration

Tivoli Plug-in for Web Servers supports third-party application integration throughenvironment variables and dynamic URL capability. The plug-in extends the range

of environment variables and HTTP headers to enable third-party applications toperform operations based on a client’s identity. In addition, the plug-in can provideaccess control on dynamic URLs, such as those that contain query text.

The following topics are covered in this chapter:

v “Maintaining session state between the client and back-end applications”

v “Providing access control to dynamic URLs” on page 161

Maintaining session state between the client and back-end

applications

As seen in “Managing session state” on page 49, Tivoli Access Manager for WebServers can maintain session state with clients over HTTP and HTTPS using avariety of different information. The plug-in can also provide user sessioninformation to back-end applications so that the back-end applications canmaintain session state with clients. Providing user session information in this wayprovides a method for identifying the user session and the ability to drop a usersession at the request of the plug-in protected application.

Without an established session state between client and server, the communication between 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.

Enabling user session ID managementThe add-session-id-to-cred parameter in the [performance] stanza of the plug-inconfiguration 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 istrue (enabled):

[performace]add-session-id-to-cred = true

To disable the creation of unique User Session IDs, set add-session-id-to-cred to false.

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 ″tag value″ prefix that is configurable using the tag-value-prefixparameter in the [pdweb-plugins] stanza of the configuration file. Specifying aprefix prevents any conflicts with other existing information 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 plug-in instance name (to support multiple plug-ininstances) and the standard plug-in session ID for the user.

A single user that logs in multiple times (for example, from different machines) hasmultiple plug-in session IDs. Because the User Session ID is based on the plug-insession ID, there exists a one-to-one mapping between them. The unique usersession ID is stored as an attribute to the user’s credential. This allows the value to

be passed across a junction as an HTTP header (using tag-value functionality) andmade 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 application server. This goal is accomplished by configuring theHTTP-Tag-Value extended attribute on the object.

You use the pdadmin object modify set attribute command to set an extendedattribute on an object in the plug-in protected object space.

pdadmin> object modify object_name set attribute attr_name attr_value

An attribute (″attr-name″) enables the plug-in to perform a specific type of functionality. The HTTP-Tag-Value attribute enables the plug-in to extract a valuefrom a credential extended attribute and send the value to the server in an HTTPheader.

The value of the HTTP-Tag-Value extended attribute uses the following format:

credential_extended_attribute_name=http_header_name

For User Session ID data, the credential_extended_attribute_name entry is the same asthe user_session_id extended attribute name specified in the configuration file butwithout the configured prefix. The entry is not case-sensitive. The value of thisextended attribute contains the unique User Session ID.

The http_header_name entry specifies the name of the HTTP header used to deliverthe data. In this example, a header called PD-USER-SESSION-ID is used:

pdadmin> object modify /PDWebPI/host set attribute \HTTP-Tag-Value user_session_id=PD-USER-SESSION-ID

When the plug-in processes a user request to a back-end application server, it looksfor any HTTP-Tag-Value extended attributes configured on the object.

In this example, the plug-in looks at the credential of the user making the request,extracts the User Session ID value from the tagvalue_user_session_id extendedattribute in the credential, and places the value in an HTTP header as:

PD-USER-SESSION-ID:user_session_id_number

In summary:

Value of HTTP-Tag-Value attributeset on the plug-in object:

user_session_id=PD-USER-SESSION-ID

Attribute name and value as theyappear in the user credential:

tagvalue_user_session_id:user_session_id_number

HTTP header name and value: PD-USER-SESSION-ID:user_session_id_number




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

Terminating user sessionsUser session ID management functionality can be used to terminate user sessionsgiven a unique user session ID or a Tivoli Access Manager username. Thesecommands can be run from the PDADMIN command line (using server task) butthey are intended for use by a back-end application through the PDAdmin API.Terminating a session using the User Session ID causes the plug-in to discard thesingle session that the User Session ID identifies. Other sessions from the sameuser can continue.

Terminating using the Tivoli Access Manager username causes the plug-in todiscard ALL sessions that are owned by the given username. This command may

end many sessions if the user is logged in multiple times from different locationsor different browsers.

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

below is two methods for terminating user sessions at an administration level:

An administrator can use the pdadmin utility to terminate a single user sessionusing the user ID.

pdadmin> server task pdwebpi- plugin-instance-name terminate all_sessions user-id

Using the all-sessions command as shown above, each session for the specified

user is terminated on all virtual-hosts on the machine.

This command can be refined to terminate user sessions for a particular user on aparticular virtual host using the -vhost parameter as in the following (entered asone line):

pdadmin> server task pdwebpi- plugin-instance-name terminate all_sessionsuser-id -vhost "virtual-host-name"

Providing access control to dynamic URLs

Tivoli Access Manager Plug-in for Web Servers can apply authorization to Webobjects based on a pattern match of the entire request string rather than just the

object’s URL. This is useful for Web applications that dynamically generate URL’sin response to each user request that still require strong protection from unwanteduse or access. This is also useful for assigning different permissions to the differentmethods of scripts.

For example, the query string GET /cgi-bin/servercontrol?action=showstatuswould have diffferent security requirements to GET /cgi-bin/servercontrol?action=shutdown. Each of these requests may need to berepresented uniquely in the objectspace so that different policy can be applied toeach.

Chapter 7. Application integration 161



The dynurl module allows a set of patterns to be defined that are matched againstincoming requests. The patterns are matched against the entire request string somatching on information in the query string is possible. For each DynURL pattern,a Tivoli Access Manager object is defined. This object appears in the objectspace sothat policy can be associated with it. At runtime, any request that matches a dynurlpattern is authorized using the object associated with the pattern rather than theobject that represents the URL. By defining different patterns that independently

match different query strings, different Tivoli Access Manager objects can be usedand different policy can be applied.

Configuring dynamic URLsThe [common-modules] stanza in the pdwebpi.conf configuration file defines theuse of all authentication methods. To enable pattern-matching of dynamic URLs forincoming requests, the dynurl module needs to be configured as apre-authorization module. This allows the dynurl module to change the requestedobject before the authorization engine is reached.

[common-modules]...pre-authzn = dynurl...

Ensure that the entry for dynamic URLs exists in the [modules] stanza of thepdwebpi.conf configuration file:

[modules]...dynurl = pdwpi-dynurl-module...

The [dynurl] stanza (by default or the stanza name matching the configuredmodule name) contains the definitions for the dynamic URL pre-authorizationmodule. This stanza can be overwritten on a per-virtual host basis, that is,[dynurl:virtual-host]. The entries within the [dynurl] stanza are of the form object = pattern each entry being on a separate line. The order of the list determines theorder in which the rules are processed. Entries which occur earlier in the stanzatake precedence over those that occur later in the stanza. For example:

[dynurl]/servershutdown = /servercontrol.asp\?*action=shutdown*/serverreset = /servercontrol.asp\?*action=reset*/helppages = *help.html

Note that the objects all start with a backslash (″/″). The last entry in theconfiguration above shows a second use of the dynurl module. In this case thepattern matches a set of URLs (any URL ending in help.html). In this case DynURLis performing a many-to-one mapping of URLs to Tivoli Access Manager objects.All requests for pages called help.html (regardless of their path) will be authorizedagainst the same Tivoli Access Manager object. This might be useful in situations

where files with similar names (that can be grouped by a pattern) all have thesame security requirements. However, note that each pattern defined is matchedagainst every request and so slows down every authorization.

Note also that use of the pattern *help.html may have security implications forscripts, since a request for say,

/servercontrol.asp?action=some_other_action&pointless_variable_used_to_evade_acl_attached_to_server_control.asp=help.html




will match the *help.html dynamic URL. Therefore, access will be evaluated basedon the /helppages object rather than the /servercontrol.asp object. Similarly, arequest for,

/someotherscript?action=someaction&other_var=help.html

will be evaluated based on the /helppages object rather than the /someotherscriptobject.

For a list of the special characters allowed in regular expressions used in the formssingle sign-on configuration file refer to Appendix E, “Special characters allowed inregular expressions,” on page 213.

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.

Chapter 7. Application integration 163



Chapter 8. Authorization decision information retrieval

This chapter contains information that describes how Tivoli Access ManagerPlug-in for Web Servers can provide, or acquire, authorization decision information

(ADI) required to evaluate authorization rules that protect resources in the TivoliAccess Manager domain.

The following topics are covered in this chapter:

1. “Overview of ADI retrieval”

2. “Retrieving ADI from the plug-in client request” on page 166

3. “Retrieving ADI from the user credential” on page 168

4. “Supplying a failure reason” on page 168

5. “Configuring dynamic ADI retrieval” on page 169

Overview of ADI retrieval

The Tivoli Access Manager authorization rules evaluator performs authorizationdecisions based on Boolean logic applied to specific access decision information(ADI). Detailed information on the construction of authorization rules (usingBoolean logic) and authorization decision information (ADI) can be found in theIBM Tivoli Access Manager Base Administration Guide.

ADI required for rules evaluation can be retrieved from the following sources:

v Authorization decision parameters provided to the authorization rule as ADI bythe authorization service.

Parameters include the target resource (protected object) and the requestedaction on the resource. Refer to the IBM Tivoli Access Manager Base Administration

Guide for further information on this topic.v The user credential

The user credential is always included with the function call to the authorizationrules evaluator, so it is immediately available.

v The resource manager environment (application context)

A resource manager, such as the plug-in, can be configured to provide ADI fromits own environment. For example, the plug-in has the capability to provide ADIcontained in parts of the client request. A special prefix is used in theauthorization rule to ″trigger″ this type of ADI source.

v An external source through dynamic ADI retrieval services.

ADI can be obtained externally through the AMWebARS Web service. A call ismade to the AMWebARS Web service through the resource manager’s

entitlement service. ADI from the external source is returned in XML format tothe authorization rules evaluator.

ADI can be obtained dynamically through calls to specific entitlement servicesthat have been configured to retrieve ADI dynamically during rule evaluation. Acall is made to each dynamic ADI retrieval service and the ADI values arereturned to the authorization rules evaluator. Examples of dynamic ADI retrievalservices shipped with Tivoli Access Manager are the ″Registry attributeentitlement service″, which retrieves ADI values from the user registry, and theAMWebARS entitlement service, which retrieves ADI values using the




AMWebARS web service. Both are discussed in more detail in the Tivoli Access Manager Authorization C Developer’s Reference.

Retrieving ADI from the plug-in client request

Authorization decision information (ADI) may be contained in the request header,the request query string, and the request POST body. You can create authorization

rules that refer to this authorization decision information (ADI). This is done usingplug-in specific XML containers that refer to the ADI to be acquired.

The resource-manager-provided-adi parameter in the [aznapi-configuration]stanza of the pdwebpi.conf configuration file specifies—to the authorization rulesevaluation process— the prefixes that can be used in container names specified byauthorization rules. To specify multiple prefixes, use multiple entries of theresource-manager-provided-adi parameter:

The following container names contain prefixes that are appropriate for theplug-in:

v AMWS_hd_name

Request header container name. The value of the HTTP header called name inthe HTTP request is returned to the authorization rules evaluator as ADI.

v AMWS_qs_name

Request query string container name. The value of name in the request querystring is returned to the authorization rules evaluator as ADI.

v AMWS_pb_name

Request POST body container name. The value of name in the request POST body is returned to the authorization rules evaluator as ADI.

Prefixes can be specific to any resource manager. Accordingly, the resourcemanager must be designed to respond appropriately to a request for ADI.

Authorization rules are written that specify the ADI required from client requests.For example, if the host name contained within the HTTP header is required asADI, the AMWS_hd_ prefix is used in the XML container name specified in the rule.This plug-in-specific prefix alerts the authorization evaluation process that therequired ADI is available in the client request and that the plug-in knows how tofind, extract, and return this ADI. The AMWS_hd_host container name is sent to theplug-in. The plug-in responds to the AMWS_hd_host container name by looking forthe ″host″ header in the client request and extracting the value associated with thatheader. The plug-in returns the ″host″ header value (as an XML container) to theauthorization rules evaluation process. The authorization rules evaluation processuses the value as ADI in its evaluation of the rule.

Example: Retrieving ADI from the request headerThe following example authorization rule requires the name of the client machine’shost name. The client request is set up to include the host name value in the ″host″header of the request. The use of the AMWS_hd_ prefix in the rule alerts theauthorization evaluation process that the required ADI is available in the clientrequest and that the plug-in knows how to find, extract, and return this ADI.

<xsl:if test=’AMWS_hd_host = "machineA"’>!TRUE!</xsl:if>

The plug-in is designed to know how to handle the extraction of ADI informationfrom the request:




[aznapi-configuration]resource-manager-provided-adi = AMWS_hd_

The plug-in understands this information can be found in the request header namehost. The plug-in extracts the value contained in the ″host″ header and returns it tothe authorization evaluation process.

The example authorization rule is evaluated to be true if the value provided in therequest’s ″host″ header is ″machineA″.

In a similar manner, information required to evaluate an authorization rule cancome from the request POST body or the query string of the request.

Example: Retrieving ADI from the request query stringThe following example authorization rule requires the name of the client’s zip codeas passed in the query string of a GET request (as submitted in response to aform). The client request is set up to include the zip code value in the ″zip″ field of the request query string.

https://www.service.com/location?zip=99999

The use of the AMWS_qs_ prefix in the rule alerts the authorization evaluationprocess that the required ADI is available in the client request and that the plug-inknows how to find, extract, and return this ADI.

<xsl:if test=’AMWS_qs_zip = "99999"’>!TRUE!</xsl:if>

The plug-in is designed to know how to handle the extraction of ADI informationform the request:

[aznapi-configuration]resource-manager-provided-adi = AMWS_qs_

The plug-in understands this information can be found in the request query stringunder the field name ″zip″. The plug-in extracts the value contained in the ″zip″

field and returns it to the authorization evaluation process.

The example authorization rule is evaluated to be true if the value provided in therequest’s query string ″zip″ field is ″99999″.

In a similar manner, information required to evaluate an authorization rule cancome from the request POST body or the request header.

Example: Retrieving ADI from the request POST bodyThe following example authorization rule requires the name of the client’s totalpurchase amount from a Web shopping cart as passed in the body of a POSTrequest (as submitted in response to a form). The client request is set up to include

the total purchase value in the″

purchase-total″

field of the request POST body.

The use of the AMWS_pb_ prefix in the rule alerts the authorization evaluationprocess that the required ADI is available in the client request and that the plug-inknows how to find, extract, and return this ADI.

<xsl:if test=’AMWS_pb_purchase-total < "1000.00"’>!TRUE!</xsl:if>

The plug-in is designed to know how to handle the extraction of ADI informationform the request:

[aznapi-configuration]resource-manager-provided-adi = AMWS_pb_

Chapter 8. Authorization decision information retrieval 167



The plug-in understands this information can be found in the request POST bodyunder the field name ″purchase-total″. The plug-in extracts the value contained inthe ″purchase-total″ field and returns it to the authorization evaluation process.

The example authorization rule is evaluated to be true if the value provided in therequest’s POST body ″purchase-total″ field is less than ″1000.00″.

In a similar manner, information required to evaluate an authorization rule cancome from the request header or the query string of the request.

Retrieving ADI from the user credential

Authorization rules can be written to use ADI that is provided initially to theauthorization rules evaluator as part of the credential. The initial call to theauthorization service (azn_decision_access_allowed_ext()) actually contains theuser’s credential information. The authorization rules evaluator always looksthrough this credential information for any ADI required by the rule beingprocessed. The authorization rule can use the value from any field in thecredential, including extended attributes added to the credential duringauthentication.

The technique for creating extended attributes in the user credential is explained in“Adding extended attributes for credentials” on page 99.

Supplying a failure reason

Authorization rules allow you to set up special, and often complex, conditionsgoverning the ability to access a protected resource. However, the standard resultof a failed authorization decision is to stop the progress of the request to theservice application that controls the resource, and present the client with a″forbidden″ message. If the authorization rule is written to include a failure reason,and is evaluated as FALSE by the Tivoli Access Manager authorization rules

evaluator, the plug-in receives the reason for the rule’s failure along with thestandard ″forbidden″ message from the authorization service. The failure reason isusually ignored and the ″forbidden″ decision is enforced

You can optionally configure the plug-in to reject this standard response and allowdenied requests to proceed to a back-end service application. The request isaccompanied by the failure reason provided in the authorization rule. The

back-end service application then has the opportunity to proceed with its ownresponse to the situation. This optional configuration in specified using thepass-on-rule-failure-reason parameter in the [boolean-rules] stanza in thepdwebpi.conf file.

Authorization rules are typically used in conjunction with service applications that

can understand and handle this more sophisticated level of access control. In somecases, it is necessary for the service application to receive a request that is denied

by the Tivoli Access Manager authorization service. Such an application is writtento understand failure reason information and can provide its own response to arequest that has failed a Tivoli Access Manager authorization rule.

For example, the order processing component of a shopping cart application can begoverned by an authorization rule that denies action on an order if the totalpurchase price exceeds the user’s credit limit. It is important for the shopping cartapplication to receive the entire request and the reason for failure. Now theshopping cart application can take matters into its own hands and provide a




user-friendly response, such as advising the user to eliminate a portion of theorder. The interaction with the user is preserved rather than cut off.

Always use this option with caution. It is important to coordinate the use of failurereasons in authorization rules with a service application’s ability to interpret andrespond to this information. You do not want to accidently create a situation whereaccess is granted to a resource controlled by an application that cannot respond

accurately to the AM_AZN_FAILURE header.

Configuring dynamic ADI retrieval

Rules can be written requiring authorization decision information (ADI) thatcannot be found in any of the information that the Tivoli Access Managerauthorization service has access to. In these cases, it is necessary to retrieve theADI from an outside source. This retrieval can be performed in real-time by adynamic ADI entitlement retrieval service. The AMWebARS Web service, currentlyprovided with the WebSEAL Attribute Retrieval Service, is one type of entitlementretrieval service.

The Attribute Retrieval Service (ARS) provides communication and formattranslation services between the plug-in’s entitlement service library and anexternal provider of authorization decision information. The following diagramillustrates the process flow for the AMWEBARS Web service:

Client request

Plug-in

AuthorizationService

EntitlementService library

Policydatabase

ADI returned

ADI requested

ADIrequested

ADIreturned

External ProfilingService

AMWebARS

Web Service DescriptionLanguage (WSDL)

WebSphere

1

2

3

4 5

6

Process flow:

1. The client makes a request for a resource protected by an authorization rule.

2. The authorization rules evaluator—part of the authorizationservice—determines that specific authorization decision information (ADI) isrequired to complete the evaluation of the rule. The ADI requested is notavailable from the user credential, the authorization service, or the plug-in.

3. The task of ADI retrieval is sent to the AMWebARS Web service through theentitlement service library. This service formats the request for ADI as a SOAP

Figure 11. Attribute retrieval service process flow..

Chapter 8. Authorization decision information retrieval 169



request. The SOAP request is sent over HTTP to the Web Service DescriptionLanguage (WSDL) interface of the AMWebARS Web service.

4. The AMWebARS Web service formats the request appropriately for the externalprofiling service that is to provide the ADI.

5. The external profiling service returns the appropriate ADI.

6. The ADI is formatted in another SOAP container and returned to the plug-in’s

entitlement service. Now the authorization rules evaluator has the necessaryinformation to evaluate the rule and make a decision to accept or deny theoriginal client request.

For information on deploying the attribute retrieval service refer to the Tivoli Access Manager WebSEAL Administrator Guide.

Configuring the plug-in to use the AMWebARS Web servicePerform the following tasks to configure plug-in to use the AMWebARS Webservice:

1. In the pdwebpi.conf configuration file, specify the identification name (ID) of the dynamic ADI entitlement retrieval service that is queried when missingADI is detected during a rules evaluation. In this case, the AMWebARS Web

service is specified:

[aznapi-configuration]dynamic-adi-entitlements-services = AMWebARS

2. In the pdwebpi.conf configuration file, use the configured dynamic ADIentitlement retrieval service ID as a parameter to specify the appropriate

built-in library that formats out-bound ADI requests and interprets incomingresponses: For example:

[aznapi-entitlement-services]dynADI = azn_ent_amwebars

3. In the pdwebpi.conf configuration file, specify the URL to the dynADI Webservice located in the WebSphere environment (entered as one line):

[amwebars]

service-url = http://websphere_hostname:websphere_port \/dynadi/dynadi/ServiceToIServicePortAdapter

4. Restart the plug-in.




Appendix A. Using pdbackup to backup plug-in data

The pdbackup utility allows you to back up and restore Tivoli Access Managerdata. The pdbackup utility uses, as an argument, a backup list file that specifies

the files and directories that require backing up. Each major Tivoli Access Managercomponent (such as Base, WebSEAL and the plug-in) has its own list file. Thepdinfo-pdwebpi.lst file specifies the plug-in files and directories that are backedup by the pdbackup utility.

This appendix describes how to use the pdbackup utility to back up and restoreplug-in data. The complete reference for the pdbackup utility is located in the IBMTivoli Access Manager Command Reference.

Functionality

Backing up plug-in dataThe pdbackup utility backs up the list of files and directories contained in theplug-in backup list file, pdinfo-pdwebpi.lst.

UNIX:By default, pdinfo-pdwebpi.lst is located in /opt/pdwebpi/etc/.

By default, the resulting backup archive is stored as a single .tar file in/var/PolicyDirector/pdbackup.

The default .tar file name is constructed using the backup list filename, plus adate and time stamp:

list-file-name_ddmmyyy.hh_mm.tar

For example:

pdinfo-pdwebpi.lst_30jul2003.10_39.tar

Alternatively, you can specify:

v A custom file name for the .tar file (use the –file option)

This custom file name does not contain a date and time stamp.

v A custom directory location for the .tar file (use the –path option)

The contents of the .tar file extract into the following directories:

opt/ var/ tmp/

Windows:By default, the pdinfo-pdwebpi.lst file is located inC:\Program Files\Tivoli\PDWebpi\etc\

By default, the resulting backup archive is stored as a directory tree in theC:\Program Files\Tivoli\PDWebpi\pdbackup\ directory.

The default .dar directory name is constructed from the backup list file name, plusa date and time stamp:

list-file-name_ddmmmyyyy.hh_mm.dar




For example:

pdinfo-pdwebpi.lst_30jul2003.10_39.dar

The contents of the .dar file extract into a sub-directory and a file:

%C%Registry

The %C% directory contains the complete backup tree. The name of this directory isdetermined by the letter designation of the drive where the plug-in files anddirectories are located. The Registry file stores the registry keys (.reg extensions).

Alternatively, you can specify:

v A custom file name for the .dar directory archive (use the –file option)

This custom file name does not contain a date and time stamp.

v A custom directory location for the .dar directory archive (use the –path option)

Restoring plug-in data

UNIX:Archived files and directories are restored from the .tar file to the /opt/pdwebpidirectory.

Windows:Archived files are restored to their original installation directory locations.

Syntax

A complete reference for the pdbackup utility can be found in the IBM Tivoli Access Manager Command Reference.

pdbackup –a backup –l backup-list-pathname \[–path custom-pathname][–file archive-pathname] [–usage] [–?]

pdbackup –a restore –file archive-pathname \[–path custom-pathname] [–usage] [–?]

Option Description

–a [backup|restore|extract] Specifies backup, restore, or extract operation.

–l backup-list-pathname Specifies the fully qualified path to the backuplist file (pdinfo-pdwebpi.lst).

–path custom-pathname Used for backup, specifies a custom archivedirectory location.

–file archive-pathname Used for backup, specifies a custom name for thearchive file.

Used for restore, specifies the fully qualified pathto the archive file that is to be restored.

You can use short versions of the command option names, but the abbreviationmust be unambiguous. For example, you can type a for action. However, valuesfor arguments to these options cannot be abbreviated.




Examples

UNIX examples1. The following example performs a standard back up with default values:

pdbackup -a backup -l /opt/pdwebpi/etc/pdinfo-pdwebpi.lst

This results in a file named pdinfo-pdwebpi.lst_date.time.tar that is stored inthe /var/PolicyDirector/pdbackup directory.

2. The following example performs a back up and stores the default archive file inthe /var/backup directory:

pdbackup -a backup -l /opt/pdwebpi/etc/pdinfo-pdwebpi.lst -path /var/backup

This results in a file named pdinfo-pdwebpi.lst_date.time.tar located in the/var/pdbackup directory.

3. The following example performs a back up and creates an archive file namedamwebarchive.tar:

pdbackup -a backup -l /opt/pdwebpi/etc/pdinfo-pdwebpi.lst -file amwebarchive

The default archive extension (.tar) is appended to the custom amwebarchivefile name. This file is stored in the default /var/PolicyDirector/pdbackupdirectory.

4. The following example restores the archive file from the default directorylocation:

pdbackup -a restore -file pdinfo-pdwebpi.lst_29Aug2003.07_24.tar

5. The following example restores the archive file from the /var/pdback directory:

pdbackup -a restore -file /var/pdback/pdinfo-pdwebpi.lst_29Aug2003.07_25.tar

Windows examples1. The following example performs a standard backup with default values:

pdbackup -a backup -l install_path\etc\pdinfo-pdwebpi.lst

This results in a file named pdinfo-pdwebpi.lst_date.time.dar located in theplug-in install_path\pdbackup directory.

2. The following example performs a back up using the default archive file nameand stores the file in the C:\pdback directory:

pdbackup -a backup -l install_path\etc\pdinfo-pdwebpi.lst -path c:\pdback

3. The following example performs a back up and creates a file namedpdarchive.dar:

pdbackup -a backup -l install_path\etc\pdinfo-pdwebpi.lst -file pdarchive

The default archive extension (.dar) is applied to the custom pdarchive filename. The file is stored in the default install_path\pdbackup directory.

4. The following example performs a back up to the \pdback directory on the F:drive:

pdbackup -a backup -l pdinfo-pdwebpi.lst -path f:\pdback

5. The following example restores the archive file from the default directory (singledirectory shown over two lines):

pdbackup -a restore -file install_path\pdbackup\pdinfo-pdwebpi.lst_29Jun2003.07_24.dar

6. The following example restores files from the H:\pdbackup directory:

Appendix A. Using pdbackup to backup plug-in data 173



pdbackup -a restore -file h:\pdbackup\pdinfo-pdwebpi.lst_29Jun2003.07_25.dar

Contents of pdinfo-pdwebpi.lst[UNIX FILES]# fully qualified file names./opt/pdwebpi/etc./var/pdwebpi/audit

./var/pdwebpi/db./var/pdwebpi/keytab

./var/pdwebpi/log

[UNIX CONF FILES]# configuration files that specify a file to include# file:stanza:option/opt/pdwebpi/etc/pdwebpi.conf:uraf-ad:ad-server-config/opt/pdwebpi/etc/pdwebpi.conf:uraf-domino:domino-server-config/opt/pdwebpi/etc/pdwebpi.conf:ldap:ldap-server-config/opt/pdwebpi/etc/pdwebpi.conf:ldap:ssl-keyfile/opt/pdwebpi/etc/pdwebpi.conf:ldap:ssl-keyfile-stash/opt/pdwebpi/etc/pdwebpi.conf:failover:failover-cookies-keyfile/opt/pdwebpi/etc/pdwebpi.conf:ltpa:ltpa-keyfile/opt/pdwebpi/etc/pdwebpi.conf:ltpa:ltpa-stash-file/opt/pdwebpi/etc/pdwebpi.conf:iis:query-log-file/opt/pdwebpi/etc/pdwebpi.conf:iis:log-file/opt/pdwebpi/etc/pdwebpi.conf:iplanet:query-log-file

[WINDOWS FILES]BASEDIR=SOFTWARE\Tivoli\Access Manager Plug-in for Web Servers:Path<BASEDIR>etc<BASEDIR>log<BASEDIR>audit<BASEDIR>db<BASEDIR>keytab

[WINDOWS CONF FILES]# configuration files that specify a file to include# file:stanza:option<BASEDIR>etc/pdwebpi.conf:uraf-ad:ad-server-config

<BASEDIR>etc/pdwebpi.conf:uraf-domino:domino-server-config<BASEDIR>etc/pdwebpi.conf:ldap:ldap-server-config<BASEDIR>etc/pdwebpi.conf:ldap:ssl-keyfile<BASEDIR>etc/pdwebpi.conf:ldap:ssl-keyfile-stash<BASEDIR>etc/pdwebpi.conf:failover:failover-cookies-keyfile<BASEDIR>etc/pdwebpi.conf:ltpa:ltpa-keyfile<BASEDIR>etc/pdwebpi.conf:ltpa:ltpa-stash-file<BASEDIR>etc/pdwebpi.conf:iis:query-log-file<BASEDIR>etc/pdwebpi.conf:iis:log-file<BASEDIR>etc/pdwebpi.conf:iplanet:query-log-file

[WINDOWS REGISTRY]# specify keys to backupSOFTWARE\Tivoli

Additional backup dataThe following stanzas and parameters are not listed in the pdinfo-pdwebpi.lst fileand are therefore not automatically backed up. If you require this data to be

backed up, you must edit the pdinfo-pdwebpi.lst and add this information.Follow the format described at the beginning of the pdinfo-pdwebpi.lst file.

[cdsso-domain-keys]<domain name> = <key file>

[ecsso-domain-keys]<domain name> = <key file>




Appendix B. pdwebpi.conf reference

Tivoli Access Manager Plug-in for Web Servers is configured using the parameterslocated in the pdwebpi.conf configuration file. The file is located in the following

directory:

UNIX:

install_path/etc/

Windows:

install_path\etc\

The following sections provide descriptions for each of the configurable parameterswithin the pdwebpi.conf configuration file. Parameters are grouped into thefollowing tables, depending on their use:

v General,

v Authentication,

v Sessions,

v LDAP,

v Proxy,

v Authorization API,

v Web Server Specific.

General configuration parameters

Table 26. General configuration parameters

General

Parameter Description[pdweb-plugins]

Defines the virtual hosts the Tivoli Access Manager Plug-in for Web Servers will protect and other global or default configuration parameters.

virtual-host Identification of subordinate stanzas that containconfiguration information about specific virtual hosts.

web-server Identifies the type of Web server in use. The acceptablevalues are:

v iis for Microsoft Internet Information Services

v ihs for IBM HTTP Server

v iplanet for Sun ONE (formerly iPlanet) Web Server

v

apache for ApacheThis parameter is set automatically during installation.




Table 26. General configuration parameters (continued)

General


windows-file-system Indicates to the Authorization Server that precautionsshould be taken to avoid security issues related to URIsrepresenting Windows file system resources.

Set to true, any access to a URI with path elements likeWindows 2000 short path names are forbidden. Inparticular, path elements ending with ~digit arerejected. On Windows systems, this parameter is set totrue by default. On UNIX systems it is set to false.

This parameter may be overridden on a per-virtualhost basis by specifying it in the appropriate[virtual_host] stanza.

case-sensitive Tells the Authorization Server how to handle the caseof URIs.

Set to false, URIs are converted to lowercase when

constructing the corresponding Tivoli Access Managerobject name against which an authorization decision ismade.

On UNIX systems this parameter is set to true. OnWindows systems it is set to false.

When the windows-file-system parameter is set to trueand case-sensitive is not defined, URIs are convertedto lowercase by default.

Note that /PDWebPI/branch portion of the object nameis not converted.

This parameter may be overridden on a per-virtual

host basis by specifying it in the appropriate[virtual_host] stanza.

log-file Identifies the filename and path of the log file whereall Authorization Server tasks are captured. May bespecified as either an absolute or relative pathname.

logs Specifies the number of log files to create beforere-using the first log file.

log-entries Specifies the number of log entries to be written beforerolling over to a new log file.

mpa-enabled Multiplexing Proxy Agents (MPA) are gateways thataccommodate multiple client access. A singleauthenticated channel to the origin server is established

and all client request and response communications aresent through this channel.

Set to true, MPA capability is enabled.

Set to false, MPA capability is disabled. This parametercan be overridden on a per-virtual host basis bydefining it in the [virtual_host] stanza.





General


mpa-protected-object Defines the MPA object against which the authorizationdecision is made.

This parameter can be overridden on a per-virtual host basis by defining it in the [virtual_host] stanza.

user On UNIX systems this parameter contains the username the manager and proxy processes are to run as.

group On UNIX systems this parameter contains the groupname the manager and proxy processes are to run as.

pre-410-compatible-tokens Enables or disables compatibility between tokenenhancements in Tivoli Access Manager version 4.1 andTivoli Access Manager 3.9. Set to true, token securityfor e-community single signon and failover cookiegeneration will interoperate with the Tivoli AccessManager 3.9 token-encoding scheme. This parameter isprocess-wide and cannot be specified on a per-virtual

host basis.

use-accept-language-header Enables or disables the use of the accept-language HTTPheader when attempting to locate the language for thegenerated HTML response.

use-accept-charset-header Enables or disables the use of the accept-charset HTTPheader is used when attempting to locate the charset inwhich to decode elements of a HTTP request, orgenerate a HTML response.

max-cached-http-body Specifies the maximum amount of HTTP body datathat will be cached for any given request. If the amountof body data exceeds the configured maximum, all of the body data will be discarded.

send-p3p-header Controls whether or not Tivoli Access Manager Plug-infor Web Servers will add a P3P header containing acompact policy statement to any HTTP responses inwhich it has set cookies.

tag-value-prefix Specifies the optional prefix added to credentialattribute names used for tag/value HTTP headers.

use-uri-encoded-session-id Controls whether or not the session ID specified in theterminate session administration task should be URIencoded.

Appendix B. pdwebpi.conf reference 177




General


remove-headers Specifies whether any headers that the tag-valuemodule may set should be removed from the request before tag-value processing. Removing these headers

ensures that they cannot be inserted by a malicioususer agent to spoof the values derived from thecredential.WARNING!DISABLING THE REMOVE HEADER CAPABILITYMAY INTRODUCE A SECURITY VULNERABILITY TOYOUR WEB SITE. APPLICATIONS RELYING ONTAG-VALUE HEADERS NOT BEING REMOVEDFROM THE REQUEST PRIOR TO TAG-VALUEPROCESSING MUST BE REIMPLEMENTED TOAVOID THE POSSIBILITY OF TAG-VALUE HTTPHEADERS BEING SPOOFED BY MALICIOUS USERAGENTS.

[module-mgr]

Contains details for the proxy module manager.

path The path containing the module shared library files.More than one path entry is permitted as the plug-inwill search all entries.

verify-step-up-user Determines, in the event of a step-up operation,whether the new user ID must match any pre-existinguser ID.

[wpiconfig]

Contains information which is set by the configuration program to aid in the unconfiguration.

server-type Set during configuration to aid with unconfiguration.

install-dir Set during configuration to aid with unconfiguration.vhosts Set during configuration to aid with unconfiguration.

[user-agent]

Creates mappings between user agents, as defined by the user-agent HTTP header, and a specificlocale. The format is:user-agent-pattern = locale string

Authentication configuration parameters

Table 27. Authentication configuration parameters

Authentication


[modules]

Declares the available authentication methods and the associated library. The format is:module_name = shared_library_name

acctmgmt Account Management

BA Basic Authentication

cert Certificate

failover Failover




Table 27. Authentication configuration parameters (continued)

Authentication


forms Forms

fsso Forms single sign-on

ip-addr IP Addressiv-headers IV Headers

session-cookie Session Cookie

ssl-id SSL ID

tag-value Tag value

http-hdr HTTP Header

token Token

ltpa LTPA Cookie

ecsso e-Community single sign-on

cdsso Cross domain single sign-on

login-redirect Login Redirect

ntlm NTLM

spnego Security Provider Negotiation

web-log Web log

boolean rules Boolean rules

switch-user Switch user

dynurl Dynamic URL

cred-refresh Credential refresh

ext-auth-int External authentication interface

[common-modules]

Contains the [common] module configuration. The stanza consists of the format: module-type =module-name. Support modules include:

Authentication Specifies the methods to use for user authentication.

Session Specifies the methods to use for maintaining sessionstate.

Pre-authzn Specifies the methods to use for any processingnecessary prior to the authorization of the user.

Post-authzn Specifies the methods to use for post-authorizationprocessing.

Response Specifies the methods to use for any processing onresponses from the Web server.

[authentication-levels]

The [authentication-levels] stanza defines step-up authentication levels as well as the ordering of authentication methods defined in the [modules] stanza.The format is:level = module_name

An authentication method defaults to a level of 1 when no entry for it is defined. Authenticationorder is determined as the highest authentication level down to the lowest authentication level forthe authentication methods defined. If an authentication level is shared by several authenticationmethods the sub-order is determined by the order in which the modules appear within the[modules] stanza.





Authentication


[authentication-mechanisms]

passwd-cdaspasswd-ldap

passwd-uraftoken-cdascert-ssl

cert-cdashttp-requestsso-create

sso-consumepasswd-strength

cred-ext-attrskerberosv5

ext-auth-interfacefailover-password

cdssosu-passwordsu-token-cardsu-certificate

su-http-requestsu-cdsso

List of supported, additional authenticationmechanisms and associated shared libraries which

plug-in to the authentication subsystem of Tivoli AccessManager.

[sessions]

Declares the default values which are common to all session modules.

max-entries Defines the maximum number of sessions which may be stored within a single instance of a session module.

timeout Defines the maximum lifetime of a session in seconds.

inactive-timeout Defines the length of idle time in seconds required fora session before it will time out.

resend-pdwebpi-cookies Defines whether Web Plug-In cookies should be sentwith each request.

reauth-lifetime-reset If yes then the credential lifetime timer will be resetupon successful reauthentication.

reauth-grace-period Specifies the amount of time in seconds the client hasas a grace period within which to successfully performreauthentication if the credential would otherwise haveexpired.

[performance]

Contains various configuration options which can aid in the fine tuning of the performance of thesystem.

enable-pop Controls whether POPs are enforced or not.

add-session-id-to-cred Controls whether the session ID will be added to thesession credential or not.

[user-agent]

Used to create mappings between user agents, as defined by the user-agent HTTP header, and aspecific locale. Conforms to the format: user-agent-pattern = locale-string.

[BA]





Authentication


basic-auth-realm Declares the realm name that will appear on thedialogue presented to the user during basicauthentication log on. MUST be surrounded by

double-quotes.strip-hdr Controls the removal of the BA header from requests.

The valid options are:

v ignore - Do nothing to the BA header.

v always - Remove the BA header from the request.

v unauth - Remove the BA header from the request if the header was not authenticated.

add-hdr Controls the addition of a new BA header to a request.The valid options for this entry are:

v none - Do not add a new BA header to the request(default).

v gso - Add a GSO BA header to the request.

v supply - Supply a static password or username or both in the BA header

gso-resource-name Contains the name of the GSO resource used to createGSO BA headers. Specifying a value is optional whenadd-hdr is set to gso. When add-hdr is set to gso andgso-resource-name is not set, the name of the virtualhost handling the request is used.

supply-password A value is required if add-hdr is set to supply. Whenset, the parameter specifies the static password used inthe created BA header.

supply-username Contains the static user name used in the created BAheader. The setting of this parameter is optional when

the add-hdr parameter is set to supply. When thesupply parameter is set and supply-username has not been set (that is, it remains commented out) the nameof the authenticated user is used in the created BAheader.

[failover]

Contains all of the configuration details for the failover cookies authentication and postauthorization modules.

failover-cookies-keyfile Declares the path to the key file used to encrypt anddecrypt credential data in the failover cookie.

failover-cookies-lifetime The valid lifetime of a failover cookie in minutes.

enable-failover-cookie-for-

domain

Enable/disable the failover cookie for the extent of the

whole domain.

failover-update-cookie Defines how often the failover cookie activitytimestamp is updated. If set to 0, the failover cookiewill be updated every request. If set to a positiveinteger, the failover cookie will be updated after thatlength of time, in seconds, has elapsed. If set to anegative integer, the failover cookie will only beupdated when authentication occurs, or when thecredential is refreshed.





Authentication


failover-require-lifetime-timestamp-validation

These entries determine whether timestamp validationis required for failover authentication to succeed.Settings are:

true: The timestamp is required. If it is missing orinvalid, failover authentication will fail.

false: The timestamp is not required, but if it existsand is invalid, failover authentication will fail.If the web plugins needs to accept failovercookies generated by an earlier version of AMWebPI or AMWebSEAL this option needsto be used for both items.

failover-require-activity-timestamp-validation

use-utf8 Defines what character set to use to encode the failovercookie.

[failover-add-attributes] Contains the configuration of which attributes to addfrom the original credential into a failover cookie.

[failover-restore-attributes] Contains the configuration of which attributes toretrieve from the failover cookie into the credentialwhen a user authenticates with a failover cookie.

[ltpa]

Contains all of the details for the LTPA cookie based post authorization module. This module isdesigned to allow single sign-on capability with a WebSphere server.

ltpa-keyfile Full path name of the LTPA key file.

ltpa-stash-file Location of the password stash file

ltpa-password The password to use in lieu of stash file.

ltpa-lifetime The lifetime in seconds of the LTPA cookie.

[forms]Contains all of the details for the forms based login module.

login-form The file name of the logon form.

login-uri The URI that the login-form submits the login detailsto. The login details must be submitted to this URIwith the user’s name specified in the POST dataattribute username and the user’s password specified inthe POST data attribute password.

create-ba-hdr Boolean value to indicate whether the suppliedusername and password should be provided in a BAheader to the destination application.

use-utf8 Indicates whether the BA header, if created, should be

encoded using UTF-8 or the local code set. Defaultvalue is true.

[fsso]

Lists the login forms to be intercepted by the Forms Single Sign On module.

login-page-stanza Records the name of one or more stanzas whichcontain the details of each login form to be intercepted.

[login-form-1]





Authentication


Login forms are identified by a 2 stage pattern matching process. FSSO intercepts all pagesmatching the login-page regular expression. Login forms within those pages are located bymatching the action attribute of HTML form elements against the login-form-action regular

expression.login-page This configuration entry is located in the stanza

specified by the login-page-stanza parameter. Itspecifies a pattern, using a regular expression, thatuniquely identifies requests for an application’s loginpage when using the plug-in’s forms single sign-onfunctionality. The configured pattern is comparedagainst the request URI.

login-form-action This parameter is located in the stanza specified by thelogin-page-stanza parameter. It specifies a pattern,using a regular expression, that identifies which formcontained in the intercepted page is the application’slogin form when using the plug-in’s forms single

sign-on functionality. If multiple forms match thepattern then the first is used.

argument-stanza This parameter is located in the stanza specified by thelogin-page-stanza parameter. It points to anothercustom stanza that lists the fields and data required forcompleting the login form.

[auth-data]

Contains one or more entries of the form: name = method:value. This parameter is located in thestanza specified by the argument-stanza parameter.

name matches the name attribute of an input element within the login form.

method is either cred, gso or string.

value contains a string interpreted according to the method value.

[web-log]

Contains all of the details for the module which specifies the information to be included in the webserver access log file, and for the SunONE, IHS and Apache web servers, the REMOTE_USERCGI variable.

format-string Format string which is used to construct the web loguser name, and for the SunONE, IHS and Apache webservers, the REMOTE_USER CGI variable.

unauth-user-string The string which is used to denote an unauthenticatedaccess manager user (%u) within the web server accesslog file.

unauth-server-user-string The string which is used to denote an unauthenticatedweb server user (%u) within the web server access logfile.

auth-type A format string for specifying the authentication typefor those web servers that allow this to bemanipulated. The only web server that permits this isiPlanet.

[tag-value]





Authentication


cache-definitions A boolean which indicates whether to cache the tagvalue definitions that are attached to the object space. If cached the proxy will need to be restarted to pick up

any changes to the tag/value definitions.cache-refresh-interval The refresh interval in seconds for the cache of

definitions.

use-utf8 Defines what character set to use to encode thetag-value data in. If the value is set to false thetag-value data will be encoded in the local code page.Default value is true.

use-uri-encoding Defines whether to perform URI encoding of thetag-value data.

[token-card]

The token-card login page.

token-login-form The file name for the token logon page.next-token-form Defines the form displayed to the user client to request

the next token. The client is requested to enter anothertoken when the server cannot successfully authenticatethe user from the first token.

[http-hdr]

Contains all of the details for the HTTP header authentication and session module.

header The header name passed to the Cross DomainAuthentication Service (CDAS) for authentication.

[iv-headers]

Contains all of the details for the IV-Headers authentication and post authorization module.

accept List of headers to accept as proof of authenticationfrom a proxy. The valid options are:

v all - Accepts all header types.

v iv-creds - User credential information.

v iv-user - Short user name.

v iv-user-l - Long user name.

v iv-groups

v iv-remote-address - IP address of the client.

v server-name

generate List of headers to generate when forwarding a requestfrom a proxy. The valid options are:

v

all - Generates all header types.v iv-creds - User credential information.

v iv-user - Short user name.

v iv-user-l - Long user name.

v iv-remote-address - IP address of the client.

use-utf8 Defines whether the iv-headers should be encoded inUTF-8, or the local code set. If the web plugins need toaccept iv-headers generated by an earlier version of AMWebPI or AMWebSEAL then this value will need to be set to false.





Authentication


server-name-header The name of the header to use when server-name ispresent in the list of values to generate. The defaultvalue is iv-server-name.

[acctmgmt]

Contains data for the account manager post-authorization module. This module is responsible formanaging account operations such as changing the user’s password, and logging out.

password-change-form The form displayed when a user requests a change of password.

password-change-form-uri The URI accessed when a user requests a change of password.

password-change-uri The URI destination after a password change.

password-change-success The page displayed when a user completes a change of password successfully.

password-change-failure The page displayed when a user fails to logon

successfully.

logout-uri The URI destination after user logout.

help-uri The location of the help page.

help-page The file name of the help page displayed when a userrequests help.

logout-success The URI or file displayed when a user successfully logsout.

[ecsso]

e-Community Single Sign-On . The stanza name must match the module name for thepdwpi-ecsso-module defined in the [modules] stanza. For correct handling of the logout URI (/pkmslogout by default) with regard to e-Community Single Sign-On, the ecsso pre-authorization

module must be configured before the acct-mgmt pre-authorization module.e-community-name The e-community name that appears in vouch-for

tokens and requests.

is-master-authn-server Specifies whether the server is a master or not in thee-community. Set to yes, this server accepts vouch-forrequests from other plug-in instances whose domainkeys are listed in the [ecsso-domain-keys] stanza.

master-authn-server The name of the master server in an e-community. Thisparameter is mandatory if is-master-authn-server is set tono.

master-http-port Specifies the port (other than the standard port 80) onthe master authentication server that listens for HTTP

requests. This parameter is ignored if the server is themaster authentication server.

master-https-port Specifies the port (other than the standard port 443) onthe master authentication server that listens for HTTPSrequests. This parameter is ignored if the server is themaster authentication server.

vf-token-lifetime The vouch-for token lifetime in seconds.

vf-url The vouch-for URL.





Authentication


allow-login-retry Enables or disables the retry of a user login when anunauthenticated user is redirected to the master serverfor authentication. Set to true, the master server allows

the users to re-enter their username/password after aninitial failed attempt. Set to false, the user is redirected back to the slave server without vouching for the user.

vf-argument The argument name of the vouch-for token as itappears in the vouch-for reply.

use-utf8 Enables or disables utf8 string encoding within theECSSO vouch-for tokens and e-community cookies.

[ecsso-token-attributes] or [ecsso_module_name-token-attributes:virtual_host]

domain_name = pattern1, pattern2,... pattern n

Specifies the credential attributes to include in theeCSSO vouch-for tokens.

[ecsso-incoming-attributes] or [ecsso_module_name-incoming-attributes]

attribute_pattern =preserve|refresh Specifies the credential attributes to accept and those toreject from incoming vouch-for tokens.

[ecsso-domain-keys]

Defines the keys to use when communicating with participants from the specified domains withinan e-community.

The name of this stanza is derived from the module name for the pdwpi-ecsso-module defined inthe [modules] stanza. It is of the form [ecsso-module-name-domain-keys]. The formatis:domain-name = key-file

[cdsso]

uri The special uri that indicates a CDSSO redirection andsingle sign-on.

cdsso-argument The name of the query string argument that specifiesthe authentication token. This is used in there-direction uri.

authtoken-lifetime The lifetime of the authentication token in seconds.

use-utf8 Controls the encoding of strings within the CDSSOtoken. This option only affects CDSSO tokens createdand consumed by the default SSO create and consumelibraries. Tokens are encoded in UTF-8 by default.

[cdsso-token-attributes]

Defines the sets of attributes to be included in CDSSO authentication tokens, specified on a per-peer or per-domain basis. This processing only takes place if the default SSO token creation andconsumption libraries are in use. The format of these entries is: domain-name = pattern-1,

pattern-2, ... pattern-n[cdsso-incoming-attributes]

Defines the sets of attributes to be accepted and rejected from incoming CDSSO authenticationtokens. The format of entries in this stanza is: attribute pattern=preserve | refresh

[cdsso-domain-keys]

Defines the keys to use when communicating with participants from the specified domains withinan e-community. The format is: domain-name = key-file

The name of this stanza is derived from the module name for the pdwpi-ecsso-module defined inthe [modules] stanza. It is of the form [ecsso-module-name-domain-keys].





Authentication


[login-redirect]

Contains all of the details for the login redirect post authorization module. For this module to work correctly it MUST be configured before the account management pre-authorization module.

redirect-uri The URI to which a user is redirected upon successfulauthentication.

[spnego]

spnego-krb-service-name Stores the service name to which the AMWebPI serverauthenticates during initialization of the spnegoauthorization module.

spnego-krb-keytab-file The path name of the Kerberos configuration file.

[ntlm]

use-pre-windows-2000-logon-name

Allows the pre-Windows 2000 logon name to representthe authenticated user in Tivoli Access Manager. This isthe username portion of the DOMAIN\USERNAME

logon name.

[web-server-authn]

use-pre-windows-2000-logon-name

Allows the pre-Windows 2000 logon name to representthe authenticated user in Tivoli Access Manager. This isthe username portion of the DOMAIN\USERNAMElogon name.

[boolean-rules]

Changes the way boolean authorization rules affect the outcome of the access decision.

pass-on-rule-failure-reason Set to the default false, or absent, if a booleanauthorization rule returns !FALSE!, then the requestwill be denied. Set to true, however, if an authorizationrule returns !FALSE! and there is a failure reason stringassociated with the rule object in the policy database,then access will be allowed, with the failure reasonstring inserted into the HTTP request in theAM_AZN_FAILURE header.

[http-method-perms]

Defines the permissions required to perform a request using a particular HTTP method.

<default> Defines the permissions required for any methods notexplicitly specified in the stanza. The <default> entryitself has no default value and must be specified as anon-empty string in the stanza.

[ext-auth-int]

Allows a credential to be created based on information supplied by a back-end application.auth-url The URL to which a user is redirected when an

authentication event is triggered due to the configuredsecurity policy.

trigger-url The URL which is used to signify that the responseshould be used to generate a credential.





Authentication


redirect-url-hdr-namepac-hdr-name

pac-svc-id-hdr-name

user-id-hdr-nameuser-auth-level-hdr-name

user-qop-hdr-nameuser-ext-attr-list-hdr-name

These entries contain the names of the responseheaders which are used in the generation of thecredential.

[switch-user]

switch-user-form Specifies the name of the HTML file which is returnedto the client upon the request to ’su’.The file should belocated in the directory,/opt/pdwebpi/nls/html/lang/charset.

switch-user-uri Specifies the name of the URI which is used to invokethe switch user function.

switch-user-post-uri Specifies the URI which the ’su’ form is submitted to.

[dynurl]

Specifies the definitions for the dynamic URL pre-authorization module. The format is:object = pattern

Sessions configuration parameters

Table 28. Sessions configuration parameters

Sessions


[sessions]

max-entries The maximum number of sessions stored within asingle instance of a session module. Maximumnumber of sessions per session module per virtualhost.

timeout The maximum lifetime of a session in seconds.

inactive-timeout The length of idle time in seconds required for asession before it times out.

resend-pdwebpi-cookies Enables or disables the sending of Web Plug-incookies with each request.

reauth-lifetime-reset Controls the session lifetime timer. Set to yes, thesession lifetime timer (that is, the value set in thetimeout parameter) is reset upon successful

reauthentication. Set to no a reset is not performedfor a successful reauthentication.

reauth-grace-period Sets the amount of time in seconds that the clienthas as a grace period within which to successfullyperform reauthentication when the credentialwould otherwise have expired.

[session-cookie]

use-same-session Specifies whether the HTTP and HTTPS protocolsshould use the same session or not.




Table 28. Sessions configuration parameters (continued)

Sessions


[cred-refresh]

Contains the configuration information for which attributes to preserve from the original credentialand which to refresh into the new credential when a credential refresh operation takes place.

preserve Defines the attributes to ’preserve’ from the originaluser credential.

refresh Defines the attributes to refresh in the newcredential.

LDAP configuration parameters

Table 29. LDAP configuration parameters

LDAP


[ldap]

bind-pwd The password for the Web Plug-in Daemon (setduring configuration).

ssl-enabled Indicates whether SSL is enabled.

ssl-keyfile Indicates path/filename of SSL keyfile.

ssl-keyfile-dn Indicates the certificate label in the SSL keyfile, if any.

ssl-keyfile-pwd Indicates the SSL keyfile password.

cache-enabled Enable and disable the local LDAP cache.

ldap-server-config Location of the ldap.conf file.

auth-using-compare Indicates whether to perform authentication usingLDAP bind or comparing passwords.

prefer-readwrite-server Indicates whether to select writable LDAP serverwhen available.

bind-dn Indicates the Distinguished Name of the daemon.

default-policy-override-support Must be yes or no. When yes, no user Policy will bechecked, only the default Policy is checked (savessome LDAP searches).

user-and-group-in-same-suffix Indicates whether the groups are defined in thesame LDAP suffix as the user.

Proxy configuration parameters

Table 30. Proxy configuration parameters

Proxy


[proxy-if]

id Specifies the ID or shared memory file name for theproxy interface. The ID must match that which isused by the plug-ins.




Table 30. Proxy configuration parameters (continued)

Proxy


number-of-workers The number of worker threads that handle plug-inrequests.

worker-size The amount of memory pre-allocated for each

worker thread the handles plug-in requests.

cleanup-interval Time in seconds between each clean-up of memory.

max-session-lifetime The time in seconds that the plug-in waits for aresponse from the Authorization Server beforetiming out.

[proxy]

error-page The path to the page displayed on the user’s browser when an unexpected server error occurs.

acct-locked-page The path to the page displayed when a userattempts to access a locked account.

retry-limit-reached-page The path to the page displayed when the allowed

maximum number of failed logon attempts has been reached. The maximum number of allowedlog on failures is set in LDAP using the policycommand.

login-success Specifies the page to be displayed when the plug-indoes not have a page to redirect the user back toafter a successful forms or token login. Thissituation can occur when you build a login formthat sends the login POST data back to the plug-indirectly.

Authorization API configuration parameters

Table 31. Authorization API configuration parameters

Authorization API


[aznapi-configuration]

Audit and Logging Parameters and Configuration.

logsize The size in bytes over which a new log file iscreated.

If set to 0, a new log file is not created.

If set to a negative number, a new log file is created

daily regardless of size.

logflush The interval in seconds at which the logs areflushed.

The maximum value is 21600 (6 hours).

logaudit Enable or disable audit logging.

auditlog The name of the audit file.




Table 31. Authorization API configuration parameters (continued)

Authorization API


auditcfg Enable or disable component-specific audit records.The valid values are:

authn - Capture authentication events.

azn - Capture authorization events.

db-file Location of the ACL database cache file.

cache-refresh-interval The interval in seconds, between checks for updatesto the master authorization server.

listen-flags Enable or disable flags for the reception of policycache update notifications.

policy-cache-size The maximum size of the in memory policy cache.This value controls how much information iscached. Size is specified as the number of entries.

resource-manager-provided-adi Specifies the prefix definitions for authorization

decision information retrieval from the HTTPrequest.

The values associated with this parameter shouldnot be changed.

input-adi-xml-prolog The prolog to be added to the top of the XMLdocument that is created using the Access DecisionInformation (ADI) needed to evaluate a Booleanauthorization rule.

xsl-stylesheet-prolog The prolog to be added to the top of the XSLstylesheet that is created using the XSL text thatdefines a Boolean authorization rule.

dynamic-adi-entitlement-services This parameter specifies a list of configured

entitlement service IDs that are queried by the rulesengine if missing ADI is detected during anauthorization rule evaluation. Entitlement serviceslisted here must adhere to the input and outputspecifications for a dynamic ADI retrieval servicewhich are outlined in the AuthorizationProgrammer’s Guide. When ADI is found to bemissing during a rule evaluation each service in theconfigured list is queried in order. These entriesmust refer to existing entitlement services that wereloaded using service entries in the entitlementservice configuration stanza or initializationattribute.

cred-attribute-entitlement-services A list of configured entitlement service IDs that will be called during credential creation, to gatherattributes to be inserted into the credential.

[aznapi-entitlement-services]

Authorization API Service Definitions.

service_id Each stanza entry defines different types of aznAPIservice. For more information refer to the IBM Tivoli Access Manager Authorization C API Developer’sReference.




Table 31. Authorization API configuration parameters (continued)

Authorization API


AZN_ENT_EXT_ATTR This is a system-level parameter that should not bechanged. It allows the use of extended attributes onthe object space.

Web server specific configuration parameters

Table 32. Web server specific configuration parameters

Web-Server Specific


[p3p-header]

Specifies the P3P compact policy that applies to all HTTP cookies set.

p3p-element This parameter can be used to specify a referenceto a full XML policy in addition to the compact

policy configured using the other parameters inthis stanza.

Uncommenting the line, p3p-element =policyref="/w3c/p3p.xml", directs the plug-in tothe full XML policy.

access Specifies the access the user has to the informationcontained within and linked to by the cookie.Possible values:

noneallnonidentcontact-and-other

ident-contactother-ident

disputes Specifies whether the full P3P policy contains someinformation regarding disputes over theinformation contained within the cookie. Validvalues are true or false. This parameter is disabled by default.

remedies Specifies the possible remedies for disputes.Possible values are:correctmoneylaw

If not specified, no remedy information is includedin the policy.

non-identifiable When set to true, this parameter specifies that noinformation in the cookie, or information linked to by the cookie, personally identifies the user in anyway. Valid values are true or false. This parameteris disabled by default.




Table 32. Web server specific configuration parameters (continued)

Web-Server Specific


purpose Specifies the purpose of the information in thecookie and linked to by the cookie. Possible valuesare:

currentadmindeveloptailoring pseudo-analysis pseudo-decisionindividual-analysisindividual-decisioncontacthistoricaltelemarketingand other-purpose.

For all values except current, an additional specifier

may be configured. The possible values are:alwaysopt-inopt-out.

For purposes not specified, the default value isalways. This value is specified after the purpose,separated by a colon, for example:

purpose = contact:opt-in

recipient Specifies the recipients of the information in thecookie, and the information linked to by thecookie. Possible values are:oursdeliverysameunrelated publicother-recipient.

retention Specifies how long the information in the cookie orthe information linked to by the cookie is to beretained.

Possible values are:no-retentionstated-purposelegal-requirementbusiness-practices

indefinitely.





Web-Server Specific


categories Specifies the type of information stored in thecookie or linked to by the cookie.

If the non-identifiable parameter is set to true, thenno categories need be configured. Possible valuesare: physicalonlineuniqueid purchase financialcomputernavigationinteractivedemographiccontentstate

politicalhealth preferencelocation governmentother-category

[ihs]

query-contents Specifies the query contents program to use for browsing the IBM HTTP Server Web space by the’pdadmin> object list’ command. This parametercan be overridden on a per branch basis byspecifying a value for it in a stanza named[ihs:branch] for example

[ihs:/PDWebPI/foo.bar.com]query-log-file Location of log file for errors encountered by the

query contents program.

doc-root Specifies the documentation root that provides theWeb space browse capability needed forperforming ’pdadmin> object list’ commands. Thisparameter is set by the configuration utility whensetting up virtual hosts - it is specified on aper-policy branch basis in an [ihs:branch] stanza forexample [ihs:/PDWebPI/foo.bar.com]

[apache]

query-contents Specifies the query contents program to use for

browsing the Apache Web space by the ’pdadmin>object list’ command. This parameter can beoverridden on a per branch basis by specifying avalue for it in a stanza named [apache:branch] forexample [apache:/PDWebPI/lotus.com]






Web-Server Specific


doc-root Specifies the documentation root that provides theWeb space browse capability needed forperforming ’pdadmin> object list’ commands. This

parameter is set by the configuration utility whensetting up virtual hosts - it is specified on aper-policy branch basis in an [apache:branch]stanza, for example [apache:/PDWebPI/lotus.com]

[iis]

query-contents Specifies the query contents program for browsingthe IIS Web space by pdadmin. This parameter can be overridden on a per branch basis by specifyinga value for it in a stanza named[iis:branch] forexample [iis:/PDWebPI/foo.bar.com]


log-file Defines the log file for error and trace messagesfrom the IIS plug-in. The messages are keptseparate from the Authorization Server’s log file inorder to ensure consistency of the files. If specifiedas a relative path, the location is relative to the logsubdirectory of the installation directory. If specified as an absolute path, the absolute path isused.

use-error-pages Controls whether the IIS configured pages for theerror code are sent back to the client, or whethersome simple constructed pages are sent backinstead.

[iplanet]

Configuration parameters specific to the Tivoli Access Manager iPlanet Web Server Plug-in.

query-contents Specifies the query contents program for browsingthe Sun ONE Web space by pdadmin. Thisparameter can be overridden on a per branch basis by specifying a value for it in a stanza named[iplanet:branch] for example[iplanet:/PDWebPI/foo.bar.com]


doc-root Specifies the documentation root which providesthe Web space browse capability needed forperforming ’pdadmin> object list’ commands. This

parameter is set by the configuration utility whensetting up virtual hosts - it is specified on aper-policy branch basis in an [iplanet:branch]stanza for example[iplanet:/PDWebPI/foo.bar.com]




Appendix C. Module quick reference

Authentication is the method of identifying an individual process or entity that isattempting to log on to a secure domain. The authentication method by which an

individual or process uses to access a plug-in protected domain can take one of many forms. IBM Tivoli Access Manager Plug-in for Web Servers supports anumber of authentication methods. These authentication methods are listed withan appropriate description in the following tables.

Table 33. Plug-in authentication method/module reference

Authentication method/module Description

BApdwpi-ba-module

Basic Authentication authentication module.

May also be configured as a session andpost-authorization module.

formspdwpi-forms-module

HTML Forms authentication module.

Authenticates using a username and passwordsubmitted through a form.

When in use, this module must also be configured as apost-authorization module.

ip-addrpdwpi-ipaddr-module

Client IP Address authentication module.

Provides authentication based solely on the client’s IPaddress. An http-request authentication mechanismmust be provided by the customer to map the IPaddress information to a Tivoli Access Managerprincipal.

May also be configured as a session module.

http-hdrpdwpi-httphdr-module

HTTP Header authentication module.

Provides authentication based solely on the value of anominated HTTP header in the request. Anhttp-request authentication mechanism must beprovided by the customer to map the headerinformation to a Tivoli Access Manager principal.

May also be configured as a session module.

tokenpdwpi-token-module

Token authentication module.

Tivoli Access Manager Plug-in for Web Serverssupports authentication using a token passcode

supplied by the client. This authentication uses a twofactor logon based on RSA SecureID fobs.

When in use, must also be configured as apost-authorization module.




Table 33. Plug-in authentication method/module reference (continued)


certpdwpi-certificate-module

Client certificate authentication module.

The subject DN of the client certificate is mapped bythe cert-ssl authentication mechanism to a Tivoli AccessManager principal name. The cert-ssl authentication

mechanism requires that the subject DN of the clientcertificate map directly to the DN of a Tivoli AccessManager user in the user registry.

This module ignores requests to authenticate requeststhat did not arrive over an SSL session and so can besafely configured for virtual hosts that handleauthorization of both HTTP and HTTPS requests.

failoverpdwpi-failovercookie-module

Failover Cookie authentication module.

This module accepts a failover cookie to authenticate auser.

When in use, this module must also be configured as a

post-authorization module.

iv-headerspdwpi-iv-headers-module

IV Headers authentication module.

Provides authentication based on the values of theiv-user, iv-user-l, iv-creds, or iv-remote-address HTTPheader in the request. This is useful for usingsingle-signing on to Tivoli Access Manager Plug-in forWeb Servers when a user has already authenticated toa front-end proxy server.

In order to be trusted, the request must have arrivedusing an authenticated session with a front-end proxyserver (for example a WebSEAL junction). The proxymust authenticate as a user with Proxy ([PDWebPI]p)permission on the protected object space branch of thevirtual host being accessed.

For authentication using iv-remote-address header, ahttp-request authentication mechanism must beprovided by the customer to map the IP addressinformation to a Tivoli Access Manager principal.

This module may also be configured as apost-authorization module and session module.

ecssopdwpi-ecsso-module

e-Community Single signon authentication module.

This module must be configured as an authenticationmodule for virtual hosts other than the masterauthentication server that is participating in thee-community.

When in use, this module must also be configured as apre-authorization module.

unauthpdpwi-unauth-module

Unauthenticated user authentication module.

This module is listed here for completeness. It isimplicitly always configured as the lowest precedenceauthentication module and is used to generate acredential for unauthenticated users.




Table 33. Plug-in authentication method/module reference (continued)


ltpapdwpi-ltpa-module

LTPA authentication module

Accepts and authenticates users based on an LTPAcookie. The LTPA cookie can either be provided byWebSEAL or by a WebSphere server.

spnegopdwpi-spnego-module

SPNEGO authentication module

Utilizes the standard SPNEGO authentication protocolwithin Windows LAN domains to achieve a SingleSignon solution for plug-in implementations on IIS.

cdssopdwpi-cdsso-module

CDSSO authentication module

Allows cross domain single sign-on between differentdomains.

ext-auth-intpdwpi-ext-auth-int-module

External authentication interface module.

Allows a credential to be created based on informationsupplied by a back-end application.

Table 34. Windows-specific authentication modules

Module Description

ntlmpdwpi-ntlm-module

NTLM authentication module.

NTLM is a Windows-specific authentication modulethat uses the Windows 2000 logon name to representthe authenticated user in Tivoli Access Manager.

web-server-authnpdwpi-websvrauth-module

Web server authentication module.

The Web server authentication modules is anauthentication module for Windows platforms. The

module uses the Windows 2000 logon name torepresent the authenticated user in Tivoli AccessManager.

Table 35. Plug-in session module reference

Module Description

BApdwpi-ba-module

Basic Authentication session module.

Use the Basic Authentication Authorization headervalue as a session key.

When in use, must also be configured as anauthentication module.

May also be configured as a post-authorization module.

ip-addrpdwpi-ipaddr-module

IP Address session module.

Uses an authenticated client IP address as the sessionkey.

When in use, it must also be configured as anauthentication module.

Appendix C. Module quick reference 199



Table 35. Plug-in session module reference (continued)

Module Description

http-hdrpdwpi-httphdr-module

HTTP Header session module.

Uses an authenticated HTTP header as the session key.

When in use, it must also be configured as an

authentication module.

session-cookiepdwpi-sesscookie-module

Session Cookie session module.

This module generates and accepts cookies for use inidentifying sessions. Generally used only as alow-priority session identification mechanism.

ssl-idpdwpi-sslsessid-module

SSL Session ID session module.

Uses the SSL Session ID as a session key. Note thatalthough this module is provided in the Windowsdistribution of Tivoli Access Manager Plug-in for WebServers, the Microsoft Internet Information ServicesWeb Server does not provide SSL Session ID

information to the plug-in so SSL Session IDs cannot beused as session keys for IIS.


IV headers session module

Uses IV headers to maintain session state.


LTPA session module.

Uses LTPA cookies to maintain session state.

Table 36. Plug-in pre-authorization module reference

Module Description

boolean-rules

pdwpi-boolean-rules-module

Boolean Rules pre-authorization module.

switch-userpdwpi-switch-user-module

Switch User pre-authorization module.

dynurlpdwpi-dynurl-module

Dynamic URL pre-authorization module.

acctmgtpdwpi-acct-mgmt-module

Account Management pre-authorization module.

This module provides the logout (/pkmslogout), changepassword (/pkmspasswd), help (/pkmshelp) features.

cred-refresh

pdwpi-cred-refresh-module

Credential Refresh pre-authorization module.

formspdwpi-forms-module

Forms pre-authorization module.




Table 36. Plug-in pre-authorization module reference (continued)

Module Description

tokenpdwpi-token-module

Token pre-authorization module.

Tivoli Access Manager Plug-in for Web Servers supportsauthentication using a token passcode supplied by theclient. This authentication uses a two factor log on

based on RSA SecureID fobs.

When in use, the token module must also be configuredas an authentication module.


External authentication interface pre-authorizationmodule.

login-redirectpdwpi-loginredirect-module

Login Redirect pre-authorization module.

When performing a login using any of the plug-insupported methods, the user is redirected to aconfigured page upon successful authentication.

ecssopdwpi-ecsso-module

e-Community single sign-on pre-authorization module.

All virtual hosts participating in an e-community musthave the ecsso module configured as apost-authorization module.

This module must also be configured as anauthentication module for all participants other than themaster authentication server.

Table 37. Plug-in post-authorization module reference

Module Description

forms

pdwpi-forms-moduleHTML Forms post-authorization module.

This module handles the submission of the form dataduring an HTML Forms-based logon.

When in use, it must also be configured as anauthentication module.

This module may also set the BA header from thesubmitted username and password.

BApdwpi-ba-module

Basic Authentication post-authorization module.

Modifies the BA header seen by the Web server or bycreating it from GSO lockbox data.

failoverpdwpi-failovercookie-module Failover Cookie post-authorization module.

This module generates a failover cookie for the client.

When in use, the failover cookie module must also beconfigured as an authentication module.

Appendix C. Module quick reference 201



Table 37. Plug-in post-authorization module reference (continued)

Module Description


IV Headers post-authorization module.

This module inserts user identity information as IVheaders in to the request before allowing the request to be handled by the Web server. This is useful for

providing single sign on to an application hosted by theWeb server. The headers that can be added are iv-user,iv-user-l, iv-groups, iv-creds, and iv-remote-address.

This module may also be configured as anauthentication module and session module.

tag-valuepdwpi-tag-value-module

Tag/Value post-authorization module.

This module inserts additional extended attributes fromthe users credential as HTTP headers in the request before allowing the request to be handled by the Webserver. These extended attributes typically correspond touser attributes from the user registry.


LTPA Cookie post-authorization module.

This module inserts a WebSphere Application Server(WAS) Lightweight Third Party Authentication (LTPA)cookie into the request before allowing the request to behandled by the Web server. This provides single sign onto a WAS being hosted by the Web server.

cdssopdwpi-cdsso-module

CDSSO post-authorization module.

boolean-rulespdwpi-boolean-rules-module

Boolean Rules post-authorization module.

fssopdwpi-fsso-module

Forms single sign-on module.

web-logpdwpi-web-log-module

Web log post-authorization module.

Table 38. Response module reference

Module Description

fssopdwpi-fsso-module

Forms single signon response module.


External authentication interface response module.




Appendix D. Command quick reference




pdwebpi_start

Starts, restarts, and stops the Tivoli Access Manager Plug-in for Web Serversprocess on UNIX installations. Note that the Plug-in for Web Servers isautomatically started and stopped when the Tivoli Access Manager base product isstarted or stopped. Also, displays the status of all Web servers.

Note: If needed, the pdwebpi_start command can be used to control the Plug-infor Web Servers independently of the Tivoli Access Manager base product.

Syntaxpdwebpi_start start

pdwebpi_start stop

pdwebpi_start restart

pdwebpi_start status

Parameterspdwebpi_start {start|stop|restart|status} where:

startStarts the Plug-in for Web Servers process on UNIX installations.

stopStops the Plug-in for Web Servers process on UNIX installations

restartStops and then restarts the Plug-in for Web Servers process on UNIXinstallations

status

Provides status information of the Plug-in for Web Servers on UNIXinstallations.

CommentsTo start and stop plug-in Windows installations, identify the Plug-in for WebServers process in the Services Control Panel and use the appropriate control

buttons.

AvailabilityThis command is located in the following default installation directories:

v UNIX systems:

/opt/pdwebpi/sbin/

v On Windows systems:

C:\Program Files\Tivoli\pdwebpi\sbin\

When an installation directory other than the default is selected, this utility islocated in the sbin directory under the installation directory (for example,install_dir\sbin\).

Return CodesThe following exit status codes can be returned:




0 The command completed successfully.

1 An error occurred.

Appendix D. Command quick reference 205



pdwebpi

Provides Tivoli Access Manager Plug-in for Web Servers version information. Also,determines whether to run Plug-in for Web Servers as a daemon or run it in theforeground.

Syntaxpdwebpi [–foreground] [–version]

Parameters

–foregroundRuns the Plug-in for Web Servers binary in the foreground as opposed torunning as a daemon.

–versionProvides version information for the Plug-in for Web Servers installation.

Availability

This command is located in the following default installation directories:v UNIX systems:

/opt/pdwebpi/bin/


C:\Program Files\Tivoli\pdwebpi\bin\

When an installation directory other than the default is selected, this utility islocated in the bin directory under the installation directory (for example,install_dir\bin\).



1 The command failed.

When a command fails, a description of the error and an error status code inhexadecimal format is provided (for example, 0x14c012f2). Refer to the IBMTivoli Access Manager Error Message Reference. This reference provides a list of the Tivoli Access Manager error messages by decimal or hexadecimal codes.




pdwpi-version

Lists the version and copyright information for the Tivoli Access Manager Plug-infor Web Servers installation.

Syntax

pdwpi-version [–h] [–V] [–l | binary [binary ... ]]

Parameters

–h Displays a help or usage message.

–l Specifies long list, which lists the versions of all binaries, not just the packageversion.

–VDisplays the version information for the pdwpi-version binary.

binary [binary]Displays version information for specified binaries, or for all files if no binaryfiles are specified.


v UNIX systems:

/opt/pdwebpi/bin/






1 An error occurred.




pdwpicfg –action config

Configures the Tivoli Access Manager Plug-in for Web Servers.

Syntaxpdwpicfg –action config –admin_id admin_id –admin_pwd admin_pwd –auth_port

authorization_port_number –web_server {iis|iplanet|ihs|apache} –iis_filter{yes|no} –web_directory server_install_directory –vhosts virtual_host_id –ssl_enable{yes|no} –keyfile keyfile –key_pwd key_password –key_label key_label –ssl_portssl_port_number

pdwpicfg –action config –interactive {yes|no}

pdwpicfg –action config –rspfile response_file

pdwpicfg –operations

pdwpicfg –help [ options]

pdwpicfg –usage

pdwpicfg –?

Parameters

–admin_id admin_idSpecifies the administration user identifier (normally, sec_master).

–admin_pwd admin_pwdSpecifies the password for the administrative user admin_id.

–auth_port authorization_port_number

Specifies the port number of the authorization server. The default port numbervalue is 7237.

–help [options]Lists the option name and a short description. If one or more options arespecified, it lists each option and a short description.

–interactive {yes|no}Enables interactive mode for the command if yes; otherwise, disablesinteractive mode for the command. The default value is yes.

–iis_filter {yes|no}Enables the Internet Information Server (IIS) filtering if yes; otherwise, disablesthe IIS filtering.

–keyfile keyfileSpecifies the LDAP SSL key file. There is no default value. Specify this optionwhen you are not running the command in interactive mode and when youhave enabled SSL between the Plug-in for Web Servers and LDAP.

–key_label key_labelSpecifies the LDAP SSL key label. There is no default value. Specify this optionwhen you are not running the command in interactive mode and when youhave enabled SSL between the Plug-in for Web Servers and LDAP.

–key_pwd key_passwordSpecifies the LDAP SSL key file password.




–operationsLists each of the option names one after another with no description.

–rspfile response_fileProvides the fully qualified path and file name for the Plug-in for Web Serversresponse file to use during silent installation. A response file can be used forconfiguration or unconfiguration. There is no default response file name. The

response file contains stanzas and option=value pair stanza entries. To useresponse files, see the procedures in the IBM Tivoli Access Manager for e-businessWeb Security Installation Guide.

–ssl_enable {yes|no}Enables SSL communications with LDAP if yes; otherwise, disables SSLcommunications with LDAP. The default value is yes.

–ssl_port ssl_port_numberSpecifies the LDAP SSL port. The default port number value is 636.

–usageDisplays the usage syntax for this command. Also displays an example.

–vhosts virtual_host_id

Specifies the virtual hosts that are to be protected. The value should be in theformat of a comma separated list of virtual host IDs. There should be nospaces between the virtual host IDs.

–web_directory server_install_directorySpecifies the Web server installation directory.

–web_server {iis|iplanet|ihs|apache}Specifies the Web server type on which the Plug-in for Web Servers is to beinstalled. The choices are: iis for Internet Information Server, iplanet for SunONE Server, ihs for IBM HTTP Server , or apache for the Apache Server. Thisoption defaults to the type and location of the configured Web server.

–? Displays the usage syntax for this command. Also displays an example.


v UNIX systems:

/opt/pdwebpi/bin/











pdwpicfg –action unconfig

Unconfigures the Tivoli Access Manager Plug-in for Web Servers.

Syntaxpdwpicfg –action unconfig –admin_id admin_id –admin_pwd admin_pwd –force

{yes|no} –remove {none|acls|objspace|all} –vhosts virtual_host_id

pdwpicfg –action unconfig –interactive {yes|no}

pdwpicfg –action unconfig –rspfile response_file

pdwpicfg –operations

pdwpicfg –help [ options]

pdwpicfg –usage

pdwpicfg –?

Parameters

–admin_id admin_idSpecifies the administration user identifier (normally, sec_master).

–admin_pwd admin_pwdSpecifies the password for the administrative user admin_id.

–force {yes|no}Forces the unconfiguration process to proceed even if the policy server cannot

be contacted. The default value is no.

–help [options]

Lists the option name and a short description. If one or more options arespecified, it lists each option and a short description.

–interactive {yes|no}Enables interactive mode for the command if yes; otherwise, disablesinteractive mode for the command. The default value is yes.

–operationsLists each of the option names one after another with no description.

–remove {none|acls|objspace|all}Specifies whether to remove the object space or the ACLs or both as part of theunconfiguration process. The default value is none.

–rspfile response_file

Provides the fully qualified path and file name for the Plug-in for Web Serversresponse file to use during silent installation. A response file can be used forconfiguration or unconfiguration. There is no default response file name. Theresponse file contains stanzas and option=value pair stanza entries. To useresponse files, see the procedures in the IBM Tivoli Access Manager for e-businessWeb Security Installation Guide.

–usageDisplays the usage syntax for this command. Also displays an example.




–vhosts virtual_host_idSpecifies the identifiers of the virtual hosts that are to be unconfigured. Thevalue can be in the format of a comma separated list of virtual host IDs. Thereshould be no spaces between the virtual host IDs.

–? Displays the usage syntax for this command. Also displays an example.


v UNIX systems:

/opt/pdwebpi/bin/











Appendix E. Special characters allowed in regularexpressions

The following table lists the special characters allowed in regular expressions usedin the pdwebpi.conf 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)




Appendix F. 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 in

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

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

IBM 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-chome, Minato-kuTokyo 106-0032, Japan

The following paragraph does not apply to the United Kingdom or any other

country where such provisions are inconsistent with local law:INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THISPUBLICATION “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHEREXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIEDWARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESSFOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express orimplied warranties in certain transactions, therefore, this statement may not applyto 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 it believes 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 78758U.S.A.

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

between 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 measurements 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 of those products, their published announcements or other publicly available sources.IBM has not tested those products and cannot confirm the accuracy of performance, 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 is for planning purposes only. The information herein is subject tochange before the products described become available.

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.

If you are viewing this information softcopy, the photographs and colorillustrations may not appear.

Trademarks

The following terms are trademarks or registered trademarks of InternationalBusiness Machines Corporation in the United States, other countries, or both:

AIXDB2IBM




IBM(logo)OS/390SecureWayTivoliTivoli (logo)Universal DatabaseWebSphere

z/OSzSeries

Microsoft and Windows are trademarks of Microsoft Corporation in the UnitedStates, other countries, or both.

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 F. Notices 217



Glossary

A

access control. In computer security, the process of ensuring that the resources of a computer system can be accessed only by authorized users in authorizedways.

access control list (ACL). In computer security, a listthat is associated with an object that identifies all thesubjects that can access the object and their accessrights. For example, an access control list is a list that isassociated with a file that identifies the users who canaccess the file and identifies the users’ access rights tothat file.

access permission. The access privilege that applies to

the entire object.

action. An access control list (ACL) permissionattribute. See also access control list.

ACL. See access control list.

administration service. An authorization API runtimeplug-in that can be used to perform administrationrequests on a Tivoli Access Manager resource managerapplication. The administration service will respond toremote requests from the pdadmin command toperform tasks, such as listing the objects under aparticular node in the protected object tree. Customersmay develop these services using the authorizationADK.

attribute list. A linked list that contains extendedinformation that is used to make authorizationdecisions. Attribute lists consist of a set of name = valuepairs.

authentication. (1) In computer security, verification of the identity of a user or the user’s eligibility to accessan object. (2) In computer security, verification that amessage has not been altered or corrupted. (3) Incomputer security, a process that is used to verify theuser of an information system or of protected resources.See also multi-factor authentication, network-based

authentication, and step-up authentication.

authorization. (1) In computer security, the rightgranted to a user to communicate with or make use of a computer system. (2) The process of granting a usereither complete or restricted access to an object,resource, or function.

authorization rule. See rule.

authorization service plug-in. A dynamically loadablelibrary (DLL or shared library) that can be loaded by

the Tivoli Access Manager authorization API runtimeclient at initialization time in order to perform

operations that extend a service interface within theAuthorization API. The service interfaces that arecurrently available include Administration, ExternalAuthorization, Credentials modification, Entitlementsand PAC manipulation interfaces. Customers maydevelop these services using the authorization ADK.

B

BA. See basic authentication.

basic authentication. A method of authentication thatrequires the user to enter a valid user name andpassword before access to a secure online resource is

granted.

bind. To relate an identifier to another object in aprogram; for example, to relate an identifier to a value,an address or another identifier, or to associate formalparameters and actual parameters.

blade. A component that provides application-specificservices and components.

business entitlement. The supplemental attribute of auser credential that describes the fine-grainedconditions that can be used in the authorization of requests for resources.

C

CA. See certificate authority.

CDAS. See Cross Domain Authentication Service.

CDMF. See Cross Domain Mapping Framework .

certificate. In computer security, a digital documentthat binds a public key to the identity of the certificateowner, thereby enabling the certificate owner to beauthenticated. A certificate is issued by a certificateauthority.

certificate authority (CA). An organization that issuescertificates. The certificate authority authenticates thecertificate owner’s identity and the services that theowner is authorized to use, issues new certificates,renews existing certificates, and revokes certificates belonging to users who are no longer authorized to usethem.

CGI. See common gateway interface.




cipher. Encrypted data that is unreadable until it has been converted into plain data (decrypted) with a key.

common gateway interface (CGI). An Internetstandard for defining scripts that pass information froma Web server to an application program, through anHTTP request, and vice versa. A CGI script is a CGIprogram that is written in a scripting language, such as

Perl.

configuration. (1) The manner in which the hardwareand software of an information processing system areorganized and interconnected. (2) The machines,devices, and programs that make up a system,subsystem, or network.

connection. (1) In data communication, an associationestablished between functional units for conveyinginformation. (2) In TCP/IP, the path between twoprotocol applications that provides reliable data streamdelivery service. In the Internet, a connection extendsfrom a TCP application on one system to a TCP

application on another system. (3) In systemcommunications, a line over which data can be passed between two systems or between a system and adevice.

container object. A structural designation thatorganizes the object space into distinct functionalregions.

cookie. Information that a server stores on a clientmachine and accesses during subsequent sessions.Cookies allow servers to remember specific informationabout clients.

credentials. Detailed information, acquired duringauthentication, that describes the user, any groupassociations, and other security-related identityattributes. Credentials can be used to perform amultitude of services, such as authorization, auditing,and delegation.

credentials modification service. An authorizationAPI runtime plug-in which can be used to modify aTivoli Access Manager credential. Credentialsmodification services developed externally bycustomers are limited to performing operation to addand remove from the credentials attribute list and onlyto those attributes that are considered modifiable.

cross domain authentication service (CDAS). AWebSEAL service that provides a shared librarymechanism that allows you to substitute the defaultWebSEAL authentication mechanisms with a customprocess that returns a Tivoli Access Manager identity toWebSEAL. See also WebSEAL.

cross domain mapping framework (CDMF). Aprogramming interface that allows a developer tocustomize the mapping of user identities and thehandling of user attributes when WebSEALe-Community SSO function are used.

D

daemon. A program that runs unattended to performcontinuous or periodic systemwide functions, such asnetwork control. Some daemons are triggeredautomatically to perform their task; others operateperiodically.

directory schema. The valid attribute types and objectclasses that can appear in a directory. The attributetypes and object classes define the syntax of theattribute values, which attributes must be present, andwhich attributes may be present for the directory.

distinguished name (DN). The name that uniquelyidentifies an entry in a directory. A distinguished nameis made up of attribute:value pairs, separated bycommas.

digital signature. In e-commerce, data that isappended to, or is a cryptographic transformation of, adata unit and that enables the recipient of the data unitto verify the source and integrity of the unit and torecognize potential forgery.

DN. See distinguished name.

domain. (1) A logical grouping of users, systems, andresources that share common services and usuallyfunction with a common purpose. (2) That part of acomputer network in which the data processingresources are under common control. See also domainname.

domain name. In the Internet suite of protocols, aname of a host system. A domain name consists of a

sequence of subnames that are separated by a delimitercharacter. For example, if the fully qualified domainname (FQDN) of a host system isas400.rchland.vnet.ibm.com, each of the following is adomain name: as400.rchland.vnet.ibm.com,vnet.ibm.com, ibm.com.

E

EAS. See External Authorization Service.

encryption. In computer security, the process of transforming data into an unintelligible form in such away that the original data either cannot be obtained orcan be obtained only by using a decryption process.

entitlement. A data structure that containsexternalized security policy information. Entitlementscontain policy data or capabilities that are formatted ina way that is understandable to a specific application.

entitlement service. An authorization API runtimeplug-in which can be used to return entitlements froman external source for a principal or set of conditions.Entitlements are normally application specific data thatwill be consumed by the resource manager application




in some way or added to the principal’s credentials foruse further on in the authorization process. Customersmay develop these services using the authorizationADK.

external authorization service. An authorization APIruntime plug-in that can be used to make applicationor environment specific authorization decisions as part

of the Tivoli Access Manager authorization decisionchain. Customers may develop these services using theauthorization ADK.

F

file transfer protocol (FTP). In the Internet suite of protocols, an application layer protocol that usesTransmission Control Protocol (TCP) and Telnetservices to transfer bulk-data files between machines orhosts.

G

global signon (GSO). A flexible single sign-onsolution that enables the user to provide alternativeuser names and passwords to the back-end Webapplication server. Global signon grants users access tothe computing resources they are authorized to use —through a single login. Designed for large enterprisesconsisting of multiple systems and applications withinheterogeneous, distributed computing environments,GSO eliminates the need for users to manage multipleuser names and passwords. See also single signon.

GSO. See global signon.

H

host. A computer that is connected to a network (suchas the Internet or an SNA network) and provides anaccess point to that network. Also, depending on theenvironment, the host may provide centralized controlof the network. The host can be a client, a server, or both a client and a server simultaneously.

HTTP. See Hypertext Transfer Protocol.

hypertext transfer protocol (HTTP). In the Internetsuite of protocols, the protocol that is used to transferand display hypertext documents.

I

Internet protocol (IP). In the Internet suite of protocols, a connectionless protocol that routes datathrough a network or interconnected networks and actsas an intermediary between the higher protocol layersand the physical network.

Internet suite of protocols. A set of protocolsdeveloped for use on the Internet and published as

Requests for Comments (RFCs) through the InternetEngineering Task Force (IETF).

interprocess communication (IPC). (1) The process bywhich programs communicate data to each other andsynchronize their activities. Semaphores, signals, andinternal message queues are common methods of interprocess communication. (2) A mechanism of an

operating system that allows processes to communicatewith each other within the same computer or over anetwork.

IP. See Internet Protocol.

IPC. See Interprocess Communication.

J

junction. An HTTP or HTTPS connection between afront-end WebSEAL server and a back-end Webapplication server. WebSEAL uses a junction to provideprotective services on behalf of the back-end server.

K

key. In computer security, a sequence of symbols thatis used with a cryptographic algorithm for encryptingor decrypting data. See private key and public key.

key database file. See key ring.

key file. See key ring.

key pair. In computer security, a public key and aprivate key. When the key pair is used for encryption,

the sender uses the public key to encrypt the message,and the recipient uses the private key to decrypt themessage. When the key pair is used for signing, thesigner uses the private key to encrypt a representationof the message, and the recipient uses the public key todecrypt the representation of the message for signatureverification.

key ring. In computer security, a file that containspublic keys, private keys, trusted roots, and certificates.

L

LDAP. See Lightweight Directory Access Protocol.

lightweight directory access protocol (LDAP). Anopen protocol that (a) uses TCP/IP to provide access todirectories that support an X.500 model and (b) doesnot incur the resource requirements of the morecomplex X.500 Directory Access Protocol (DAP).Applications that use LDAP (known asdirectory-enabled applications) can use the directory asa common data store and for retrieving informationabout people or services, such as e-mail addresses,public keys, or service-specific configurationparameters. LDAP was originally specified in RFC

Glossary 221



1777. LDAP version 3 is specified in RFC 2251, and theIETF continues work on additional standard functions.Some of the IETF-defined standard schemas for LDAPare found in RFC 2256.

lightweight third party authentication (LTPA). Anauthentication framework that allows single sign-onacross a set of Web servers that fall within an Internet

domain.

LTPA. See lightweight third party authentication.

M

management domain. The default domain in whichTivoli Access Manager enforces security policies forauthentication, authorization, and access control. Thisdomain is created when the policy server is configured.See also domain.

management server. Obsolete. See policy server.

metadata. Data that describes the characteristics of stored data.

migration. The installation of a new version or releaseof a program to replace an earlier version or release.

multi-factor authentication. A protected object policy(POP) that forces a user to authenticate using two ormore levels of authentication. For example, the accesscontrol on a protected resource can require that theusers authenticate with both user name/password anduser name/token passcode. See also protected object policy.

multiplexing proxy agent (MPA). A gateway thataccommodates multiple client access. These gatewaysare sometimes known as Wireless Access Protocol(WAP) gateways when clients access a secure domainusing a WAP. Gateways establish a single authenticatedchannel to the originating server and tunnel all clientrequests and responses through this channel.

N

network-based authentication. A protected objectpolicy (POP) that controls access to objects based on theinternet protocol (IP) address of the user. See also protected object policy.

P

PAC. See privilege attribute certificate.

permission. The ability to access a protected object,such as a file or directory. The number and meaning of permissions for an object are defined by the accesscontrol list (ACL). See also access control list.

policy. A set of rules that are applied to managedresources.

policy server. The Tivoli Access Manager server thatmaintains the location information about other serversin the secure domain.

polling. The process by which databases are

interrogated at regular intervals to determine if dataneeds to be transmitted.

POP. See protected object policy.

portal. An integrated Web site that dynamicallyproduces a customized list of Web resources, such aslinks, content, or services, available to a specific user, based on the access permissions for the particular user.

privilege attribute certificate. A digital document thatcontains a principal’s authentication and authorizationattributes and a principal’s capabilities.

privilege attribute certificate service. Anauthorization API runtime client plug-in whichtranslates a PAC of a predetermined format in to aTivoli Access Manager credential, and vice-versa. Theseservices could also be used to package or marshall aTivoli Access Manager credential for transmission toother members of the secure domain. Customers maydevelop these services using the authorization ADK.See also privilege attribute certificate.

protected object. The logical representation of anactual system resource that is used for applying ACLsand POPs and for authorizing user access. See also protected object policy and protected object space.

protected object policy (POP). A type of securitypolicy that imposes additional conditions on theoperation permitted by the ACL policy to access aprotected object. It is the responsibility of the resourcemanager to enforce the POP conditions. See also accesscontrol list, protected object, and protected object space.

protected object space. The virtual objectrepresentation of actual system resources that is usedfor applying ACLs and POPs and for authorizing useraccess. See also protected object and protected object policy.

private key. In computer security, a key that is knownonly to its owner. Contrast with public key.

public key. In computer security, a key that is madeavailable to everyone. Contrast with private key.

Q

quality of protection. The level of data security,determined by a combination of authentication,integrity, and privacy conditions.




R

registry. The datastore that contains access andconfiguration information for users, systems, andsoftware.

replica. A server that contains a copy of the directory

or directories of another server. Replicas back upservers in order to enhance performance or responsetimes and to ensure data integrity.

resource object. The representation of an actualnetwork resource, such as a service, file, and program.

response file. A file that contains a set of predefinedanswers to questions asked by a program and that isused instead of entering those values one at a time.

role activation. The process of applying the accesspermissions to a role.

role assignment. The process of assigning a role to a

user, such that the user has the appropriate accesspermissions for the object defined for that role.

routing file. An ASCII file that contains commandsthat control the configuration of messages.

RSA encryption. A system for public-keycryptography used for encryption and authentication. Itwas invented in 1977 by Ron Rivest, Adi Shamir, andLeonard Adleman. The system’s security depends onthe difficulty of factoring the product of two largeprime numbers.

rule. One or more logical statements that enable the

event server to recognize relationships among events(event correlation) and to execute automated responsesaccordingly.

run time. The time period during which a computerprogram is executing. A runtime environment is anexecution environment.

S

scalability. The ability of a network system to respondto increasing numbers of users who access resources.

schema. The set of statements, expressed in a data

definition language, that completely describe thestructure of a database. In a relational database, theschema defines the tables, the fields in each table, andthe relationships between fields and tables.

secure sockets layer (SSL). A security protocol thatprovides communication privacy. SSL enablesclient/server applications to communicate in a way thatis designed to prevent eavesdropping, tampering, andmessage forgery. SSL was developed by NetscapeCommunications Corp. and RSA Data Security, Inc.

security management. The management disciplinethat addresses an organization’s ability to control accessto applications and data that are critical to its success.

self-registration. The process by which a user canenter required data and become a registered TivoliAccess Manager user, without the involvement of anadministrator.

service. Work performed by a server. A service can bea simple request for data to be sent or stored (as withfile servers, HTTP servers, e-mail servers, and fingerservers), or it can be more complex work such as thatof print servers or process servers.

silent installation. An installation that does not sendmessages to the console but instead stores messagesand errors in log files. Also, a silent installation can useresponse files for data input. See also response file.

single signon (SSO). The ability of a user to logononce and access multiple applications without having

to logon to each application separately. See also globalsignon.

SSL. See Secure Sockets Layer.

SSO. See Single Signon.

step-up authentication. A protected object policy(POP) that relies on a preconfigured hierarchy of authentication levels and enforces a specific level of authentication according to the policy set on a resource.The step-up authentication POP does not force the userto authenticate using multiple levels of authenticationto access any given resource but requires the user toauthenticate at a level at least as high as that required

by the policy protecting a resource.

suffix. A distinguished name that identifies the topentry in a locally held directory hierarchy. Because of the relative naming scheme used in LightweightDirectory Access Protocol (LDAP), this suffix applies toevery other entry within that directory hierarchy. Adirectory server can have multiple suffixes, eachidentifying a locally held directory hierarchy.

T

token. (1) In a local area network, the symbol of

authority passed successively from one data station toanother to indicate the station temporarily in control of the transmission medium. Each data station has anopportunity to acquire and use the token to control themedium. A token is a particular message or bit patternthat signifies permission to transmit. (2) In local areanetworks (LANs), a sequence of bits passed from onedevice to another along the transmission medium.When the token has data appended to it, it becomes aframe.

Glossary 223



trusted root. In the Secure Sockets Layer (SSL), thepublic key and associated distinguished name of acertificate authority (CA).

U

uniform resource identifier (URI). The character

string used to identify content on the Internet,including the name of the resource (a directory and filename), the location of the resource (the computerwhere the directory and file name exist), and how theresource can be accessed (the protocol, such as HTTP).An example of a URI is a uniform resource locator, orURL.

uniform resource locator (URL). A sequence of characters that represent information resources on acomputer or in a network such as the Internet. Thissequence of characters includes (a) the abbreviatedname of the protocol used to access the informationresource and (b) the information used by the protocol

to locate the information resource. For example, in thecontext of the Internet, these are abbreviated names of some protocols used to access various informationresources: http, ftp, gopher, telnet, and news; and thisis the URL for the IBM home page:http://www.ibm.com.

URI. See uniform resource identifier.

URL. See uniform resource locator.

user. Any person, organization, process, device,program, protocol, or system that uses a serviceprovided by others.

user registry. See registry.

V

virtual hosting. The capability of a Web server thatallows it to appear as more than one host to theInternet.

W

Web Portal Manager (WPM). A Web-based graphicalapplication used to manage Tivoli Access Manager Baseand WebSEAL security policy in a secure domain. Analternative to the pdadmin command line interface, thisGUI enables remote administrator access and enablesadministrators to create delegated user domains andassign delegate administrators to these domains.

WebSEAL. A Tivoli Access Manager blade. WebSEALis a high performance, multi-threaded Web server thatapplies a security policy to a protected object space.WebSEAL can provide single sign-on solutions andincorporate back-end Web application server resourcesinto its security policy.

WPM. See Web Portal Manager.




Index

Aaccept parameter 94

acct-locked-page parameter 12ACL permissions 111ACL policies 109ACL policy

default 111add-hdr 61ADI 165allow-login-retry 153AMWebARS

configuring 170anonymous client processing 123Apache

considerations 17API service 33applying unauthenticated HTTPS 123

architecture 1audit configuration 30audit records 29auditcfg parameter 30auditing 28auditlog parameter 30authentication 39

configuration for virtual hosts 42configuration overview 41, 55forms 61goals of 4methods 44

order of 44quick reference 197

multi-factor 118network based POP policy 121NTLM 76overview 4parameters 178step-up 116Web server 77with Basic Authentication 59with certificates 64with failover cookies 78with HTTP headers 95with IP addresses 97with IV headers 93with LTPA cookies 98with SPNEGO 69with tokens 65

authentication challenge

process flow 48authentication mechanism

Basic Authentications 59certificates 65forms 62HTTP header 96switch user 22tokens 68with IP addresses 97with IV headers 95

authentication mechanisms 56authentication methods 57

authentication modulesquick reference 197

authentication process 41authentication strength POP

IP address for sessions 116authentication upgrade process 40authentication-levels stanza 44authorization decision information

configuring retrieval 169overview 165retrieving 166

authorization process 40authorization server

configuration 11

BBA headersmanipulating 60

UTF-8 encoding 63 back-end applications

maintaining session state 159 backup 171Basic Authentication 52, 59

branch parameter 14

Ccache

database settings 32cache database 28cache inactivity timeout 51

cache-definitions 104cache-refresh-interval 104cache-refresh-interval parameter 32CDAS authentication parameters 56CDSSO 141

enabling 143cdsso credential attributes 144cdsso_key_gen 87cert-cdas parameter 56cert-ssl parameter 56certificates 64cleanup-interval parameter 11commands 203

change of password 57help 57logout 57

common-modules stanza 41components 1configuration

API service 33audit logs 28auditing 30authentication 41

methods 44authentication for virtual hosts 42authentication methods 57authentication overview 55Authorization Server 11




configuration (continued)Basic authentication for authentication 59Basic Authentication for sessions 52cache 32cache database 28certificate authentication 64credential refresh 33default 57

e-community single sign-on 151fail-over for LDAP 24failover cookies for authentication 78for Web servers 16forms for authentication 61HTTP headers for authentication 95HTTP headers for sessions 54HTTP request caching 34IP address for authentication 97IP address for sessions 54, 55IV headers for authentication 93iv-headers for sessions 55Kerberos 72login redirection 99logs 28LTPA cookies for authentication 98

NTLM authentication 76of pdwebpimgr.conf 9P3P 26parameters

authentication 178authorization API 190general 175LDAP 189proxy 189sessions 188Web server specific 192

pdwebpi.conf 8plug-in 8post-authorization 48server specific 15

session cookies for sessions 53session/credentials cache 50SPNEGO for authentication 69SSL session ID for sessions 52stanzas 175switch user 21tag value for post-authorization 99, 102token response pages 69tokens for authentication 65virtual hosts 13Web server authentication 77

configuringerror pages 12

create-ba-hdr 63creating a BA Header 63

cred-ext-attrs 103credentialacquisition 5

credential refresh 33cross domain

single sign-on 141

Ddb-file parameter 32doc-root 16dynamic ADI retrieval 169

dynamic URLsaccess control 161

dynurl 161

Ee-community single sign-on

configuration 151

configuration example 155cookie 149encrypting vouch-for token 150example 155features and requirements 147overview 146process flow 148

e-community-name 151ecsso credential attributes 154ecsso Domain Keys 153enable-failover-cookie-for-domain 91EPAC 5error messages 9error pages

configuring 12

error-page parameter 12errors, customizing for IIS 9Extended Privilege Attribute Certificate (EPAC) 5

Ffail-over for LDAP 24failover authentication 78

backwards compatibility 84configuration 85domain-wide 84library 80upgrading 85

Failover cookiesingle sign-on 129

failover cookies 78, 81, 83configure cookie lifetime 87enable domain-wide cookies 91encrypting/decrypting cookie data 87

failover-cdsso 86failover-certificate 86failover-cookie-lifetime 87failover-cookies-keyfile 87failover-http-request 86failover-password 86failover-token-card 86failure reasons

supplying 168features 3forms

single sign-on 133forms authentication 61

Ggenerate parameter 94Global Single sign-on - GSO 130GSO 130




Hheader types

specifying 96Headers

P3P 25HTML response forms 62HTTP error messages 9HTTP headers 54

authentication 95single sign-on 126

HTTP request caching 34http-request parameter 56

Iid parameter 11, 14ihs

specific configuration 15IHS

considerations 17iis

specific configuration 15IIS

considerations 17IIS errors

customizing 9installation directory 7IP addresses 54, 55, 97IP addresses and ranges 121iplanet see Sun ONE 15is-master-authn-server 151IV headers 126

authentication 93UTF-8 encoding 95

iv-creds 93iv-groups 93iv-headers 55iv-remote-address 93

iv-user 93iv-user-l 93

KKerberos 71

Llanguages

support for 35LDAP

configuring fail-over 24extended attributes 99, 102

ldap-ext-cred-tags stanza 103LDAP, configuration parameters 189libfailoverauthn shared library 86listen-flags parameter 32local authentication parameters 56log on

forcing 123log-file 16logaudit parameter 30logflush parameter 30logging 28login-form 62login-redirect 99

login-success parameter 12login-uri 63logon policy 112logsize parameter 30LTPA

post-authorization processing 98LTPA cookies 98, 127ltpa-keyfile 98

ltpa-password 98ltpa-stash-file 98

Mmacro support 10master-authn-server 152master-http-port 152master-https-port 152max-entries parameter 50max-session-lifetime 11max-session-lifetime parameter 12modules 41

quick reference 197modules configuration 41

modules stanza 41MPAs 104multi-factor authentication 118multi-lingual support 35Multiplexing Proxy Agents 104

Nnetwork based authentication POP policy 121NTLM authentication 76number-of-workers parameter 11

Oobject listings 18overview

request handling process 39

PP3P 25

configuring 26passwd-cdas parameter 56passwd-ldap parameter 56password policy 113pdbackup 171pdweb-plugin stanza 13pdweb-plugins stanza 15pdwebpi 206

pdwebpi_start 204pdwebpi.conf 8pdwebpimgr.conf 9pdwpi-version 207pdwpicfg -action config 208pdwpicfg -action unconfig 210permissions

ACL 111WebDAV 111

pkmshelp 58pkmslogout 57pkmspasswd 58Platform for Privacy Headers 25

Index 227



plug-inauthentication 4configuration 11features 3HTTP error messages 9installation directory 7macro support 10request handling 39

security policy 3starting and stopping 9plug-in process flow 1policy

ACL 109, 111authentication strength POP 116controlling unauthenticated users 124IP addresses 121logon 112network based authentication POP 121password 113quality of protection POP 122reauthentication 119

conditions 119creating and applying 120

step-up 116

user and global 115POP policy

algorithm 122authentication strength - step up 116network based authentication 121quality of protection 122reauthentication 119

post-authorizationlogin redirection 99with tag value 99, 102

post-authorization processing 40, 48pre-authorization processing 40protocols parameter 14proxy-if stanza 11, 12

QQuality of protection POP policy 122query-contents 16query-log-file 16

Rrealm name, setting 59reauth-grace-period 51reauth-lifetime-reset 51reauthentication 119redirection after logon 99regular expressions 213

related publications xviirequest handling processoverview 39

response handling 40retry-limit-reached-page parameter 12root directory 7

Ssecurity policy 3session cache 50session cookies 53session identification 39

session reauthentication reset 51session state

maintaining 159managing 49with Basic Authentication 52with HTTP headers 54with IP addresses 54, 55with iv-headers 55

with session cookies 53with SSL session ID 52session timeout 51sessions stanza 50single sign-on

concepts 125cross domain 141e-community 146forms 133GSO 130SPNEGO 133to proxy 128to WebSEAL 128using failover cookies 129using HTTP headers 126using LTPA cookies 127

single signonusing SPNEGO 69Windows 71

special characters 213SPNEGO 69, 133

enabling 74single signon 69

SSL session ID 52stanzas, configuration file 175starting the plug-in 9step-up 116

disabling by IP address 122enabling 117limitations 118

stopping the plug-in 9

strip-hdr 60Sun ONE

specific configuration 15supply-password 61supply-username 61switch user

configuration 19enabling 20impacts 23process flow 20

Ttag value 99, 102terminating user sessions 161

timeoutcache inactivity 51

timeout parameter 12token authentication 65token response pages 69token-cdas parameter 56tokens 65trace 31

pdadmin commands 31troubleshooting

Kerberos 75SPNEGO 75




Uunauthenticated HTTPS 123unauthenticated users 123

controlling with policy 124unprotected-virtual-host parameter 13use-utf8 153utilities

pdwebpi 206

pdwebpi_start 204pdwpi-version 207pdwpicfg -action config 208pdwpicfg -action unconfig 210

Vvf-argument 152vf-token-lifetime 152vf-url 152virtual host branches explained 14virtual hosts

authentication configuration 42configuring 13support for 2

virtual-host parameter 13vouch-for

request and reply 149token 150token encryption 150

WWeb server authentication 77WebDAV permissions 111WebSEAL

single sign-on to 128worker threads, configuring 11worker-size parameter 11

Index 229

am51 webservers guide

Documents