IBM Tivoli Access Manager Plug-in for Edge …publib.boulder.ibm.com/.../GC23-4685-00/en_US/PDF/esmst.pdfiv IBM Tivoli Access Manager Plug-in for Edge Server: User’s Guide Preface

IBM Tivoli Access Manager Plug-in for Edge Server

User’s GuideVersion 3.9

GC23-4685-00

IBM Tivoli Access Manager Plug-in for Edge Server

User’s GuideVersion 3.9

GC23-4685-00

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

Second Edition (April 2002)

This edition replaces GC32-0739-00.

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

Contents

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vWho should read this book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vWhat this book contains . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vPublications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vi

IBM Tivoli Access Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . viRelated publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ixAccessing publications online. . . . . . . . . . . . . . . . . . . . . . . . . . . . . xOrdering publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xProviding feedback about publications . . . . . . . . . . . . . . . . . . . . . . . . . xi

Accessibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiContacting customer support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiConventions used in this book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi

Typeface conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi

Chapter 1. Introducing the IBM Tivoli Access Manager plug-in for Edge Server . . . . . 1System requirements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

Supported operating systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1Software prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

Access Manager security model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2Plug-in for Edge Server security enforcement . . . . . . . . . . . . . . . . . . . . . . . . 2

Reverse proxy access control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3Forward proxy access control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Chapter 2. Installing the plug-in for Edge Server . . . . . . . . . . . . . . . . . . 7Installing the plug-in for Edge Server on AIX . . . . . . . . . . . . . . . . . . . . . . . . 7Installing the plug-in for Edge Server on Linux . . . . . . . . . . . . . . . . . . . . . . . . 7Installing the plug-in for Edge Server on Solaris . . . . . . . . . . . . . . . . . . . . . . . 8Installing the plug-in for Edge Server on Windows . . . . . . . . . . . . . . . . . . . . . . 8Configuring the plug-in for Edge Server . . . . . . . . . . . . . . . . . . . . . . . . . . 8Upgrading the plug-in for Edge Server . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Chapter 3. Administering the plug-in for Edge Server. . . . . . . . . . . . . . . . 11Managing user accounts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11Creating an Access Manager object space . . . . . . . . . . . . . . . . . . . . . . . . . 11

Creating an object space for the caching proxy. . . . . . . . . . . . . . . . . . . . . . . 12Creating an object space for other Web servers . . . . . . . . . . . . . . . . . . . . . . 12

Starting and stopping the plug-in for Edge Server . . . . . . . . . . . . . . . . . . . . . . 13Configuration files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Base configuration file (ibmwesas.conf) . . . . . . . . . . . . . . . . . . . . . . . . . 14Object space definition configuration file (osdef.conf) . . . . . . . . . . . . . . . . . . . . 14User mapping configuration file (usermap.conf) . . . . . . . . . . . . . . . . . . . . . . 16

Log files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Chapter 4. Understanding the plug-in for Edge Server configuration . . . . . . . . . 19Server configuration model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19Server configuration concepts applied . . . . . . . . . . . . . . . . . . . . . . . . . . 20Object space configuration model . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23Single signon configuration model. . . . . . . . . . . . . . . . . . . . . . . . . . . . 24Configuration procedure summarized . . . . . . . . . . . . . . . . . . . . . . . . . . 24

Chapter 5. Deploying the plug-in for Edge Server . . . . . . . . . . . . . . . . . 27Designing the Web site . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Content distribution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27Single signon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

© Copyright IBM Corp. 2001, 2002 iii

Configuring the Web site . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

Chapter 6. Creating a Cross-domain Authentication Service . . . . . . . . . . . . . 31Authentication models. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Single authentication model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31Dispatched authentication model . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

Building a custom shared library . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33CDAS application development kit . . . . . . . . . . . . . . . . . . . . . . . . . . 34Programming the custom shared library . . . . . . . . . . . . . . . . . . . . . . . . . 34User authentication data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36Returning the client identity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36Compiling the custom shared library . . . . . . . . . . . . . . . . . . . . . . . . . . 36

Configuring the plug-in for Edge Server to use a custom shared library . . . . . . . . . . . . . . . 37Configuring a custom shared library . . . . . . . . . . . . . . . . . . . . . . . . . . 37Custom shared library configuration scenario . . . . . . . . . . . . . . . . . . . . . . . 37Configuring the demonstration library . . . . . . . . . . . . . . . . . . . . . . . . . 38Loading the custom shared library . . . . . . . . . . . . . . . . . . . . . . . . . . 39

CDAS core and utility functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40CDAS API core function reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

xauthn_authenticate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41xauthn_change_password. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42xauthn_initialize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43xauthn_shutdown . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

Chapter 7. Removing the plug-in for Edge Server . . . . . . . . . . . . . . . . . 45Removing the plug-in for Edge Server on AIX . . . . . . . . . . . . . . . . . . . . . . . . 45Removing the plug-in for Edge Server on Linux . . . . . . . . . . . . . . . . . . . . . . . 45Removing the plug-in for Edge Server on Solaris . . . . . . . . . . . . . . . . . . . . . . . 46Removing the plug-in for Edge Server on Windows . . . . . . . . . . . . . . . . . . . . . . 47

Appendix A. Base configuration file reference . . . . . . . . . . . . . . . . . . . 49

Appendix B. Object space definition configuration file reference . . . . . . . . . . . 51Server definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51Single signon definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

Appendix C. wesosm command reference . . . . . . . . . . . . . . . . . . . . 63Command syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63wesosm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64

Appendix D. Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67Trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

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

Preface

The IBM® Tivoli® Access Manager (Access Manager) plug-in for IBM WebSphere®

Edge Server (plug-in for Edge Server) provides authentication and authorizationsecurity services. Installed on the Edge Server caching proxy, the plug-in for EdgeServer is the gateway between your clients and Web servers, implementing thesecurity policies that protect your Web resources. The plug-in secures Web contentand application server resources at the caching proxy through virtual hosting, andprovides single signon solutions for the protected Web servers.

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, theterm management server is now referred to as policy server.

The IBM Tivoli Access Manager Plug-in for Edge Server User’s Guide providesinstallation instructions, administration procedures, and technical referenceinformation for securing your Web domain using the plug-in for Edge Server.

Who should read this bookThis guide is for system administrators responsible for the installation,deployment, and administration of the plug-in for Edge Server.

Readers should be familiar with the following:v Microsoft® Windows® and UNIX® operating systemsv Security managementv Internet protocols, including HTTP, HTTPS, and TCP/IPv Lightweight Directory Access Protocol (LDAP) and directory servicesv Authentication and authorizationv Access Manager security model and its capabilities

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 containsThis book contains the following sections:v Chapter 1, “Introducing the IBM Tivoli Access Manager plug-in for Edge Server”

on page 1Describes the supported platforms, installation packages, and softwareprerequisites for the plug-in for Edge Server. Also describes the Access Managersecurity model and the plug-in for Edge Server security enforcement.

v Chapter 2, “Installing the plug-in for Edge Server” on page 7Provides installation and configuration instructions for all supported platforms.

v Chapter 3, “Administering the plug-in for Edge Server” on page 11Describes how to manage user accounts, create an Access Manager object space,and start and stop the plug-in. Also describes the plug-in for Edge Serverconfiguration and log files.

© Copyright IBM Corp. 2001, 2002 v

v Chapter 4, “Understanding the plug-in for Edge Server configuration” onpage 19Provides an overview of the plug-in for Edge Server configuration.

v Chapter 5, “Deploying the plug-in for Edge Server” on page 27Describes an example deployment of the plug-in for Edge Server in a Webcommerce environment.

v Chapter 6, “Creating a Cross-domain Authentication Service” on page 31Explains how to create a Cross-domain Authentication Service (CDAS) sharedlibrary, which enables custom handling and processing of client authenticationinformation. Also describes how to configure the plug-in for Edge Server torecognize the specific type of authentication data being passed to the customshared library.

v Chapter 7, “Removing the plug-in for Edge Server” on page 45Describes how to unconfigure and remove the plug-in for Edge Server from eachof the supported operating system platforms.

v Appendix A, “Base configuration file reference” on page 49v Appendix B, “Object space definition configuration file reference” on page 51v Appendix C, “wesosm command reference” on page 63

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

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

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

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

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

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

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

v IBM Tivoli Access Manager for e-business Release Notes

GI11-0919 (am39_relnotes.pdf)

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

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

Base informationv IBM Tivoli Access Manager Base Installation Guide

GC32-0844 (am39_install.pdf)Provides installation, configuration, and upgrade instructions for AccessManager base software, including the Web portal manager interface.

v IBM Tivoli Access Manager Base Administrator’s Guide

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

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

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

WebSEAL informationv IBM Tivoli Access Manager WebSEAL Installation Guide

GC32-0848 (amweb39_install.pdf)Provides installation, configuration, and upgrade instructions for the WebSEALserver and the WebSEAL application development kit.

v IBM Tivoli Access Manager WebSEAL Administrator’s Guide

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

v IBM Tivoli Access Manager WebSEAL Developer’s Reference

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

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

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

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

GC32-0850 (amwas39_user.pdf)Provides installation, configuration, and administration instructions for AccessManager for IBM WebSphere® Application Server.

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

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

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

Preface vii

GC23-4685 (amedge39_user.pdf)Provides installation, configuration, and administration instructions for theplug-in for Edge Server application.

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

GC23-4686 (amws39_user.pdf)Provides installation, configuration, and administration instructions for securingyour Web domain using the plug-in for Web servers application.

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

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

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

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

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

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

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

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

v IBM Tivoli Access Manager WebSEAL Developer’s Reference

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

Technical supplementsv IBM Tivoli Access Manager Performance Tuning Guide

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

v IBM Tivoli Access Manager Capacity Planning Guide

GC32-0847 (am39_capplan.pdf)Assists planners in determining the number of WebSEAL, LDAP, and backendWeb servers needed to achieve a required workload.

v IBM Tivoli Access Manager Error Message Reference

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

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

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

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

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

IBM DB2® Universal Database™

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

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

IBM Global Security ToolkitAccess Manager provides data encryption through the use of IBM Global SecurityToolkit (GSKit). GSKit is shipped on the IBM Tivoli Access Manager Base CD foryour particular platform.

The GSKit package installs the iKeyman key management utility (gsk5ikm), whichenables you to create key databases, public-private key pairs, and certificaterequests. The following document is available in the /doc/GSKit directory:v SSL Introduction and iKeyman User’s Guide (gskikm5c.pdf)

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

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

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

Windows® operating systems.v IBM SecureWay Directory Release Notes

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

v IBM SecureWay Directory Readme Addendum

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

v IBM SecureWay Directory Server Readme

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

v IBM SecureWay Directory Client Readme

Preface ix

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

v IBM SecureWay Directory Configuration Schema

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

v IBM SecureWay Directory Tuning Guide

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

you are locatedv What information you should gather before contacting support

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

Typeface conventionsThe following typeface conventions are used in this book:

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

Italic Variables, command options, and values you must provide appear

Preface xi

in italics. Titles of publications and special words or phrases thatare emphasized also appear in italics.

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

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

Chapter 1. Introducing the IBM Tivoli Access Manager plug-infor Edge Server

The plug-in for Edge Server adds authentication and authorization functionality tothe IBM WebSphere Edge Server product. When implemented as an authorizationservice in your secure domain, this plug-in can provide single signon solutions toresources within that domain.

This chapter describes the supported platforms, installation packages, and softwareprerequisites for the plug-in for Edge Server. This chapter also describes the IBMTivoli Access Manager security model and the plug-in for Edge Server securityenforcement.

System requirementsAccess Manager has specific software and hardware prerequisites that must be metbefore it can be installed and deemed fully functional. These include operatingsystems, hardware platforms, and so on.

The requirements listed in the following sections constitute the recommendedenvironment for the plug-in for Edge Server components at the time of publication.For the most current information, see the IBM Tivoli Access Manager for e-businessRelease Notes.

Supported operating systemsThe plug-in for Edge Server is supported on the following platforms:v IBM AIX 4.3.3 and 5.1v Microsoft Windows 2000 Advanced Serverv Red Hat Linux 7.1v Sun Solaris 2.7 and 2.8

Software prerequisitesThe plug-in for Edge Server operates in a secure domain installed with AccessManager, Version 3.9. The plug-in for Edge Server has the following softwareprerequisites. You must install and configure these prerequisites on the samesystem as the plug-in for Edge Server.

Note that if your system already runs Access Manager, Version 3.9, then the GSKit,IBM SecureWay Directory client, and Access Manager runtime are already installedand configured. However, if you plan to install the plug-in on a new system that isnot currently a part of your Access Manager secure domain, follow installationinstructions in the IBM Tivoli Access Manager Base Installation Guide.v IBM WebSphere Edge Server, Version 2.0, with program temporary fix (PTF) 1.

To download the PTF 1, see the following Web address:http://www-1.ibm.com/support/manager.wss?rs=0&rt=1&cat=Downloadable+files&r=10&mr=200&q=Edge+Server&path=Product+Group%3DSoftware

v IBM Global Security Toolkit (GSKit), Version 5.0.4.67v IBM SecureWay Directory, Version 3.2.2, client

© Copyright IBM Corp. 2001, 2002 1

v Access Manager runtime environment

Access Manager security modelThe plug-in for Edge Server adds authentication and authorization control to theEdge Server caching proxy. To administer the plug-in for Edge Server, you need tobe familiar the Access Manager model for enforcing security policies.

The Access Manager model is based on understanding the business policies thatmust apply to users, programs, and data in a network environment. To establish asecure environment, Access Manager requires an administrator to define thefollowing entities:v Objects to be securedv Actions permitted on each objectv Users permitted to perform the actions

