IBM Tivoli Access Manager Plug-in for Edge Server

IBM Tivoli Access Manager Plug-in for Edge Server
User’s Guide
Version 3.9
GC23-4685-00
IBM Tivoli Access Manager Plug-in for Edge Server
User’s Guide
Version 3.9
GC23-4685-00
Note
Before 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 Contract
with IBM Corp.
Contents
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . v
Who should read this book . . . . .
What this book contains . . . . . .
Publications . . . . . . . . . .
IBM Tivoli Access Manager . . . .
Related publications . . . . . .
Accessing publications online. . . .
Ordering publications . . . . . .
Providing feedback about publications
Accessibility . . . . . . . . . .
Contacting customer support . . . .
Conventions used in this book . . . .
Typeface conventions . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. v
. v
. . . . . . . . . . . . . . . . . . . . . . . . . vi
. . . . . . . . . . . . . . . . . . . . . . . . . vi
. . . . . . . . . . . . . . . . . . . . . . . . . ix
. . . . . . . . . . . . . . . . . . . . . . . . . x
. . . . . . . . . . . . . . . . . . . . . . . . . x
. . . . . . . . . . . . . . . . . . . . . . . . . xi
. . . . . . . . . . . . . . . . . . . . . . . . . xi
. . . . . . . . . . . . . . . . . . . . . . . . . xi
. . . . . . . . . . . . . . . . . . . . . . . . . xi
. . . . . . . . . . . . . . . . . . . . . . . . . xi
Chapter 1. Introducing the IBM Tivoli Access Manager plug-in for Edge Server . . . . . 1
System requirements. . . . . . . . .
Supported operating systems . . . . .
Software prerequisites . . . . . . .
Access Manager security model . . . . .
Plug-in for Edge Server security enforcement
Reverse proxy access control . . . . .
Forward proxy access control . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
1
1
1
2
2
3
5
Chapter 2. Installing the plug-in for Edge Server . . . . . . . . . . . . . . . . . . 7
Installing the plug-in for Edge Server on AIX . .
Installing the plug-in for Edge Server on Linux . .
Installing the plug-in for Edge Server on Solaris .
Installing the plug-in for Edge Server on Windows
Configuring the plug-in for Edge Server . . . .
Upgrading the plug-in for Edge Server . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
7
7
8
8
8
9
Chapter 3. Administering the plug-in for Edge Server. . . . . . . . . . . . . . . . 11
Managing user accounts . . . . . . . . . . .
Creating an Access Manager object space . . . . .
Creating an object space for the caching proxy. . .
Creating an object space for other Web servers . .
Starting and stopping the plug-in for Edge Server . .
Configuration files . . . . . . . . . . . . .
Base configuration file (ibmwesas.conf) . . . . .
Object space definition configuration file (osdef.conf)
User mapping configuration file (usermap.conf) . .
Log files . . . . . . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
11
11
12
12
13
13
14
14
16
16
Chapter 4. Understanding the plug-in for Edge Server configuration . . . . . . . . . 19
Server configuration model . . . .
Server configuration concepts applied
Object space configuration model . .
Single signon configuration model. .
Configuration procedure summarized
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
19
20
23
24
24
Chapter 5. Deploying the plug-in for Edge Server . . . . . . . . . . . . . . . . . 27
Designing the Web site
Content distribution
Single signon . . .
.
.
.
.
.
.
.
.
.
© Copyright IBM Corp. 2001, 2002
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 27
. 27
. 27
iii
Configuring the Web site .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 28
Chapter 6. Creating a Cross-domain Authentication Service . . . . . . . . . . . . . 31
Authentication models. . . . . . . . . . . .
Single authentication model . . . . . . . . .
Dispatched authentication model . . . . . . .
Building a custom shared library . . . . . . . .
CDAS application development kit . . . . . .
Programming the custom shared library . . . . .
User authentication data . . . . . . . . . .
Returning the client identity . . . . . . . . .
Compiling the custom shared library . . . . . .
Configuring the plug-in for Edge Server to use a custom
Configuring a custom shared library . . . . . .
Custom shared library configuration scenario . . .
Configuring the demonstration library . . . . .
Loading the custom shared library . . . . . .
CDAS core and utility functions . . . . . . . .
CDAS API core function reference . . . . . . . .
xauthn_authenticate . . . . . . . . . . .
xauthn_change_password. . . . . . . . . .
xauthn_initialize . . . . . . . . . . . . .
xauthn_shutdown . . . . . . . . . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
shared library
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
31
31
32
33
34
34
36
36
36
37
37
37
38
39
40
40
41
42
43
44
Chapter 7. Removing the plug-in for Edge Server . . . . . . . . . . . . . . . . . 45
Removing
Removing
Removing
Removing
the
the
the
the
plug-in
plug-in
plug-in
plug-in
for
for
for
for
Edge
Edge
Edge
Edge
Server
Server
Server
Server
on AIX . .
on Linux .
on Solaris .
on Windows
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
45
45
46
47
Appendix A. Base configuration file reference . . . . . . . . . . . . . . . . . . . 49
Appendix B. Object space definition configuration file reference . . . . . . . . . . . 51
Server definitions . . .
Single signon definitions .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 51
. 59
Appendix C. wesosm command reference . . . . . . . . . . . . . . . . . . . . 63
Command syntax .
wesosm . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 63
. 64
Appendix D. Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
Trademarks .
iv
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
IBM Tivoli Access Manager Plug-in for Edge Server: User’s Guide
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 69
Preface
The IBM® Tivoli® Access Manager (Access Manager) plug-in for IBM WebSphere®
Edge Server (plug-in for Edge Server) provides authentication and authorization
security services. Installed on the Edge Server caching proxy, the plug-in for Edge
Server is the gateway between your clients and Web servers, implementing the
security policies that protect your Web resources. The plug-in secures Web content
and application server resources at the caching proxy through virtual hosting, and
provides single signon solutions for the protected Web servers.
Note: IBM Tivoli Access Manager is the new name of the previously released
software entitled Tivoli SecureWay® Policy Director. Also, for users familiar
with the Tivoli SecureWay Policy Director software and documentation, the
term management server is now referred to as policy server.
The IBM Tivoli Access Manager Plug-in for Edge Server User’s Guide provides
installation instructions, administration procedures, and technical reference
information for securing your Web domain using the plug-in for Edge Server.
Who should read this book
This 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 systems
v Security management
v
v
v
v
Internet protocols, including HTTP, HTTPS, and TCP/IP
Lightweight Directory Access Protocol (LDAP) and directory services
Authentication and authorization
Access Manager security model and its capabilities
If you are enabling Secure Sockets Layer (SSL) communication, you also should be
familiar with SSL protocol, key exchange (public and private), digital signatures,
cryptographic algorithms, and certificate authorities.
What this book contains
This book contains the following sections:
v Chapter 1, “Introducing the IBM Tivoli Access Manager plug-in for Edge Server”
on page 1
Describes the supported platforms, installation packages, and software
prerequisites for the plug-in for Edge Server. Also describes the Access Manager
security model and the plug-in for Edge Server security enforcement.
v Chapter 2, “Installing the plug-in for Edge Server” on page 7
Provides installation and configuration instructions for all supported platforms.
v Chapter 3, “Administering the plug-in for Edge Server” on page 11
Describes 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 Server
configuration and log files.
© Copyright IBM Corp. 2001, 2002
v
v Chapter 4, “Understanding the plug-in for Edge Server configuration” on
page 19
Provides an overview of the plug-in for Edge Server configuration.
v Chapter 5, “Deploying the plug-in for Edge Server” on page 27
Describes an example deployment of the plug-in for Edge Server in a Web
commerce environment.
v Chapter 6, “Creating a Cross-domain Authentication Service” on page 31
Explains how to create a Cross-domain Authentication Service (CDAS) shared
library, which enables custom handling and processing of client authentication
information. Also describes how to configure the plug-in for Edge Server to
recognize the specific type of authentication data being passed to the custom
shared library.
v Chapter 7, “Removing the plug-in for Edge Server” on page 45
Describes how to unconfigure and remove the plug-in for Edge Server from each
of the supported operating system platforms.
v Appendix A, “Base configuration file reference” on page 49
v Appendix B, “Object space definition configuration file reference” on page 51
v Appendix C, “wesosm command reference” on page 63
Publications
This section lists publications in the Access Manager library and any other related
documents. It also describes how to access Tivoli publications online, how to order
Tivoli publications, and how to make comments on Tivoli publications.
IBM Tivoli Access Manager
The Access Manager library is organized into the following categories:
v Release information
v
v
v
v
v
Base information
WebSEAL information
Web security information
Developer reference information
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, open
the 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, see
the following Web sites:
http://www.ibm.com/redbooks
https://www.tivoli.com/secure/support/documents/fieldguides
Release information
v 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 information
v IBM Tivoli Access Manager Base Installation Guide
GC32-0844 (am39_install.pdf)
Provides installation, configuration, and upgrade instructions for Access
Manager 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 manager
interface 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 the
zSeries platform.
WebSEAL information
v IBM Tivoli Access Manager WebSEAL Installation Guide
GC32-0848 (amweb39_install.pdf)
Provides installation, configuration, and upgrade instructions for the WebSEAL
server 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 technical
reference information for using WebSEAL to manage the resources of your
secure Web domain.
v IBM Tivoli Access Manager WebSEAL Developer’s Reference
GC23-4683 (amweb39_devref.pdf)
Provides administration and programming information for the Cross-domain
Authentication 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 WebSEAL
server and the WebSEAL application development kit for Linux on the zSeries
platform.
Web security information
v IBM Tivoli Access Manager for WebSphere Application Server User’s Guide
GC32-0850 (amwas39_user.pdf)
Provides installation, configuration, and administration instructions for Access
Manager 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 Access
Manager 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 the
plug-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 securing
your Web domain using the plug-in for Web servers application.
Developer references
v 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 Manager
authorization C API and the Access Manager service plug-in interface to add
Access 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 of
the 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 an
application to perform Access Manager administration tasks. This document
describes 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 of
the administration API to enable an application to perform Access Manager
administration tasks.
v IBM Tivoli Access Manager WebSEAL Developer’s Reference
GC23-4683 (amweb39_devref.pdf)
Provides administration and programming information for the Cross-domain
Authentication Service (CDAS), the Cross-domain Mapping Framework (CDMF),
and the Password Strength Module.
Technical supplements
v IBM Tivoli Access Manager Performance Tuning Guide
GC43-0846 (am39_perftune.pdf)
Provides performance tuning information for an environment consisting of
Access 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 backend
Web 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 by
Access 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 to
Tivoli software. The Tivoli Glossary is available, in English only, at the following
Web site:
http://www.tivoli.com/support/documents/glossary/termsm03.htm
Related publications
This 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 at
the following Web site:
http://www.ibm.com/software/data/db2/
IBM Global Security Toolkit
Access Manager provides data encryption through the use of IBM Global Security
Toolkit (GSKit). GSKit is shipped on the IBM Tivoli Access Manager Base CD for
your particular platform.
The GSKit package installs the iKeyman key management utility (gsk5ikm), which
enables you to create key databases, public-private key pairs, and certificate
requests. 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 to
enable SSL communication in their Access Manager secure domain.
IBM SecureWay Directory
IBM SecureWay Directory, Version 3.2.2, is shipped on the IBM Tivoli Access
Manager Base CD for your particular platform. If you plan to install the IBM
SecureWay Directory server as your user registry, the following documents are
available in the /doc/Directory path on the IBM Tivoli Access Manager Base CD
for 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 IBM
SecureWay 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 documentation
and 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 IBM
SecureWay Directory documentation had been translated. This file is in English
only.
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, Version
3.2.2. This software development kit (SDK) provides LDAP application
development support.
v IBM SecureWay Directory Configuration Schema
(scparent.pdf)
Describes the directory information tree (DIT) and the attributes that are used to
configure the slapd32.conf file. In IBM SecureWay Directory Version 3.2, the
directory 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. Tuning
considerations for directory sizes ranging from a few thousand entries to
millions 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 Server
IBM WebSphere Application Server, Advanced Single Server Edition 4.0.2, is
installed with the Web portal manager interface. For information about IBM
WebSphere Application Server, see the following Web site:
http://www.ibm.com/software/webservers/appserv/infocenter.html
Accessing publications online
Publications in the product library are included in Portable Document Format
(PDF) on the product CD. To access these publications using a Web browser, open
the 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 hardcopy
publications, they are posted to the Tivoli Information Center. The Tivoli
Information Center contains the most recent version of the publications in the
product library in PDF or HTML format, or both. Translated documents are also
available for some products.
You can access the Tivoli Information Center and other sources of technical
information 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 to
page check box in the Adobe Acrobat Print dialog (which is available when
you click File → Print) to ensure that the full dimensions of a letter-sized
page are printed on the paper that you are using.
Ordering publications
You 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-2755
v In Canada: 800-426-4968
v 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 publications
We are very interested in hearing about your experience with Tivoli products and
documentation, and we welcome your suggestions for improvements. If you have
comments or suggestions about our products and documentation, contact us in one
of the following ways:
v Send an e-mail to pubs@tivoli.com.
v Complete our customer feedback survey at the following Web site:
http://www.tivoli.com/support/survey/
Accessibility
Accessibility features help a user who has a physical disability, such as restricted
mobility or limited vision, to use software products successfully. With this product,
you can use assistive technologies to hear and navigate the interface. You can also
use the keyboard instead of the mouse to operate all features of the graphical user
interface.
Contacting customer support
If you have a problem with any Tivoli product, you can contact Tivoli Customer
Support. 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 Customer
Support, depending on the severity of your problem, and the following
information:
v Registration and eligibility
v Telephone numbers and e-mail addresses, depending on the country in which
you are located
v What information you should gather before contacting support
Conventions used in this book
This guide uses several conventions for special terms and actions, operating
system-dependent commands and paths, and margin graphics.
Typeface conventions
The following typeface conventions are used in this book:
Bold
Command names and options, keywords, and other information
that 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 that
are emphasized also appear in italics.
Monospace
xii
Code examples, command lines, screen output, file and directory
names, and system messages appear in monospace font.
IBM Tivoli Access Manager Plug-in for Edge Server: User’s Guide
Chapter 1. Introducing the IBM Tivoli Access Manager plug-in
for Edge Server
The plug-in for Edge Server adds authentication and authorization functionality to
the IBM WebSphere Edge Server product. When implemented as an authorization
service in your secure domain, this plug-in can provide single signon solutions to
resources within that domain.
This chapter describes the supported platforms, installation packages, and software
prerequisites for the plug-in for Edge Server. This chapter also describes the IBM
Tivoli Access Manager security model and the plug-in for Edge Server security
enforcement.
System requirements
Access Manager has specific software and hardware prerequisites that must be met
before it can be installed and deemed fully functional. These include operating
systems, hardware platforms, and so on.
The requirements listed in the following sections constitute the recommended
environment 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-business
Release Notes.
Supported operating systems
The plug-in for Edge Server is supported on the following platforms:
v IBM AIX 4.3.3 and 5.1
v Microsoft Windows 2000 Advanced Server
v Red Hat Linux 7.1
v Sun Solaris 2.7 and 2.8
Software prerequisites
The plug-in for Edge Server operates in a secure domain installed with Access
Manager, Version 3.9. The plug-in for Edge Server has the following software
prerequisites. You must install and configure these prerequisites on the same
system 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 installed
and configured. However, if you plan to install the plug-in on a new system that is
not currently a part of your Access Manager secure domain, follow installation
instructions 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.67
v IBM SecureWay Directory, Version 3.2.2, client
© Copyright IBM Corp. 2001, 2002
1
v Access Manager runtime environment
Access Manager security model
The plug-in for Edge Server adds authentication and authorization control to the
Edge Server caching proxy. To administer the plug-in for Edge Server, you need to
be familiar the Access Manager model for enforcing security policies.
The Access Manager model is based on understanding the business policies that
must apply to users, programs, and data in a network environment. To establish a
secure environment, Access Manager requires an administrator to define the
following entities:
v Objects to be secured
v Actions permitted on each object
v 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) that
consist 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 by
attaching 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 in
the file hierarchy. The more restrictive ACL overrides the ACL that is attached at
the top of the hierarchy. The plug-in for Edge Server enforces access control by
checking for the read (r), modify (m), or execute (x) permission on each requested
object, based on the requested action.
The Access Manager security model is flexible and supports many different
configurations. Before you use the plug-in for Edge Server, you need to be familiar
with Access Manager capabilities. For more information, see the IBM Tivoli Access
Manager Base Administrator’s Guide.
Plug-in for Edge Server security enforcement
The plug-in for Edge Server works with the IBM WebSphere Edge Server to
provide access control. It sits at the edge of an enterprise network where access
requests from clients outside the firewall are evaluated.
Edge Server consists of two key components:
v Caching proxy
v Network dispatcher
The plug-in is invoked by the caching proxy component on every request to
determine if the user is authorized to access the requested resource. The caching
proxy 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, it
can be used for load balancing across replicated servers in high volume
environments.
Generally, when a user issues a request from a browser to a Web site, the object
represented in the URL corresponds to an object on a Web server. The plug-in for
Edge Server provides access control by verifying that the user is authorized to
perform the requested action on the Web server object. The plug-in does this by
authenticating the user against the Access Manager user registry and authorizing
the user against the Access Manager object space, as illustrated in Figure 1. The
plug-in returns status information to the caching proxy indicating whether the user
was authorized to perform the requested action on the object. The caching proxy
uses this information to either deny or allow the requested action. When the
security policy permits, the Edge Server caching proxy caches the requested object
to optimize performance.
Browser
Edge Server
Internet
Gateway
Caching
Proxy
Access Manager
Registry Server
Web Server
Access Manager
Plug-in
Access Manager
Policy Server
Figure 1. Example of plug-in for Edge Server security enforcement
The plug-in for Edge Server provides access control for the following Edge Server
caching proxy configurations:
v Reverse proxy
v Forward proxy
These concepts are discussed in the following sections.
Reverse proxy access control
The Edge Server caching proxy functions as a reverse proxy when it is located
between a client browser on the Internet and Web servers that are located behind a
firewall. In this role, the caching proxy intercepts user requests arriving from the
Internet, forwards them to the appropriate host Web server, caches the returned
data, 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 inbound
client requests. This is accomplished by configuring the public domain name of the
Web site on the Edge Server caching proxy machine and specifying a route to the
corresponding backend Web server, as illustrated in Figure 2 on page 4.
Chapter 1. Introducing the IBM Tivoli Access Manager plug-in for Edge Server
3
Browser
Edge Server
newbooks.com
Internet
Gateway
Caching
Proxy
Web Server
backend1.com
Access Manager
Plug-in
Figure 2. Plug-in for Edge Server in a reverse proxy configuration
In this example, the plug-in for Edge Server is configured to provide access control
to the objects on newbooks.com. After a user is authorized, the request is routed to
the corresponding backend server either by the plug-in for Edge Server, or by a
load balancing module, such as the content-based routing module of the Edge
Server network dispatcher. The plug-in for Edge Server performs URL mapping,
similar to the function provided by the Proxy statements in the Edge Server
caching proxy configuration file.
You configure the plug-in for Edge Server access control by setting values for
parameters 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.com
login_method = forms
form_login_file = http://newbooks.com/pub/login.html
form_login_errorfile = http://newbooks.com/pub/loginerr.html
form_logout_url = /pub/logout.html
route = 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 the
entry /ESproxy/reverse/newbooks.com in the Access Manager protected object
name space.
v Use forms-based login as the login method
v 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 for
reverse proxy requests. You can set additional options for this server definition. If
4
IBM Tivoli Access Manager Plug-in for Edge Server: User’s Guide
you do not specify a setting for an option, the setting for that option is inherited
from the [Global] section of the osdef.conf configuration file.
The plug-in for Edge Server supports several login methods. In addition to the
forms-based login shown in the sample configuration, you can also configure the
plug-in for Edge Server to use:
v Basic authentication
v Client certificate authentication
For information about osdef.conf file options, see Appendix B, “Object space
definition configuration file reference” on page 51.
Forward proxy access control
The Edge Server caching proxy functions as a forward proxy when it is located
between a client browser (behind a firewall) and the Internet. The client browsers
are configured to direct requests to the Edge Server caching proxy. The forward
caching proxy forwards a client’s request to a content host located across the
Internet, 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 these
outbound client requests, as illustrated in Figure 3.
Edge Server
Internet
Web Server
Gateway
Browser
Caching
Proxy
Access Manager
Plug-in
Figure 3. Plug-in for Edge Server in a forward proxy configuration
By default, the plug-in for Edge Server checks /ESproxy/forward/domain_name for
forward proxy requests. You can override this default setting by creating one or
more server definitions in the object space definition configuration file as shown:
[Remote: /ESproxy/forward/blockedsites]
domains = games.com *.games.com *.competitor.com
route = 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 policy
Web page located at the following Web address:
backend2.com
Alternatively, you can attach an Access Manager ACL at this location in the object
space. For example, this ACL could deny all users access to any of the listed Web
sites.
Chapter 1. Introducing the IBM Tivoli Access Manager plug-in for Edge Server
5
6
IBM Tivoli Access Manager Plug-in for Edge Server: User’s Guide
Chapter 2. Installing the plug-in for Edge Server
This chapter describes how to install and configure the plug-in for Edge Server on
AIX, Solaris, and Windows platforms. Note that if your system is currently set up
with supported versions of GSKit, IBM SecureWay Directory client, and the IBM
Tivoli Access Manager runtime environment, you need to install only the plug-in
package.
This chapter contains the following sections:
v “Installing the plug-in for Edge Server on AIX” on page 7
v
v
v
v
“Installing the plug-in for Edge Server on Linux” on page 7
“Installing the plug-in for Edge Server on Solaris” on page 8
“Installing the plug-in for Edge Server on Windows” on page 8
“Configuring the plug-in for Edge Server” on page 8
Installing the plug-in for Edge Server on AIX
The following steps show you how to install components necessary for the plug-in
for Edge Server.
Note: Before you install the plug-in package, ensure that you install prerequisite
software 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 the
instructions in “Configuring the plug-in for Edge Server” on page 8.
Installing the plug-in for Edge Server on Linux
The following steps show you how to install components necessary for the plug-in
for Edge Server.
Note: Before you install the plug-in package, ensure that you install prerequisite
software 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 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 the
instructions in “Configuring the plug-in for Edge Server” on page 8.
© Copyright IBM Corp. 2001, 2002
7
Installing the plug-in for Edge Server on Solaris
The following steps show you how to install components necessary for the plug-in
for Edge Server.
Note: Before you install the plug-in package, ensure that you install prerequisite
software 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 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 the
instructions in “Configuring the plug-in for Edge Server” on page 8.
Installing the plug-in for Edge Server on Windows
The following steps show you how to install components necessary for the plug-in
for Edge Server.
Note: Before you install the plug-in package, ensure that you install prerequisite
software in “System requirements” on page 1.
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 Server
The plug-in for Edge Server provides a configuration utility named wslconfig.sh
(on UNIX systems) or wslconfig.exe (on Windows systems). This utility
accomplishes 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 an
Active Directory user registry requires an administrator password for
8
IBM Tivoli Access Manager Plug-in for Edge Server: User’s Guide
the configuration tool to perform successfully. When configuring, use
the 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 space
manager utility, by using the wesosm command. This utility updates the Access
Manager object space to create a new object space container for the plug-in for
Edge Server.
Configuration of the plug-in for Edge Server is now complete. The Edge Server
caching proxy is now running with the plug-in for Edge Server loaded. The
administrative user, sec_master, can be used to access the caching proxy’s home
page.
Upgrading the plug-in for Edge Server
The configuration tool for the earlier versions of the plug-in automatically replaced
user configuration files during the unconfiguration process, which sometimes
caused the loss of user configuration information. The plug-in for Edge Server,
Version 3.9, does not replace user configuration files during the unconfiguration
process. 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
10
IBM Tivoli Access Manager Plug-in for Edge Server: User’s Guide
Chapter 3. Administering the plug-in for Edge Server
This chapter provides the concepts, administrative procedures, and technical
reference information for using the plug-in for Edge Server to manage the
resources of your secure domain. This chapter contains the following sections:
v
v
v
v
v
“Managing user accounts” on page 11
“Creating an Access Manager object space” on page 11
“Starting and stopping the plug-in for Edge Server” on page 13
“Configuration files” on page 13
“Log files” on page 16
Managing user accounts
IBM Tivoli Access Manager maintains and manages user accounts through the
pdadmin command line interface. Users and groups are created, deleted, and
modified using this interface. The plug-in authenticates a user by verifying that the
submitted 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 to
the plug-in during authentication. The plug-in does not maintain any password
policy information but relies on Access Manager to maintain information such as
max-login-failures, account-expiry-date, and max-password-age. During
authentication, the plug-in verifies that the user account is valid and ensures that
the user’s password has not expired. If the user account is disabled, the user fails
authorization. However, if the password has expired and a change password form
was configured for the plug-in, then the user is presented with the form to change
the expired password.
Creating an Access Manager object space
Access Manager uses a protected object name space to represent objects that need
to have access control policies applied. The protected object space can include
resources on a Web server. The simplest way to add Web resources to the object
space is to import the Web server file system and apply Access Manager access
control lists (ACLs) as needed.
The plug-in for Edge Server provides an object space manager utility that adds
resources to the Access Manager object space. The utility is invoked with the
wesosm command. You can use wesosm to generate the object space for both the
Edge Server caching proxy and for Web servers that the plug-in for Edge Server
protects.
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 object
space:
v “Creating an object space for the caching proxy” on page 12
v “Creating an object space for other Web servers” on page 12
© Copyright IBM Corp. 2001, 2002
11
Creating an object space for the caching proxy
Although the Edge Server caching proxy is a proxy, it can function like a Web
server when requests are made directly to the primary domain name of the Edge
Server caching proxy machine. Typically, informational and error messages are
stored in the Web space of the proxy. The plug-in for Edge Server enforces access
control 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 object
space. 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 object
spaces and for adding, modifying, and deleting objects. For more information, see
the IBM Tivoli Access Manager Base Administrator’s Guide.
You can also add a series of Web resources to the object space by using the
query_contents utility to get an inventory of the objects in a Web hierarchy. This
method is discussed in “Creating an object space for other Web servers” on page
12.
The following example server definition in the configuration file osdef.conf
represents an Edge Server caching proxy named bookproxy.com:
[Local: /ESproxy/bookproxy.com]
domains = bookproxy.com
query_command = http://bookproxy.com/cgi-bin/query_contents?dirlist=/
When you configure the plug-in for Edge Server at installation time, the wslconfig
utility executes the wesosm command to generate the default object space for the
Edge Server caching proxy. The default object space contains the following
container objects:
/ESproxy
/Esproxy/proxy_host_name
/ESproxy/forward
/ESproxy/reverse
After the objects are created, you can place ACLs at the appropriate locations in
the object space for the Edge Server caching proxy.
Creating an object space for other Web servers
Use the object space manager wesosm command to query a remote Web server’s
file system to create corresponding entries in the Access Manager object space. The
object space manager reads the osdef.conf configuration file and creates object
entries for each server definition in the file.
Use the query_contents utility to import a Web server’s file system into the
protected object space. Place this utility in the cgi-bin directory on the target Web
server. Also, specify the root location of the Web server’s files. For more
information about the query_contents utility, see the IBM Tivoli Access Manager
WebSEAL Administrator’s Guide.
After you have configured the query_contents utility, add an entry to the object
space definition configuration file that tells the wesosm command how to query
the remote Web server’s file system. For example, add the following entry in the
configuration file:
12
IBM Tivoli Access Manager Plug-in for Edge Server: User’s Guide
[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 space
manager 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, it
connects to the Access Manager policy server to create entries in the object space
underneath /ESproxy/reverse/newbooks.com. If a server definition does not have a
query_contents utility associated with it, only the root branch is created. You can
attach ACLs in appropriate locations after the object space has been created.
You also can use the wesosm command to maintain the object space by pruning
any obsolete entries that might accumulate over time. To remove obsolete entries
from 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 Server
To manually start the Edge Server caching proxy and load the plug-in for Edge
Server, do one of the following:
v On UNIX systems, use the wslstartwte command.
Note: You can add the wslstartwte utility to UNIX startup scripts to
automatically start the Edge Server caching proxy and the plug-in for
Edge 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 files
The plug-in for Edge Server configuration files are created and placed on the
filesystem when the plug-in for Edge Server is installed and configured. You can
manually 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 14
v “Object space definition configuration file (osdef.conf)” on page 14
v “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 utility
initializes 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 Edge
Server. 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
settings
These include LDAP host and port numbers. When Access Manager
communication with the LDAP server is over Secure Sockets Layer (SSL), the
SSL 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
v
v
v
Lightweight Third Party Authentication (LTPA) cookie single signon settings
WebSEAL cookie single signon settings
Location of the osdef.conf object space definition file
Location of the usermap.conf user mapping file
For more information on the ibmwesas.conf file, see Appendix A, “Base
configuration file reference” on page 49.
Object space definition configuration file (osdef.conf)
The object space definition configuration file is named osdef.conf. The osdef.conf
file specifies configuration settings that the plug-in for Edge Server uses to enforce
access control for all client requests. The object space definition configuration file
has its settings grouped into the following sections:
v [Global]
Specifies settings that apply to all requests that are not explicitly overwritten in
another section ([Local] or [Remote]).
v [Local]
Specifies settings that apply to requests for objects on the Edge Server caching
proxy.
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 Server
can use to pass authentication information to a Web server.
The [Global] section of the osdef.conf file includes the following configuration
options:
v Administrator name and password
v Enable or disable updating of the object space
v Object space locations for the object space root, forward proxy entries, and
reverse proxy entries
14
IBM Tivoli Access Manager Plug-in for Edge Server: User’s Guide
v File system type
v URL resolution using reverse Domain Name System (DNS) lookup
v Login method
– None
It is recommended that you use the Access Manager unauthenticated ACL
rather than the None login type.
– Basic authentication
– Forms-based login
– Certificates
v Forms-based login settings
Includes forms file locations, error file locations, password handling, and
security type to be used for secure form login.
v Cache size and cache timeout values for storing authenticated user information
v Logging message settings
The [Local] section of the osdef.conf file includes the following configuration
options:
v Domain names
v Login method
v Query command settings
These values are used to collect object space information for the local Edge
Server caching proxy objects.
The [Remote] section of the osdef.conf file contains definitions for each remote
server that is being secured by the plug-in for Edge Server. The settings for each
server include:
v Domain names
v
v
v
v
Login method and supporting files
Query commands
SSL access requirements
Single signon options
v Routing options
The [SSO] section of the osdef.conf file contains single signon definitions and
settings for single signon configurations. The plug-in for Edge Server can skip the
authentication step if a user has already been authenticated. The plug-in for Edge
Server can also pass single signon information to a Web server as either an HTTP
header or a cookie.
The following single signon types are predefined:
v IBM WebSphere LTPA cookie
v Access Manager WebSEAL failover cookie
v CDAS module single signon
The plug-in for Edge Server provides several predefined macros that you can use
to format single signon information. For information about these macros and for
examples of formatted single signon information, see the sample entries in the
osdef.conf file.
Chapter 3. Administering the plug-in for Edge Server
15
The plug-in for Edge Server supports many different configuration scenarios.
Accordingly, many configuration options can be adjusted. The osdef.conf
configuration file documents each option in detail and provides a default and
sample value for each option.
After you develop a basic understanding of the plug-in for Edge Server, you can
easily customize and configure it to work in your environment. The plug-in for
Edge Server runs well using default values. Therefore, you do not need to set
every option to use it effectively. Set only the relevant options.
For more information on the osdef.conf file, see Appendix B, “Object space
definition 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 Access
Manager users. For more information about the user mapping file, see comments
provided in the usermap.conf template file. The usermap.conf template file is
located in one of the following directories:
v For UNIX systems:
/opt/pdweb-lite/etc
v For Windows systems:
install_dir\etc
Log files
The plug-in for Edge Server logs events to the event log file of the Edge Server
caching proxy. You can examine this log file to view the actions that the plug-in for
Edge 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.
16
IBM Tivoli Access Manager Plug-in for Edge Server: User’s Guide
[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.com
Authorization: Basic Yah7dglDai84qBXf=
[03/15/02
[03/15/02
[03/15/02
[03/15/02
[03/15/02
[03/15/02
[03/15/02
[03/15/02
[03/15/02
10:06:02
10:06:02
10:06:02
10:06:02
10:06:03
10:06:03
10:06:03
10:06:03
10:06:03
2560]
2560]
2560]
2560]
2560]
2560]
2560]
2560]
2560]
Authenticating user ’joe’ through Access Manager
Authentication succeeded for user ’joe’
Creating LDAP identity for user ’joe’
Loading credentials to authorize user ’joe’
Checking access (r) on ACL string /ESproxy/reverse/newbooks.com
Permission was granted to access object
User ’joe’ was successfully authorized (return code = 200)
Routing request to http://backend1.com/ using reverse proxy route
Exiting Authorization Plugin: WTESeal_Authorize()
Figure 4. Event log file excerpt
Chapter 3. Administering the plug-in for Edge Server
17
18
IBM Tivoli Access Manager Plug-in for Edge Server: User’s Guide
Chapter 4. Understanding the plug-in for Edge Server
configuration
This chapter provides an overview of the plug-in for Edge Server configuration
explaining concepts, models, and procedures. This chapter contains the following
sections:
v
v
v
v
v
“Server configuration model”
“Server configuration concepts applied” on page 20
“Object space configuration model” on page 23
“Single signon configuration model” on page 24
“Configuration procedure summarized” on page 24
Server configuration model
The plug-in for Edge Server provides authentication and authorization services for
Web servers within a secured domain by enforcing the security at the Edge Server
proxy, rather than at the Web server. By implementing the security enforcement at
the proxy, the plug-in centrally provides security services for all Web servers
within the secured domain. After a user is authorized, the plug-in forwards the
request to the corresponding Web server with the user’s information.
Because the content of a Web site might span multiple Web servers for
performance and content distribution, the plug-in needs to provide security
services for multiple Web servers within the secured domain. While some Web
servers might host content, others might host a wide variety of Web applications,
each with different security requirements. For example, some servers might not
require authentication, but other servers might require it. Each server requiring
authentication might require the user information be submitted in a unique format.
While some security settings are common to all servers such as form session
timeout and logging level, some are unique to each server such as login method
and single signon.
The plug-in secures the varied array of Web servers, each with its unique
configuration requirements through its object space definition configuration file,
osdef.conf. This configuration file organizes the settings for each protected Web
server into server definitions. Within each server definition, server specific settings
are set. There are three types of server definitions used in the configuration file as
shown in the following table.
Server definition
Description
[Global]
Settings listed under this definition apply to
all Web servers. There is only one instance
of this definition.
[Local]
Settings listed under this definition apply
only to the Edge Server caching proxy. There
is only one instance of this definition.
[Remote]
Settings listed under this definition apply to
external or remote Web servers secured by
the plug-in. There can be multiple instances
of this definition.
© Copyright IBM Corp. 2001, 2002
19
With a few exceptions that are documented in the osdef.conf file, any setting can
be 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 = forms
form_login_file = /opt/pdweb-lite/samples/forms/welcome.html
form_session_timeout = 10
[Remote: /ESproxy/reverse/anyother.com]
domains = anyother.com
[Remote: /ESproxy/reverse/verysecure.com]
domains = verysecure.com
form_session_timeout = 1
In this example, any user who logs into verysecure.com is not allowed to remain
idle for more than one minute, otherwise their session expires. However, for any
user who logs into anyother.com and all other domains, the idle timeout is 10
minutes due to it being set in the [Global] definition. With a few exceptions, this
model of inheritance can be used on any server setting in the configuration file but
is not applicable to single signon [SSO] settings, as illustrated in Figure 5.
Internal Access
Manager Plug-in
Default Values
[Global]
[Local]
[Remote 1]
[Remote N]
Figure 5. Plug-in for Edge Server using model of inheritance
Using this model of inheritance, settings that are the same for each Web server do
not need to be repeated under each server definition but can be listed once
underneath the [Global] definition of the configuration file. For example, if all
servers uses the same form login file, then that setting can be listed in the [Global]
definition.
Server configuration concepts applied
With a basic understanding of the configuration file, it is easier to understand how
the plug-in enforces security using this configuration file. Whenever a request is
received 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.
20
IBM Tivoli Access Manager Plug-in for Edge Server: User’s Guide
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 file
for configuration information about the request. Each step requires one or more
settings to be retrieved from the osdef.conf configuration file. For example, step 2
on page 20 requires the retrieval of the login_method setting.
To retrieve a setting for the request, the plug-in needs to first determine which
definition it should retrieve the setting from. It needs to correlate the request with
a specific server definition in the configuration file. While the plug-in can enforce
security for both reverse and forward proxy requests, the plug-in does not consider
whether the request is a reverse or forward proxy request.
The domain name is the public identifier for the corresponding Web server hosting
the protected resource. In a reverse proxy scenario, this requires the creation of
aliases or public domain names on the plug-in system, as illustrated in Figure 6.
Browser
Web Servers
Edge Server
www.newbooks.com
newbooks.com
newnovels.com
newpoems.com
backend1.com
Hosts www.newbooks.com
and newbooks.com
backend2..com
Hosts newnovels.com
backend3.com
Internet
Hosts newpoems.com
Caching
Proxy
Internal Gateway
Access Manager
Plug-in
Browser
Figure 6. Creation of aliases on a plug-in system
In this configuration, all requests for www.newbooks.com, newbooks.com,
newnovels.com, and newpoems.com arrive at the Edge Server proxy and are
secured by the plug-in. Using the domain name as the unique identifier for the
request, the plug-in can now search the configuration file for the server definition
that 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.com
login_method = forms
route = http://backend1.com
# Definition 2
[Remote: /ESproxy/reverse/label2]
domains = newnovels.com
login_method = certificate
route = http://backend2.com
Chapter 4. Understanding the plug-in for Edge Server configuration
21
# Definition 3
[Remote: /ESproxy/check_here/this_is_just_a_label]
domains = newpoems.com
route = 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 server
where 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.html
If the user typed the IP address of www.newbooks.com, the plug-in first
performs a reverse DNS lookup on the IP address and still matches the request
to definition 1.
The login method is forms because it is explicitly set under this definition. For
the authorization check, the domain name would be replaced with the
authorization string and the URL path would be appended. In this example, the
authorization check for read (r) permission would be performed at
/ESproxy/reverse/newbooks.com/private.html. The request is forwarded to
backend1.com because of the route setting.
v If a user types the following URL, the plug-in would match the request to
definition 2 because the domains setting contains the value, newnovels.com:
http://IP_address_of_newnovels.com/gifs/private.html
The 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 to
backend2.com because of the route setting.
v If a user types the following URL, the plug-in would match the request to
definition 3 because the domains setting contains the value, newpoems.com:
http://newpoems.com/logo.gif
The login method is basic because it is not explicitly set under this definition
and 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 the
following URL, the plug-in does not find a match for the request and uses the
[Global] definition:
http://internet.com/mail/logo.gif
The login method is basic. For the authorization check, the default forward
proxy template, /ESproxy/forward/domain/path is used. In this example, the
authorization check for read (r) permission is performed at
/ESproxy/forward/internet.com/mail/logo.gif. Since this object might not exist
in the object space, the effective permission is inherited from the ACL attached
to /ESproxy/forward. The request is automatically forwarded to internet.com
because it was a forward proxy request. However, it is possible to create a
definition in the configuration file that performed an authorization check at
another location in the object space and forwards the internet.com request
elsewhere. The plug-in does not consider if the request is a forward or reverse
proxy request. In both configurations, the request is handled in the same
manner.
22
IBM Tivoli Access Manager Plug-in for Edge Server: User’s Guide
Object space configuration model
When the plug-in performs an authorization check underneath a branch in the
Access Manager object space, it maps the requested resource or URL to the object
space. For example, in server definition 1, the following mapping is performed for
the authorization check:
URL Object: http://www.newbooks.com/private.html
Access Manager Object: /ESproxy/reverse/newbooks.com/private.html
In order to apply access control to specific objects using Access Manager ACLs, the
object space must be structured in a manner where there is a direct mapping
between the set of objects that users request in their URLs and the set of objects
provided by the Web server. The simplest case is a direct mapping between
referenced 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 files
http://www.newbooks.com/private.html
http://www.newbooks.com/public.html
http://www.newbooks.com/gifs
http://www.newbooks.com/gifs/logo.gif
The sample query_contents utility provides the wesosm utility with the paths of
all files on the Web server. The file information is copied into the object space so
that when the plug-in performs the authorization check, there is a direct mapping
between the URL objects and server objects.
This model works well if the set of URL objects are always going to be physical
files on the destination Web server that the query_contents utility finds. In some
cases, the set of URL objects might not correspond directly to physical files on the
Web server. In this case, the query_contents utility can be modified to return the
virtual 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 objects
http://www.newbooks.com/object1
http://www.newbooks.com/object2
http://www.newbooks.com/object3
http://www.newbooks.com/object3/object3.1
In this scenario, the objects served by the Web server do not correspond directly to
physical files on the Web server. However, the Web server understands what these
objects are and knows how to retrieve them. As long as the query_contents utility
can enumerate these virtual objects for the wesosm utility, the plug-in can perform
authorization checks on these virtual objects.
The plug-in performs authorization checks by verifying the appropriate
permissions in the Access Manager object space. It maps the URL to the object
space to determine the exact location to perform the authorization check. In order
to apply ACLs on specific objects secured by the plug-in, it is necessary to ensure
Chapter 4. Understanding the plug-in for Edge Server configuration
23
that the set of objects represented in the object space corresponds to the set of
objects represented in the URL requests for the secured Web server.
Single signon configuration model
The plug-in supports customizable single signon tokens that are created
underneath the [SSO] categories of the configuration file as indicated in the
following table.
Server definition
Description
[SSO]
Settings listed under this definition are used
to define single signon tokens. There can be
multiple 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_list
setting, 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 as
parameters to accept_sso and submit_sso, which are valid underneath the server
categories. The following example shows the definition of an iv-user token which
is needed by two Web servers:
[Remote: /ESproxy/reverse/newbooks.com]
domains = newbooks.com
accept_sso = mysso
submit_sso = mysso
route = http://backend1.com
[Remote: /ESproxy/reverse/newnovels.com]
domains = newnovels.com
submit_sso = mysso
route = http://backend2.com
[SSO: mysso]
name = iv-user
format = <userid>
trust_basis = IP_Address
trust_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 any
IP address that makes a request to newbooks.com. If the iv-user token is found, it
extracts the user ID from the token and authorizes the user. The plug-in also
submits the iv-user token to the respective backend server for requests to
newbooks.com and newnovels.com.
Configuration procedure summarized
The plug-in for Edge Server provides a flexible framework to configure access
control to the protected resources on your Web servers. It allows you to set server
specific configuration items such as the login method, single signon token, and
destination server. Settings that apply to each server need to only be set in one
place 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.
24
IBM Tivoli Access Manager Plug-in for Edge Server: User’s Guide
3. Set server specific settings underneath the definition for that server and set
global settings in the [Global] definition of the configuration file. It is sufficient
to use the default internal plug-in values for most settings.
4. Run the wesosm utility to generate the object space and set the appropriate
ACLs 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 to
determine the cause of a configuration error, check the event log file for
information describing how the plug-in handled the request. Running the UNIX
tail -f command on the event log file can help in observing events as they happen
in real time. It is easier to determine the cause of the configuration problem after
observing the event log.
Chapter 4. Understanding the plug-in for Edge Server configuration
25
26
IBM Tivoli Access Manager Plug-in for Edge Server: User’s Guide
Chapter 5. Deploying the plug-in for Edge Server
This chapter describes an example deployment for the Access Manager Plug-in for
Edge Server. This deployment shows an example of a commercial Web site where
visitor access must be controlled. The example is described in the following
sections:
v “Designing the Web site” on page 27
v “Configuring the Web site” on page 28
Designing the Web site
In this section, a complete plug-in for Edge Server configuration for newbooks.com
is designed. This Web site allows users to browse and purchase books. Many of the
key features of the plug-in for Edge Server are illustrated in this example. The Web
site design is divided into the following components:
v “Content distribution” on page 27
v “Single signon” on page 27
Content distribution
In this design, rather than storing the entire content for the Web site on one Web
server, it is distributed across several Web servers. The Web content is divided into
the following sections:
v newbooks.com
v catalog.newbooks.com
v account.newbooks.com
v payment.newbooks.com
The newbooks.com domain contains the greeting page and links to other parts of
the Web site. The catalog.newbooks.com subdomain contains a repository of all the
books sold at this Web site. These sections of the Web site do not require access
control and therefore are not protected.
The account.newbooks.com directory contains HTML and Java code that is used to
manage the user’s account. The payment.newbooks.com directory also contains
HTML 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 underneath
account.newbooks.com is used to register new users. This directory is not
protected.
Single signon
In this design, an application running on the Web server hosting the
account.newbooks.com subdomain requires an encrypted Lightweight Third Party
Authentication (LTPA) cookie to identify the authenticated user. Another
application running on the Web server hosting the payment.newbooks.com
subdomain requires the HTTP header, App-User, with the user ID in it. It also
requires basic authentication from the plug-in for Edge Server as the trust basis for
accepting the authenticated user. The plug-in for Edge Server is required to
authenticate itself to this application with the user ID, plugin, and the password,
bookworm.
© Copyright IBM Corp. 2001, 2002
27
In this example, a relationship has been established with another vendor,
newnovels.com, to forward authenticated users through the plug-in for Edge
Server to protected areas of newbooks.com. The gateway at newnovels.com is
required to authenticate itself to the plug-in for Edge Server by using an
authorization header with the user ID, novelgateway, and the password,
bookworm. The gateway places the authenticated user ID in the cookie
Novel-User, as illustrated in Figure 7.
Browser
Web Servers
backend1.newbooks.com
Hosts newbooks.com and
catalog.newbooks.com
Edge Server
newbooks.com
backend2.newbooks.com
LTPA
Cookie
Hosts account.newbooks.com
backend3.newbooks.com
Internet
Hosts payment.newbooks.com
App-User
Caching
Proxy
Gateway
newnovels.com
Novel-User
Internal Gateway
Access Manager
Plug-in
Browser
Figure 7. Web site design for newbooks.com
Configuring the Web site
To provide access control for newbooks.com, the plug-in for Edge Server must be
configured. The configuration begins by defining the global settings in the
osdef.conf configuration file as shown in the following example:
[Global]
# Administrator userid and password needed to run wesosm
update_admin_userid = sec_master
update_admin_password = secret5
# Error message indicating that SSL is required
require_ssl_errorfile = /opt/pdweb-lite/samples/errorpages/require_ssl.htmls
# Form login and logout information
login_method = forms
form_login_file = http://newbooks.com/pub/login.html
form_login_errorfile = http://newbooks.com/pub/loginerr.html
form_logout_url = /pub/logout.html
# Change password information
form_chgpasswd_file = http://newbooks.com/pub/chgpasswd.html
form_chgpasswd_submit_url = /pub/chgpasswd
form_chgpasswd_response_url = /pub/passwdchanged.html
# Single signon tokens to look for
accept_sso = NovelSSO
The [Global] definition in the configuration file specifies settings that apply to
every request handled by the plug-in for Edge Server. In this configuration, the
administrator user ID and password is provided so that the wesosm utility can
create and update the object space. Also, if a request requires a secure connection
and 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.
28
IBM Tivoli Access Manager Plug-in for Edge Server: User’s Guide
This configuration also specifies the login method as forms and lists the login
forms. The login forms can be retrieved from a remote Web server (begins with
http) or can be retrieved from the local file system. If the form has references to
images in it, the URL links in the forms for these images should contain the full
URL 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 path
specified for the logout URL. Also, as the configuration shows, a change password
form is sent to authenticated users when their passwords expire.
Single signon users are accepted from the gateway at newnovels.com, using the
NovelSSO single signon definition. This single signon definition must be defined in
the configuration file.
The [Local] definition in the configuration file specifies settings that apply to
objects on the file system managed by the Edge Server caching proxy. There should
only be one of these definitions in the configuration file. This server definition was
created by the configuration tool and is similar to the following:
[Local: /ESproxy/bookproxy.com]
domains = bookproxy.com
query_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 that
the Edge Server caching proxy is running on. The alias newbooks.com is another
domain name (with its associated IP address) assigned to the same machine. The
plug-in for Edge Server differentiates between requests for objects belonging to the
Edge Server caching proxy and objects belonging to newbooks.com by matching
the requested domain name with a server definition in the configuration file. The
domains setting indicates the domains to which a server definition applies.
The [Remote] definitions in the configuration file specify settings that apply to
external Web servers. There is no limit on the number of server definitions that
you can have. For this example, the following definition would be appropriate for
newbooks.com:
[Remote: /ESproxy/reverse/newbooks.com]
domains = newbooks.com www.newbooks.com
# Query command to create object space
query_command = http://backend1.newbooks.com/cgi-bin/query_contents?dirlist=/home
# Server to map requests
route = http://backend1.newbooks.com/home
The following subdomain definitions are defined for the other sections of the Web
site:
[Remote: /ESproxy/reverse/catalog.newbooks.com]
domains = catalog.newbooks.com
query_command = http://backend1.newbooks.com/cgi-bin/query_contents?dirlist=/catalog
route = http://backend1.newbooks.com/catalog
[Remote: /ESproxy/reverse/account.newbooks.com]
domains = account.newbooks.com
query_command = http://backend2.newbooks.com/cgi-bin/query_contents?dirlist=/
require_ssl = yes
submit_sso = LTPA-COOKIE
route = https://backend2.newbooks.com
Chapter 5. Deploying the plug-in for Edge Server
29
[Remote: /ESproxy/reverse/payment.newbooks.com]
domains = payment.newbooks.com
query_command = http://backend3.newbooks.com/cgi-bin/query_contents?dirlist=/
require_ssl = yes
submit_sso = PayAppSSO PayAppAuth
route = https://backend3.newbooks.com
These server definitions specify the single signon tokens to submit to each Web
server that requires one. The definitions also tell the plug-in for Edge Server to
map the URL to the corresponding Web server hosting the requested content. If
another routing module is to be used in place of the plug-in for Edge Server URL
mapping, simply delete all references to the route keyword from the configuration
file.
The [SSO] definitions in the configuration file define single signon tokens that can
either be accepted or submitted as shown:
[SSO: PayAppSSO]
type = header
name = App-User
format = “<userid>”
[SSO: PayAppAuth]
type = auth_header
format = plugin:bookworm
[SSO: NovelSSO]
type = cookie
name = Novel-User
format = “<userid>”
trust_basis = basic_auth
trust_list = novelgateway:bookworm
After you create single signon definitions, they can be supplied as options to the
accept_sso and submit_sso keywords. Single signon requirements in this example
are now satisfied.
30
IBM Tivoli Access Manager Plug-in for Edge Server: User’s Guide
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 client
authentication information. It also describes how to configure the plug-in for Edge
Server to use the custom shared library for authentication.
A demonstration CDAS library is packaged with the plug-in for Edge Server that
illustrates the implementation of the CDAS functions. You can recompile and
modify 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 33
v “Configuring the plug-in for Edge Server to use a custom shared library” on
page 37
v “CDAS core and utility functions” on page 40
v “CDAS API core function reference” on page 40
Authentication models
This section describes two types of CDAS authentication models:
v “Single authentication model” on page 31
v “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. Rather
than authenticating the user against the Access Manager user registry, the CDAS
shared library authenticates the user against an alternate user registry using an
external authentication mechanism. Ultimately, the CDAS returns an Access
Manager identity to the plug-in for authorization against the Access Manager
object space.
If you create a custom CDAS shared library to handle user name and password
authentication, the client authentication data must contain the user’s name and
password. However, if the shared library is written to handle certificate
authentication, the client authentication data must contain the client’s certificate.
Single authentication model
Figure 8 on page 32 illustrates an example of single authentication CDAS
functionality.
© Copyright IBM Corp. 2001, 2002
31
Access Manager Plug-in
authentication
information
5
User
Registry
Resource
Manager
1
External
Registry
Client
authn
info
2
4
identity
Custom CDAS Shared
Library
3
External
Authentication
Service
Figure 8. Example CDAS authentication model
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 the
resulting Access Manager identity back to the plug-in (step 4). For example, the
shared 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 external
authentication 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 attribute
data 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 identity
with an entry in the Access Manager user registry. If a match is found, the
plug-in treats the client as authenticated. Otherwise, it treats the client as
unauthorized.
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 later
for appropriate use. The credential enables the user to participate in the Access
Manager secure domain.
Dispatched authentication model
You can create a CDAS module that dispatches authentication requests to other
CDAS modules based on a correlating parameter passed in from the plug-in. The
dispatching CDAS module does not perform any authentication itself, but
delegates the authentication and creation of extended attributes to the other CDAS
modules and passes the returned identity from the CDAS modules back to the
plug-in. Using this model, the plug-in can authenticate against different user
registries, based on the URL.
32
IBM Tivoli Access Manager Plug-in for Edge Server: User’s Guide
Figure 9 illustrates an example of the CDAS dispatched functionality.
Access Manager Plug-in
Client
7
User
Registry
authentication
information
Resource
Manager
1
authn
info
2
External
Registry
6
identity
5
CDAS
Dispatcher
3
Custom CDAS
Shared Library
4
External
Authentication
Service
Custom CDAS
Shared Library
Figure 9. Example dispatched authentication model
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 the
resulting Access Manager identity back to the plug-in. For example, the shared
library 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 external
authentication 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 and
extended attributes to the CDAS dispatcher.
6. The CDAS dispatcher module 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 attribute
data 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 identity
with an entry in the Access Manager user registry. If a match is found, the
plug-in treats the client as authenticated. Otherwise, it treats the client as
unauthorized.
Building a custom shared library
Before you build a custom CDAS library, you must determine how you want the
specific authentication and mapping service to operate in your secure domain. Use
the resources of the demonstration CDAS to implement your custom CDAS library.
This section contains the following topics:
Chapter 6. Creating a Cross-domain Authentication Service
33
v
v
v
v
v
“CDAS application development kit”
“Programming the custom shared library”
“User authentication data” on page 35
“Returning the client identity” on page 36
“Compiling the custom shared library” on page 36
CDAS application development kit
The CDAS application development kit (ADK) includes the following components:
v API library (utility functions)
v API header files
v 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 to
demonstrate a functional CDAS
Header files
The following header files are contained in the include directory.
Files
Contents
pdxauthn.h
Definition of function prototypes, client identity, and error codes
used 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 library
A custom CDAS shared library must contain the following APIs:
v xauthn_initialize
For more information, see “Initialization: xauthn_initialize” on page 35
v xauthn_shutdown
For more information, see “Shutdown: xauthn_shutdown” on page 35
v xauthn_authenticate
34
IBM Tivoli Access Manager Plug-in for Edge Server: User’s Guide
For more information, see “Authentication: xauthn_authenticate” on page 35
v xauthn_change_password
For more information, see “Password change: xauthn_change_password” on
page 35
Note: These API functions are described in detail in the “CDAS API core function
reference” on page 40.
Initialization: xauthn_initialize
The plug-in loads the CDAS shared library and initializes it by calling
xauthn_initialize.
This function contains the argc and argv options. These options contain the values
specified in the osdef.conf configuration file. Unlike the C language argv, the
argv[0] array entry is the first option.
Shutdown: xauthn_shutdown
During shutdown, the plug-in calls the xauthn_shutdown function to stop the
CDAS shared library process.
The xauthn_shutdown function is called with the same argc and argv options that
were passed to the xauthn_initialize function when the shared library was first
initialized.
Authentication: xauthn_authenticate
After the CDAS shared library is configured and a request is received, the plug-in
passes the user’s information to the shared library through the
xauthn_authenticate function.
User authentication information is passed to this function in a name/value data
list (xnvlist_t). The content of the name/value data list can vary and is specific to
the configured authentication method.
The xauthn_authenticate function performs the application-specific authentication
process based on the authentication information found in the data list and returns
the resulting client identity (xauthn_identity_t) to the plug-in.
It is important to note that the client identity returned through this function can
contain extended attribute data.
Password change: xauthn_change_password
This function allows the user to make changes to the account password that is
stored in the alternate user registry. Only the user name and password
authentication method supports this function. If the external authentication
mechanism 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 data
list (xnvlist_t). The data list contains the user’s name, the old password, and the
new password.
User authentication data
The plug-in can pass a variety of client authentication information to the shared
library. The information is passed using a name/value list format, where the name
is an identifier that specifies the value type.
Chapter 6. Creating a Cross-domain Authentication Service
35
The information is stored in the xnvlist_t data type. Values can be accessed by
using the utility function xnvlist_get.
The following table lists the user authentication options that the plug-in passes to
the CDAS module.
Authentication method
Name
Value
User name/Password
xauthn_username
xauthn_password
xauthn_new_password
xauthn_ipaddr
xauthn_browser_info
xauthn_extended_handle
xauthn_extended_parameter
-
User name
User password
User new password
User IP address
Browser information
Caching proxy handle
Configuration file option
Certificate
xauthn_cert_dn
xauthn_ipaddr
xauthn_browser_info
xauthn_extended_handle
xauthn_extended_parameter
-
Certificate’s DN
User IP address
Browser information
Caching proxy handle
Configuration file option
Single signon
xauthn_ipaddr
xauthn_browser_info
″Request-URI″
″Request-Headers″
xauthn_extended_handle
xauthn_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 to
WebSEAL, 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’s
API.
v xauthn_extended_parameter provides the CDAS module with a correlating
option from the osdef.conf configuration file.
Returning the client identity
The CDAS shared library is required to return the resulting client identity back to
the 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’s
Guide.
Compiling the custom shared library
The source code for the CDAS demonstration library is located in one of the
following 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.
36
IBM Tivoli Access Manager Plug-in for Edge Server: User’s Guide
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. The
makefile assumes that your compiler and link commands can be invoked from
the current directory and are already in the system’s path.
3. After the customized CDAS module is successfully built, the resulting shared
library is named as follows:
v For AIX systems: libwescdas.a
v For Linux systems: libwescdas.so
v For Solaris systems: libwescdas.so
v For Windows systems: wescdas.dll
4. Stop the plug-in and copy the new CDAS module over the existing CDAS
module 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 “Starting
and stopping the plug-in for Edge Server” on page 13.
Configuring the plug-in for Edge Server to use a custom shared library
This section discusses the specific configuration steps that you must perform so
that the plug-in for Edge Server can use the CDAS interface.
This section contains the following topics:
v
v
v
v
“Configuring a custom shared library” on page 37
“Custom shared library configuration scenario”
“Configuring the demonstration library” on page 38
“Loading the custom shared library” on page 39
Configuring a custom shared library
To configure a custom CDAS shared library, modify the configuration options
included in the osdef.conf file. For more information about osdef.conf
configuration options, see Appendix B, “Object space definition configuration file
reference” on page 51.
Custom shared library configuration scenario
The following scenario illustrates the use of the configuration options. The scenario
shows 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.
Chapter 6. Creating a Cross-domain Authentication Service
37
[Global]
...
cdas_loaded = yes
cdas_init_parameter = ldap /etc/ldap.conf
cdas_init_parameter = cert /etc/cert.conf
[Remote: /ESproxy/reverse/newnovels.com]
domains = newnovels.com
login_method = forms
cdas_enabled = yes
cdas_auth_parameter = ldap
[Remote: /ESproxy/reverse/newpoems.com]
domains = newpoems.com
login_method = certificate
cdas_enabled = yes
cdas_auth_parameter = cert
[Remote: /ESproxy/reverse/newbooks.com]
domains = newbooks.com
login_method = basic
accept_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 accessing
newnovels.com is authenticated with xauthn_extended_parameter = ldap, but a
user accessing newpoems.com is authenticated with xauthn_extended_parameter =
cert. The CDAS module is also invoked to detect pre-authenticated users accessing
newbooks.com.
The CDAS shared library can simultaneously support multiple user repositories
and 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 would
otherwise require multiple CDAS libraries.
Configuring the demonstration library
To configure the CDAS demonstration library, modify the configuration options in
the osdef.conf file. For example, consider the options shown in Figure 10.
[Global]
...
cdas_loaded=yes
cdas_init_parameter=demouser userid demopassword password democertn CertDN validpddn validpdDN
[Local]
cdas_enabled=yes
cdas_auth_parameter=basic_auth
Figure 10. Example of configuration options in osdef.conf
Note: For the demonstration module, basic _auth and cert are valid values for
cdas_auth_parameter.
In this example, the demonstration module is configured with a user ID and
password, the distinguished name of the corresponding Access Manager user, and
the distinguished name of a certificate. The arguments specified by the
cdas_init_parameter are passed to the demonstration module when the
xauthn_initialize function is called. The following values are passed to the
xauthn_initialize routine:
38
IBM Tivoli Access Manager Plug-in for Edge Server: User’s Guide
argc = 8
argv[0] =
argv[1] =
argv[2] =
argv[3] =
argv[4] =
argv[5] =
argv[6] =
argv[7] =
demouser
userid
demopassword
password
democertdn
CertDN
validpddn
validpdDN
Authentication is performed with the xauthn_authenticate function when a
protected resource on the local Web server is accessed. The sample module checks
the value of xauthn_extended_parameter when the xauthn_authenticate function
is called. If basic_auth is passed in, the user ID and password passed in are
checked against the user ID and password that were passed in at initialization
time. If cert is passed in, then the CertDN passed in is checked against the CertDN
that was passed in at initialization time. If authentication is successful, the valid
Access Manager distinguished name is returned to the plug-in for authorization.
Loading the custom shared library
The CDAS shared library is loaded during the initialization of the plug-in. The
CDAS 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 one
of 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 the
following:
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
Chapter 6. Creating a Cross-domain Authentication Service
39
v For Windows systems, replace the wescdas.dll file with the custom CDAS
shared library file.
Note: If a problem occurs loading your custom CDAS shared library, you can
revert back to the demonstration CDAS library.
CDAS core and utility functions
The following core API functions must be implemented in your custom CDAS
shared 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.lib
for Windows, contains the utility functions. To use these functions, you must link
your custom shared library to this file.
The following utility functions facilitate data manipulation:
v xnvlist_get
v xattr_malloc
v
v
v
v
xattr_free
xattr_get
xattr_set
xattr_dup
The xnvlist_get function retrieves the authentication data passed in from the
plug-in. The remaining utilities allow you to construct extended attributes for the
Access Manager identity.
For more information, see the “CDAS API core function reference” on page 40. For
more information about utility functions, see the IBM Tivoli Access Manager
WebSEAL Developer’s Reference.
CDAS API core function reference
This section lists the following core API functions used to implement your CDAS
shared library:
v xauthn_authenticate
v xauthn_change_password
v xauthn_initialize
v xauthn_shutdown
40
IBM Tivoli Access Manager Plug-in for Edge Server: User’s Guide
xauthn_authenticate
Performs the CDAS authentication.
Context
xauthn_status_t
xauthn_authenticate(
xnvlist_t *authnInfo,
xauthn_identity_t *ident
);
Description
The plug-in calls this interface to perform the customer-specific external
authentication. Client authentication information is passed by the plug-in through
the input argument authnInfo.
Refer to “User authentication data” on page 35 for the list of authentication options
that authnInfo can contain.
Based on the authentication information, this function implements the specific
authentication mechanism and stores the resulting client information in ident. This
information is then returned to the plug-in.
It is important to note that the client identity ident can contain additional user
information.
Options
Input
authnInfo
The authnInfo option is a name/value data list containing client authentication
information.
Input/Output
ident
The ident option contains the authenticated user information.
Return Codes
If successful, the function returns XAUTHN_S_COMPLETE.
Possible error codes can be found in the pdxauthn.h header file.
Chapter 6. Creating a Cross-domain Authentication Service
41
xauthn_change_password
Performs the CDAS password change.
Context
xauthn_status_t
xauthn_change_password(
xnvlist_t *authnInfo
);
Description
The plug-in calls this interface to implement a custom password change
mechanism. This interface is supported only for the user name and password
authentication mechanism. Client password change information is passed by the
plug-in through the input argument authnInfo.
Refer to “User authentication data” on page 35 for the list of authentication data
that authnInfo can contain.
Options
Input
authnInfo
The authnInfo option is a name/value data list containing client authentication
information.
Return Codes
If successful, the function returns XAUTHN_S_COMPLETE.
XAUTHN_S_UNSUPPORTED_AUTHN_METHOD is returned if the external
authentication process does not support password changes.
Possible error codes can be found in the pdxauthn.h header file.
42
IBM Tivoli Access Manager Plug-in for Edge Server: User’s Guide
xauthn_initialize
Initializes the CDAS shared library.
Context
xauthn_status_t
xauthn_initialize(
int argc,
const char **argv
);
Description
Use this function to initialize an authentication shared library. The input options
argc and argv are built from options specified for cdas_init_parameter in the
osdef.conf configuration file. The following example definition illustrates the
initialization 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 array
contains the following values:
argv[0] = “-dbms”
argv[1] = “sys.db”
Do not modify input options.
Options
Input
argc
The number of arguments contained in the argv array.
argv
The string arguments passed in the service definition for this service instance.
Return Codes
If successful, the function returns XAUTHN_S_COMPLETE.
Possible error codes can be found in the pdxauthn.h header file.
Chapter 6. Creating a Cross-domain Authentication Service
43
xauthn_shutdown
Shuts down the CDAS shared library.
Context
xauthn_status_t
xauthn_shutdown(
int argc,
const char **argv
);
Description
During normal shutdown, the plug-in calls this interface to perform any shut
down processes that might be required by the custom environment. The input
options argc and argv are built from the options specified with the
cdas_init_parameter directive in the osdef.conf configuration file. The following
example 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 array
contains the following values:
argv[0] = “-dbms”
argv[1] = “sys.db”
Options
Input
argc
The number of arguments contained in the argv array.
argv
The string arguments passed in the service definition for this service instance.
Return Codes
If successful, the function returns XAUTHN_S_COMPLETE.
Possible error codes can be found in the pdxauthn.h header file.
44
IBM Tivoli Access Manager Plug-in for Edge Server: User’s Guide
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 the
following sections:
v
v
v
v
“Removing
“Removing
“Removing
“Removing
the
the
the
the
plug-in
plug-in
plug-in
plug-in
for
for
for
for
Edge
Edge
Edge
Edge
Server
Server
Server
Server
on AIX” on page 45
on Linux” on page 45
on Solaris” on page 46
on Windows” on page 47
Removing the plug-in for Edge Server on AIX
Removal of the plug-in for Edge Server on AIX is a two-part process. You must
first 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. You
can press Enter to accept the default user of sec_master.
A prompt appears requesting the password for the Access Manager
administrator.
4. Enter the password for sec_master.
A series of status messages appear. The plug-in for Edge Server logs in to the
Access 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 the
following:
installp -u -g PDPlgES
Note: Use the –g option only if you want dependent software for the specified
package removed.
The plug-in for Edge Server files are removed. The installp utility exits. Removal
of the plug-in for Edge Server on AIX is complete.
If you want to remove prerequisite Access Manager components, follow the
removal instructions in the IBM Tivoli Access Manager Base Installation Guide.
Removing the plug-in for Edge Server on Linux
Removal of the plug-in for Edge Server on Linux is a two-part process. You must
first 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:
© Copyright IBM Corp. 2001, 2002
45
wslconfig.sh -u
3. Enter the user ID for the Access Manager administrative user. You can press
Enter to accept the default user of sec_master.
A prompt appears requesting the password for the Access Manager
administrator.
4. Enter the password for sec_master.
A series of status messages appear. The plug-in for Edge Server logs in to the
Access Manager policy server and unconfigures itself.
The unconfiguration completes and the wslconfig utility exits.
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 of
the plug-in for Edge Server on Linux is complete.
If you want to remove the Access Manager runtime environment or other Access
Manager components, follow the instructions in the IBM Tivoli Access Manager Base
Installation Guide.
Removing the plug-in for Edge Server on Solaris
Removal of the plug-in for Edge Server on Solaris is a two-part process. You must
first 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
3. Enter the user ID for the Access Manager administrative user. You can press
Enter to accept the default user of sec_master.
A prompt appears requesting the password for the Access Manager
administrator.
4. Enter the password for sec_master.
A series of status messages appear. The plug-in for Edge Server logs in to the
Access Manager policy server and unconfigures itself.
The unconfiguration completes and the wslconfig utility exits.
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 of
the plug-in for Edge Server on Solaris is complete.
If you want to remove the Access Manager runtime environment or other Access
Manager components, follow the instructions in the IBM Tivoli Access Manager Base
Installation Guide.
46
IBM Tivoli Access Manager Plug-in for Edge Server: User’s Guide
Removing the plug-in for Edge Server on Windows
Removal of the plug-in for Edge Server on Windows is a two-part process. You
must 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
3. Enter the user ID for the Access Manager administrative user. You can press
Enter to accept the default user of sec_master.
A prompt appears requesting the password for the Access Manager
administrator.
4. Enter the password for sec_master.
A series of status messages appear. The plug-in for Edge Server logs in to the
Access Manager policy server and unconfigures itself.
The unconfiguration completes and the wslconfig utility exits.
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.
If you want to remove the Access Manager runtime environment or other Access
Manager components, follow the instructions in the IBM Tivoli Access Manager Base
Installation Guide.
Chapter 7. Removing the plug-in for Edge Server
47
48
IBM Tivoli Access Manager Plug-in for Edge Server: User’s Guide
Appendix A. Base configuration file reference
The ibmwesas.conf file contains settings used to initialize the plug-in. These
settings include Access Manager configuration settings and the LTPA & WebSEAL
Fail Over cookie module configuration settings. Additional configuration is
available through the object space definition configuration file. Only settings
requiring user modification have been listed in the following table. All other
settings are properly set by the configuration tool and generally do not require
user modification.
Option
Description
LTPA_Cookie_Enabled
Indicates whether the LTPA cookie module is
initialized using the key file and the key file
password. The default value is no.
LTPA_Cookie_Keyfile
Indicates the LTPA key file containing the cipher
keys used for encryption and decryption. This
file can be generated by WebSphere Application
Server for single signon between the plug-in and
server.
LTPA_Cookie_Keyfile_Password
Indicates the password needed to access the
LTPA key file.
LTPA_Cookie_TTL
Indicates the idle expiration period for an LTPA
cookie that is not refreshed by the plug-in. The
default value is 20 minutes.
LTPA_Cookie_Validation
Indicates whether an LTPA cookie’s signature is
validated for increased security when the plug-in
decrypts the cookie. Note that this validation can
be more CPU intensive than simply decrypting
the cookie. The default value is yes.
WebSEAL_Cookie_Enabled
Indicates whether the WebSEAL Fail Over cookie
module is initialized using the key file and the
key file label. The default value is no.
WebSEAL_Cookie_Keyfile
Indicates the WebSEAL Fail Over cookie key file
containing the cipher keys used for encryption
and decryption. This key file is generated during
the configuration of the plug-in.
WebSEAL_Cookie_Keylabel
Indicates the label used to extract the cipher keys
from the WebSEAL Fail Over cookie key file.
WebSEAL_Cookie_TTL
Indicates the idle expiration period for a
WebSEAL Fail Over cookie that is not refreshed
by the plug-in. The default value is 20 minutes.
ObjectSpace_File
Indicates the location of the object space
definition configuration file. This file tells the
plug-in which branch of the Access Manager
object space is used for authorization, based on
the domain name specified in the URL. This file
also specifies domain specific configuration
settings.
© Copyright IBM Corp. 2001, 2002
49
Option
UserMap_File
50
IBM Tivoli Access Manager Plug-in for Edge Server: User’s Guide
Description
Indicates the location of the user mapping file.
This file tells the plug-in how to map a generic
user ID or certificate distinguished name to an
Access Manager user. This file is used to
determine credentials for certificate users and
users who are authenticated before reaching the
plug-in.
Appendix B. Object space definition configuration file
reference
This appendix provides reference information on the object space definition
configuration file and includes the following sections:
v “Server definitions”
v “Single signon definitions” on page 59
Server definitions
The osdef.conf file defines a mapping between protected objects (URLs) and the
Access Manager object space. Settings for protected Web servers are organized into
server definitions. Within each server definition, server specific settings such as the
domain, login method, the branch of the object space that should be used to
perform authorization checks against users, and other domain specific settings are
configured.
Option
Description
Object space (wesosm only)
update_objectspace
Indicates whether this instance of the plug-in
is responsible for updating the Access
Manager object space with each Web server’s
file system information. The default value is
yes.
update_admin_userid
Indicates the Access Manager administrator
user ID that is required to modify the object
space.
update_admin_password
Indicates the Access Manager administrator
password that is required to modify the object
space.
query_command
Indicates the HTTP request issued to get
object space information. The format of the
data returned by this request should conform
to the WebSEAL query_contents utility.
query_authentication
Indicates the HTTP authorization header
parameter passed to the Web server hosting
query_contents. If this option is not specified,
no authorization header is sent.
query_interval
Indicates the rate at which the object space
underneath this branch is updated. If the
value is set to 0, no updates are performed to
this branch of the Access Manager object
space. The default value is 1440 minutes (1
day).
query_files
Indicates whether the files in each directory
are also queried into the Access Manager
object space. If you intend to attach ACLs only
to directories, then there is no need for Access
Manager to store the Web files in the object
space. The default value is no.
© Copyright IBM Corp. 2001, 2002
51
Option
Description
query_depth
Indicates the depth of subdirectories that is
queried into the Access Manager object space.
Since the object space is stored in the
authorization database, it is beneficial not to
store unnecessary file system information in
this database. It is sufficient to store just the
objects in the Web space that should have
ACLs attached to them. Setting this value to 0
disables depth constraints for this branch in
the object space. The default value is 0.
query_removal
Indicates whether unrecognized or unknown
entries are removed from the object space. If
enabled, all existing entries underneath this
branch that are not found on the Web server,
are removed from the object space. The
default value is yes.
Object space (wesosm and plug-in)
objectspace_branch_reverse
Indicates the object space branch under which
authorization requests take place for reverse
proxy requests not explicitly defined in this
file. The default value is /reverse.
objectspace_branch_forward
Indicates the object space branch under which
authorization requests take place for forward
proxy requests not explicitly defined in this
file. The default value is /forward.
objectspace_filesystem_type
Indicates the type of file system that the
content Web server runs on. This setting
determines how each URL is mapped to an
ACL string to authorize the user. The default
value is unix.
File system types:
v unix - Case sensitive UNIX file system
v win32 - Case insensitive WIN32 file system
General
domains
52
IBM Tivoli Access Manager Plug-in for Edge Server: User’s Guide
Indicates the list of domains for which a
server definition applies to. If the domain
name in a requested URL matches any of the
specified domain names, then the
configuration settings for the request are
retrieved from that server definition.
Option
login_method
Description
Indicates the login method for this domain.
The login method can be associated with a
specific device profile (WebSphere EveryPlace
Suite only). If no device is specified, all
devices use the same login method. The
default value is basic.
Login methods:
v none - The user is not required to login.
v basic - The user logs in using basic
authentication.
v forms - The user logs in using a form.
v certificate - The user logs in using a client
certificate.
Syntax: login method [device profile list]
reverse_dns_lookup
If a URL contains an IP address or incomplete
domain name, this option tells the plug-in to
perform a reverse DNS look up to determine
the fully qualified domain name and make
authorization decisions based on the
expanded name. This option is valid only in
the [Global] section of this file. The default
value is yes.
User information
realm
Indicates the realm to append to each user ID
before authenticating the user. For example, if
the realm is bank_a, then user joe is
authenticated as joe@bank_a. Since Access
Manager uses a single name space for all user
IDs, it might be necessary to create user IDs in
Access Manager with realms appended to
them. This way, identical userids belonging to
different domains can coexist in Access
Manager’s user registry (example: joe@bank_a,
joe@bank_b).
Error pages
require_ssl_errorfile
If a domain requires an SSL connection, and
the established connection is not SSL, then this
error is returned to the user.
require_cert_errorfile
If a domain requires a certificate, and one is
not provided by the user’s browser, then this
error is returned to the user.
Form login
form_login_file
Indicates the form login file used for
authentication. This file can exist locally, or
exist as a remote file specified in a URL. If this
option is unspecified, then form login is not
used for this domain. Form login can be
associated with a specific device profile. If no
device is specified, then all devices will use
the same form.
Syntax: local path | URL [device profile list]
Appendix B. Object space definition configuration file reference
53
Option
form_login_errorfile
Description
Indicates the form error file sent when a user
fails form authentication. This file can be
identical to the login file with the exception of
an error message indicating that the user
failed to login.
Syntax: local path | URL [device profile list]
form_logout_file
Indicates the form logout file sent when a user
submits the logout URL. This file can contain
a message telling the user that the session has
ended. If unspecified, the request passes
through to the backend server.
Syntax: local path | URL [device profile list]
form_logout_url
Indicates the form logout URL submitted by
the user to logout. The plug-in deletes the
user’s session information when the user
makes 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. A
special type can be required for wireless
devices. If no type is specified, then text/html
is assumed.
Syntax: type [device profile list]
form_session_size
Indicates the maximum number of users that
can be simultaneously logged in using form
login. This option is valid only in the [Global]
section of this file. The default value is 10000
users.
form_session_timeout
Indicates the amount of time that a user can
remain idle and not submit a request when
logged in using form login. After this timeout
period, the user is required to login again. The
default value is 20 minutes.
form_signature_login
A form signature is a hidden attribute to value
assignment in a form. If the plug-in receives a
form submission that includes this assignment
when forms is selected as the login method, it
extracts the user ID and password from the
form to authenticate the user. Using this
method for form login, the plug-in can
authenticate a user even if the user had not
previously tried to access a protected Web
page. Note that if this option is specified, the
signature must be found in the form,
otherwise if unspecified, no form signature is
checked.
Syntax: name=value
54
IBM Tivoli Access Manager Plug-in for Edge Server: User’s Guide
Option
Description
form_ssl_security
Indicates the type of security used for secure
form login. When form login is used over a
secure connection, the user ID and password
is stored locally and associated with a secure
session ID. The default value is ssl_sessionId.
Form login security options:
v ssl_sessionId - The SSL session ID is
associated with the user ID and password.
v cookie_sessionId - A transient
undecipherable value, stored in a session
cookie, is associated with the user ID and
password.
form_client_validation
Indicates whether a user’s IP address is
allowed to change when the user authenticates
using form login. If enabled, the user’s IP
address is verified for the duration of the form
login session. The default value is yes.
form_fieldname_postdata
Indicates the hidden field name in
authentication form which stores contents of
saved POST data. The plug-in retrieves saved
POST data from this field when a form is
submitted for authentication. The default
value is PostCacheData.
form_fieldvalue_postdata
Indicates hidden field value in authentication
form, which the plug-in replaces with POST
data. The plug-in replaces this value with the
submitted POST data when an authentication
form is returned to a user who submits a
POST request. The default value is
INSERT.POST.DATA.HERE.
form_fieldname_userid
Indicates the field name of the user ID data
submitted by the POST operation. The default
value is UserID.
form_fieldname_password
Indicates the field name of the password data
submitted by the POST operation. This setting
applies to both the login and change
password form. The default value is
Password.
form_fieldname_newpassword
Indicates the field name of the new password
data submitted by the POST operation when
the user’s password is changed. The default
value is NewPassword.
form_fieldname_verifynewpassword
Indicates the field name of the new password
verification data submitted by the POST
operation when the user’s password is
changed. The default value is
VerifyNewPassword.
Change password
Appendix B. Object space definition configuration file reference
55
Option
form_chgpasswd_submit_url
Description
Indicates the URL where password change
requests are submitted. When a password
change request is submitted to this URL, the
plug-in updates the user’s password with the
submitted information. A user must already be
authenticated before the plug-in changes the
user’s password. This feature is supported
only for the Access Manager user registry.
Syntax: URL
form_chgpasswd_response_url
Indicates the response URL sent to the user
when the password is changed successfully.
This page tells the user that the password has
successfully been changed. The default value
is /.
Syntax: URL
form_chgpasswd_file
Indicates the form sent to the user to change
an expired password when the login method
is basic or forms. When a user’s password
expires, this form is sent to the user for the
user to change the expired password. If this
option is unspecified, no password expiration
check is performed.
Syntax: local path | URL
form_chgpasswd_generic_errorfile
Indicates the error file sent to the user
specifying that a generic error occurred while
the user’s password was being changed.
Syntax: local path | URL
form_chgpasswd_oldpasswd_errorfile
Indicates the error file sent to the user
specifying that the old password was not
correct.
Syntax: local path | URL
form_chgpasswd_newpasswd_errorfile
Indicates the error file sent to the user
specifying that the new password failed the
password policy validation check.
Syntax: local path | URL
form_chgpasswd_verifypasswd_errorfile
Indicates the error file sent to the user
specifying that the new password was
incorrectly verified by the user.
Syntax: local path | URL
Security
cookie_security_enabled
56
IBM Tivoli Access Manager Plug-in for Edge Server: User’s Guide
Indicates whether cookies created over a
secure connection are allowed to flow over
non-secure connections. If enabled, secure
cookies are not allowed to flow over
non-secure connections. The default value is
yes.
Option
require_ssl
Description
Indicates whether a secure connection is
required to access this domain. If a secure
connection is required, the browser is
automatically redirected to the secure site.
Single signon
accept_sso
Indicates single signon tokens to accept for
this domain. The plug-in can skip
authentication if the user has already been
authenticated. The plug-in searches this list
until it finds a single signon token. See the
SSO section for more information on single
signon.
submit_sso
Indicates single signon tokens to submit for
this domain. The plug-in can submit an
authenticated user’s information to the
backend server. The plug-in submits each
single signon token in the list to the backend
server. See the SSO section for more
information on single signon.
Routing
route
Indicates the destination server to forward the
request in reverse proxy configurations. In this
configuration, DNS is configured to map
multiple domain names to the plug-in. The
route option tells the plug-in to route the
request to the corresponding content Web
server. If no route option is specified in this
configuration, the caching proxy routes the
request using its configured mapping rules.
Syntax: URL [default page]
proxy
Indicates the URL of the HTTP proxy server
that all requests are proxied through. For
example, a transcoder proxy server can be
used to convert HTML files into device
compatible files. This option is applicable only
when the request is routed.
Syntax: URL
Caching
user_cache_size
Indicates the maximum number of users that
are stored in the cache table for authenticated
users. When a user authenticates successfully,
the user’s credentials are stored in this cache.
On subsequent requests by the same user, the
user’s credentials are retrieved from this
cache. After this time elapses, the user’s
credentials are verified against the user
registry. This option is valid only in the
[Global] section of this file. The default value
is 20000. When WES support is enabled, set
the MaxSessionCache parameter in
ibmwesas.conf instead.
Appendix B. Object space definition configuration file reference
57
Option
user_cache_timeout
Description
Indicates the maximum amount of time that
an authenticated user is stored in the cache.
After the specified time, the user’s cached
credentials are verified against the user
registry. If verification fails, the user is
required to login again. The default value is
10 minutes. When WES support is enabled, set
the MaxSessionAge parameter in
ibmwesas.conf instead.
Logging
logging_flags
Indicates the category of logging messages
that the plug-in sends to the event log file.
Only messages matching the specified
category are sent to the log file. This option is
valid 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 informational
and debugging log messages. This value can
range from 0 to 5. A higher number means
that more messages are logged. This option is
valid only in the [Global] section of this file.
The default value is 3.
CDAS Support
58
cdas_loaded
Indicates whether the CDAS module is loaded
and initialized. This option is valid only in the
[Global] section of this file. The default value
is no.
cdas_init_parameter
Indicates the initialization parameters that are
passed to the CDAS module. The CDAS
initialization function is called multiple times
if multiple entries are defined. This option is
valid only in the [Global] section of this file.
cdas_enabled
Indicates whether the CDAS module is
invoked when the login method is basic,
forms, or certificate. Using this option, CDAS
can be enabled for some URLs and disabled
for others. Note that CDAS does not need to
be enabled for single signon support. The
default value is no.
cdas_auth_parameter
Indicates the correlating parameters that are
passed to the CDAS module for all requests
matching the server definition in the
configuration file. Using this option, the
CDAS module can choose the authentication
method based on this parameter. There is no
default value.
IBM Tivoli Access Manager Plug-in for Edge Server: User’s Guide
Option
Description
cdas_sso_mapping
Indicates whether the corresponding Access
Manager user ID is submitted for single
signon to the backend server. If disabled, the
original CDAS userid is submitted for single
signon. The default value is yes.
cdas_sso_headers
Indicates whether HTTP headers are
generated for each entry in the extended
attribute list returned from the CDAS module.
If enabled, an HTTP header is generated for
each name/value pair in the extended
attribute list that has a name of the format,
tagvalue_name. The generated HTTP header is
formatted, name: value. The default value is
yes.
Single signon definitions
The plug-in can skip the authentication step if a user has already been
authenticated. The plug-in can also pass single signon information to a Web server
either as an HTTP header or a cookie. The plug-in only accepts pre-authenticated
users from authentication servers that are trusted.
The following single signon definitions are predefined and can be used as
parameters to accept_sso and submit_sso:
v CDAS-MODULE: CDAS Module Single SignOn (SSO accept only)
v LTPA-COOKIE: WebSphere LTPA Cookie
v WEBSEAL-COOKIE: WebSEAL’s Fail Over Cookie
Option
type
Description
Indicates single signon type:
v cookie - Cookie header
v header - HTTP header
v auth_header - Authorization header (SSO
submit only)
v IP_address - IP address (SSO accept only)
name
Indicates the name of the cookie or HTTP header
that contains the user’s SSO information. This
option defaults to Authorization for SSO types
of auth_header and is not applicable for SSO
types of IP_address.
Appendix B. Object space definition configuration file reference
59
Option
format
Description
Indicates the format of the cookie or header
value. The following macros listed can be used
to specify the location of the user ID in the
header or cookie. This option is not applicable
for SSO types of IP_address.
The following predefined macros can be used to
format the single signon information:
v <userid> - User’s ID
v <userdn> - User’s Access Manager
distinguished name
v <pd_cred> - User’s Access Manager EPAC
credentials (SSO submit only)
v <opaque> - Data not recognized by the plug-in
(SSO accept only)
60
sso_realm
Indicates the realm appended to the
pre-authenticated user ID using this single
signon definition, before the user ID is mapped
to an Access Manager distinguished name. The
purpose of this realm is to uniquely identify a
mapping rule for all user IDs from this
pre-authentication server. See the user mapping
file for more information. This option is not
applicable when SSO information is submitted.
default_user
Indicates the default Access Manager user whose
credentials are used to authorize users who have
already been authenticated using this single
signon definition. If a mapping entry is not
found for a pre-authenticated user ID, then the
credentials for this user are used to perform the
authorization. If a mapping entry is not found
for a pre-authenticated userid and this option is
not specified, then the plug-in directs Access
Manager to lookup the user ID in the registry.
This option is not applicable when SSO
information is submitted.
IBM Tivoli Access Manager Plug-in for Edge Server: User’s Guide
Option
trust_basis
Description
Indicates the basis on which the plug-in can trust
the pre-authentication server. The plug-in accepts
a pre-authenticated user only if the
pre-authentication server is trusted by the
plug-in. The default value is IP_address. This
option is not applicable when SSO information is
submitted.
Trust basis options:
v IP_address - The IP address of the
pre-authentication server must match an entry
in the trust_list setting. If no IP address is
specified for the trust_list, then no
pre-authenticated users are accepted using this
single signon definition.
v basic_auth - The pre-authentication server
must authenticate using an Authorization
header. The user ID and password submitted
must match an entry in the trust_list setting.
v proxy_auth - The pre-authentication server
must authenticate using a Proxy-Authorization
header. The user ID and password submitted
must match an entry in the trust_list setting.
v certificate - The pre-authentication server must
authenticate using a client certificate. The
certificate DN must match an entry in the
trust_list setting.
trust_list
Indicates the list of acceptable identifications that
can be presented to the plug-in by the
pre-authentication server. This option is not
applicable when SSO information is submitted.
Appendix B. Object space definition configuration file reference
61
62
IBM Tivoli Access Manager Plug-in for Edge Server: User’s Guide
Appendix C. wesosm command reference
This appendix lists the commands related to the wesosm utility.
Command syntax
The commands in this appendix use the following special characters to define
command syntax:
[]
Identifies elements that are optional. Those not enclosed in brackets are
required.
...
Indicates that you can specify multiple values for the previous element.
Separate multiple values by a space, unless otherwise directed by a
command’s information.
If the ellipsis for an element follows a closing bracket, use the syntax
within the brackets to specify multiple values. For example, to specify two
administrators for the option [–a admin]..., use –a admin1 –a admin2.
If the ellipsis for an element is within the brackets, use the syntax of the
last element to specify multiple values. For example, to specify two hosts
for the option [–h host...], use –h host1 host2.
|
Indicates mutually exclusive information. You can use the element on
either the left or right of the vertical bar.
{}
Delimits a set of mutually exclusive elements when one of them is
required. 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.
© Copyright IBM Corp. 2001, 2002
63
wesosm
Purpose
Creates and maintains the Access Manager object space for the plug-in for Edge
Server
Syntax
wesosm {–start | –stop | –run | –file [output_file]}
[–infile input_file] [–logging [log_file] [-clean]
[–force [branch]] [–fast] [–skiperrors] [–verbose]
Options
64
–clean
Removes all entries from the object space underneath /ESproxy,
which are not found in the configuration file, osdef.conf. Use this
option with care because any attached ACLs are lost when object
space entries are deleted.
–fast
When checking for differences between the Access Manager object
space and the Web server’s file system, this parameter tells the
utility to compare the object names only and not to compare the
types. The Access Manager object type indicates whether the object
space entry is a file or directory. For example, if an existing file on
the Web server is changed to a directory but the name remains the
same, the utility does not detect this when this parameter is
specified.
–file
Starts the object space manager to update the object space once
and then terminates the utility. Rather than updating the Access
Manager object space, the object space information is written to the
specified file.
–force
When starting the object space manager as a daemon, forces the
utility to initially update the object space before waiting on an
interval for the next update. If specified, only the indicated branch
in the object space is updated. Wild cards can be used to specify
the branch.
–infile
Indicates the location of the configuration file, osdef.conf, that is
used to update the object space.
–logging
Indicates if the object space manager should log object space
updates 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 once
and then terminates the utility.
–skiperrors
When updating the object space, the utility does not terminate if it
encounters 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 installs
itself in memory to update the object space on intervals, as
IBM Tivoli Access Manager Plug-in for Edge Server: User’s Guide
configured in the osdef.conf configuration file. This ensures that
the object space is kept in synchronization with the content on the
corresponding Web server.
–stop
Stops the object space manager daemon. The daemon removes
itself from memory and ceases to perform further updates to the
object space.
–verbose
When updating the object space, displays information about the
exact entries that are created, deleted, and modified in the object
space.
Appendix C. wesosm command reference
65
66
IBM Tivoli Access Manager Plug-in for Edge Server: User’s Guide
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 in
other countries. Consult your local IBM representative for information on the
products and services currently available in your area. Any reference to an IBM
product, program, or service is not intended to state or imply that only that IBM
product, program, or service may be used. Any functionally equivalent product,
program, or service that does not infringe any IBM intellectual property right may
be used instead. However, it is the user’s responsibility to evaluate and verify the
operation of any non-IBM product, program, or service.
IBM may have patents or pending patent applications covering subject matter
described in this document. The furnishing of this document does not give you
any license to these patents. You can send license inquiries, in writing, to:
IBM Director of Licensing
IBM Corporation
North Castle Drive
Armonk, NY 10504-1785
U.S.A.
For license inquiries regarding double-byte (DBCS) information, contact the IBM
Intellectual Property Department in your country or send inquiries, in writing, to:
IBM World Trade Asia Corporation
Licensing
2-31 Roppongi 3-chome, Minato-ku
Tokyo 106, Japan
The following paragraph does not apply to the United Kingdom or any other
country where such provisions are inconsistent with local law:
INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS
PUBLICATION ″AS IS″ WITHOUT WARRANTY OF ANY KIND, EITHER
EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS
FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or
implied warranties in certain transactions, therefore, this statement may not apply
to you.
This information could include technical inaccuracies or typographical errors.
Changes are periodically made to the information herein; these changes will be
incorporated in new editions of the publication. IBM may make improvements
and/or changes in the product(s) and/or the program(s) described in this
publication at any time without notice.
Any references in this information to non-IBM Web sites are provided for
convenience only and do not in any manner serve as an endorsement of those Web
sites. The materials at those Web sites are not part of the materials for this IBM
product and use of those Web sites is at your own risk.
IBM may use or distribute any of the information you supply in any way it
believes appropriate without incurring any obligation to you.
© Copyright IBM Corp. 2001, 2002
67
Licensees of this program who wish to have information about it for the purpose
of enabling: (i) the exchange of information between independently created
programs and other programs (including this one) and (ii) the mutual use of the
information which has been exchanged, should contact:
IBM Corporation
2Z4A/101
11400 Burnet Road
Austin, TX 78758
U.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 material
available for it are provided by IBM under terms of the IBM Customer Agreement,
IBM International Program License Agreement or any equivalent agreement
between us.
Information concerning non-IBM products was obtained from the suppliers of
those products, their published announcements or other publicly available sources.
IBM has not tested those products and cannot confirm the accuracy of
performance, compatibility or any other claims related to non-IBM products.
Questions on the capabilities of non-IBM products should be addressed to the
suppliers of those products.
All statements regarding IBM’s future direction or intent are subject to change or
withdrawal without notice, and represent goals and objectives only.
This information contains examples of data and reports used in daily business
operations. To illustrate them as completely as possible, the examples include the
names of individuals, companies, brands, and products. All of these names are
fictitious and any similarity to the names and addresses used by an actual business
enterprise is entirely coincidental.
COPYRIGHT LICENSE:
This information contains sample application programs in source language, which
illustrates programming techniques on various operating platforms. You may copy,
modify, and distribute these sample programs in any form without payment to
IBM, for the purposes of developing, using, marketing or distributing application
programs conforming to the application programming interface for the operating
platform for which the sample programs are written. These examples have not
been thoroughly tested under all conditions. IBM, therefore, cannot guarantee or
imply reliability, serviceability, or function of these programs. You may copy,
modify, and distribute these sample programs in any form without payment to
IBM for the purposes of developing, using, marketing, or distributing application
programs conforming to IBM’s application programming interfaces.
Each copy or any portion of these sample programs or any derivative work, must
include 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 rights
reserved.
68
IBM Tivoli Access Manager Plug-in for Edge Server: User’s Guide
If you are viewing this information softcopy, the photographs and color
illustrations may not appear.
Trademarks
The following terms are trademarks or registered trademarks of International
Business Machines Corporation in the United States, other countries, or both:
AIX
DB2
IBM
IBM logo
OS/390
SecureWay
Tivoli
Tivoli logo
Universal Database
WebSphere
zSeries
z/OS
Java and all Java-based trademarks and logos are trademarks or registered
trademarks of Sun Microsystems, Inc. in the United States and other countries.
Microsoft and Windows are trademarks of Microsoft Corporation in the United
States, other countries, or both. Java and all Java-based trademarks and logos are
trademarks or registered trademarks of Sun Microsystems, Inc. in the United States
and other countries.
UNIX is a registered trademark of The Open Group in the United States and other
countries.
Other company, product, or service names may be trademarks or service marks of
others.
Appendix D. Notices
69
70
IBM Tivoli Access Manager Plug-in for Edge Server: User’s Guide
Printed in U.S.A.
GC23-4685-00