Access Manager manages each of these entities as follows:v Objects are listed and defined in a hierarchal protected object name space or

object space.v Standard actions, such as read and write, are defined as permissions.

Administrators can also define custom application-specific actions.v Users and groups are defined in an Access Manager supported user registry.

Access Manager combines these concepts to form access control lists (ACLs) thatconsist of combinations of specific users or groups and a list of the permissions(actions). The administrator attaches these ACLs to objects in the object space.

For example, an administrator can control access to the contents of a Web server byattaching an ACL to a file at the top of a hierarchal file system on a Web server.The administrator can also choose to apply a more restrictive ACL further down inthe file hierarchy. The more restrictive ACL overrides the ACL that is attached atthe top of the hierarchy. The plug-in for Edge Server enforces access control bychecking for the read (r), modify (m), or execute (x) permission on each requestedobject, based on the requested action.

The Access Manager security model is flexible and supports many differentconfigurations. Before you use the plug-in for Edge Server, you need to be familiarwith Access Manager capabilities. For more information, see the IBM Tivoli AccessManager Base Administrator’s Guide.

Plug-in for Edge Server security enforcementThe plug-in for Edge Server works with the IBM WebSphere Edge Server toprovide access control. It sits at the edge of an enterprise network where accessrequests from clients outside the firewall are evaluated.

Edge Server consists of two key components:v Caching proxyv Network dispatcher

The plug-in is invoked by the caching proxy component on every request todetermine if the user is authorized to access the requested resource. The cachingproxy subsequently enforces the authorization decision returned by the plug-in.

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

Although the network dispatcher component is not required to run the plug-in, itcan be used for load balancing across replicated servers in high volumeenvironments.

Generally, when a user issues a request from a browser to a Web site, the objectrepresented in the URL corresponds to an object on a Web server. The plug-in forEdge Server provides access control by verifying that the user is authorized toperform the requested action on the Web server object. The plug-in does this byauthenticating the user against the Access Manager user registry and authorizingthe user against the Access Manager object space, as illustrated in Figure 1. Theplug-in returns status information to the caching proxy indicating whether the userwas authorized to perform the requested action on the object. The caching proxyuses this information to either deny or allow the requested action. When thesecurity policy permits, the Edge Server caching proxy caches the requested objectto optimize performance.

The plug-in for Edge Server provides access control for the following Edge Servercaching proxy configurations:v Reverse proxyv Forward proxy

These concepts are discussed in the following sections.

Reverse proxy access controlThe Edge Server caching proxy functions as a reverse proxy when it is locatedbetween a client browser on the Internet and Web servers that are located behind afirewall. In this role, the caching proxy intercepts user requests arriving from theInternet, forwards them to the appropriate host Web server, caches the returneddata, and delivers that data to the client user across the Internet.

The plug-in for Edge Server can be used to provide access control to these inboundclient requests. This is accomplished by configuring the public domain name of theWeb site on the Edge Server caching proxy machine and specifying a route to thecorresponding backend Web server, as illustrated in Figure 2 on page 4.

Internet Gateway

Browser

Edge Server

CachingProxy

Web Server

Access ManagerPolicy Server

Access ManagerPlug-in

Access ManagerRegistry Server

Figure 1. Example of plug-in for Edge Server security enforcement

Chapter 1. Introducing the IBM Tivoli Access Manager plug-in for Edge Server 3

In this example, the plug-in for Edge Server is configured to provide access controlto the objects on newbooks.com. After a user is authorized, the request is routed tothe corresponding backend server either by the plug-in for Edge Server, or by aload balancing module, such as the content-based routing module of the EdgeServer network dispatcher. The plug-in for Edge Server performs URL mapping,similar to the function provided by the Proxy statements in the Edge Servercaching proxy configuration file.

You configure the plug-in for Edge Server access control by setting values forparameters in the plug-in configuration file, osdef.conf. For this example Web site,you would add the following entries:[Remote: /ESproxy/reverse/newbooks.com]domains = newbooks.com www.newbooks.comlogin_method = formsform_login_file = http://newbooks.com/pub/login.htmlform_login_errorfile = http://newbooks.com/pub/loginerr.htmlform_logout_url = /pub/logout.htmlroute = http://backend1.com

This entry configures the plug-in for Edge Server to perform the following actions:v Authorize all requests for newbooks.com and www.newbooks.com by consulting

the ACLs that are attached to objects under theentry /ESproxy/reverse/newbooks.com in the Access Manager protected objectname space.

v Use forms-based login as the login methodv Map every URL to the following Web server:

backend1.com

In this example, the administrator should attach the unauthenticated ACL on the/pub directory. For more information about the use of the unauthenticated ACL,see the IBM Tivoli Access Manager Base Administrator’s Guide.

Note also that if the user submits a URL request that matches /pub/logout.html,the user is logged out.

By default, the plug-in for Edge Server checks /ESproxy/reverse/domain_name forreverse proxy requests. You can set additional options for this server definition. If

Internet Gateway

Browser

Edge Servernewbooks.com

CachingProxy

Access Manager

Web Serverbackend1.com

Plug-in

Figure 2. Plug-in for Edge Server in a reverse proxy configuration


you do not specify a setting for an option, the setting for that option is inheritedfrom the [Global] section of the osdef.conf configuration file.

The plug-in for Edge Server supports several login methods. In addition to theforms-based login shown in the sample configuration, you can also configure theplug-in for Edge Server to use:v Basic authenticationv Client certificate authentication

For information about osdef.conf file options, see Appendix B, “Object spacedefinition configuration file reference” on page 51.

Forward proxy access controlThe Edge Server caching proxy functions as a forward proxy when it is locatedbetween a client browser (behind a firewall) and the Internet. The client browsersare configured to direct requests to the Edge Server caching proxy. The forwardcaching proxy forwards a client’s request to a content host located across theInternet, caches the retrieved data, and delivers the retrieved data to the client.

The plug-in for Edge Server can be used to provide access control to theseoutbound client requests, as illustrated in Figure 3.

By default, the plug-in for Edge Server checks /ESproxy/forward/domain_name forforward proxy requests. You can override this default setting by creating one ormore server definitions in the object space definition configuration file as shown:[Remote: /ESproxy/forward/blockedsites]domains = games.com *.games.com *.competitor.comroute = http://backend2.com /pub/browsepolicy.html

In this example, all browser requests matching the domain names games.com,*.games.com, or *.competitor.com are redirected to the company’s browsing policyWeb page located at the following Web address:

backend2.com

Alternatively, you can attach an Access Manager ACL at this location in the objectspace. For example, this ACL could deny all users access to any of the listed Websites.

Internet Gateway

Edge Server

CachingProxy


Web Server Browser

Figure 3. Plug-in for Edge Server in a forward proxy configuration

Chapter 1. Introducing the IBM Tivoli Access Manager plug-in for Edge Server 5


Chapter 2. Installing the plug-in for Edge Server

This chapter describes how to install and configure the plug-in for Edge Server onAIX, Solaris, and Windows platforms. Note that if your system is currently set upwith supported versions of GSKit, IBM SecureWay Directory client, and the IBMTivoli Access Manager runtime environment, you need to install only the plug-inpackage.

This chapter contains the following sections:v “Installing the plug-in for Edge Server on AIX” on page 7v “Installing the plug-in for Edge Server on Linux” on page 7v “Installing the plug-in for Edge Server on Solaris” on page 8v “Installing the plug-in for Edge Server on Windows” on page 8v “Configuring the plug-in for Edge Server” on page 8

Installing the plug-in for Edge Server on AIXThe following steps show you how to install components necessary for the plug-infor Edge Server.

Note: Before you install the plug-in package, ensure that you install prerequisitesoftware in “System requirements” on page 1.

1. Log in to the system as root.2. Insert the IBM Tivoli Access Manager Web Security, Version 3.9, for AIX CD.3. To install the Plug-in for Edge Server package in the default location, enter the

following:installp -c -a -g -X -d /dev/cd0 PDPlgES

4. To complete the installation of the plug-in for Edge Server, follow theinstructions in “Configuring the plug-in for Edge Server” on page 8.

Installing the plug-in for Edge Server on LinuxThe following steps show you how to install components necessary for the plug-infor Edge Server.


1. Log in to the system as root.2. Insert the IBM Tivoli Access Manager Web Security, Version 3.9, for Linux CD.3. Change to the directory /mnt/cdrom/linux, where /mnt/cdrom is the mount

point for your CD.4. To install the plug-in for Edge Server package in the default location, enter the

following:rpm -i --nodeps PDPlgES-PD-3.9.0-0.i386.rpm

5. To complete the installation of the plug-in for Edge Server, follow theinstructions in “Configuring the plug-in for Edge Server” on page 8.


Installing the plug-in for Edge Server on SolarisThe following steps show you how to install components necessary for the plug-infor Edge Server.


1. Log in to the system as root.2. Insert the IBM Tivoli Access Manager Web Security, Version 3.9, for Solaris CD.3. Change to the /cdrom/cdrom0/solaris directory.4. To install the plug-in for Edge Server package, enter the following:

pkgadd -d /cdrom/cdrom0/solaris -a /cdrom/cdrom0/solaris/pddefault PDPlgES

5. To complete the installation of the Plug-in for Edge Server, follow theinstructions in “Configuring the plug-in for Edge Server” on page 8.

Installing the plug-in for Edge Server on WindowsThe following steps show you how to install components necessary for the plug-infor Edge Server.


1. Log in to the system as a user with administrator privileges.2. Insert the IBM Tivoli Access Manager Web Security, Version 3.9, for Windows CD.3. Run the setup.exe file in the following location:

cdrom_drive\windows\PolicyDirector\Disk Images\Disk1

4. From the Select Packages window, select the plug-in for Edge Server package.5. To complete the installation of the plug-in for Edge Server, follow the

instructions in “Configuring the plug-in for Edge Server” on page 8.

Configuring the plug-in for Edge ServerThe plug-in for Edge Server provides a configuration utility named wslconfig.sh(on UNIX systems) or wslconfig.exe (on Windows systems). This utilityaccomplishes the following tasks:v Creates an Access Manager identity for the plug-in for Edge Server.v Creates an Access Manager protected object space for the plug-in for Edge

Server.v On the Windows platform only, configures the Edge Server caching proxy to

automatically load the plug-in for Edge Server at application startup.

To configure the plug-in for Edge Server, follow these steps:1. To start the configuration utility, enter the following:

v On UNIX systems:wslconfig.sh

v On Windows systems:wslconfig.exe

Note: On Windows 2000 systems only, configuration of the plug-in for anActive Directory user registry requires an administrator password for


the configuration tool to perform successfully. When configuring, usethe wslconfig command with the following parameter:wslconfig -adpwd Active_Directory_admin_password

2. When prompted, enter the following information:v The port number for the Edge Server caching proxy. The default port number

is 80.v The Access Manager administrative user ID and password. For example,

enter sec_master and its associated password.

The configuration utility completes the following tasks:v Creates registry objects for the server.v Adds the server to the security groups, ivacld-servers and SecurityGroup.v Creates an SSL certificate.v Obtains an SSL signed certificate from the Access Manager policy server.v Configures the Edge Server caching proxy to use the plug-in for Edge Server by

setting directives in the Edge Server caching proxy configuration file,ibmproxy.conf.

v Restarts the Edge Server caching proxy process, ibmproxy.

Next, the configuration utility starts the plug-in for Edge Server object spacemanager utility, by using the wesosm command. This utility updates the AccessManager object space to create a new object space container for the plug-in forEdge Server.

Configuration of the plug-in for Edge Server is now complete. The Edge Servercaching proxy is now running with the plug-in for Edge Server loaded. Theadministrative user, sec_master, can be used to access the caching proxy’s homepage.

Upgrading the plug-in for Edge ServerThe configuration tool for the earlier versions of the plug-in automatically replaceduser configuration files during the unconfiguration process, which sometimescaused the loss of user configuration information. The plug-in for Edge Server,Version 3.9, does not replace user configuration files during the unconfigurationprocess. When upgrading from an existing version of the plug-in for Edge Server,you need to back up all user modified configuration files, such as ibmwesas.conf,osdef.conf, ibmproxy.conf, before unconfiguring the plug-in.

Chapter 2. Installing the plug-in for Edge Server 9


Chapter 3. Administering the plug-in for Edge Server

This chapter provides the concepts, administrative procedures, and technicalreference information for using the plug-in for Edge Server to manage theresources of your secure domain. This chapter contains the following sections:v “Managing user accounts” on page 11v “Creating an Access Manager object space” on page 11v “Starting and stopping the plug-in for Edge Server” on page 13v “Configuration files” on page 13v “Log files” on page 16

Managing user accountsIBM Tivoli Access Manager maintains and manages user accounts through thepdadmin command line interface. Users and groups are created, deleted, andmodified using this interface. The plug-in authenticates a user by verifying that thesubmitted user information matches a user entry in the Access Manager registry.The plug-in also verifies that the user account status is valid.

All password policies for users are set through Access Manager and conveyed tothe plug-in during authentication. The plug-in does not maintain any passwordpolicy information but relies on Access Manager to maintain information such asmax-login-failures, account-expiry-date, and max-password-age. Duringauthentication, the plug-in verifies that the user account is valid and ensures thatthe user’s password has not expired. If the user account is disabled, the user failsauthorization. However, if the password has expired and a change password formwas configured for the plug-in, then the user is presented with the form to changethe expired password.

Creating an Access Manager object spaceAccess Manager uses a protected object name space to represent objects that needto have access control policies applied. The protected object space can includeresources on a Web server. The simplest way to add Web resources to the objectspace is to import the Web server file system and apply Access Manager accesscontrol lists (ACLs) as needed.

The plug-in for Edge Server provides an object space manager utility that addsresources to the Access Manager object space. The utility is invoked with thewesosm command. You can use wesosm to generate the object space for both theEdge Server caching proxy and for Web servers that the plug-in for Edge Serverprotects.

Note: For more information about the wesosm command, see Appendix C,“wesosm command reference” on page 63.

The following sections describe how to add Web resources to the protected objectspace:v “Creating an object space for the caching proxy” on page 12v “Creating an object space for other Web servers” on page 12


Creating an object space for the caching proxyAlthough the Edge Server caching proxy is a proxy, it can function like a Webserver when requests are made directly to the primary domain name of the EdgeServer caching proxy machine. Typically, informational and error messages arestored in the Web space of the proxy. The plug-in for Edge Server enforces accesscontrol to the objects that are managed by the Edge Server caching proxy.

Each object that needs to be secured must be defined in the Access Manager objectspace. There are two methods for adding objects to the object space.

You can add objects to the object space manually by using the pdadmin command.The pdadmin command contains command line options for creating new objectspaces and for adding, modifying, and deleting objects. For more information, seethe IBM Tivoli Access Manager Base Administrator’s Guide.

You can also add a series of Web resources to the object space by using thequery_contents utility to get an inventory of the objects in a Web hierarchy. Thismethod is discussed in “Creating an object space for other Web servers” on page12.

The following example server definition in the configuration file osdef.confrepresents an Edge Server caching proxy named bookproxy.com:[Local: /ESproxy/bookproxy.com]domains = bookproxy.comquery_command = http://bookproxy.com/cgi-bin/query_contents?dirlist=/

When you configure the plug-in for Edge Server at installation time, the wslconfigutility executes the wesosm command to generate the default object space for theEdge Server caching proxy. The default object space contains the followingcontainer objects:/ESproxy/Esproxy/proxy_host_name/ESproxy/forward/ESproxy/reverse

After the objects are created, you can place ACLs at the appropriate locations inthe object space for the Edge Server caching proxy.

Creating an object space for other Web serversUse the object space manager wesosm command to query a remote Web server’sfile system to create corresponding entries in the Access Manager object space. Theobject space manager reads the osdef.conf configuration file and creates objectentries for each server definition in the file.

Use the query_contents utility to import a Web server’s file system into theprotected object space. Place this utility in the cgi-bin directory on the target Webserver. Also, specify the root location of the Web server’s files. For moreinformation about the query_contents utility, see the IBM Tivoli Access ManagerWebSEAL Administrator’s Guide.

After you have configured the query_contents utility, add an entry to the objectspace definition configuration file that tells the wesosm command how to querythe remote Web server’s file system. For example, add the following entry in theconfiguration file:


[Remote: /ESproxy/reverse/newbooks.com]domains = newbooks.com www.newbooks.com...query_command = http://backend1.com/cgi-bin/query_contents?dirlist=/

After the entry has been added to the configuration file, run the object spacemanager from the plug-in for Edge Server machine as shown:wesosm -run -infile location_of_osdef.conf -verbose

The wesosm command connects to the Web server to query its file system. Next, itconnects to the Access Manager policy server to create entries in the object spaceunderneath /ESproxy/reverse/newbooks.com. If a server definition does not have aquery_contents utility associated with it, only the root branch is created. You canattach ACLs in appropriate locations after the object space has been created.

You also can use the wesosm command to maintain the object space by pruningany obsolete entries that might accumulate over time. To remove obsolete entriesfrom the object space, run the wesosm command with the following options:wesosm -run -infile location_of_osdef.conf -clean -verbose

Starting and stopping the plug-in for Edge ServerTo manually start the Edge Server caching proxy and load the plug-in for EdgeServer, do one of the following:v On UNIX systems, use the wslstartwte command.

Note: You can add the wslstartwte utility to UNIX startup scripts toautomatically start the Edge Server caching proxy and the plug-in forEdge Server whenever a system restarts.

v On Windows systems, start the IBM Caching Proxy service.

To stop the Edge Server caching proxy UNIX systems, do one of the following:v On UNIX systems, use the wslstopwte command:v On Windows systems, stop the IBM Caching Proxy service.

Configuration filesThe plug-in for Edge Server configuration files are created and placed on thefilesystem when the plug-in for Edge Server is installed and configured. You canmanually modify these files after initial configuration.

The configuration files are located in one of the following directories:v On UNIX systems:

/opt/pdweb-lite/etc

v On Windows systems:install_dir\etc

Configuration files are described in the following sections:v “Base configuration file (ibmwesas.conf)” on page 14v “Object space definition configuration file (osdef.conf)” on page 14v “User mapping configuration file (usermap.conf)” on page 16

Chapter 3. Administering the plug-in for Edge Server 13

Base configuration file (ibmwesas.conf)The base configuration file is named ibmwesas.conf. The wslconfig utilityinitializes this file when the plug-in for Edge Server is installed and configured.This file contains entries that are used to initialize and start the plug-in for EdgeServer. Typically, you do not need to modify this file after initial configuration.

The ibmwesas.conf file contains entries that specify the following values:v Access Manager Lightweight Directory Access Protocol (LDAP) configuration

settingsThese include LDAP host and port numbers. When Access Managercommunication with the LDAP server is over Secure Sockets Layer (SSL), theSSL configuration values are included here.

v Access Manager configuration values:– Database replication mode (local or remote)– Database location– Audit file location– Cache refresh interval– Location of the SSL configuration file containing certificate information

v Lightweight Third Party Authentication (LTPA) cookie single signon settingsv WebSEAL cookie single signon settingsv Location of the osdef.conf object space definition filev Location of the usermap.conf user mapping file

For more information on the ibmwesas.conf file, see Appendix A, “Baseconfiguration file reference” on page 49.

Object space definition configuration file (osdef.conf)The object space definition configuration file is named osdef.conf. The osdef.conffile specifies configuration settings that the plug-in for Edge Server uses to enforceaccess control for all client requests. The object space definition configuration filehas its settings grouped into the following sections:v [Global]

Specifies settings that apply to all requests that are not explicitly overwritten inanother section ([Local] or [Remote]).

v [Local]

Specifies settings that apply to requests for objects on the Edge Server cachingproxy.

v [Remote]

Specifies settings that apply to requests for objects on remote Web servers.v [SSO]

Specifies single signon definitions and settings that the plug-in for Edge Servercan use to pass authentication information to a Web server.

The [Global] section of the osdef.conf file includes the following configurationoptions:v Administrator name and passwordv Enable or disable updating of the object spacev Object space locations for the object space root, forward proxy entries, and

reverse proxy entries


v File system typev URL resolution using reverse Domain Name System (DNS) lookupv Login method

– NoneIt is recommended that you use the Access Manager unauthenticated ACLrather than the None login type.

– Basic authentication– Forms-based login– Certificates

v Forms-based login settingsIncludes forms file locations, error file locations, password handling, andsecurity type to be used for secure form login.

v Cache size and cache timeout values for storing authenticated user informationv Logging message settings

The [Local] section of the osdef.conf file includes the following configurationoptions:v Domain namesv Login methodv Query command settings

These values are used to collect object space information for the local EdgeServer caching proxy objects.

The [Remote] section of the osdef.conf file contains definitions for each remoteserver that is being secured by the plug-in for Edge Server. The settings for eachserver include:v Domain namesv Login method and supporting filesv Query commandsv SSL access requirementsv Single signon optionsv Routing options

The [SSO] section of the osdef.conf file contains single signon definitions andsettings for single signon configurations. The plug-in for Edge Server can skip theauthentication step if a user has already been authenticated. The plug-in for EdgeServer can also pass single signon information to a Web server as either an HTTPheader or a cookie.

The following single signon types are predefined:v IBM WebSphere LTPA cookiev Access Manager WebSEAL failover cookiev CDAS module single signon

The plug-in for Edge Server provides several predefined macros that you can useto format single signon information. For information about these macros and forexamples of formatted single signon information, see the sample entries in theosdef.conf file.


The plug-in for Edge Server supports many different configuration scenarios.Accordingly, many configuration options can be adjusted. The osdef.confconfiguration file documents each option in detail and provides a default andsample value for each option.

After you develop a basic understanding of the plug-in for Edge Server, you caneasily customize and configure it to work in your environment. The plug-in forEdge Server runs well using default values. Therefore, you do not need to setevery option to use it effectively. Set only the relevant options.

For more information on the osdef.conf file, see Appendix B, “Object spacedefinition configuration file reference” on page 51.

User mapping configuration file (usermap.conf)The usermap.conf file is used to map single signon and certificate users to AccessManager users. For more information about the user mapping file, see commentsprovided in the usermap.conf template file. The usermap.conf template file islocated in one of the following directories:v For UNIX systems:

/opt/pdweb-lite/etc

v For Windows systems:install_dir\etc

Log filesThe plug-in for Edge Server logs events to the event log file of the Edge Servercaching proxy. You can examine this log file to view the actions that the plug-in forEdge Server has taken.

The log file on UNIX systems is as follows:/opt/ibm/edge/cp/server_root/logs/event.date

The log file on Windows systems is as follows:C:\Program Files\IBM\edge\cp\server_root\Logs\event.date

Figure 4 on page 17 shows an excerpt from an event log file.


[03/15/02 10:04:53 1] --------------------------------------------[03/15/02 10:04:53 1] Entering Initialization Plugin: WTESeal_Init()[03/15/02 10:04:53 1] Initialization of configuration settings succeeded[03/15/02 10:04:55 1] Initialization of WebSEAL cookie module succeeded[03/15/02 10:04:55 1] Initializing attribute list[03/15/02 10:04:55 1] [00]: azn_init_audit_file[03/15/02 10:04:55 1] [01]: azn_init_cache_refresh_interval[03/15/02 10:04:55 1] [02]: azn_init_cfg_file[03/15/02 10:04:55 1] [03]: azn_init_db_file[03/15/02 10:04:55 1] [04]: azn_init_ldap_bind_dn[03/15/02 10:04:55 1] [05]: azn_init_ldap_bind_pwd[03/15/02 10:04:55 1] [06]: azn_init_ldap_host[03/15/02 10:04:55 1] [07]: azn_init_ldap_port[03/15/02 10:04:55 1] [08]: azn_init_listen_flags[03/15/02 10:04:55 1] [09]: azn_init_mode[03/15/02 10:04:55 1] AZN API client library version 3.9.0 (Build 020315)[03/15/02 10:04:55 1] Initialization of Access Manager succeeded[03/15/02 10:04:55 1] Exiting Initialization Plugin: WTESeal_Init()[03/15/02 10:04:55 1] Waiting for connections...[03/15/02 10:06:02 2560][03/15/02 10:06:02 2560] --- Accepted a non-secure connection ---[03/15/02 10:06:02 2560] Entering PreExit Plugin: WTESeal_PreExit()[03/15/02 10:06:02 2560] User from 110.120.130.140 submitted request: GET /[03/15/02 10:06:02 2560] Login method for this request is basic[03/15/02 10:06:02 2560] Checking authorization header for reverse proxy mode[03/15/02 10:06:02 2560] Successfully extracted user ’joe’ from authorization header[03/15/02 10:06:02 2560] Exiting PreExit Plugin: WTESeal_PreExit()[03/15/02 10:06:02 2560][03/15/02 10:06:02 2560] Entering Authorization Plugin: WTESeal_Authorize()[03/15/02 10:06:02 2560]HTTP Headers:Host: newbooks.comAuthorization: Basic Yah7dglDai84qBXf=

[03/15/02 10:06:02 2560] Authenticating user ’joe’ through Access Manager[03/15/02 10:06:02 2560] Authentication succeeded for user ’joe’[03/15/02 10:06:02 2560] Creating LDAP identity for user ’joe’[03/15/02 10:06:02 2560] Loading credentials to authorize user ’joe’[03/15/02 10:06:03 2560] Checking access (r) on ACL string /ESproxy/reverse/newbooks.com[03/15/02 10:06:03 2560] Permission was granted to access object[03/15/02 10:06:03 2560] User ’joe’ was successfully authorized (return code = 200)[03/15/02 10:06:03 2560] Routing request to http://backend1.com/ using reverse proxy route[03/15/02 10:06:03 2560] Exiting Authorization Plugin: WTESeal_Authorize()

Figure 4. Event log file excerpt



Chapter 4. Understanding the plug-in for Edge Serverconfiguration

This chapter provides an overview of the plug-in for Edge Server configurationexplaining concepts, models, and procedures. This chapter contains the followingsections:v “Server configuration model”v “Server configuration concepts applied” on page 20v “Object space configuration model” on page 23v “Single signon configuration model” on page 24v “Configuration procedure summarized” on page 24

Server configuration modelThe plug-in for Edge Server provides authentication and authorization services forWeb servers within a secured domain by enforcing the security at the Edge Serverproxy, rather than at the Web server. By implementing the security enforcement atthe proxy, the plug-in centrally provides security services for all Web serverswithin the secured domain. After a user is authorized, the plug-in forwards therequest to the corresponding Web server with the user’s information.

Because the content of a Web site might span multiple Web servers forperformance and content distribution, the plug-in needs to provide securityservices for multiple Web servers within the secured domain. While some Webservers might host content, others might host a wide variety of Web applications,each with different security requirements. For example, some servers might notrequire authentication, but other servers might require it. Each server requiringauthentication might require the user information be submitted in a unique format.While some security settings are common to all servers such as form sessiontimeout and logging level, some are unique to each server such as login methodand single signon.

The plug-in secures the varied array of Web servers, each with its uniqueconfiguration requirements through its object space definition configuration file,osdef.conf. This configuration file organizes the settings for each protected Webserver into server definitions. Within each server definition, server specific settingsare set. There are three types of server definitions used in the configuration file asshown in the following table.

Server definition Description

[Global] Settings listed under this definition apply toall Web servers. There is only one instanceof this definition.

[Local] Settings listed under this definition applyonly to the Edge Server caching proxy. Thereis only one instance of this definition.

[Remote] Settings listed under this definition apply toexternal or remote Web servers secured bythe plug-in. There can be multiple instancesof this definition.


With a few exceptions that are documented in the osdef.conf file, any setting canbe placed under any definition. For example, the form_session_timeout setting,can be placed underneath the [Global] definition, or underneath a [Remote]definition as shown:[Global]login_method = formsform_login_file = /opt/pdweb-lite/samples/forms/welcome.htmlform_session_timeout = 10

[Remote: /ESproxy/reverse/anyother.com]domains = anyother.com

[Remote: /ESproxy/reverse/verysecure.com]domains = verysecure.comform_session_timeout = 1

In this example, any user who logs into verysecure.com is not allowed to remainidle for more than one minute, otherwise their session expires. However, for anyuser who logs into anyother.com and all other domains, the idle timeout is 10minutes due to it being set in the [Global] definition. With a few exceptions, thismodel of inheritance can be used on any server setting in the configuration file butis not applicable to single signon [SSO] settings, as illustrated in Figure 5.

Using this model of inheritance, settings that are the same for each Web server donot need to be repeated under each server definition but can be listed onceunderneath the [Global] definition of the configuration file. For example, if allservers uses the same form login file, then that setting can be listed in the [Global]definition.

Server configuration concepts appliedWith a basic understanding of the configuration file, it is easier to understand howthe plug-in enforces security using this configuration file. Whenever a request isreceived by the plug-in, it follows the following basic steps to authorize the user.1. If the user is already authenticated, for example, by a trusted gateway, accept

the user single signon information and proceed to step 4 on page 21.2. Obtain the user identity based on one of the following login methods:

v For basic authentication and forms login, obtain the user ID and password.v For certificate login, obtain the certificate distinguished name.

3. Authenticate the user against the Access Manager user registry.

[Global]

[Local] [Remote 1]

Internal Access

Default Values

[Remote N]

Manager Plug-in

Figure 5. Plug-in for Edge Server using model of inheritance


4. Authorize the user against the Access Manager object space.5. Submit single signon information for the user.6. Forward the request to the corresponding Web server.

To execute these authorization steps, the plug-in must consult the configuration filefor configuration information about the request. Each step requires one or moresettings to be retrieved from the osdef.conf configuration file. For example, step 2on page 20 requires the retrieval of the login_method setting.

To retrieve a setting for the request, the plug-in needs to first determine whichdefinition it should retrieve the setting from. It needs to correlate the request witha specific server definition in the configuration file. While the plug-in can enforcesecurity for both reverse and forward proxy requests, the plug-in does not considerwhether the request is a reverse or forward proxy request.

The domain name is the public identifier for the corresponding Web server hostingthe protected resource. In a reverse proxy scenario, this requires the creation ofaliases or public domain names on the plug-in system, as illustrated in Figure 6.

In this configuration, all requests for www.newbooks.com, newbooks.com,newnovels.com, and newpoems.com arrive at the Edge Server proxy and aresecured by the plug-in. Using the domain name as the unique identifier for therequest, the plug-in can now search the configuration file for the server definitionthat matches the domain name.

Consider the following osdef.conf configuration file:[Global]login_method = basic

# Definition 1[Remote: /ESproxy/reverse/newbooks.com]domains = newbooks.com *.newbooks.comlogin_method = formsroute = http://backend1.com

# Definition 2[Remote: /ESproxy/reverse/label2]domains = newnovels.comlogin_method = certificateroute = http://backend2.com

Browser

Internal Gateway

backend2..comHosts newnovels.com

backend3.comHosts newpoems.com

Internet

BrowserEdge Server

newbooks.com

CachingProxy


backend1.comHosts www.newbooks.comand newbooks.com

Web Servers

www.newbooks.com

newpoems.comnewnovels.com

Figure 6. Creation of aliases on a plug-in system

Chapter 4. Understanding the plug-in for Edge Server configuration 21

# Definition 3[Remote: /ESproxy/check_here/this_is_just_a_label]domains = newpoems.comroute = http://backend3.com

Consider the following requests where the plug-in determines the login method,object space location where the user is authorized, and destination Web serverwhere the request is forwarded:v If a user types the following URL, the plug-in matches the request to definition 1

because the domains setting contains the value, *.newbooks.com:http://www.newbooks.com/private.htmlIf the user typed the IP address of www.newbooks.com, the plug-in firstperforms a reverse DNS lookup on the IP address and still matches the requestto definition 1.The login method is forms because it is explicitly set under this definition. Forthe authorization check, the domain name would be replaced with theauthorization string and the URL path would be appended. In this example, theauthorization check for read (r) permission would be performed at/ESproxy/reverse/newbooks.com/private.html. The request is forwarded tobackend1.com because of the route setting.

v If a user types the following URL, the plug-in would match the request todefinition 2 because the domains setting contains the value, newnovels.com:http://IP_address_of_newnovels.com/gifs/private.htmlThe login method is certificate because it is explicitly set under this definition.The authorization check for read (r) permission is performed at/ESproxy/reverse/label2/gifs/private.html. The request is forwarded tobackend2.com because of the route setting.

v If a user types the following URL, the plug-in would match the request todefinition 3 because the domains setting contains the value, newpoems.com:http://newpoems.com/logo.gifThe login method is basic because it is not explicitly set under this definitionand is retrieved from the [Global] definition. The authorization check for read (r)permission is performed at /ESproxy/check_here/this_is_just_a_label/logo.gif. The request is forwarded to backend3.com due to the route setting.

v If a user configures their browser to use Edge Server as a proxy and types thefollowing URL, the plug-in does not find a match for the request and uses the[Global] definition:http://internet.com/mail/logo.gifThe login method is basic. For the authorization check, the default forwardproxy template, /ESproxy/forward/domain/path is used. In this example, theauthorization check for read (r) permission is performed at/ESproxy/forward/internet.com/mail/logo.gif. Since this object might not existin the object space, the effective permission is inherited from the ACL attachedto /ESproxy/forward. The request is automatically forwarded to internet.combecause it was a forward proxy request. However, it is possible to create adefinition in the configuration file that performed an authorization check atanother location in the object space and forwards the internet.com requestelsewhere. The plug-in does not consider if the request is a forward or reverseproxy request. In both configurations, the request is handled in the samemanner.


Object space configuration modelWhen the plug-in performs an authorization check underneath a branch in theAccess Manager object space, it maps the requested resource or URL to the objectspace. For example, in server definition 1, the following mapping is performed forthe authorization check:URL Object: http://www.newbooks.com/private.htmlAccess Manager Object: /ESproxy/reverse/newbooks.com/private.html

In order to apply access control to specific objects using Access Manager ACLs, theobject space must be structured in a manner where there is a direct mappingbetween the set of objects that users request in their URLs and the set of objectsprovided by the Web server. The simplest case is a direct mapping betweenreferenced files in the URLs and actual files on the Web server, as illustrated:Access Manager Object: /ESproxy/reverse/newbooks.com/server files/ESproxy/reverse/newbooks.com/private.html/ESproxy/reverse/newbooks.com/public.html/ESproxy/reverse/newbooks.com/gifs/ESproxy/reverse/newbooks.com/gifs/logo.gif

URL Object: http://www.newbooks.com/server fileshttp://www.newbooks.com/private.htmlhttp://www.newbooks.com/public.htmlhttp://www.newbooks.com/gifshttp://www.newbooks.com/gifs/logo.gif

The sample query_contents utility provides the wesosm utility with the paths ofall files on the Web server. The file information is copied into the object space sothat when the plug-in performs the authorization check, there is a direct mappingbetween the URL objects and server objects.

This model works well if the set of URL objects are always going to be physicalfiles on the destination Web server that the query_contents utility finds. In somecases, the set of URL objects might not correspond directly to physical files on theWeb server. In this case, the query_contents utility can be modified to return thevirtual objects that are served by the Web server as shown:Access Manager Object: /ESproxy/reverse/newbooks.com/virtual objects/ESproxy/reverse/newbooks.com/object1/ESproxy/reverse/newbooks.com/object2/ESproxy/reverse/newbooks.com/object3/ESproxy/reverse/newbooks.com/object3/object3.1

URL Object: http://www.newbooks.com/virtual objectshttp://www.newbooks.com/object1http://www.newbooks.com/object2http://www.newbooks.com/object3http://www.newbooks.com/object3/object3.1

In this scenario, the objects served by the Web server do not correspond directly tophysical files on the Web server. However, the Web server understands what theseobjects are and knows how to retrieve them. As long as the query_contents utilitycan enumerate these virtual objects for the wesosm utility, the plug-in can performauthorization checks on these virtual objects.

The plug-in performs authorization checks by verifying the appropriatepermissions in the Access Manager object space. It maps the URL to the objectspace to determine the exact location to perform the authorization check. In orderto apply ACLs on specific objects secured by the plug-in, it is necessary to ensure


that the set of objects represented in the object space corresponds to the set ofobjects represented in the URL requests for the secured Web server.

Single signon configuration modelThe plug-in supports customizable single signon tokens that are createdunderneath the [SSO] categories of the configuration file as indicated in thefollowing table.

Server definition Description

[SSO] Settings listed under this definition are usedto define single signon tokens. There can bemultiple instances of this definition.

The settings listed in this definition are not related to the settings listed in the[Global], [Local], and [Remote] server definitions. For example, the trust_listsetting, is not valid underneath any server definition in the configuration file.However, by defining the single signon tokens in one place, they can be used asparameters to accept_sso and submit_sso, which are valid underneath the servercategories. The following example shows the definition of an iv-user token whichis needed by two Web servers:[Remote: /ESproxy/reverse/newbooks.com]domains = newbooks.comaccept_sso = myssosubmit_sso = myssoroute = http://backend1.com

[Remote: /ESproxy/reverse/newnovels.com]domains = newnovels.comsubmit_sso = myssoroute = http://backend2.com

[SSO: mysso]name = iv-userformat = <userid>trust_basis = IP_Addresstrust_list = 0.0.0.0/0.0.0.0

In this example, the plug-in checks for the existence of the iv-user token from anyIP address that makes a request to newbooks.com. If the iv-user token is found, itextracts the user ID from the token and authorizes the user. The plug-in alsosubmits the iv-user token to the respective backend server for requests tonewbooks.com and newnovels.com.

Configuration procedure summarizedThe plug-in for Edge Server provides a flexible framework to configure accesscontrol to the protected resources on your Web servers. It allows you to set serverspecific configuration items such as the login method, single signon token, anddestination server. Settings that apply to each server need to only be set in oneplace and settings that are server specific can be set for each respective server.

The general approach to configuring the plug-in is as follows:1. For a reverse proxy configuration, create an alias domain name on the plug-in

machine for each Web server that requires the authorization services.2. Create a corresponding [Remote] server definition for each respective server

and assign the alias domain name to that definition.


3. Set server specific settings underneath the definition for that server and setglobal settings in the [Global] definition of the configuration file. It is sufficientto use the default internal plug-in values for most settings.

4. Run the wesosm utility to generate the object space and set the appropriateACLs in the Access Manager object space for access control to that server.

Always restart the plug-in after making configuration changes. If you are unable todetermine the cause of a configuration error, check the event log file forinformation describing how the plug-in handled the request. Running the UNIXtail -f command on the event log file can help in observing events as they happenin real time. It is easier to determine the cause of the configuration problem afterobserving the event log.



Chapter 5. Deploying the plug-in for Edge Server

This chapter describes an example deployment for the Access Manager Plug-in forEdge Server. This deployment shows an example of a commercial Web site wherevisitor access must be controlled. The example is described in the followingsections:v “Designing the Web site” on page 27v “Configuring the Web site” on page 28

Designing the Web siteIn this section, a complete plug-in for Edge Server configuration for newbooks.comis designed. This Web site allows users to browse and purchase books. Many of thekey features of the plug-in for Edge Server are illustrated in this example. The Website design is divided into the following components:v “Content distribution” on page 27v “Single signon” on page 27

Content distributionIn this design, rather than storing the entire content for the Web site on one Webserver, it is distributed across several Web servers. The Web content is divided intothe following sections:v newbooks.comv catalog.newbooks.comv account.newbooks.comv payment.newbooks.com

The newbooks.com domain contains the greeting page and links to other parts ofthe Web site. The catalog.newbooks.com subdomain contains a repository of all thebooks sold at this Web site. These sections of the Web site do not require accesscontrol and therefore are not protected.

The account.newbooks.com directory contains HTML and Java code that is used tomanage the user’s account. The payment.newbooks.com directory also containsHTML and Java code to receive the user’s payment for books to be purchased.Most of these sections of the Web site are protected. A directory underneathaccount.newbooks.com is used to register new users. This directory is notprotected.

Single signonIn this design, an application running on the Web server hosting theaccount.newbooks.com subdomain requires an encrypted Lightweight Third PartyAuthentication (LTPA) cookie to identify the authenticated user. Anotherapplication running on the Web server hosting the payment.newbooks.comsubdomain requires the HTTP header, App-User, with the user ID in it. It alsorequires basic authentication from the plug-in for Edge Server as the trust basis foraccepting the authenticated user. The plug-in for Edge Server is required toauthenticate itself to this application with the user ID, plugin, and the password,bookworm.


In this example, a relationship has been established with another vendor,newnovels.com, to forward authenticated users through the plug-in for EdgeServer to protected areas of newbooks.com. The gateway at newnovels.com isrequired to authenticate itself to the plug-in for Edge Server by using anauthorization header with the user ID, novelgateway, and the password,bookworm. The gateway places the authenticated user ID in the cookieNovel-User, as illustrated in Figure 7.

Configuring the Web siteTo provide access control for newbooks.com, the plug-in for Edge Server must beconfigured. The configuration begins by defining the global settings in theosdef.conf configuration file as shown in the following example:[Global]# Administrator userid and password needed to run wesosmupdate_admin_userid = sec_masterupdate_admin_password = secret5

# Error message indicating that SSL is requiredrequire_ssl_errorfile = /opt/pdweb-lite/samples/errorpages/require_ssl.htmls

# Form login and logout informationlogin_method = formsform_login_file = http://newbooks.com/pub/login.htmlform_login_errorfile = http://newbooks.com/pub/loginerr.htmlform_logout_url = /pub/logout.html

# Change password informationform_chgpasswd_file = http://newbooks.com/pub/chgpasswd.htmlform_chgpasswd_submit_url = /pub/chgpasswdform_chgpasswd_response_url = /pub/passwdchanged.html

# Single signon tokens to look foraccept_sso = NovelSSO

The [Global] definition in the configuration file specifies settings that apply toevery request handled by the plug-in for Edge Server. In this configuration, theadministrator user ID and password is provided so that the wesosm utility cancreate and update the object space. Also, if a request requires a secure connectionand one is not provided, the specified error page is returned to the user. However,if possible, the browser is automatically redirected to the secure site.

Browser

Internal Gateway

backend2.newbooks.comHosts account.newbooks.com

backend3.newbooks.comHosts payment.newbooks.com

Internet

Browser

Gatewaynewnovels.com Novel-User

Edge Servernewbooks.com

CachingProxy


App-User

LTPACookie

backend1.newbooks.comHosts newbooks.com and

catalog.newbooks.com

Web Servers

Figure 7. Web site design for newbooks.com


This configuration also specifies the login method as forms and lists the loginforms. The login forms can be retrieved from a remote Web server (begins withhttp) or can be retrieved from the local file system. If the form has references toimages in it, the URL links in the forms for these images should contain the fullURL of the images, such as the following:

http://newbooks.com/pub/gifs/banner.gif

The user is logged out when the requested path of the URL matches the pathspecified for the logout URL. Also, as the configuration shows, a change passwordform is sent to authenticated users when their passwords expire.

Single signon users are accepted from the gateway at newnovels.com, using theNovelSSO single signon definition. This single signon definition must be defined inthe configuration file.

The [Local] definition in the configuration file specifies settings that apply toobjects on the file system managed by the Edge Server caching proxy. There shouldonly be one of these definitions in the configuration file. This server definition wascreated by the configuration tool and is similar to the following:[Local: /ESproxy/bookproxy.com]domains = bookproxy.comquery_command = http://bookproxy.com/cgi-bin/query_contents?dirlist=/login_method = basic

In this example, bookproxy.com is the primary domain name of the machine thatthe Edge Server caching proxy is running on. The alias newbooks.com is anotherdomain name (with its associated IP address) assigned to the same machine. Theplug-in for Edge Server differentiates between requests for objects belonging to theEdge Server caching proxy and objects belonging to newbooks.com by matchingthe requested domain name with a server definition in the configuration file. Thedomains setting indicates the domains to which a server definition applies.

The [Remote] definitions in the configuration file specify settings that apply toexternal Web servers. There is no limit on the number of server definitions thatyou can have. For this example, the following definition would be appropriate fornewbooks.com:[Remote: /ESproxy/reverse/newbooks.com]domains = newbooks.com www.newbooks.com

# Query command to create object spacequery_command = http://backend1.newbooks.com/cgi-bin/query_contents?dirlist=/home

# Server to map requestsroute = http://backend1.newbooks.com/home

The following subdomain definitions are defined for the other sections of the Website:[Remote: /ESproxy/reverse/catalog.newbooks.com]domains = catalog.newbooks.comquery_command = http://backend1.newbooks.com/cgi-bin/query_contents?dirlist=/catalogroute = http://backend1.newbooks.com/catalog

[Remote: /ESproxy/reverse/account.newbooks.com]domains = account.newbooks.comquery_command = http://backend2.newbooks.com/cgi-bin/query_contents?dirlist=/require_ssl = yessubmit_sso = LTPA-COOKIEroute = https://backend2.newbooks.com

Chapter 5. Deploying the plug-in for Edge Server 29

[Remote: /ESproxy/reverse/payment.newbooks.com]domains = payment.newbooks.comquery_command = http://backend3.newbooks.com/cgi-bin/query_contents?dirlist=/require_ssl = yessubmit_sso = PayAppSSO PayAppAuthroute = https://backend3.newbooks.com

These server definitions specify the single signon tokens to submit to each Webserver that requires one. The definitions also tell the plug-in for Edge Server tomap the URL to the corresponding Web server hosting the requested content. Ifanother routing module is to be used in place of the plug-in for Edge Server URLmapping, simply delete all references to the route keyword from the configurationfile.

The [SSO] definitions in the configuration file define single signon tokens that caneither be accepted or submitted as shown:[SSO: PayAppSSO]type = headername = App-Userformat = “<userid>”

[SSO: PayAppAuth]type = auth_headerformat = plugin:bookworm

[SSO: NovelSSO]type = cookiename = Novel-Userformat = “<userid>”trust_basis = basic_authtrust_list = novelgateway:bookworm

After you create single signon definitions, they can be supplied as options to theaccept_sso and submit_sso keywords. Single signon requirements in this exampleare now satisfied.


Chapter 6. Creating a Cross-domain Authentication Service

This chapter explains how to create a Cross-domain Authentication Service (CDAS)shared library, which enables custom handling and processing of clientauthentication information. It also describes how to configure the plug-in for EdgeServer to use the custom shared library for authentication.

A demonstration CDAS library is packaged with the plug-in for Edge Server thatillustrates the implementation of the CDAS functions. You can recompile andmodify this demonstration library to create a custom shared library.

This chapter includes the following sections:v “Authentication models”v “Building a custom shared library” on page 33v “Configuring the plug-in for Edge Server to use a custom shared library” on

page 37v “CDAS core and utility functions” on page 40v “CDAS API core function reference” on page 40

Authentication modelsThis section describes two types of CDAS authentication models:v “Single authentication model” on page 31v “Dispatched authentication model” on page 32

When IBM Tivoli Access Manager plug-in for Edge Server receives a client request,it passes the appropriate authentication data to the custom shared library. Ratherthan authenticating the user against the Access Manager user registry, the CDASshared library authenticates the user against an alternate user registry using anexternal authentication mechanism. Ultimately, the CDAS returns an AccessManager identity to the plug-in for authorization against the Access Managerobject space.

If you create a custom CDAS shared library to handle user name and passwordauthentication, the client authentication data must contain the user’s name andpassword. However, if the shared library is written to handle certificateauthentication, the client authentication data must contain the client’s certificate.

Single authentication modelFigure 8 on page 32 illustrates an example of single authentication CDASfunctionality.


Steps illustrated in Figure 8 are as follows:1. The client supplies authentication information to the plug-in.2. In this example, the plug-in is configured to use a custom CDAS shared library

for authentication.The CDAS shared library could authenticate this user internally and pass theresulting Access Manager identity back to the plug-in (step 4). For example, theshared library could accept a digital certificate, modify the Distinguished Name(DN) data, and return the modified DN as the Access Manager identity.

3. The custom shared library could instead send the data to an externalauthentication service that performs its own authentication of the client,perhaps using a third-party (legacy) user registry.

4. The CDAS returns one of the following status codes to the plug-in:v A successful status code (indicating a successful authentication attempt) and

an Access Manager identity.v An unsuccessful status code, indicating a failed authentication attempt.

In addition, the custom CDAS can be written to provide extended attributedata to the plug-in (for inclusion in the user credential).

5. If a successful status code is returned, the plug-in tries to match the identitywith an entry in the Access Manager user registry. If a match is found, theplug-in treats the client as authenticated. Otherwise, it treats the client asunauthorized.

A successful authentication results in an Access Manager credential for the user.Any extended attribute data is included in the credential and can be extracted laterfor appropriate use. The credential enables the user to participate in the AccessManager secure domain.

Dispatched authentication modelYou can create a CDAS module that dispatches authentication requests to otherCDAS modules based on a correlating parameter passed in from the plug-in. Thedispatching CDAS module does not perform any authentication itself, butdelegates the authentication and creation of extended attributes to the other CDASmodules and passes the returned identity from the CDAS modules back to theplug-in. Using this model, the plug-in can authenticate against different userregistries, based on the URL.

Client

ResourceManager

ExternalAuthentication

Service

authenticationinformation

identity

1

Access Manager Plug-in

Custom CDAS SharedLibrary

authninfo

2

3

4

UserRegistry

ExternalRegistry

5

Figure 8. Example CDAS authentication model


Figure 9 illustrates an example of the CDAS dispatched functionality.

Steps illustrated in Figure 9 are as follows:1. The client supplies authentication information to the plug-in.2. In this example, the plug-in is configured to use a custom CDAS shared library

to handle this type of authenticated data.3. Based on a parameter passed in from the plug-in, the CDAS module dispatches

the authentication to the appropriate CDAS module for the request.The CDAS shared library could authenticate this user internally and pass theresulting Access Manager identity back to the plug-in. For example, the sharedlibrary could accept a digital certificate, modify the Distinguished Name (DN)data, and return the modified DN as the Access Manager identity.

4. The custom shared library could instead send the data to an externalauthentication service that performs its own authentication of the client,perhaps using a third-party (legacy) user registry.

5. The appropriate CDAS module returns the Access Manager identity andextended attributes to the CDAS dispatcher.

6. The CDAS dispatcher module returns one of the following status codes to theplug-in:v A successful status code (indicating a successful authentication attempt) and

an Access Manager identity.v An unsuccessful status code, indicating a failed authentication attempt.

In addition, the custom CDAS can be written to provide extended attributedata to the plug-in (for inclusion in the user credential).

7. If a successful status code is returned, the plug-in tries to match the identitywith an entry in the Access Manager user registry. If a match is found, theplug-in treats the client as authenticated. Otherwise, it treats the client asunauthorized.

Building a custom shared libraryBefore you build a custom CDAS library, you must determine how you want thespecific authentication and mapping service to operate in your secure domain. Usethe resources of the demonstration CDAS to implement your custom CDAS library.

This section contains the following topics:

Client

authenticationinformation

1

Access Manager Plug-in

3

ResourceManager

authninfo

2

4External

AuthenticationService

ExternalRegistry

UserRegistry

5CDAS

Dispatcher

Custom CDASShared Library

identity6

7

Custom CDASShared Library

Figure 9. Example dispatched authentication model

Chapter 6. Creating a Cross-domain Authentication Service 33

v “CDAS application development kit”v “Programming the custom shared library”v “User authentication data” on page 35v “Returning the client identity” on page 36v “Compiling the custom shared library” on page 36

CDAS application development kitThe CDAS application development kit (ADK) includes the following components:v API library (utility functions)v API header filesv Example CDAS source file (for demonstration only)v Makefile

The CDAS ADK files are located in one of the following directories:v On UNIX systems:

/opt/pdweb-lite/samples/cdas_adk

v On Windows systems:install_dir\samples\cdas_adk

The ADK components are contained in the following subdirectories.

Directory Contents

include This directory contains the C header files.See “Header files”.

lib This directory contains the static CDAS API utility library:- On UNIX systems: libpdxauthn.a- On Windows systems: pdxauthn.lib

example The example directory contains:- Source file (xauthn.c)- Makefile- A pre-built platform-specific example shared library todemonstrate a functional CDAS

Header filesThe following header files are contained in the include directory.

Files Contents

pdxauthn.h Definition of function prototypes, client identity, and error codesused for authentication CDAS API functions

xnvlist.h User authentication data structure utility functions

xattr.h User extended attributes data structure utility functions

Programming the custom shared libraryA custom CDAS shared library must contain the following APIs:v xauthn_initialize

For more information, see “Initialization: xauthn_initialize” on page 35v xauthn_shutdown

For more information, see “Shutdown: xauthn_shutdown” on page 35v xauthn_authenticate


For more information, see “Authentication: xauthn_authenticate” on page 35v xauthn_change_password

For more information, see “Password change: xauthn_change_password” onpage 35

Note: These API functions are described in detail in the “CDAS API core functionreference” on page 40.

Initialization: xauthn_initializeThe plug-in loads the CDAS shared library and initializes it by callingxauthn_initialize.

This function contains the argc and argv options. These options contain the valuesspecified in the osdef.conf configuration file. Unlike the C language argv, theargv[0] array entry is the first option.

Shutdown: xauthn_shutdownDuring shutdown, the plug-in calls the xauthn_shutdown function to stop theCDAS shared library process.

The xauthn_shutdown function is called with the same argc and argv options thatwere passed to the xauthn_initialize function when the shared library was firstinitialized.

Authentication: xauthn_authenticateAfter the CDAS shared library is configured and a request is received, the plug-inpasses the user’s information to the shared library through thexauthn_authenticate function.

User authentication information is passed to this function in a name/value datalist (xnvlist_t). The content of the name/value data list can vary and is specific tothe configured authentication method.

The xauthn_authenticate function performs the application-specific authenticationprocess based on the authentication information found in the data list and returnsthe resulting client identity (xauthn_identity_t) to the plug-in.

It is important to note that the client identity returned through this function cancontain extended attribute data.

Password change: xauthn_change_passwordThis function allows the user to make changes to the account password that isstored in the alternate user registry. Only the user name and passwordauthentication method supports this function. If the external authenticationmechanism does not support password changes, this function returns:XAUTHN_S_UNSUPPORTED_AUTHN_METHOD

User authentication information is passed to this function in a name/value datalist (xnvlist_t). The data list contains the user’s name, the old password, and thenew password.

User authentication dataThe plug-in can pass a variety of client authentication information to the sharedlibrary. The information is passed using a name/value list format, where the nameis an identifier that specifies the value type.


The information is stored in the xnvlist_t data type. Values can be accessed byusing the utility function xnvlist_get.

The following table lists the user authentication options that the plug-in passes tothe CDAS module.

Authentication method Name Value

User name/Password xauthn_usernamexauthn_passwordxauthn_new_passwordxauthn_ipaddrxauthn_browser_infoxauthn_extended_handlexauthn_extended_parameter

- User name- User password- User new password- User IP address- Browser information- Caching proxy handle- Configuration file option

Certificate xauthn_cert_dnxauthn_ipaddrxauthn_browser_infoxauthn_extended_handlexauthn_extended_parameter

- Certificate’s DN- User IP address- Browser information- Caching proxy handle- Configuration file option

Single signon xauthn_ipaddrxauthn_browser_info″Request-URI″″Request-Headers″xauthn_extended_handlexauthn_extended_parameter

- User IP address- Browser information- Request URL- Request Headers- Caching proxy handle- Configuration file option

While the CDAS implementation for the plug-in for Edge Server is similar toWebSEAL, there are minor differences. These are as follows:v xauthn_extended_handle and xauthn_extended_parameter are options that the

plug-in for Edge Server passes to the CDAS module.v xauthn_extended_handle provides the CDAS module with the caching proxy’s

handle necessary to extract additional HTTP headers using the caching proxy’sAPI.

v xauthn_extended_parameter provides the CDAS module with a correlatingoption from the osdef.conf configuration file.

Returning the client identityThe CDAS shared library is required to return the resulting client identity back tothe plug-in. The client identity is defined by the xauthn_identity_t data structure.

For more information, see the IBM Tivoli Access Manager WebSEAL Developer’sGuide.

Compiling the custom shared libraryThe source code for the CDAS demonstration library is located in one of thefollowing directories:v For UNIX systems:

/opt/pdweb-lite/samples/cdas_adk/example

v For Windows systems:install_dir\samples\cdas_adk\example

The source files xauthn.c and xauthn.h are used to create the CDAS shared object.


To customize and compile the custom CDAS shared library, do the following:1. Customize the source files to implement the logic necessary to authenticate

users to your user registry.2. To recompile the code, use one of the following makefiles:

v For UNIX systems:/opt/pdweb-lite/samples/cdas_adk/example/Makefile.in

v For Windows systems:install_dir\samples\cdas_adk\example\Makefile.in

Instructions for compiling on each platform are included in Makefile.in. Themakefile assumes that your compiler and link commands can be invoked fromthe current directory and are already in the system’s path.

3. After the customized CDAS module is successfully built, the resulting sharedlibrary is named as follows:v For AIX systems: libwescdas.av For Linux systems: libwescdas.sov For Solaris systems: libwescdas.sov For Windows systems: wescdas.dll

4. Stop the plug-in and copy the new CDAS module over the existing CDASmodule that is located in one of the following directories:v For UNIX systems:

/opt/pdweb-lite/lib

v For Windows systems: install_dir\bin

Note: For more information on starting and stopping the plug-in, see “Startingand stopping the plug-in for Edge Server” on page 13.

Configuring the plug-in for Edge Server to use a custom shared libraryThis section discusses the specific configuration steps that you must perform sothat the plug-in for Edge Server can use the CDAS interface.

This section contains the following topics:v “Configuring a custom shared library” on page 37v “Custom shared library configuration scenario”v “Configuring the demonstration library” on page 38v “Loading the custom shared library” on page 39

Configuring a custom shared libraryTo configure a custom CDAS shared library, modify the configuration optionsincluded in the osdef.conf file. For more information about osdef.confconfiguration options, see Appendix B, “Object space definition configuration filereference” on page 51.

Custom shared library configuration scenarioThe following scenario illustrates the use of the configuration options. The scenarioshows three Web sites using CDAS. The first site uses forms as the login method,but the second site uses certificates. A third Web site uses CDAS for single signon,but uses Access Manager for basic authentication.


[Global]...cdas_loaded = yescdas_init_parameter = ldap /etc/ldap.confcdas_init_parameter = cert /etc/cert.conf

[Remote: /ESproxy/reverse/newnovels.com]domains = newnovels.comlogin_method = formscdas_enabled = yescdas_auth_parameter = ldap

[Remote: /ESproxy/reverse/newpoems.com]domains = newpoems.comlogin_method = certificatecdas_enabled = yescdas_auth_parameter = cert

[Remote: /ESproxy/reverse/newbooks.com]domains = newbooks.comlogin_method = basicaccept_sso = CDAS-MODULE

In this scenario, xauthn_init is called twice with the argv[0] = ldap, argv[1] =/etc/ldap.conf initialization options on the first call and the argv[0] = cert, argv[1] =/etc/cert/conf initialization options on the second call. A user accessingnewnovels.com is authenticated with xauthn_extended_parameter = ldap, but auser accessing newpoems.com is authenticated with xauthn_extended_parameter =cert. The CDAS module is also invoked to detect pre-authenticated users accessingnewbooks.com.

The CDAS shared library can simultaneously support multiple user repositoriesand perform a switch based on the xauthn_extended_parameter value it receives.Multiple initializations can also be performed based on the argv[0] option,allowing one CDAS shared library to perform the functionality that wouldotherwise require multiple CDAS libraries.

Configuring the demonstration libraryTo configure the CDAS demonstration library, modify the configuration options inthe osdef.conf file. For example, consider the options shown in Figure 10.

Note: For the demonstration module, basic _auth and cert are valid values forcdas_auth_parameter.

In this example, the demonstration module is configured with a user ID andpassword, the distinguished name of the corresponding Access Manager user, andthe distinguished name of a certificate. The arguments specified by thecdas_init_parameter are passed to the demonstration module when thexauthn_initialize function is called. The following values are passed to thexauthn_initialize routine:

[Global]...cdas_loaded=yescdas_init_parameter=demouser userid demopassword password democertn CertDN validpddn validpdDN

[Local]cdas_enabled=yescdas_auth_parameter=basic_auth

Figure 10. Example of configuration options in osdef.conf


argc = 8argv[0] = demouserargv[1] = useridargv[2] = demopasswordargv[3] = passwordargv[4] = democertdnargv[5] = CertDNargv[6] = validpddnargv[7] = validpdDN

Authentication is performed with the xauthn_authenticate function when aprotected resource on the local Web server is accessed. The sample module checksthe value of xauthn_extended_parameter when the xauthn_authenticate functionis called. If basic_auth is passed in, the user ID and password passed in arechecked against the user ID and password that were passed in at initializationtime. If cert is passed in, then the CertDN passed in is checked against the CertDNthat was passed in at initialization time. If authentication is successful, the validAccess Manager distinguished name is returned to the plug-in for authorization.

Loading the custom shared libraryThe CDAS shared library is loaded during the initialization of the plug-in. TheCDAS library file can be found at one of the following locations:v For UNIX systems:

/opt/pdweb-lite/lib/libwescdas.ext

where ext is one of the following:– For AIX systems: a– For Linux systems: so– For Solaris systems: so

v For Windows systems:install_dir\bin\wescdas.dll

If you want the plug-in to use the packaged demonstration CDAS library, do oneof the following:v For UNIX systems, replace the libwescdas.ext file with the libcdasdemo.ext file,

found at the following location:/opt/pdweb-lite/lib/libcdasdemo.ext

where ext is one of the following:– For AIX systems: a– For Linux systems: so– For Solaris systems: so

v For Windows systems, replace the wescdas.dll file with the cdasdemo.dll file,found at the following location:install_dir\bin\cdasdemo.dll

If you want the plug-in to use a custom CDAS shared library, do one of thefollowing:v For UNIX systems, replace the libwescdas.ext file with the custom CDAS

shared library file where ext is one of the following:– For AIX systems: a– For Linux systems: so– For Solaris systems: so


v For Windows systems, replace the wescdas.dll file with the custom CDASshared library file.

Note: If a problem occurs loading your custom CDAS shared library, you canrevert back to the demonstration CDAS library.

CDAS core and utility functionsThe following core API functions must be implemented in your custom CDASshared library:v xauthn_initialize

v xauthn_shutdown

v xauthn_authenticate

v xauthn_change_password

The CDAS utility library is located in the one of the following directories:v For UNIX systems:

/opt/pdweb-lite/samples/cdas_adk/lib

v For Windows systems:install_dir\samples\cdas_adk\lib

The static library file, libpdxauthn.a for AIX, Linux, and Solaris or pdxauthn.libfor Windows, contains the utility functions. To use these functions, you must linkyour custom shared library to this file.

The following utility functions facilitate data manipulation:v xnvlist_get

v xattr_malloc

v xattr_free

v xattr_get

v xattr_set

v xattr_dup

The xnvlist_get function retrieves the authentication data passed in from theplug-in. The remaining utilities allow you to construct extended attributes for theAccess Manager identity.

For more information, see the “CDAS API core function reference” on page 40. Formore information about utility functions, see the IBM Tivoli Access ManagerWebSEAL Developer’s Reference.

CDAS API core function referenceThis section lists the following core API functions used to implement your CDASshared library:v xauthn_authenticate

v xauthn_change_password

v xauthn_initialize

v xauthn_shutdown


xauthn_authenticatePerforms the CDAS authentication.

Contextxauthn_status_txauthn_authenticate(

xnvlist_t *authnInfo,xauthn_identity_t *ident

);

DescriptionThe plug-in calls this interface to perform the customer-specific externalauthentication. Client authentication information is passed by the plug-in throughthe input argument authnInfo.

Refer to “User authentication data” on page 35 for the list of authentication optionsthat authnInfo can contain.

Based on the authentication information, this function implements the specificauthentication mechanism and stores the resulting client information in ident. Thisinformation is then returned to the plug-in.

It is important to note that the client identity ident can contain additional userinformation.

OptionsInput

authnInfoThe authnInfo option is a name/value data list containing client authenticationinformation.

Input/Output

identThe ident option contains the authenticated user information.

Return CodesIf successful, the function returns XAUTHN_S_COMPLETE.

Possible error codes can be found in the pdxauthn.h header file.


xauthn_change_passwordPerforms the CDAS password change.

Contextxauthn_status_txauthn_change_password(

xnvlist_t *authnInfo);

DescriptionThe plug-in calls this interface to implement a custom password changemechanism. This interface is supported only for the user name and passwordauthentication mechanism. Client password change information is passed by theplug-in through the input argument authnInfo.

Refer to “User authentication data” on page 35 for the list of authentication datathat authnInfo can contain.

OptionsInput

authnInfoThe authnInfo option is a name/value data list containing client authenticationinformation.


XAUTHN_S_UNSUPPORTED_AUTHN_METHOD is returned if the externalauthentication process does not support password changes.



xauthn_initializeInitializes the CDAS shared library.

Contextxauthn_status_txauthn_initialize(

int argc,const char **argv

);

DescriptionUse this function to initialize an authentication shared library. The input optionsargc and argv are built from options specified for cdas_init_parameter in theosdef.conf configuration file. The following example definition illustrates theinitialization of the sample CDAS shared library:cdas_init_parameter = -dbms sys.db

In the example, xauthn_initialize is called with an argc value of 2. The argv arraycontains the following values:argv[0] = “-dbms”argv[1] = “sys.db”

Do not modify input options.

OptionsInput

argcThe number of arguments contained in the argv array.

argvThe string arguments passed in the service definition for this service instance.




xauthn_shutdownShuts down the CDAS shared library.

Contextxauthn_status_txauthn_shutdown(

int argc,const char **argv

);

DescriptionDuring normal shutdown, the plug-in calls this interface to perform any shutdown processes that might be required by the custom environment. The inputoptions argc and argv are built from the options specified with thecdas_init_parameter directive in the osdef.conf configuration file. The followingexample illustrates the termination of the sample CDAS shared library:cdas_init_parameter = -dbms sys.db

In the example, xauthn_shutdown is called with an argc value of 2. The argv arraycontains the following values:argv[0] = “-dbms”argv[1] = “sys.db”

OptionsInput

argcThe number of arguments contained in the argv array.

argvThe string arguments passed in the service definition for this service instance.




Chapter 7. Removing the plug-in for Edge Server

This chapter describes how to unconfigure and remove the plug-in for Edge Server.To unconfigure and remove the plug-in, complete the instructions in one of thefollowing sections:v “Removing the plug-in for Edge Server on AIX” on page 45v “Removing the plug-in for Edge Server on Linux” on page 45v “Removing the plug-in for Edge Server on Solaris” on page 46v “Removing the plug-in for Edge Server on Windows” on page 47

Removing the plug-in for Edge Server on AIXRemoval of the plug-in for Edge Server on AIX is a two-part process. You mustfirst unconfigure the plug-in package and then remove it.

To unconfigure the plug-in package on AIX, do the following:1. Log in as root.2. Enter the following command:

wslconfig.sh -u

3. Enter the user ID for the IBM Tivoli Access Manager administrative user. Youcan press Enter to accept the default user of sec_master.A prompt appears requesting the password for the Access Manageradministrator.

4. Enter the password for sec_master.A series of status messages appear. The plug-in for Edge Server logs in to theAccess Manager policy server and unconfigures itself.The unconfiguration completes and the wslconfig utility exits.

To remove the plug-in package and any dependent software on AIX, enter thefollowing:installp -u -g PDPlgES

Note: Use the –g option only if you want dependent software for the specifiedpackage removed.

The plug-in for Edge Server files are removed. The installp utility exits. Removalof the plug-in for Edge Server on AIX is complete.

If you want to remove prerequisite Access Manager components, follow theremoval instructions in the IBM Tivoli Access Manager Base Installation Guide.

Removing the plug-in for Edge Server on LinuxRemoval of the plug-in for Edge Server on Linux is a two-part process. You mustfirst unconfigure the plug-in package and then remove it.

To unconfigure the plug-in on Linux, do the following:1. Log in as root.2. Enter the following command:


wslconfig.sh -u

3. Enter the user ID for the Access Manager administrative user. You can pressEnter to accept the default user of sec_master.A prompt appears requesting the password for the Access Manageradministrator.


To remove the plug-in files on Linux, enter the following command:rpm -e PDPlgES-PD

The plug-in for Edge Server files are removed. The rpm utility exits. Removal ofthe plug-in for Edge Server on Linux is complete.

If you want to remove the Access Manager runtime environment or other AccessManager components, follow the instructions in the IBM Tivoli Access Manager BaseInstallation Guide.

Removing the plug-in for Edge Server on SolarisRemoval of the plug-in for Edge Server on Solaris is a two-part process. You mustfirst unconfigure the plug-in package and then remove it.

To unconfigure the plug-in on Solaris, do the following:1. Log in as root.2. Enter the following command:

wslconfig.sh -u



To remove the plug-in files on Solaris, enter the following:pkgrm PDPlgES

The plug-in for Edge Server files are removed. The pkgrm utility exits. Removal ofthe plug-in for Edge Server on Solaris is complete.



Removing the plug-in for Edge Server on WindowsRemoval of the plug-in for Edge Server on Windows is a two-part process. Youmust first unconfigure the plug-in package and then remove it.

To unconfigure the plug-in on Windows, do the following:1. Log in as root.2. Enter the following command:

wslconfig -u



To remove the plug-in files on Windows, do the following:1. Select Start → Settings → Control Panel. Click Add/Remove Programs. The

Add/Remove Programs dialog is displayed, listing all installed software.2. Select Access Manager Plug-in for Edge Server. Click Add/Remove. The

Choose Language Setup dialog is displayed.3. Select the language that you want to use for the removal process and click OK.4. From the Confirm Component Removal message box, click Yes. The plug-in for

Edge Server files are removed.5. Click OK to exit the program.

Removal of the plug-in for Edge Server on Windows is complete.


Chapter 7. Removing the plug-in for Edge Server 47


Appendix A. Base configuration file reference

The ibmwesas.conf file contains settings used to initialize the plug-in. Thesesettings include Access Manager configuration settings and the LTPA & WebSEALFail Over cookie module configuration settings. Additional configuration isavailable through the object space definition configuration file. Only settingsrequiring user modification have been listed in the following table. All othersettings are properly set by the configuration tool and generally do not requireuser modification.

Option Description

LTPA_Cookie_Enabled Indicates whether the LTPA cookie module isinitialized using the key file and the key filepassword. The default value is no.

LTPA_Cookie_Keyfile Indicates the LTPA key file containing the cipherkeys used for encryption and decryption. Thisfile can be generated by WebSphere ApplicationServer for single signon between the plug-in andserver.

LTPA_Cookie_Keyfile_Password Indicates the password needed to access theLTPA key file.

LTPA_Cookie_TTL Indicates the idle expiration period for an LTPAcookie that is not refreshed by the plug-in. Thedefault value is 20 minutes.

LTPA_Cookie_Validation Indicates whether an LTPA cookie’s signature isvalidated for increased security when the plug-indecrypts the cookie. Note that this validation canbe more CPU intensive than simply decryptingthe cookie. The default value is yes.

WebSEAL_Cookie_Enabled Indicates whether the WebSEAL Fail Over cookiemodule is initialized using the key file and thekey file label. The default value is no.

WebSEAL_Cookie_Keyfile Indicates the WebSEAL Fail Over cookie key filecontaining the cipher keys used for encryptionand decryption. This key file is generated duringthe configuration of the plug-in.

WebSEAL_Cookie_Keylabel Indicates the label used to extract the cipher keysfrom the WebSEAL Fail Over cookie key file.

WebSEAL_Cookie_TTL Indicates the idle expiration period for aWebSEAL Fail Over cookie that is not refreshedby the plug-in. The default value is 20 minutes.

ObjectSpace_File Indicates the location of the object spacedefinition configuration file. This file tells theplug-in which branch of the Access Managerobject space is used for authorization, based onthe domain name specified in the URL. This filealso specifies domain specific configurationsettings.


Option Description

UserMap_File Indicates the location of the user mapping file.This file tells the plug-in how to map a genericuser ID or certificate distinguished name to anAccess Manager user. This file is used todetermine credentials for certificate users andusers who are authenticated before reaching theplug-in.


Appendix B. Object space definition configuration filereference

This appendix provides reference information on the object space definitionconfiguration file and includes the following sections:v “Server definitions”v “Single signon definitions” on page 59

Server definitionsThe osdef.conf file defines a mapping between protected objects (URLs) and theAccess Manager object space. Settings for protected Web servers are organized intoserver definitions. Within each server definition, server specific settings such as thedomain, login method, the branch of the object space that should be used toperform authorization checks against users, and other domain specific settings areconfigured.

Option Description

Object space (wesosm only)

update_objectspace Indicates whether this instance of the plug-inis responsible for updating the AccessManager object space with each Web server’sfile system information. The default value isyes.

update_admin_userid Indicates the Access Manager administratoruser ID that is required to modify the objectspace.

update_admin_password Indicates the Access Manager administratorpassword that is required to modify the objectspace.

query_command Indicates the HTTP request issued to getobject space information. The format of thedata returned by this request should conformto the WebSEAL query_contents utility.

query_authentication Indicates the HTTP authorization headerparameter passed to the Web server hostingquery_contents. If this option is not specified,no authorization header is sent.

query_interval Indicates the rate at which the object spaceunderneath this branch is updated. If thevalue is set to 0, no updates are performed tothis branch of the Access Manager objectspace. The default value is 1440 minutes (1day).

query_files Indicates whether the files in each directoryare also queried into the Access Managerobject space. If you intend to attach ACLs onlyto directories, then there is no need for AccessManager to store the Web files in the objectspace. The default value is no.


Option Description

query_depth Indicates the depth of subdirectories that isqueried into the Access Manager object space.Since the object space is stored in theauthorization database, it is beneficial not tostore unnecessary file system information inthis database. It is sufficient to store just theobjects in the Web space that should haveACLs attached to them. Setting this value to 0disables depth constraints for this branch inthe object space. The default value is 0.

query_removal Indicates whether unrecognized or unknownentries are removed from the object space. Ifenabled, all existing entries underneath thisbranch that are not found on the Web server,are removed from the object space. Thedefault value is yes.

Object space (wesosm and plug-in)

objectspace_branch_reverse Indicates the object space branch under whichauthorization requests take place for reverseproxy requests not explicitly defined in thisfile. The default value is /reverse.

objectspace_branch_forward Indicates the object space branch under whichauthorization requests take place for forwardproxy requests not explicitly defined in thisfile. The default value is /forward.

objectspace_filesystem_type Indicates the type of file system that thecontent Web server runs on. This settingdetermines how each URL is mapped to anACL string to authorize the user. The defaultvalue is unix.

File system types:

v unix - Case sensitive UNIX file system

v win32 - Case insensitive WIN32 file system

General

domains Indicates the list of domains for which aserver definition applies to. If the domainname in a requested URL matches any of thespecified domain names, then theconfiguration settings for the request areretrieved from that server definition.


Option Description

login_method Indicates the login method for this domain.The login method can be associated with aspecific device profile (WebSphere EveryPlaceSuite only). If no device is specified, alldevices use the same login method. Thedefault value is basic.

Login methods:

v none - The user is not required to login.

v basic - The user logs in using basicauthentication.

v forms - The user logs in using a form.

v certificate - The user logs in using a clientcertificate.

Syntax: login method [device profile list]

reverse_dns_lookup If a URL contains an IP address or incompletedomain name, this option tells the plug-in toperform a reverse DNS look up to determinethe fully qualified domain name and makeauthorization decisions based on theexpanded name. This option is valid only inthe [Global] section of this file. The defaultvalue is yes.

User information

realm Indicates the realm to append to each user IDbefore authenticating the user. For example, ifthe realm is bank_a, then user joe isauthenticated as joe@bank_a. Since AccessManager uses a single name space for all userIDs, it might be necessary to create user IDs inAccess Manager with realms appended tothem. This way, identical userids belonging todifferent domains can coexist in AccessManager’s user registry (example: joe@bank_a,joe@bank_b).

Error pages

require_ssl_errorfile If a domain requires an SSL connection, andthe established connection is not SSL, then thiserror is returned to the user.

require_cert_errorfile If a domain requires a certificate, and one isnot provided by the user’s browser, then thiserror is returned to the user.

Form login

form_login_file Indicates the form login file used forauthentication. This file can exist locally, orexist as a remote file specified in a URL. If thisoption is unspecified, then form login is notused for this domain. Form login can beassociated with a specific device profile. If nodevice is specified, then all devices will usethe same form.

Syntax: local path | URL [device profile list]

Appendix B. Object space definition configuration file reference 53

Option Description

form_login_errorfile Indicates the form error file sent when a userfails form authentication. This file can beidentical to the login file with the exception ofan error message indicating that the userfailed to login.


form_logout_file Indicates the form logout file sent when a usersubmits the logout URL. This file can containa message telling the user that the session hasended. If unspecified, the request passesthrough to the backend server.


form_logout_url Indicates the form logout URL submitted bythe user to logout. The plug-in deletes theuser’s session information when the usermakes a request that matches this URL.

Syntax: URL [device profile list]

form_type Indicates the form MIME content type,specifying the format of the form file. Aspecial type can be required for wirelessdevices. If no type is specified, then text/htmlis assumed.

Syntax: type [device profile list]

form_session_size Indicates the maximum number of users thatcan be simultaneously logged in using formlogin. This option is valid only in the [Global]section of this file. The default value is 10000users.

form_session_timeout Indicates the amount of time that a user canremain idle and not submit a request whenlogged in using form login. After this timeoutperiod, the user is required to login again. Thedefault value is 20 minutes.

form_signature_login A form signature is a hidden attribute to valueassignment in a form. If the plug-in receives aform submission that includes this assignmentwhen forms is selected as the login method, itextracts the user ID and password from theform to authenticate the user. Using thismethod for form login, the plug-in canauthenticate a user even if the user had notpreviously tried to access a protected Webpage. Note that if this option is specified, thesignature must be found in the form,otherwise if unspecified, no form signature ischecked.

Syntax: name=value


Option Description

form_ssl_security Indicates the type of security used for secureform login. When form login is used over asecure connection, the user ID and passwordis stored locally and associated with a securesession ID. The default value is ssl_sessionId.

Form login security options:

v ssl_sessionId - The SSL session ID isassociated with the user ID and password.

v cookie_sessionId - A transientundecipherable value, stored in a sessioncookie, is associated with the user ID andpassword.

form_client_validation Indicates whether a user’s IP address isallowed to change when the user authenticatesusing form login. If enabled, the user’s IPaddress is verified for the duration of the formlogin session. The default value is yes.

form_fieldname_postdata Indicates the hidden field name inauthentication form which stores contents ofsaved POST data. The plug-in retrieves savedPOST data from this field when a form issubmitted for authentication. The defaultvalue is PostCacheData.

form_fieldvalue_postdata Indicates hidden field value in authenticationform, which the plug-in replaces with POSTdata. The plug-in replaces this value with thesubmitted POST data when an authenticationform is returned to a user who submits aPOST request. The default value isINSERT.POST.DATA.HERE.

form_fieldname_userid Indicates the field name of the user ID datasubmitted by the POST operation. The defaultvalue is UserID.

form_fieldname_password Indicates the field name of the password datasubmitted by the POST operation. This settingapplies to both the login and changepassword form. The default value isPassword.

form_fieldname_newpassword Indicates the field name of the new passworddata submitted by the POST operation whenthe user’s password is changed. The defaultvalue is NewPassword.

form_fieldname_verifynewpassword Indicates the field name of the new passwordverification data submitted by the POSToperation when the user’s password ischanged. The default value isVerifyNewPassword.

Change password


Option Description

form_chgpasswd_submit_url Indicates the URL where password changerequests are submitted. When a passwordchange request is submitted to this URL, theplug-in updates the user’s password with thesubmitted information. A user must already beauthenticated before the plug-in changes theuser’s password. This feature is supportedonly for the Access Manager user registry.

Syntax: URL

form_chgpasswd_response_url Indicates the response URL sent to the userwhen the password is changed successfully.This page tells the user that the password hassuccessfully been changed. The default valueis /.

Syntax: URL

form_chgpasswd_file Indicates the form sent to the user to changean expired password when the login methodis basic or forms. When a user’s passwordexpires, this form is sent to the user for theuser to change the expired password. If thisoption is unspecified, no password expirationcheck is performed.

Syntax: local path | URL

form_chgpasswd_generic_errorfile Indicates the error file sent to the userspecifying that a generic error occurred whilethe user’s password was being changed.


form_chgpasswd_oldpasswd_errorfile Indicates the error file sent to the userspecifying that the old password was notcorrect.


form_chgpasswd_newpasswd_errorfile Indicates the error file sent to the userspecifying that the new password failed thepassword policy validation check.


form_chgpasswd_verifypasswd_errorfile Indicates the error file sent to the userspecifying that the new password wasincorrectly verified by the user.


Security

cookie_security_enabled Indicates whether cookies created over asecure connection are allowed to flow overnon-secure connections. If enabled, securecookies are not allowed to flow overnon-secure connections. The default value isyes.


Option Description

require_ssl Indicates whether a secure connection isrequired to access this domain. If a secureconnection is required, the browser isautomatically redirected to the secure site.

Single signon

accept_sso Indicates single signon tokens to accept forthis domain. The plug-in can skipauthentication if the user has already beenauthenticated. The plug-in searches this listuntil it finds a single signon token. See theSSO section for more information on singlesignon.

submit_sso Indicates single signon tokens to submit forthis domain. The plug-in can submit anauthenticated user’s information to thebackend server. The plug-in submits eachsingle signon token in the list to the backendserver. See the SSO section for moreinformation on single signon.

Routing

route Indicates the destination server to forward therequest in reverse proxy configurations. In thisconfiguration, DNS is configured to mapmultiple domain names to the plug-in. Theroute option tells the plug-in to route therequest to the corresponding content Webserver. If no route option is specified in thisconfiguration, the caching proxy routes therequest using its configured mapping rules.

Syntax: URL [default page]

proxy Indicates the URL of the HTTP proxy serverthat all requests are proxied through. Forexample, a transcoder proxy server can beused to convert HTML files into devicecompatible files. This option is applicable onlywhen the request is routed.

Syntax: URL

Caching

user_cache_size Indicates the maximum number of users thatare stored in the cache table for authenticatedusers. When a user authenticates successfully,the user’s credentials are stored in this cache.On subsequent requests by the same user, theuser’s credentials are retrieved from thiscache. After this time elapses, the user’scredentials are verified against the userregistry. This option is valid only in the[Global] section of this file. The default valueis 20000. When WES support is enabled, setthe MaxSessionCache parameter inibmwesas.conf instead.


Option Description

user_cache_timeout Indicates the maximum amount of time thatan authenticated user is stored in the cache.After the specified time, the user’s cachedcredentials are verified against the userregistry. If verification fails, the user isrequired to login again. The default value is10 minutes. When WES support is enabled, setthe MaxSessionAge parameter inibmwesas.conf instead.

Logging

logging_flags Indicates the category of logging messagesthat the plug-in sends to the event log file.Only messages matching the specifiedcategory are sent to the log file. This option isvalid only in the [Global] section of this file.The default value is EWI.

Log message flag options:

v E - Error messages

v W - Warning messages

v I - Informational messages

v D - Debugging messages

logging_level Indicates the verbosity level for informationaland debugging log messages. This value canrange from 0 to 5. A higher number meansthat more messages are logged. This option isvalid only in the [Global] section of this file.The default value is 3.

CDAS Support

cdas_loaded Indicates whether the CDAS module is loadedand initialized. This option is valid only in the[Global] section of this file. The default valueis no.

cdas_init_parameter Indicates the initialization parameters that arepassed to the CDAS module. The CDASinitialization function is called multiple timesif multiple entries are defined. This option isvalid only in the [Global] section of this file.

cdas_enabled Indicates whether the CDAS module isinvoked when the login method is basic,forms, or certificate. Using this option, CDAScan be enabled for some URLs and disabledfor others. Note that CDAS does not need tobe enabled for single signon support. Thedefault value is no.

cdas_auth_parameter Indicates the correlating parameters that arepassed to the CDAS module for all requestsmatching the server definition in theconfiguration file. Using this option, theCDAS module can choose the authenticationmethod based on this parameter. There is nodefault value.


Option Description

cdas_sso_mapping Indicates whether the corresponding AccessManager user ID is submitted for singlesignon to the backend server. If disabled, theoriginal CDAS userid is submitted for singlesignon. The default value is yes.

cdas_sso_headers Indicates whether HTTP headers aregenerated for each entry in the extendedattribute list returned from the CDAS module.If enabled, an HTTP header is generated foreach name/value pair in the extendedattribute list that has a name of the format,tagvalue_name. The generated HTTP header isformatted, name: value. The default value isyes.

Single signon definitionsThe plug-in can skip the authentication step if a user has already beenauthenticated. The plug-in can also pass single signon information to a Web servereither as an HTTP header or a cookie. The plug-in only accepts pre-authenticatedusers from authentication servers that are trusted.

The following single signon definitions are predefined and can be used asparameters to accept_sso and submit_sso:v CDAS-MODULE: CDAS Module Single SignOn (SSO accept only)v LTPA-COOKIE: WebSphere LTPA Cookiev WEBSEAL-COOKIE: WebSEAL’s Fail Over Cookie

Option Description

type Indicates single signon type:

v cookie - Cookie header

v header - HTTP header

v auth_header - Authorization header (SSOsubmit only)

v IP_address - IP address (SSO accept only)

name Indicates the name of the cookie or HTTP headerthat contains the user’s SSO information. Thisoption defaults to Authorization for SSO typesof auth_header and is not applicable for SSOtypes of IP_address.


Option Description

format Indicates the format of the cookie or headervalue. The following macros listed can be usedto specify the location of the user ID in theheader or cookie. This option is not applicablefor SSO types of IP_address.

The following predefined macros can be used toformat the single signon information:

v <userid> - User’s ID

v <userdn> - User’s Access Managerdistinguished name

v <pd_cred> - User’s Access Manager EPACcredentials (SSO submit only)

v <opaque> - Data not recognized by the plug-in(SSO accept only)

sso_realm Indicates the realm appended to thepre-authenticated user ID using this singlesignon definition, before the user ID is mappedto an Access Manager distinguished name. Thepurpose of this realm is to uniquely identify amapping rule for all user IDs from thispre-authentication server. See the user mappingfile for more information. This option is notapplicable when SSO information is submitted.

default_user Indicates the default Access Manager user whosecredentials are used to authorize users who havealready been authenticated using this singlesignon definition. If a mapping entry is notfound for a pre-authenticated user ID, then thecredentials for this user are used to perform theauthorization. If a mapping entry is not foundfor a pre-authenticated userid and this option isnot specified, then the plug-in directs AccessManager to lookup the user ID in the registry.This option is not applicable when SSOinformation is submitted.


Option Description

trust_basis Indicates the basis on which the plug-in can trustthe pre-authentication server. The plug-in acceptsa pre-authenticated user only if thepre-authentication server is trusted by theplug-in. The default value is IP_address. Thisoption is not applicable when SSO information issubmitted.

Trust basis options:

v IP_address - The IP address of thepre-authentication server must match an entryin the trust_list setting. If no IP address isspecified for the trust_list, then nopre-authenticated users are accepted using thissingle signon definition.

v basic_auth - The pre-authentication servermust authenticate using an Authorizationheader. The user ID and password submittedmust match an entry in the trust_list setting.

v proxy_auth - The pre-authentication servermust authenticate using a Proxy-Authorizationheader. The user ID and password submittedmust match an entry in the trust_list setting.

v certificate - The pre-authentication server mustauthenticate using a client certificate. Thecertificate DN must match an entry in thetrust_list setting.

trust_list Indicates the list of acceptable identifications thatcan be presented to the plug-in by thepre-authentication server. This option is notapplicable when SSO information is submitted.



Appendix C. wesosm command reference

This appendix lists the commands related to the wesosm utility.

Command syntaxThe commands in this appendix use the following special characters to definecommand syntax:

[ ] Identifies elements that are optional. Those not enclosed in brackets arerequired.

... Indicates that you can specify multiple values for the previous element.Separate multiple values by a space, unless otherwise directed by acommand’s information.

If the ellipsis for an element follows a closing bracket, use the syntaxwithin the brackets to specify multiple values. For example, to specify twoadministrators for the option [–a admin]..., use –a admin1 –a admin2.

If the ellipsis for an element is within the brackets, use the syntax of thelast element to specify multiple values. For example, to specify two hostsfor the option [–h host...], use –h host1 host2.

| Indicates mutually exclusive information. You can use the element oneither the left or right of the vertical bar.

{ } Delimits a set of mutually exclusive elements when one of them isrequired. If the elements are optional, they are enclosed in brackets ([ ]).

In addition to the special characters, the typeface conventions described in“Typeface conventions” on page xi are used.


wesosm

PurposeCreates and maintains the Access Manager object space for the plug-in for EdgeServer

Syntaxwesosm {–start | –stop | –run | –file [output_file]}

[–infile input_file] [–logging [log_file] [-clean]

[–force [branch]] [–fast] [–skiperrors] [–verbose]

Options–clean Removes all entries from the object space underneath /ESproxy,

which are not found in the configuration file, osdef.conf. Use thisoption with care because any attached ACLs are lost when objectspace entries are deleted.

–fast When checking for differences between the Access Manager objectspace and the Web server’s file system, this parameter tells theutility to compare the object names only and not to compare thetypes. The Access Manager object type indicates whether the objectspace entry is a file or directory. For example, if an existing file onthe Web server is changed to a directory but the name remains thesame, the utility does not detect this when this parameter isspecified.

–file Starts the object space manager to update the object space onceand then terminates the utility. Rather than updating the AccessManager object space, the object space information is written to thespecified file.

–force When starting the object space manager as a daemon, forces theutility to initially update the object space before waiting on aninterval for the next update. If specified, only the indicated branchin the object space is updated. Wild cards can be used to specifythe branch.

–infile Indicates the location of the configuration file, osdef.conf, that isused to update the object space.

–logging Indicates if the object space manager should log object spaceupdates to a log file. If no log file is specified, the default log file,wesosm.log is used.

–run Starts the object space manager to update the object space onceand then terminates the utility.

–skiperrors When updating the object space, the utility does not terminate if itencounters an error updating the Access Manager object space.This is useful if the object space contains invalid entries in it.

–start Starts the object space manager as a daemon. The daemon installsitself in memory to update the object space on intervals, as


configured in the osdef.conf configuration file. This ensures thatthe object space is kept in synchronization with the content on thecorresponding Web server.

–stop Stops the object space manager daemon. The daemon removesitself from memory and ceases to perform further updates to theobject space.

–verbose When updating the object space, displays information about theexact entries that are created, deleted, and modified in the objectspace.

Appendix C. wesosm command reference 65


Appendix D. Notices

This information was developed for products and services offered in the U.S.A.IBM may not offer the products, services, or features discussed in this document inother countries. Consult your local IBM representative for information on theproducts and services currently available in your area. Any reference to an IBMproduct, program, or service is not intended to state or imply that only that IBMproduct, program, or service may be used. Any functionally equivalent product,program, or service that does not infringe any IBM intellectual property right maybe used instead. However, it is the user’s responsibility to evaluate and verify theoperation of any non-IBM product, program, or service.

IBM may have patents or pending patent applications covering subject matterdescribed in this document. The furnishing of this document does not give youany license to these patents. You can send license inquiries, in writing, to:

IBM Director of LicensingIBM CorporationNorth Castle DriveArmonk, NY 10504-1785U.S.A.

For license inquiries regarding double-byte (DBCS) information, contact the IBMIntellectual Property Department in your country or send inquiries, in writing, to:

IBM World Trade Asia CorporationLicensing2-31 Roppongi 3-chome, Minato-kuTokyo 106, Japan

The following paragraph does not apply to the United Kingdom or any othercountry 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 itbelieves appropriate without incurring any obligation to you.


Licensees of this program who wish to have information about it for the purposeof enabling: (i) the exchange of information between independently createdprograms and other programs (including this one) and (ii) the mutual use of theinformation which has been exchanged, should contact:

IBM Corporation2Z4A/10111400 Burnet RoadAustin, TX 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 document and all licensed materialavailable for it are provided by IBM under terms of the IBM Customer Agreement,IBM International Program License Agreement or any equivalent agreementbetween us.

Information concerning non-IBM products was obtained from the suppliers ofthose products, their published announcements or other publicly available sources.IBM has not tested those products and cannot confirm the accuracy ofperformance, compatibility or any other claims related to non-IBM products.Questions on the capabilities of non-IBM products should be addressed to thesuppliers of those products.

All statements regarding IBM’s future direction or intent are subject to change orwithdrawal without notice, and represent goals and objectives only.

This information contains examples of data and reports used in daily businessoperations. To illustrate them as completely as possible, the examples include thenames of individuals, companies, brands, and products. All of these names arefictitious and any similarity to the names and addresses used by an actual businessenterprise is entirely coincidental.

COPYRIGHT LICENSE:

This information contains sample application programs in source language, whichillustrates programming techniques on various operating platforms. You may copy,modify, and distribute these sample programs in any form without payment toIBM, for the purposes of developing, using, marketing or distributing applicationprograms conforming to the application programming interface for the operatingplatform for which the sample programs are written. These examples have notbeen thoroughly tested under all conditions. IBM, therefore, cannot guarantee orimply reliability, serviceability, or function of these programs. You may copy,modify, and distribute these sample programs in any form without payment toIBM for the purposes of developing, using, marketing, or distributing applicationprograms conforming to IBM’s application programming interfaces.

Each copy or any portion of these sample programs or any derivative work, mustinclude a copyright notice as follows:

© (your company name) (year). Portions of this code are derived from IBM Corp.Sample Programs. © Copyright IBM Corp. _enter the year or years_. All rightsreserved.


If you are viewing this information softcopy, the photographs and colorillustrations may not appear.

TrademarksThe following terms are trademarks or registered trademarks of InternationalBusiness Machines Corporation in the United States, other countries, or both:

AIXDB2IBMIBM logoOS/390SecureWayTivoliTivoli logoUniversal DatabaseWebSpherezSeriesz/OS

Java and all Java-based trademarks and logos are trademarks or registeredtrademarks of Sun Microsystems, Inc. in the United States and other countries.

Microsoft and Windows are trademarks of Microsoft Corporation in the UnitedStates, other countries, or both. Java and all Java-based trademarks and logos aretrademarks or registered trademarks of Sun Microsystems, Inc. in the United Statesand other countries.

UNIX is a registered trademark of The Open Group in the United States and othercountries.

Other company, product, or service names may be trademarks or service marks ofothers.

Appendix D. Notices 69


Printed in U.S.A.

GC23-4685-00

Documents

IBM Tivoli Access Manager Plug-in for Edge …publib.boulder.ibm.com/.../GC23-4685-00/en_US/PDF/esmst.pdfiv IBM Tivoli Access Manager Plug-in for Edge Server: User’s Guide Preface