ibm tivoli access manager for weblogic server: user.s guide · ibm tivoli access manager...

IBM Tivoli Access Managerfor WebLogic Server

User’s GuideVersion 4.1

SC32-1137-01

��

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

Second Edition (August 2003)

This edition replaces SC32-0831-00

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

Contents

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

Release information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . viBase information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . viWebSEAL information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . viWeb security information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . viiDeveloper references . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . viiTechnical supplements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . viiRelated publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . viiiAccessing publications online. . . . . . . . . . . . . . . . . . . . . . . . . . . . . xOrdering publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . x

Accessibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xContacting software support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xConventions used in this book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi

Typeface conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiOperating system differences. . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi

Chapter 1. Introduction and overview . . . . . . . . . . . . . . . . . . . . . . . 1Integrating Tivoli Access Manager and WebLogic Server . . . . . . . . . . . . . . . . . . . . . 2

Using Tivoli Access Manager authentication . . . . . . . . . . . . . . . . . . . . . . . . 3Using Tivoli Access Manager authorization . . . . . . . . . . . . . . . . . . . . . . . . 5

Chapter 2. Installation instructions . . . . . . . . . . . . . . . . . . . . . . . . 7Supported platforms. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7Disk and memory requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8Software prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

Tivoli Access Manager policy server . . . . . . . . . . . . . . . . . . . . . . . . . . 8Tivoli Access Manager WebSEAL . . . . . . . . . . . . . . . . . . . . . . . . . . . 9WebLogic Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9Tivoli Access Manager runtime components . . . . . . . . . . . . . . . . . . . . . . . . 9Tivoli Access Manager application development kit . . . . . . . . . . . . . . . . . . . . . 10

Upgrading from a previous release . . . . . . . . . . . . . . . . . . . . . . . . . . . 10Upgrading Tivoli Access Manager for WebLogic . . . . . . . . . . . . . . . . . . . . . . 10Upgrading only WebLogic Server . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

Installation procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13Installing on Solaris . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13Installing on AIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14Installing on HP-UX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15Installing on Linux . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16Installing on Windows. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Chapter 3. Configuration procedures . . . . . . . . . . . . . . . . . . . . . . . 19Part 1: Configuring Tivoli Access Manager Java runtime environment . . . . . . . . . . . . . . . . 19Part 2: Joining a Tivoli Access Manager secure domain . . . . . . . . . . . . . . . . . . . . . 21Part 3: Creating user accounts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23Part 4: Setting CLASSPATH for startWebLogic . . . . . . . . . . . . . . . . . . . . . . . . 25Part 5: Configuring a Custom Realm . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Part 5A: Creating a new Custom Realm . . . . . . . . . . . . . . . . . . . . . . . . . 27Part 5B: Configuring a new caching realm . . . . . . . . . . . . . . . . . . . . . . . . 30Part 5C: Caching credentials and group name mappings . . . . . . . . . . . . . . . . . . . 31

Part 6: Configuring a WebSEAL junction for WebLogic Server . . . . . . . . . . . . . . . . . . 32Part 7: Testing the configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

© Copyright IBM Corp. 2002, 2003 iii

Chapter 4. Administration tasks . . . . . . . . . . . . . . . . . . . . . . . . . 35Using the demonstration application . . . . . . . . . . . . . . . . . . . . . . . . . . . 35Creating test users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36Usage tips . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36Troubleshooting tips . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

Single sign-on failure using forms-based login . . . . . . . . . . . . . . . . . . . . . . . 37Authorization service won’t start on HP-UX . . . . . . . . . . . . . . . . . . . . . . . 37WebLogic Server throws memory exception . . . . . . . . . . . . . . . . . . . . . . . 37

Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

Chapter 5. Removal instructions. . . . . . . . . . . . . . . . . . . . . . . . . 39Removing from Solaris . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39Removing from Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39Removing from AIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40Removing from HP-UX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40Removing from Linux . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

Appendix. Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43Trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

iv IBM Tivoli Access Manager for WebLogic Server: User’s Guide

Preface

Welcome to IBM® Tivoli® Access Manager for WebLogic Server (hereafter referredto as Tivoli Access Manager for WebLogic). This product extends IBM Tivoli AccessManager to support applications written for BEA WebLogic Server.

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

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

The IBM Tivoli Access Manager for WebLogic Server User’s Guide provides installation,configuration, and administration instructions for using IBM Tivoli Access Managerwith WebLogic Server.

Who should read this bookThe target audience for this administration guide includes:v Security administratorsv Network system administratorsv IT architects

Readers should be familiar with:v Internet protocols, including HTTP, TCP/IP, file transfer protocol (FTP), and

Telnetv Deployment and management of WebLogic Server systemsv Security management, including authentication and authorization

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

What this book containsThis document contains the following chapters:v Chapter 1, “Introduction and overview”

Presents an overview of the authentication and authorization services providedby Tivoli Access Manager for WebLogic.

v Chapter 2, “Installation instructions″

Describes how to install Tivoli Access Manager for WebLogic.v Chapter 3, ″Configuration procedures”

Describes how to configure Tivoli Access Manager for WebLogic.

© Copyright IBM Corp. 2002, 2003 v

v Chapter 4, “Administration tasks”Describes how to use the demonstration application, and provides usage tips,troubleshooting information, and limitations.

v Chapter 5, “Removal instructions”Describes how to remove Tivoli Access Manager for WebLogic.

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

Release informationv IBM Tivoli Access Manager Read Me First Card

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

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

Base informationv IBM Tivoli Access Manager Base Installation Guide

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

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

WebSEAL informationv IBM Tivoli Access Manager WebSEAL Installation Guide

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

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

vi IBM Tivoli Access Manager for WebLogic Server: User’s Guide

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

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

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

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

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

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

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

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

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

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

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

Technical supplementsv IBM Tivoli Access Manager Command Reference

GC32-1107-01 (am41_cmdref.pdf)

Preface vii

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

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

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

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

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

The Tivoli Software Library provides a variety of Tivoli publications such as whitepapers, datasheets, demonstrations, redbooks, and announcement letters. The TivoliSoftware Library is available on the Web at:http://www.ibm.com/software/tivoli/library/

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

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

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

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

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

v Microsoft™ Windows™

v Sun Solaris Operating Environment

DB2 information is available at:

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

viii IBM Tivoli Access Manager for WebLogic Server: User’s Guide

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


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

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

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

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

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

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

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

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

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

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

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

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

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

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

Preface ix

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

x IBM Tivoli Access Manager for WebLogic Server: User’s Guide


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

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

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

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

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

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

Typeface conventionsThe following typeface conventions are used in this reference:

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

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

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

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

Preface xi

xii IBM Tivoli Access Manager for WebLogic Server: User’s Guide

Chapter 1. Introduction and overview

IBM Tivoli Access Manager for WebLogic Server (hereafter referred to as TivoliAccess Manager for WebLogic) is an extension to IBM Tivoli Access Manager fore-business (Tivoli Access Manager) that implements a Custom Realm for BEAWebLogic Server. The Custom Realm provides a user registry that is administeredby Tivoli Access Manager. User passwords can be authenticated to the TivoliAccess Manager user registry and group membership in the user registry can beused to affect authorization decisions made by WebLogic Server. The CustomRealm can also be used with IBM Tivoli Access Manager WebSEAL (WebSEAL) tosupport end-user single sign-on.

Tivoli Access Manager for WebLogic enables WebLogic Server applications to useTivoli Access Manager security without requiring any coding or deploymentchanges.

Tivoli Access Manager for WebLogic implements a Custom Realm that uses thesecurity services provided by a Tivoli Access Manager secure domain. The securedomain must be deployed prior to installation of Tivoli Access Manager forWebLogic.

Users who are new to Tivoli Access Manager should review the Tivoli AccessManager security model before deploying a secure domain. A brief summary of thesecurity model is presented here.

The Tivoli Access Manager security model

Tivoli Access Manager is a complete authorization and network security policymanagement solution that provides end-to-end protection of resources overgeographically dispersed intranets and extranets.

Tivoli Access Manager features state-of-the-art security policy management. Inaddition, it supports authentication, authorization, data security, and resourcemanagement capabilities. You use Tivoli Access Manager in conjunction withstandard Internet-based applications to build highly secure and well-managedintranets and extranets.

At its core, Tivoli Access Manager provides:v An authentication framework

Tivoli Access Manager supports a wide range of authentication mechanisms.v An authorization framework

Tivoli Access Manager provides a framework for authorization policymanagement. Authorization policy is managed centrally and distributedautomatically to access enforcement points across the enterprise, including theTivoli Access Manager. The Tivoli Access Manager authorization service providespermit and deny decisions on access requests for native Tivoli Access Managerservers and third-party applications.

WebSEAL is the Tivoli Access Manager resource security manager for Web-basedresources. WebSEAL is a high performance, multi-threaded Web server that applies

© Copyright IBM Corp. 2002, 2003 1

fine-grained security to protected Web resources. WebSEAL can provide singlesign-on solutions and incorporate back-end Web application server resources intoits security policy.

Getting started with Tivoli Access Manager product documentation

You can learn more about Tivoli Access Manager, including information necessaryto make deployment decisions, by reviewing the documentation for IBM TivoliAccess Manager. Start with the following guides:v IBM Tivoli Access Manager Base Installation Guide

This guide describes how to plan, install, and configure a Tivoli Access Managersecure domain. A series of easy installation scripts enable you to quickly deploya fully functional secure domain. These scripts are very useful when prototypinga secure domain that meets your security policy requirements.

v IBM Tivoli Access Manager Base Administrator’s Guide

This document presents an overview of the Tivoli Access Manager securitymodel for managing protected resources. This guide also describes how toconfigure the Tivoli Access Manager servers that make access control decisions.In addition, detailed instructions describe how to perform important tasks suchas declaring security policies, defining protected object namespaces, andadministering user and group profiles.

v IBM Tivoli Access Manager WebSEAL Administrator’s Guide

This guide provides a comprehensive set of procedures and referenceinformation for managing resources in a secure Web domain. The guide alsopresents overview and concept material that describes the wide range ofWebSEAL functionality.

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

This guide describes how to use the Tivoli Access Manager authorization API toadd security to third party applications. This document includes a description ofthe svrsslcfg utility. This utility is used during the configuration of Tivoli AccessManager for WebLogic.

The IBM Tivoli Access Manager documentation is available from the IBM TivoliCustomer Support Web site.

Integrating Tivoli Access Manager and WebLogic ServerTivoli Access Manager for WebLogic, Version 4.1, supports a Custom Realm for thefollowing releases:v WebLogic Server 6.1v WebLogic Server 7.0, running in compatibility mode only

Compatibility mode security is used to run WebLogic Server 6 securityconfigurations within WebLogic Server 7.0.Note that this release of Tivoli Access Manager for WebLogic does not supportthe Security Service Provider Interface that is new to WebLogic Server 7.0.

Tivoli Access Manager provides the following integration points with WebLogicServer:v Centralized access control.

– A centralized user registry is shared by the Tivoli Access Manager policyserver and WebLogic Server. The Tivoli Access Manager product distributionincludes IBM Directory. The Tivoli Access Manager Custom Realm allows this

2 IBM Tivoli Access Manager for WebLogic Server: User’s Guide

registry, as well as other third-party registries that are supported by TivoliAccess Manager, to be used as the WebLogic registry.

– The changing of a user’s Tivoli Access Manager group memberships altersthat user’s access privileges to WebLogic’s Java™ 2 Enterprise Edition (J2EE)resources in accordance with the group-to-role mappings contained in thedeployment descriptors for each WebLogic Server application.

– WebSEAL controls access to Uniform Resource Locators (URLs) thatcorrespond to objects in the Tivoli Access Manager policy database. Theseobjects can be static URL strings or can be represented by pattern matching.

v Integrated authorizationIntegrated authorization is achieved by WebLogic Server’s use of the TivoliAccess Manager Custom Realm to determine which users belong to the groupsthat are mapped to the J2EE application’s security roles. This means that a TivoliAccess Manager administrator can affect the authorization decisions of WebLogicServer through group membership within the Tivoli Access Manager registry.

v Single sign-on through the use of WebSEALSingle sign-on is achieved by combining the one-time user authentication ofWebSEAL with the validation of user identity by the Tivoli Access ManagerCustom Realm.This allows many authentication mechanisms, including certificates, to be usedwithout any impact to the target application.The WebLogic server’s trust of WebSEAL is achieved through a combination of aWebSEAL junction and the use of the Tivoli Access Manager Custom Realm. Ajunction is a network connection between a WebSEAL server and an applicationserver, such that:1. There is trust between WebSEAL and the application server.2. WebSEAL protects both its own resources and the resources on the

junctioned application server.

Using Tivoli Access Manager authenticationTivoli Access Manager can be used to provide authentication for either externalusers or internal users. Authentication for external users uses WebSEAL singlesign-on. For optimum network security, each WebLogic Server that receives accessrequests from external users through WebSEAL should not accept access requestsfrom internal users. The following sections describe how authentication is handledfor both external and internal users.

Authenticating external usersThe diagram below displays the model for the processing of requests from externalusers for access to protected resources.

Chapter 1. Introduction and overview 3

1. An external user requests access to a protected resource. The request is receivedby WebSEAL before entering the secure network of the enterprise. (See Figure1, arrow 1)

2. WebSEAL authenticates the user in the Tivoli Access Manager secure domain.(See Figure 1, arrow 2)WebSEAL supports the following authentication methods: username andpassword, certificates, username and RSA SecureID, or a custom authenticationmechanism.WebSEAL applies its own authorization decision based on the requested URLand the Tivoli Access Manager access policy. WebSEAL can applyconsiderations such as account validity, time-of-day, and authenticationmechanism.

3. When the user’s request has been authorized, WebSEAL forwards the request tothe WebLogic server. The request includes the external username and a specialpassword within the basic authentication header. The special password belongsto the configured_user, and allows the Tivoli Access Manager Custom Realm toconfirm WebSEAL as the origin of the request. (See Figure 1, arrow 3)For more information about the configured_user, see Chapter 3, “Configurationprocedures”, on page 19.

4. The WebLogic server transparently passes the authenticated user identity andpassword to the Tivoli Access Manager Custom Realm. (See Figure 1, arrow 4)

5. The Tivoli Access Manager Custom Realm uses Tivoli Access Managerauthentication services to verify that the password provided by WebSEAL iscorrect for the configured_user described above. That is, this password providesthe basis of trust that the request’s origin is WebSEAL. (See Figure 1, arrow 5)

The request is now ready for authorization.

Authenticating internal usersThe diagram below displays the model for the processing of requests for access toprotected resources by internal users who do not go through a WebSEAL junction:

WebLogic Server

J2EEApplicationDeploymentDescriptors

WebLogicUser

Authentication

Access ManagerCustom Realm

for WebLogic Server

WebLogicAccess

Managers

ExternalBrowser

AccessManager

WebSEAL

Access ManagerPolicy Server

Policy Database

1

2

3

4

5

B

A

User Registry

AuthenticatingExternal Users

Figure 1. Tivoli Access Manager provides single sign-on authentication for external users


1. Internal user sends request for access to a protected resource. (See Figure 2,arrow 1)

2. The WebLogic user authentication module sends the user identity to the TivoliAccess Manager Custom Realm. (See Figure 2,, arrow 2)

3. The Tivoli Access Manager Custom Realm sends the authentication request tothe user registry. (See Figure 2, arrow 3)If authentication is successful, the Tivoli Access Manager Custom Realm returnsthe username to WebLogic Server as the authenticated user.

The request is now ready for authorization.

Using Tivoli Access Manager authorizationThe authorization process occurs as follows:1. When a request for a J2EE resource is received by WebLogic Server, it checks

the relevant deployment descriptor information to determine if access to theresource is restricted to certain roles. (See Figure 1 or Figure 2, arrow A)

2. If the request requires the user to assume a role, the WebLogic Server queriesthe Tivoli Access Manager Custom Realm to determine whether the requestinguser is a member of any of the groups that are mapped to the role. (See Figure1 or Figure 2, arrow B)

3. The Tivoli Access Manager Custom Realm consults the Tivoli Access Managerauthorization server to determine if the current user is a member of the group.If the user is a member of a group that is mapped to a permitted role, access isgranted. Otherwise, access is denied. (See Figure 1, arrow 5, or Figure 2, arrow3)

WebLogic Server

J2EEApplicationDeploymentDescriptors

WebLogicUser

Authentication

Access ManagerCustom Realm

for WebLogic Server

WebLogicAccess

Managers

Access ManagerPolicy Server

Policy Database

2

3

B

A

User Registry

1InternalBrowser

AuthenticatingInternalUsers

Figure 2. Tivoli Access Manager Custom Realm provides authentication of internal users

Chapter 1. Introduction and overview 5

Chapter 2. Installation instructions

This chapter contains the following topics:v “Supported platforms”v “Disk and memory requirements” on page 8v “Software prerequisites” on page 8v “Upgrading from a previous release” on page 10v “Installation procedures” on page 13

Supported platformsTivoli Access Manager for WebLogic, Version 4.1, supports a Custom Realm for thefollowing releases:v WebLogic Server 6.1v WebLogic Server 7.0, running in compatibility mode only.

Compatibility mode security is used to run WebLogic Server 6 securityconfigurations within WebLogic Server 7.0.Note that Tivoli Access Manager for WebLogic Version 4.1 does not support theSecurity Service Provider Interface that is new to WebLogic Server 7.0.

Tivoli Access Manager for WebLogic is supported on the operating system releasesdescribed in the following table. Note that currently WebLogic Server Version 7.0 isnot supported on all operating system releases supported by Tivoli AccessManager Version 4.1.

Note also that BEA provides a number of service packs for WebLogic Server. Theservice pack level can differ across the different operating system releases that BEAsupports. To determine the proper service pack for each operating system, usersshould consult the BEA platform certification tables:http://www.weblogic.com/platforms/index.html

Table 1. Supported platforms

Tivoli Access Manager for WebLogic supported platforms

Operating System Release BEA WebLogic Server Releases

AIX 4.3.3AIX 5.1.0

WebLogic Server 6.1

Note: WebLogic Server 7.0 does not supportAIX 4.3.3 or AIX 5.1.0.

Solaris Operating Environment 7 WebLogic Server 6.1

Note: WebLogic Server 7.0 does not supportSolaris Operating Environment 7.


Table 1. Supported platforms (continued)

Solaris Operating Environment 8

HP-UX 11.0

HP-UX 11i

Microsoft Windows 2000 Advanced Serverwith Service Pack 2

Microsoft Windows NT 4.0 with ServicePack 6A

Red Hat Linux 7.2

WebLogic Server 6.1

WebLogic Server 7.0

Disk and memory requirementsTivoli Access Manager for WebLogic has the following disk and memoryrequirements:v 64 MB RAM

This is the amount of memory needed in addition to the memory requirementsspecified by WebLogic Server and by any other Tivoli Access Managercomponents. The additional 64 MB RAM is used to optimize cachingperformance.The amount of memory needed by other Tivoli Access Manager components willdepend on which Tivoli Access Manager components are installed on the hostsystem. For more information, see the IBM Tivoli Access Manager Base InstallationGuide.

v 250 KB (kilobytes) disk spaceThis requirement is in addition to the disk space required by WebLogic Serverand by any other Tivoli Access Manager components.

Software prerequisitesSuccessful installation of Tivoli Access Manager for WebLogic requires theprerequisites described in the following sections:v “Tivoli Access Manager policy server”v “Tivoli Access Manager WebSEAL” on page 9v “WebLogic Server” on page 9v “Tivoli Access Manager runtime components” on page 9

Tivoli Access Manager policy serverA Tivoli Access Manager secure domain must be established prior to installingTivoli Access Manager for WebLogic.

The Tivoli Access Manager secure domain is established when you install theTivoli Access Manager policy server. This policy server is distributed on the IBMTivoli Access Manager Base CD for your operating system.

Typically, the Tivoli Access Manager policy server is installed on a system otherthan the system that hosts Tivoli Access Manager for WebLogic.


Tivoli Access Manager WebSEALTivoli Access Manager WebSEAL (WebSEAL) provides Web-based security servicesthat can be used by Tivoli Access Manager for WebLogic. When combined withWebSEAL junctions, Tivoli Access Manager for WebLogic can be used to provide aWebSEAL to WebLogic Server single sign-on solution.

WebSEAL is a prerequisite for enabling the Tivoli Access Manager single sign-onsolution. It is not a prerequisite for installing Tivoli Access Manager for WebLogic.WebSEAL is typically installed on a system other than the system that hosts TivoliAccess Manager for WebLogic.

For complete WebSEAL installation instructions, see the IBM Tivoli Access ManagerWebSEAL Installation Guide.

WebLogic ServerWebLogic Server must be installed and configured on the system that will hostTivoli Access Manager for WebLogic. WebLogic Server is currently installedwithout a default Custom Realm and is launched using the startWebLogiccommand.

WebLogic Server is distributed with the necessary Java Runtime Environment.Tivoli Access Manager for WebLogic uses this same Java Runtime Environment.Successful installation of WebLogic Server satisfies the Tivoli Access Manager forWebLogic prerequisite for a Java Runtime Environment.

WebLogic Server 7.0 compatibility mode requirementAttention: To use WebLogic Server 7.0 with Tivoli Access Manager for WebLogic,you must boot WebLogic Server 7.0 in compatibility mode the first time WebLogicServer is started. If WebLogic Server 7.0 is booted in 7.0 mode, it is no longerpossible to access existing domains in compatibility mode.

When you boot WebLogic Server 7.0 for the first time, make sure that you initializecompatibility security by following the steps in the WebLogic Serverdocumentation for booting in compatibility mode. This ensures that WebLogicServer 7.0 will, on future reboots, automatically start in compatibility mode.

IBM Java Runtime Environment Version 1.3 on AIX

On AIX systems, WebLogic Server requires IBM Java Runtime Environment Version1.3. WebLogic Server distributes this Java Runtime Environment and installs itduring the WebLogic Server installation. Tivoli Access Manager for WebLogic usesthis same version of the Java Runtime Environment.

Note: WebLogic Server 7.0 does not support AIX.

Tivoli Access Manager for WebLogic uses Java Native Interface code. Ensure thatthe AIX environment is configured as described in:/BEA_installation_directory/jdk130/README.HTML

Tivoli Access Manager runtime componentsThe following runtime components from the Tivoli Access Manager Base must beinstalled on the system that will host Tivoli Access Manager for WebLogic:v Tivoli Access Manager runtime environmentv Tivoli Access Manager Java runtime environment

Chapter 2. Installation instructions 9

The Tivoli Access Manager secure domain must be established prior to configuringthese components on the system that will host Tivoli Access Manager forWebLogic.

TheTivoli Access Manager runtime environment provides trusted, securecommunication with the Tivoli Access Manager secure domain, and the ability toauthenticate users against the domain user registry. The Tivoli Access ManagerJava runtime environment provides Java-based administration facilities. These Javaclasses extend the Java runtime environment that is used by WebLogic Server.

The Tivoli Access Manager runtime environment and Tivoli Access Manager Javaruntime environment are distributed on the IBM Tivoli Access Manager Base CDfor each supported operating system. For installation instructions, see the IBMTivoli Access Manager Base Installation Guide.

Tivoli Access Manager application development kitThe Tivoli Access Manager application development kit contains a demonstrationapplication and a sample authorization API application configuration file. You canuse this application and configuration file to test that the Tivoli Access Managerauthorization API is correctly configured.

Note, however, that Tivoli Access Manager for WebLogic ships a defaultconfiguration file called PDRealm.conf. You can use this configuration file to verifythe authorization API configuration, instead of using the sample authorization APIconfiguration file supplied in the application development kit. Thus, installation ofthe application development kit is optional.

The kit is distributed on the IBM Tivoli Access Manager Base CD for eachsupported operating system. For installation instructions, see the IBM Tivoli AccessManager Base Installation Guide.

Upgrading from a previous releaseYou can upgrade Tivoli Access Manager for WebLogic from a previous release. Theupgrade process replaces the product files without changing the existing customrealm configuration data.

Upgrade to Tivoli Access Manager for WebLogic Version 4.1 is supported from thefollowing releases:v Tivoli Access Manager for WebLogic Server, Version 3.9v Tivoli Policy Director for WebLogic Server, Version 3.8

BEA supports an upgrade of WebLogic Server Version 6.1 to WebLogic ServerVersion 7.0.

This section describes the following upgrade scenarios:v “Upgrading Tivoli Access Manager for WebLogic”v “Upgrading only WebLogic Server” on page 12

Upgrading Tivoli Access Manager for WebLogicThis section describes the following upgrades:

Table 2. Upgrading Tivoli Access Manager for WebLogic

Upgrade from: Upgrade to:


Table 2. Upgrading Tivoli Access Manager for WebLogic (continued)

Tivoli Access Manager for WebLogic Version3.9, with WebLogic Server, Version 6.1

Tivoli Access Manager for WebLogic, Version4.1, with WebLogic Server, Version 6.1

Policy Director for WebLogic Server, Version3.8, with WebLogic Server, Version 6.1



Policy Director for WebLogic Server, Version3.8, with WebLogic Server, Version 6.1

Complete the following steps:1. Stop the WebLogic Server.2. If you do not need to upgrade WebLogic Server, skip this step. Go to the next

step.If you need to upgrade WebLogic Server from Version 6.1 to Version 7.0, do itnow. Follow the instructions in “Upgrading only WebLogic Server” on page 12.

3. If the Tivoli Access Manager for WebLogic authorization server files that getgenerated by svrsslcfg are located in the Tivoli Access Manager for WebLogicinstallation directory, make a backup copy of them. The files includes:v The configuration file PDRealm.conf.v A key file (filename ending in .kdb)v A stash file (filename ending in .sth)

Note that during initial configuration with svrsslcfg, the configuration file wasspecified by the –f option, and the directory containing the key file and stashfile was specified by the –d option.

4. Remove Tivoli Access Manager for WebLogic Version 3.9.See the Tivoli Access Manager for WebLogic Version 3.9 User Guide for instructionsspecific to your operating system.Attention: Do not unconfigure the custom realm before removing TivoliAccess Manager for WebLogic Version 3.9.

5. Upgrade the prerequisite Tivoli Access Manager base packages and securedomain from Version 3.9 to Version 4.1.Determine which Tivoli Access Manager base packages are installed on thecomputer that hosts Tivoli Access Manager for WebLogic. Each deploymentincludes:v Tivoli Access Manager runtime environmentv Tivoli Access Manager Java runtime

Depending on the topology of the Tivoli Access Manager secure domain, thehost computer might also include:v Tivoli Access Manager policy serverv Tivoli Access Manager authorization server

When the local computer contains the policy server and authorization server,you can upgrade all Tivoli Access Manager base packages at one time.

When the local computer system does not include the policy server andauthorization server, you must first upgrade the secure domain on thecomputer system that hosts those servers. When the policy server and


authorization server are upgraded to Version 4.1, you can then upgrade thebase runtime packages (Tivoli Access Manager runtime environment and Javaruntime) on the local computer.

For instructions on upgrading Tivoli Access Manager base packages and thesecure domain, see IBM Tivoli Access Manager Base Installation Guide. Completethe instructions in that document before continuing to the next step.

6. Tivoli Access Manager for WebLogic Version 3.9 deployments optionally useTivoli Access Manager WebSEAL to support single sign-on. If your deploymentuses WebSEAL, upgrade WebSEAL from Version 3.9 to Version 4.1 now.For upgrade instructions, see IBM Tivoli Access Manager WebSEAL InstallationGuide.

7. Install Tivoli Access Manager for WebLogic Version 4.1. Follow the instructionsfor your operating system in “Installation procedures” on page 13.

8. It is not necessary to configure Tivoli Access Manager for WebLogic. Theconfiguration information from the previous version is retained. If you backedup PDRealm.conf, a key file, or a stash file before removing Version 3.9 of TivoliAccess Manager for WebLogic, restore them now.Verify that the custom realm is correctly configured by following the steps in“Part 7: Testing the configuration” on page 34.

Note: If you are also upgrading WebLogic Server from 6.1 to 7.0, the BEAupgrade instructions ensure that the configuration information isretained.

Attention: To use WebLogic Server 7.0 with Tivoli Access Manager forWebLogic, you must boot WebLogic Server 7.0 in compatibility mode the firsttime WebLogic Server is started. If WebLogic Server 7.0 is booted in 7.0 mode,it is no longer possible to access existing domains in compatibility mode.

When you boot WebLogic Server 7.0 for the first time, make sure that youinitialize compatibility security by following the steps in the WebLogic Serverdocumentation for booting in compatibility mode. This ensures that WebLogicServer 7.0 will, on future reboots, automatically start in compatibility mode.

Upgrading only WebLogic ServerThis section describes the following upgrade:

Table 3. Upgrading WebLogic Server from 6.1 to 7.0

Upgrade from: Upgrade to:



Tivoli Access Manager for WebLogic Version 4.1 supports both WebLogic ServerVersion 6.1 and WebLogic Server Version 7.0 (in compatibility mode). When youhave configured Tivoli Access Manager for WebLogic with WebLogic Server 6.1,and want to upgrade WebLogic Server to Version 7.0, follow the upgradeprocedures that BEA provides for upgrading a WebLogic 6.x domain to a WebLogic7.0 domain.

When the BEA upgrade procedures are completed, the Version 7.0 WebLogic Serverstarts in compatibility mode.


In this upgrade scenario, no changes are required to either Tivoli Access Managerfor WebLogic or the prerequisite Tivoli Access Manager packages, including theoptional WebSEAL package.

Attention: To use WebLogic Server 7.0 with Tivoli Access Manager for WebLogic,you must boot WebLogic Server 7.0 in compatibility mode the first time WebLogicServer is started. If WebLogic Server 7.0 is booted in 7.0 mode, it is no longerpossible to access existing domains in compatibility mode.

When you boot WebLogic Server 7.0 for the first time, make sure that you initializecompatibility security by following the steps in the WebLogic Serverdocumentation for booting in compatibility mode. This ensures that WebLogicServer 7.0 will, on future reboots, automatically start in compatibility mode.

Installation proceduresComplete the instructions in the section for your operating system:v “Installing on Solaris”v “Installing on AIX” on page 14v “Installing on HP-UX” on page 15v “Installing on Linux” on page 16v “Installing on Windows” on page 17

Installing on SolarisThe Tivoli Access Manager for WebLogic installation separates file extraction frompackage configuration. Use pkgadd to install software packages on SolarisOperating Environment (hereinafter referred to as Solaris). Then configure TivoliAccess Manager manually.

Note: If you have already installed and configured Tivoli Access Manager forWebLogic and need to reinstall it, you must first unconfigure and remove it.See “Removing from Solaris” on page 39.

To install Tivoli Access Manager for WebLogic on Solaris, complete the followinginstructions:1. Log in as user root.2. Verify that the software prerequisites, including the required components from

the Tivoli Access Manager base, have been satisfied. See “Softwareprerequisites” on page 8.Attention: To use WebLogic Server 7.0 with Tivoli Access Manager forWebLogic, you must boot WebLogic Server 7.0 in compatibility mode the firsttime WebLogic Server is started. If WebLogic Server 7.0 is booted in 7.0 mode,it is no longer possible to access existing domains in compatibility mode.


3. Mount the IBM Tivoli Access Manager Web Security CD on /cdrom/cdrom0.4. Change directory to /cdrom/cdrom0/solaris.5. Enter the following command to install the Tivoli Access Manager for

WebLogic package:


# pkgadd -d . PDWLS

When prompted to continue, type y and press Enter. Files are extracted fromthe CD and installed on the hard disk. A message displays indicating thatinstallation of the Tivoli Access Manager package was successful. The pkgaddutility exits.

6. Next, configure Tivoli Access Manager for WebLogic. Go to Chapter 3,“Configuration procedures”, on page 19.

Installing on AIXThe Tivoli Access Manager for WebLogic installation separates file extraction frompackage configuration. Use SMIT to install software packages on AIX. Thenconfigure Tivoli Access Manager for WebLogic manually.

Note: If you have already installed and configured Tivoli Access Manager forWebLogic and need to reinstall it, you must first unconfigure and removethe Tivoli Access Manager for WebLogic package. See “Removing from AIX”on page 40.

To install Tivoli Access Manager for WebLogic on AIX complete the followinginstructions:1. Log in as root.2. Verify that the software prerequisites, including the required components from

the Tivoli Access Manager base, have been satisfied. See “Softwareprerequisites” on page 8.Attention: To use WebLogic Server 7.0 with Tivoli Access Manager forWebLogic, you must boot WebLogic Server 7.0 in compatibility mode the firsttime WebLogic Server is started. If WebLogic Server 7.0 is booted in 7.0mode, it is no longer possible to access existing domains in compatibilitymode.


3. Insert the IBM Tivoli Access Manager Web Security CD into the CD drive.4. Enter the following command at a shell prompt:

# smit

The SMIT utility starts.5. Select Software Installation and Maintenance. Select Install and Update

Software.v On AIX 4.3 systems, select Install and Update Software from LATEST

Available Software.v On AIX 5.1 systems, select Install Software.

6. When prompted for input device:v On AIX 4.3, enter the location where the CD is mountedv On AIX 5.1, enter the directory on the CD containing the installation

packages. For example:/<mount_point>/usr/sys/inst.images

Click OK.


7. Click the List button for SOFTWARE to install.A Multi-select List window displays the list of IBM Tivoli Access Managersoftware packages.

8. Select the Access Manager for WebLogic package (PDWLS). Click OK.9. The Install and Update Software from LATEST Available Software window

opens.10. Verify that the default value of yes is present in the field labeled

AUTOMATICALLY install requisite software.11. Set other fields to values appropriate to your installation. In most cases, you

can accept the default values. Click OK.12. A message box displays asking if you are sure you want to install this

package. Click OK.The package files are installed. Several status messages are displayed. A finalstatus message indicates success upon completion of file extraction.

13. Click Done. Click Cancel to exit SMIT.14. Next, configure Tivoli Access Manager for WebLogic. Go to: Chapter 3,

“Configuration procedures”, on page 19.

Installing on HP-UXThe Tivoli Access Manager for WebLogic installation separates file extraction frompackage configuration. Use swinstall to install software packages on HP-UX. Thenconfigure Tivoli Access Manager for WebLogic manually.

Note: If you have already installed and configured Tivoli Access Manager forWebLogic and need to reinstall it, you must first unconfigure and remove it.See “Removing from HP-UX” on page 40.

To install Tivoli Access Manager for WebLogic on HP-UX, complete the followingsteps:1. Log in as user root.2. Verify that the software prerequisites, including the required components from



3. Insert the IBM Tivoli Access Manager Web Security CD in the drive. Use thefollowing commands to mount the CD:# nohup /usr/sbin/pfs_mountd &# nohup /usr/sbin/pfsd &# /usr/sbin/pfs_mount <mount_device> <mount_point>

For example:# /usr/sbin/pfs_mount /dev/dsk/c0t0d0 /cdrom

4. Change directory to hp.


5. Enter the following command to install the Tivoli Access Manager forWebLogic package:# swinstall -s /temp_directory PDWLS

A message displays indicating that the analysis phase has succeeded. Anothermessage displays indicating that the execution phase is beginning. Files areextracted from the CD and installed on the hard disk. A message displaysindicating that the execution phase has succeeded. The swinstall utility exits.

6. Verify that SHLIB_PATH is set to either /usr/lib or /opt/ibm/gsk5/lib. If it isnot set it, enter:export SHLIB_PATH=/opt/ibm/gsk5/lib

When this variable is not set, the Tivoli Access Manager authorization servicemay not be able to access the IBM Global Security Toolkit (GSKIT) libraries.

7. Next, configure Tivoli Access Manager for WebLogic. Go to: Chapter 3,“Configuration procedures”, on page 19.

Installing on LinuxThe Tivoli Access Manager for WebLogic installation separates file extraction frompackage configuration. Use rpm to install software packages on Linux. Thenmanually configure Tivoli Access Manager for WebLogic.

Note: If you have already installed and configured Tivoli Access Manager forWebLogic and need to reinstall it, you must first unconfigure and remove it.See “Removing from Linux” on page 41.

To install Tivoli Access Manager for WebLogic on Linux, complete the followingsteps:1. Log in as user root.2. Verify that the software prerequisites, including the required components from



3. Set the following environment variable:

# export LD_PRELOAD=/usr/lib/libstdc++-libc6.1-2.so.3:/usr/lib/libstdc++-3-libc6.2-2-2.10.0.so

Note: You must set this environment variable to avoid a conflict between theversions of the C++ libraries used by Tivoli Access Manager and the IBMGlobal Security Toolkit.

4. Set the following environment variable, in order to ensure that the Java NativeInterface can locate the appropriate Tivoli Access Manager for WebLogic Clibraries:


# export LD_LIBRARY_PATH=/opt/pdwls/lib

5. Mount the IBM Tivoli Access Manager Web Security CD.6. Change directory to /mount_point/linux.7. Enter the following command to install the Tivoli Access Manager for

WebLogic package:# rpm -i PDWLS-PD-4.1.0-0.i386.rpm

When prompted to continue, type y and press Enter. Files are extracted andinstalled on the hard disk. The rpm utility exits.

8. Next, configure Tivoli Access Manager for WebLogic. Go to Chapter 3,“Configuration procedures”, on page 19.

Installing on WindowsThe Tivoli Access Manager for WebLogic installation separates file extraction frompackage configuration. Use an InstallShield setup.exe to install the Tivoli AccessManager for WebLogic files. When InstallShield completes, manually configureTivoli Access Manager for WebLogic.

Note: If you have already installed and configured Tivoli Access Manager forWebLogic and need to reinstall it, you must first unconfigure and remove it.See “Removing from Windows” on page 39.

To install and configure Tivoli Access Manager for WebLogic on Windowscomplete the following instructions:1. Log in to the Windows domain as a user with Windows administrator

privileges.2. Verify that the software prerequisites, including the required components from

the Tivoli Access Manager base, have been satisfied. See “Softwareprerequisites” on page 8.Attention: To use WebLogic Server 7.0 with Tivoli Access Manager forWebLogic, you must boot WebLogic Server 7.0 in compatibility mode the firsttime WebLogic Server is started. If WebLogic Server 7.0 is booted in 7.0mode, it is no longer possible to access existing domains in compatibilitymode.


3. Insert the IBM Tivoli Access Manager Web Security CD into the CD drive.4. Run the Tivoli Access Manager for WebLogic InstallShield setup program by

double-clicking on the following file, where the letter E: in the followingcommand represents the CD drive:

E:\Windows\AccessManager\Disk Images\Disk1\PDWLS\Disk Images\Disk 1\setup.exe

The Choose Setup Language window opens.5. Select the appropriate language and click OK.


The InstallShield program starts and the Welcome window opens.6. Click Next.

The License Agreement window opens.7. Click Yes to accept the License Agreement.

The Choose Destination Location window opens.8. Accept the default or specify an alternative location. Click Next.

The files are extracted to the disk. A message displays indicating that the fileshave been installed.

9. Click Finish to exit the setup program.10. Next, configure Tivoli Access Manager for WebLogic. Go to Chapter 3,

“Configuration procedures”, on page 19.


Chapter 3. Configuration procedures

To configure Tivoli Access Manager for WebLogic, complete the instructions ineach of the following sections:v “Part 1: Configuring Tivoli Access Manager Java runtime environment”v “Part 2: Joining a Tivoli Access Manager secure domain” on page 21v “Part 3: Creating user accounts” on page 23v “Part 4: Setting CLASSPATH for startWebLogic” on page 25v “Part 5: Configuring a Custom Realm” on page 27v “Part 6: Configuring a WebSEAL junction for WebLogic Server” on page 32v “Part 7: Testing the configuration” on page 34

Note: The instructions in this chapter assume you have installed Tivoli AccessManager for WebLogic and the prerequisite software, includingconfiguration of the Tivoli Access Manager base components. If you havenot installed the software, install it now by following the instructions inChapter 2, “Installation instructions”, on page 7.

Part 1: Configuring Tivoli Access Manager Java runtime environmentThe Tivoli Access Manager Java runtime environment is a prerequisite of the TivoliAccess Manager for WebLogic. The Java runtime component must be configuredcorrectly before a WebLogic Server Custom Realm can be configured. Use theTivoli Access Manager utility pdjrtecfg to update the Java Runtime Environmentused by the WebLogic Server. Also, if the system contains multiple Java runtimes,ensure that the Java Runtime Environment used by WebLogic Server is used toexecute the pdjrtecfg utility.1. Verify that you have installed and configured the Tivoli Access Manager base

runtime component.2. Verify that the Tivoli Access Manager Base Java runtime environment has been

installed.For more information see “Software prerequisites” on page 8.

3. Verify that the correct version of Java will be accessed when pdjrtecfg is run:a. Determine the location of the Java runtime environment used by WebLogic

Server.The exact directory location is specific to the operating system type. Also,some WebLogic Server deployments (such as WebLogic Server 7.0 forLinux) use JDKs that must be downloaded after WebLogic Server isinstalled. In these cases, the location of the JDK is determined by theinstaller.For example:UNIX: /WebLogic_install_directory/jdk_release/jre/bin/javaWindows: C:\WebLogic_install_directory\jdk_release\jre

The default WebLogic installation directory on Windows is C:\bea.

The default WebLogic installation directory on UNIX is /opt/bea.


Note: See the WebLogic Server documentation for recommended ways toensure that the PATH environment variable is set to use the JavaDevelopment Kit provided by WebLogic Server

b. Choose the following instruction for your operating system:v On Windows systems, verify that the %PATH% variable lists the Java

runtime environment supplied by WebLogic Server as the first one in thepath.

v On UNIX systems, enter the following command:# which java

The response should match the location you determined in the previousstep.– The default location for most WebLogic Server 6.1 UNIX installations

is:/WebLogic_install_directory/jdk131/jre/bin/java

– The default location for most WebLogic Server 7.0 UNIX installationscan vary depending on the revision level of the JDK for that platform.Note that WebLogic Server 7.0 does not currently support AIX.

4. Change directory to the sbin directory in the Tivoli Access Manager installationpath. For example:(UNIX) /opt/PolicyDirector/sbin

(Windows) C:\Program Files\Tivoli\Policy Director\sbin

5. Execute the pdjrtecfg command. For example, enter the following as onecontinuous command line:Windows:MSDOS> pdjrtecfg -action config-java_home C:\WebLogic_install_directory\JDK131\jre

UNIX:# pdjrtecfg -action config -java_home /WebLogic_install_directory/jdk131/jre

Note: The JDK directory names shown above might need to be modifiedslightly to reflect the directories used by versions of JDK 1.3.1 that arespecific to your operating system.

For more information on the use of pdjrtecfg, see the reference page for it inthe IBM Tivoli Access Manager Base Installation Guide.

6. Add the following entries to the CLASSPATH variable:

Table 4. CLASSPATH entries for UNIX operating systems.

UNIX

/opt/PolicyDirector/java/export/pdjrte/PD.jar/opt/PolicyDirector/java/export/pdjrte/ibmjceprovider.jar/opt/PolicyDirector/java/export/pdjrte/jaas.jar/opt/PolicyDirector/java/export/pdjrte/US_export_policy.jar/opt/PolicyDirector/java/export/pdjrte/ibmjsse.jar/opt/PolicyDirector/java/export/pdjrte/local_policy.jar/opt/PolicyDirector/java/export/pdjrte/ibmjcefw.jar/opt/PolicyDirector/java/export/pdjrte/ibmpkcs.jar

Table 5. CLASSPATH entries for Windows operating system.

Windows


Table 5. CLASSPATH entries for Windows operating system. (continued)

C:\Program Files\Tivoli\PolicyDirector\java\export\pdjrte\PD.jarC:\Program Files\Tivoli\PolicyDirector\java\export\pdjrte\ibmjceprovider.jarC:\Program Files\Tivoli\PolicyDirector\java\export\pdjrte\jaas.jarC:\Program Files\Tivoli\PolicyDirector\java\export\pdjrte\US_export_policy.jarC:\Program Files\Tivoli\PolicyDirector\java\export\pdjrte\ibmjsse.jarC:\Program Files\Tivoli\PolicyDirector\java\export\pdjrte\local_policy.jarC:\Program Files\Tivoli\PolicyDirector\java\export\pdjrte\ibmjcefw.jarC:\Program Files\Tivoli\PolicyDirector\java\export\ibmpkcs.jar

Part 2: Joining a Tivoli Access Manager secure domainTivoli Access Manager for WebLogic joins a Tivoli Access Manager secure domainby registering a Tivoli Access Manager authorization API application andcustomizing some configuration file settings. The configuration steps can besummarized as follows:v Copy the sample configuration file to the location that will be used to store

Tivoli Access Manager for WebLogic files.v Use the Java class SvrSslCfg to provide connectivity with the policy server.

Note: Use of this class is dependent on proper configuration of the Tivoli AccessManager Java runtime, as described in “Part 1: Configuring Tivoli AccessManager Java runtime environment” on page 19.

v Use the svrsslcfg utility to create necessary users and adjust configuration filesettings.

Each step is described in detail in the following instructions. To configure TivoliAccess Manager for WebLogic into the Tivoli Access Manager secure domain,complete each of the following steps:1. Tivoli Access Manager for WebLogic includes a sample configuration file,

PDRealm.conf. This file is distributed in the etc directory located in the TivoliAccess Manager for WebLogic installation directory.Copy the sample configuration file to a directory of your choice. For example,if you create a directory PDRealm under the WebLogic Server installationdirectory, enter the following command as one continuous command line:

Table 6. How to copy the sample configuration file on UNIX operating systems

UNIX

# cp /opt/pdwls/etc/PDRealm.conf \/WebLogic_install_directory/PDRealm/PDRealm.conf

Table 7. How to copy the sample configuration file on Windows operating systems

Windows

> copy \C:\Program Files\Tivoli\pdwls\etc\PDRealm.confC:\WebLogic_install_directory\PDRealm\PDRealm.conf

2. Use the Tivoli Access Manager SvrSslCfg Java class to configure SSLcommunication with remote Tivoli Access Manager servers. The syntax, enteredas one continuous command line, is:java com.tivoli.mts.SvrSslCfg Name sec_master_passwordAccess_Manager_policy_server_hostnameAccess_Manager_policy_server_hostname

Chapter 3. Configuration procedures 21

The options are:v Name

The name of the Tivoli Access Manager for WebLogic application to createand associate with the SSL communication. This application is a server. Forexample:amwlsserver

v sec_master_password

Password for the sec_master user.v Access_Manager_policy_server_hostname

Name of the system where the Tivoli Access Manager policy server isrunning.

v Access_Manager_policy_server_hostname

Name of the system where the Tivoli Access Manager policy server isrunning.The Tivoli Access Manager policy server host name is specified twice. Thesecond entry is required because the SvrSslCfg class needs an entry for thehost name of an authorization server. When the Tivoli Access Manager securedomain does not include an authorization server, you must instead specifythe host name for the policy server. Note that Tivoli Access Manager forWebLogic does not require an authorization server. Therefore, in a typicalTivoli Access Manager for WebLogic installation, you must specify the policyserver host name a second time.For more information on com.tivoli.mts.SvrSslCfg, see the IBM Tivoli AccessManager Administration Java Classes Developer’s Reference.

3. Enter the following svrsslcfg command as one continuous command line:

Table 8. Command line parameters for svrsslcfg on UNIX operating systems.

UNIX

# svrsslcfg -config -f /WebLogic_install_directory/PDRealm/PDRealm.conf-d /WebLogic_install_directory/PDRealm -n amwlsserver -s remote-P sec_master_password -S amwlsserver_password -r 0

Table 9. Command line parameters for svrsslcfg on Windows operating systems.

Windows

svrsslcfg -config -f c:\WebLogic_install_directory\PDRealm\PDRealm.conf-d c:\WebLogic_install_directory\PDRealm -n amwlsserver -s remote-P sec_master_password -S amwlsserver_password -r 0

This example invocation of svrsslcfg accomplishes the following tasks:v Creates a user called amwlsserver. This user identity will be used by the

application when communicating over SSL with the Tivoli Access Managerpolicy server.

v Creates a password for amwlsserver, as specified by the -S option.v Creates an SSL key file for that user, and places is in the directory specified

by the -d option.v Adds the user to the remote-acl-users group (based on the -s remote option)


Note: Use of this remote argument means that authorization is configured inremote mode. This means that an authorization server must beconfigured on another host system within the Tivoli Access Managersecure domain.

v Modifies settings in the specified configuration file PDRealm.conf. Note thatthe absolute pathname of the configuration file must be supplied to the -foption.

For more information about svrsslcfg, see the IBM Tivoli Access ManagerAdministration C API Developer’s Reference.

4. Verify that you can contact the policy server. Log in to pdadmin as theadministrator sec_master, and enter the following command:pdadmin> server list

The response from this command should show two servers. One is the name ofthe Tivoli Access Manager for WebLogic application, as entered when youcalled java com.tivoli.mts.SvrSslCfg in the previous section, combined withthe host name. The other is the result of the configuration steps performed bythe svrsslcfg utility.

Note: The two servers cannot have the same name.

The following example shows the two servers listed in bold font:pdadmin> server listpdwls-securixamwlsserver-securix.ibm.comwebseald-securix.ibm.comivacld-securix.ibm.com

Part 3: Creating user accountsTivoli Access Manager for WebLogic needs an account for use by the CustomRealm when calling Tivoli Access Manager administration API interfaces. Whenconfiguring single sign-on capabilities through WebSEAL, an additional account isneeded.

To create the necessary accounts, complete the following instructions.1. Use pdadmin to create the pdadmin_context_user.

For example, the following command, entered as one continuous command line,creates a user:pdadmin> user create pdadmin_context_usercn=pdadmin_context_user,o=ibm,c=aupdadmin_context_user pdadmin_context_userpdadmin_context_user_password iv-admin


The pdadmin_context_user is the user name that will be usedto create a pdadmin context. This is the context that the CustomRealm uses with the Tivoli Access Manager administration API.

This user must be in the iv-admin user group or be assignedsufficient permissions to be able to create, delete, modify, and list users andgroups. You can do this by giving the user the following permissions onan access control list (ACL) attached to an appropriate object withinthe /Management objectspace:

TcmdbsvatNWA

The name of the default ACL attached to the /Management object isdefault-management

2. Use pdadmin to activate the new pdadmin_context_user account. For example:pdadmin> user modify pdadmin_context_user account-valid yes

3. If you do not want to use WebSEAL to provide single sign-on capability, skipthis step. Go to “Part 4: Setting CLASSPATH for startWebLogic” on page 25.If you want to use WebSEAL to provide single sign-on capability, create theWebSEAL configured_user using the Tivoli Access Manager Web Portal Manageror the Tivoli Access Manager utility pdadmin.

The configured_user is a special Tivoli Access Manager user that is usedto form a trust relationship between WebSEAL and WebLogic Server. Thename of this user can be any valid Tivoli Access Manager user name.

For example, if configured_user is websealsso and the password for websealssois pdwebwlssso, enter the following pdadmin commands. Each commandshould be entered as one continuous command line:pdadmin> user create websealsso cn=websealsso,o=ibm,c=auwebsealsso websealsso pdwebwlssso

pdadmin> user modify websealsso account-valid yes

Note: Substitute appropriate values for your organization (o=ibm) and country(c=au) in the above command.

For optimum security, protect the configured_user password.Change the password at regular intervals. Use of the Tivoli Access Managerrandom password generator is recommended:

UNIX: /opt/PolicyDirector/sbin/genpass


Part 4: Setting CLASSPATH for startWebLogicThe startWebLogic command is used to start the WebLogic Server. You need tomodify the CLASSPATH environment variable to enable startWebLogic to access andload the correct Java classes.

Complete the following instructions:1. If the WebLogic Server is running, stop it now.2. Add the following file names to the CLASSPATH variable of the startWebLogic

command.

Table 10. File names to add to CLASSPATH on UNIX operating systems.

UNIX

/opt/pdwls/lib/PDWASAuthzManager.jar/opt/pdwls/lib/pdAuthzn.jar/opt/pdwls/lib/PDRealm.jar

Table 11. File names to add to CLASSPATH on Windows operating systems.

Windows

C:\Progra~1\Tivoli\pdwls\lib\PDWASAuthzManager.jarC:\Progra~1\Tivoli\pdwls\lib\pdAuthzn.jarC:\Progra~1\Tivoli\pdwls\lib\PDRealm.jar

The startWebLogic command is located in the directory of the installed domainof the WebLogic Server. In a standard installation this is:v WebLogic Server 6.1

(Windows) C:\bea\wlserver6.1\config\mydomain(UNIX) /bea/wlserver6.1/config/mydomain

v WebLogic Server 7.0(Windows) C:\WebLogic_install_directory\user_projects\domain_name(UNIX) /WebLogic_install_directory/user_projects/domain_name

The variable domain_name is the name you selected when created yourWebLogic Server 7.0 domain.

3. Complete the instructions in this step to ensure that the WebLogic Server loadsthe correct Java classes.Attention: You must complete this step or WebLogic Server will not restart.Remove the Tivoli Access Manager Base Java runtime environment files fromthe library extensions directory for the Java runtime environment that wasinstalled as a prerequisite for WebLogic Server.The library extensions directory is:UNIX: /Java_runtime_environment_path/lib/extWindows: C:\Java_runtime_environment_path\lib\ext

The location of Java runtime environment path should match the path that youdetermined in “Part 1: Configuring Tivoli Access Manager Java runtimeenvironment” on page 19.


Remove the following files from the library extensions directory:

Table 12. List of files to remove from the extensions directory

PD.jarUS_export_policy.jaribmjcefw.jaribmjceprovider.jar

ibmjsse.jaribmpkcs.jarjaas.jarlocal_policy.jar

Note: These files were copied to this directory during the configuration of theTivoli Access Manager Base Java runtime environment. You are removinga copy of the files. You are not removing the original files.

4. Add the following entries to the CLASSPATH variable defined in thestartWebLogic command. Ensure that the entries are placed after the WebLogicServer entries.Attention: You must complete this step or WebLogic Server will not restart.

Table 13. New CLASSPATH entries on UNIX operating systems

UNIX

/opt/PolicyDirector/java/export/pdjrte/PD.jar/opt/PolicyDirector/java/export/pdjrte/US_export_policy.jar/opt/PolicyDirector/java/export/pdjrte/ibmjcefw.jar/opt/PolicyDirector/java/export/pdjrte/ibmjceprovider.jar/opt/PolicyDirector/java/export/pdjrte/ibmjsse.jar/opt/PolicyDirector/java/export/pdjrte/ibmpkcs.jar/opt/PolicyDirector/java/export/pdjrte/jaas.jar/opt/PolicyDirector/java/export/pdjrte/local_policy.jar

Table 14. New CLASSPATH entries on Windows operating systems

Windows

C:\Progra~1\Tivoli\Policy~1\java\export\pdjrte\PD.jarC:\Progra~1\Tivoli\Policy~1\java\export\pdjrte\US_export_policy.jarC:\Progra~1\Tivoli\Policy~1\java\export\pdjrte\ibmjcefw.jarC:\Progra~1\Tivoli\Policy~1\java\export\pdjrte\ibmjceprovider.jarC:\Progra~1\Tivoli\Policy~1\java\export\pdjrte\ibmjsse.jarC:\Progra~1\Tivoli\Policy~1\java\export\pdjrte\ibmpkcs.jarC:\Progra~1\Tivoli\Policy~1\java\export\pdjrte\jaas.jarC:\Progra~1\Tivoli\Policy~1\java\export\pdjrte\local_policy.jar

5. If you are using the default language (English) skip this step. Go to “Part 5:Configuring a Custom Realm” on page 27.If you are using a language pack to support a language other than the default(English), you must add the following path to the CLASSPATH defined in thestartWebLogic script:v UNIX systems:

/opt/pdwls/nls/java

v Windows systems:C:\Progra~1\Tivoli\pdwls\nls\java

Note: The addition of this directory will enable access to the resource bundlesthat are installed in /opt/pdwls/nls/java/com/tivoli/pdwls/nls/ by thelanguage pack installation.


Part 5: Configuring a Custom RealmComplete the instructions in each of the following sections:v “Part 5A: Creating a new Custom Realm”v “Part 5B: Configuring a new caching realm” on page 30v “Part 5C: Caching credentials and group name mappings” on page 31

Part 5A: Creating a new Custom Realm1. Use startWebLogic to start the WebLogic server.

If you are using WebLogic Server 7.0, and have not yet booted the server forthe first time, read the following notice:Attention: To use WebLogic Server 7.0 with Tivoli Access Manager forWebLogic, you must boot WebLogic Server 7.0 in compatibility mode the firsttime WebLogic Server is started. If WebLogic Server 7.0 is booted in 7.0 mode,it is no longer possible to access existing domains in compatibility mode.


2. Launch the WebLogic Server console in a browser. This can be done byaccessing the following URL:http://WebLogic_Server_host:WebLogic_Server_listening_port/console

WebLogic_Server_host is the host name of the WebLogic Server system.

WebLogic_Server_listening_port is the port on which the WebLogic Server islistening. The default value for this port is 7001.

3. Select the appropriate menu items:v For WebLogic Server 7.0 in compatibility mode, select:

Compatibility Security Mode > Realms > Configure a new Custom Realm

v For WebLogic Server 6.1, select:Click Security -> Realms -> Configure a new Custom Realm

4. Create a Custom Realm. Specify the following values:v Name: PDRealm

This is the name of the Tivoli Access Manager Custom Realm that will beadded to WebLogic Server. This name can be anything you choose. The namePDRealm is provided here as an example.

v Realm Class Name: com.tivoli.pdwls.realm.PDRealmv Password: (not required).

During the creation of a new domain in WebLogic Server 7.0, the DomainConfiguration Wizard provides the option of specifying a system user nameother than the default name of system. If you choose to do this, you mustalso specify the property wls.configurable.user.name, as described in thenext step.In WebLogic Server 7.0, if you specify a system user name other than system,and you do not set wls.configurable.user.name, Tivoli Access Manager for


WebLogic will use the default name of system. This will leave yournon-default system user name in an invalid state.For example, if a domain is created and the user name myuser was specifiedas the system user during the domain creation, thenwls.configurable.system.user=myuser must be added to the custom realmconfiguration. Omitting this configuration item causes Tivoli Access Managerfor WebLogic to default the system user to system. This leaves myuser in aninvalid state and incapable of being administered. When a user is invalid, theuser cannot be deleted and the password cannot be changed.When you enable compatibility mode under WebLogic Server 7.0, the systemuser is automatically created if it was not specified during domain creation.The password of the user system will initially be the same as the passwordspecified for the system user set at domain creation.For example, assume a domain has been created with a system user name ofmyuser and password of mypassword. Enabling compatibility modeautomatically creates a system user with password mypassword. It is thenpossible to boot the WebLogic server and access the WebLogic Web-basedconsole as either the user myuser or the user system.

5. Enter the appropriate configuration data for the Custom Realm propertysettings. Consult the information contained in this step When all propertyvalues are set, click Create.How to determine property settings

Tivoli Access Manager for WebLogic includes an example text file that containsall of the necessary configuration settings. You can copy this file into theWebLogic console window and modify the values to fit your environment.The sample text file is in the following location:v UNIX systems:

/opt/pdwls/sbin/DefaultConfig.txt

v Windows systems:C:\Progam Files\Tivoli\pdwls\sbin\DefaultConfig.txt

The following table describes the properties that are included in the sampleconfiguration file. Use the definitions in this table to help you determine whatthese values should be in your environment.

Table 15. Custom Realm property settings

Realm Property: webseal.sso.configuredValid Values: true or false

Description: Defines whether WebSEAL will be configured and determines if the Tivoli Access ManagerCustom Security Realm will attempt to perform single sign-on.

Realm Property: pdadmin.user.nameValid Values: pdadmin_context_user

Description: The pdamin.user.name is the pdadmin_context_user and is the user name that willbe used to create a pdadmin context. This is the context that the Custom Realm uses with theTivoli Access Manager administration API. This user name was defined in a previous step inthese configuration instructions.


Table 15. Custom Realm property settings (continued)

Realm Property: pdadmin.passwordValid Values: pdadmin_context_user_password

Description: The password for the pdadmin.user.name. This should match the passworddefined above in a previous step in these configuration instructions.

Realm Property: pdrealm.registry.listingValid Values: true or false

Description: Defines whether the Tivoli Access Manager Custom Realm should list users andgroups, including group memberships, to the WebLogic Server console application. Thisshould be set to false in production environments. Set it to true only in a test environment.

Realm Property: connection.poolValid Values: 1 -n

Description: Where n is an integer defining the number of Realm objects to instantiate in theRealm pool.

Realm Property: pdrealm.tracingValid Values: true or false

Description: Turn Tivoli Access Manager for WebLogic Realm tracing on or off. Trace will be sent tothe WebLogic Server log.

Realm Property: wls.admin.userValid Values: configured_user

Description: The special user that is configured to form a trust relationship between WebSEAL andWebLogic Server. This entry must match the configured_user identity that you created previouslyin these configuration instructions.

Realm Property: group.dnValid Values: A valid Distinguished Name (DN)

Description: LDAP naming context where groups are defined. For example, o=ibm,c=au.

Realm Property: user.dnValid Values: A valid Distinguished Name (DN)

Description: LDAP naming context where users are defined. For example, o=ibm,c=au.


Table 15. Custom Realm property settings (continued)

Realm Property: aznapi.conf.fileValid Values: authorization_api_configuration_file_path

Description: The fully qualified path of the Tivoli Access Manager authorization configuration filePDRealm.conf that is generated when using svrsslcfg to configure a Tivoli Access Managerauthorization API application.

Realm Property: wls.configurable.system.userValid Values:

Description: This setting specifies the system user name. This setting is requiredwhen a WebLogic Server 7.0 domain has been created, and the system user name for that domain hasbeen specified to a value other than the default name system. The value for this property should bethe user name entered for the system user when the WebLogic Server 7.0 domain was created.

Note that this configuration item is not needed when configuring a WebLogic Server 6.1 domain,or when upgrading from an existing WebLogic Server 6.1 domain to a WebLogic Server 7.0 domain.

Realm Property: wls.admin.user.password.expiryValid Values: number_of_minutes

Description: Specifies when the cached version of the configured_user’s password expires. The valueis specified in minutes. If you do not want the password to expire, either do not set this property, orset it to a value less than 1.

When the configured_user’s password expires, the Custom Realm will re-authenticate thepassword received from WebSEAL to the Tivoli Access Manager user registry.If the password has been changed in the user registry, the WebSEAL configurationmust be updated with the new password and WebSEAL must be restarted.

Part 5B: Configuring a new caching realmComplete the steps in this section to configure a new caching realm. Theseinstructions assume that you have the WebLogic console running.1. Select the appropriate menu items:

v For WebLogic Server 7.0 in compatibility mode, select:Compatibility Security Mode > Caching Realms > Configure a newCaching Realm

v For WebLogic Server 6.1, select:Security -> Realms -> Configure a new Caching Realm

2. Specify the following values:a. Name: PD_Caching_Realm

This is the name of the Tivoli Access Manager Caching Realm that will beadded to WebLogic Server. This name can be anything you choose. Thename PD_Caching_Realm is provided here as an example.

b. Basic Realm: PDRealmThis name should match the name of the Custom Realm. that you specifiedin the previous step. The example used previously was PDRealm.


c. Case Sensitive: No3. Click Create.4. Continue to “Part 5C: Caching credentials and group name mappings”.

Part 5C: Caching credentials and group name mappingsTivoli Access Manager for WebLogic provides additional caching settings for usewith Tivoli Access Manager security. These settings are used to configuring cachingfor:v User credentialsv Group name mappings

Complete the following instructions:1. If you want to use the default settings for caching user credentials, skip this

step and continue to the next step.Use the settings in this section to enable the caching of user credentials. Theuse of a credential cache optimizes performance. The entries described in thefollowing table should be added to the configuration data of the AccessManager Security Realm.

Table 16. User credentials cache settings

Credentials Cache

Realm Property: credential.cache.entry.lifetimeValid Values: number_of_minutes

Description: Specifies how long, in minutes, to retain a user credential inthe cache. For example, 5. If this value is not specified, or has a value ofless than 1, credential caching is disabled.

Note that this parameter should be set to the time required for changes togroup membership to take effect. The Custom Realm will not detect a changein the user’s credentials until this amount of time has passed.

Realm Property: credential.cache.max.entriesValid Values: integer

Description: Specifies the maximum number of entries in the cache. For example,10000. If this value is not specified, or has a value of less than 1,credential caching is disabled.

Realm Property: credential.cache.num.bucketsValid Values: integer

Description: Specifies the number of caches (buckets) to have within the cache.For example: 20. The use of multiple buckets optimizes the performance ofcredential lookups in the cache. If this value is not specified, or has a value ofless than 1, credential caching is disabled.

2. If you want to use the default settings for group name mappings, skip this stepand continue to the next step.Group Name Mapping Cache


This cache stores the mapping between group Distinguished Names or UUIDsand the Tivoli Access Manager short names. This mapping is used to comparegroup information from J2EE deployment descriptors against groupinformation contained in the user registry. Caching of this informationoptimizes performance when processing access (authorization) requests basedon role memberships. The entries described in the following table should beadded to the configuration data of the Tivoli Access Manager for WebLogicSecurity Realm.

Table 17. Caching settings for group name mappings

Group Name Mapping Cache

Realm Property: group.mapping.cache.entry.lifetimeValid Values: number_of_minutes

Description: Specifies the lifetime, in minutes, of each cache entry.For example, 720.

Realm Property: group.mapping.cache.max.entriesValid Values: integer

Description: Specifies the maximum number of entries in the cache.For example: 500. Use this value to ensure that installations with very largenumbers of groups do not exhaust available system memory.

3. Choose the instructions that match the release number of your WebLogicServer:WebLogic Server 6.1

a. Go to Security -> FileRealm. andb. Set it to the name of the caching realm that you specified in the previous

step. The example caching realm name in the previous step wasPD_Caching_Realm. Leave all other fields unchanged.

WebLogic Server 7.0

a. Click on mydomain –> Security

b. Click the General tab. For the Default Realm, select CompatibilityRealm.c. Click the FileRealm tab. For Caching Realm, select the name of the realm

you created.d. Click Apply.

4. Restart WebLogic Server.Security settings will now take effect.

Part 6: Configuring a WebSEAL junction for WebLogic ServerIf you want to use WebSEAL to provide single sign-on services, use theinstructions in this section to configure the necessary WebSEAL junction. If you arenot using WebSEAL single sign-on, skip this section and go to “Part 7: Testing theconfiguration” on page 34.

Attention: When using single sign-on services, deny direct access by internalusers to WebLogic Server.


If your WebLogic Server installation needs to handle access requests from usersexternal to your local network, there is significant advantage in using WebSEAL toprovide single sign-on services. In this case, WebSEAL provides all authenticationservices for WebLogic Server.

When using WebSEAL to provide single sign-on services for external users,however, do not allow internal users to access WebLogic Server without goingthrough WebSEAL. WebSEAL manipulates the user name and password entries foreach request as part of the trust relationship with WebLogic Server. The trustrelationship requires that authentication lock out (maximum login failures) bedisabled for the special WebSEAL user, configured_user.

Because authentication lock out is disabled for configured_user, a malicious internaluser could attempt to impersonate WebSEAL to the WebLogic Server, and attempta brute force password attack. The best defense against this unlikely, butpotentially serious, breach of the trust relationship is to require that allauthentication be performed by WebSEAL. Thus, when using single sign-on, theWebLogic Server should reject all direct access requests from internal users.

To configure a WebSEAL junction for WebLogic Server, complete the followingsteps on the system that hosts the WebSEAL server:1. Update the following configuration item in the WebSEAL configuration file,

webseald.conf:basicauth-dummy-passwd = configured_user_password

2. Stop and restart WebSEAL, to make the configuration change take effect.3. Use the pdadmin command to disable authentication lock out for the special

WebSEAL user, configured_user:pdadmin> policy set max-login-failures unset -user configured_user

4. Use the pdadmin command to create a WebSEAL junction.

Note: This step can be done on any machine in the Tivoli Access Managersecure domain. You do not have to execute it on a WebSEAL system. Forexample, you could run it on the Tivoli Access Manager policy serversystem.

Be sure to use the -b option to supply the junction target URL. This is requiredfor single sign-on.

For example, enter the following command as one continuous command line:pdadmin> server task webseald_server_name create -t tcp-p WebLogic_Server_listen_port -h WebLogic_Server-b supply junction_target

The following table defines the variables in the above pdadmin command:

Table 18. Options for the pdadmin command

Option Description


Table 18. Options for the pdadmin command (continued)

webseald_server_name Name of the WebSEAL server.The name consists of two parts:webseald-WebSEAL_server_instance.Use your system’s host name for WebSEAL_server_instance.

For example, if the host machine name is cruz,the webseald_server_name would be:

webseald-cruz

Note: If you have installed multiple instances ofWebSEAL on the same server, you need to specifythe server instance also. For instructions oncreating junctions with multiple server instances,see theIBM Tivoli Access Manager WebSEAL Administrator’s Guide.

WebLogic_Server The host name of the WebLogic Server

WebLogic_Server_listen_port The port on which the WebLogic Server is listening

junction_target The URL target of the junction

For complete information on creating and using WebSEAL junctions, see the IBMTivoli Access Manager WebSEAL Administrator’s Guide.

Part 7: Testing the configurationVerify that the Tivoli Access Manager Custom Realm has been correctly configuredby completing the following steps:1. Use the WebLogic Server console to create a new test user.2. Execute the following pdadmin command:

pdadmin> user show test_user

v Verify that account-valid is yes.v Verify that password-valid is yes.

The Tivoli Access Manager Custom Realm single sign-on solution allows a singleauthentication step through WebSEAL that transparently authenticates the user tothe WebLogic Server. You can confirm that authentication is configured correctly byrunning the demonstration application. The demonstration application is describedin “Using the demonstration application” on page 35.


Chapter 4. Administration tasks

This chapter contains the following information about Tivoli Access Manager forWebLogic:v “Using the demonstration application”v “Creating test users” on page 36v “Usage tips” on page 36v “Troubleshooting tips” on page 37v “Limitations” on page 38

Using the demonstration applicationYou can use the demonstration application to see an example of two types ofauthorization and to exercise the WebSEAL single sign-on capability.

The two types of authorization are:v Declarative

Uses Deployment Descriptors to grant users and groups specific roles. ThePDDemoApp application does not, by default, grant access to any user.

v ProgrammaticUsing programmatic security, the Enterprise Java Bean ensures that only theowners of each account have the permission to view their own account balance.For example, user Mark cannot view user Luke’s balance.

To run the demonstration application, complete the following steps:1. Copy the demonstration application PDDemoApp.ear into

WebLogic_domain_directory\applications. Note that use of this directory is notrequired. You can place the EAR file into any directory on your file system.

2. Use the WebLogic Server console to install the demonstration application.3. Use the WebLogic Server console to create the following users:

Banker1Banker2Banker3Banker4

4. Use the WebLogic Server console to add a group to the BankMembersRole inthe PDDemoApp. This can be a group that already exists, or you can create a newgroup by using the WebLogic Server console. Alternatively, add the userscreated above to the BankMembersRole.For instructions on using the WebLogic Server console, see the WebLogic Serverdocumentation.

5. If you added a group to the BankMembersRole in the step above, add all of theusers created above (Banker1, Banker2, Banker3, Banker4) to the group. If youadded the users individually into the BankMembersRole, skip this step.

6. To access the demonstration application, access the following URL:http://WebLogic_Server_host:WebLogic_Server_listening_port/pddemo/PDDemo

Authenticate with one of the users defined above.

WebLogic_Server_host is the hostname of the WebLogic Server system


WebLogic_Server_listening_port is the port on which the WebLogic Server islistening.

7. Verify that only users who have been granted the BankMembersRole can accessthe Servlet.

8. Verify that the authenticated users can view their own balances, but not thebalance of any other user.

To test the WebSEAL single sign-on, complete the following steps:1. Access the following URL:

https://webseald_server_name/junction_target/pddemo/PDDemo

WebSEAL will prompt you to authenticate.

For an explanation of the variables webseald_server_name and junction_target, see“Part 6: Configuring a WebSEAL junction for WebLogic Server” on page 32.

Note: Use HTTPS here because the default WebSEAL behavior prevents Basicor Forms-based authentication over HTTP.

2. Authenticate as one of the users defined above.This process enables the user to single sign-on to the WebLogic Server, and theServlet will be invoked without requiring a second authentication. Whenaccessed through WebSEAL, the PDDemo demonstration application will showidentical behavior to that shown when accessing the WebLogic Server directly.

3. Verify that the authenticated users can view their own balances, but not thebalance of any other user.

Creating test usersFor convenience, if many test users are required, a script named users.sh isprovided. This tool can be used to create or delete multiple test users, by creatingappropriate pdadmin scripts:v Run users.sh to generate two text files that pdadmin can use to add and

remove a set of users to or from the user registry.v To use the users.sh script, edit the script and define the variables appropriate

for your environment.Two files are generated: add_users.txt and remove_users.txt. Use these files asinput to pdadmin scripts as follows:pdadmin -a sec_master -p <password> <add_users.txt

pdadmin -a sec_master -p <password> <remove_users.txt

Usage tips1. Observe good security practices when enabling single sign-on for external

users. Ensure that authentication is performed only by the WebSEAL server. Toachieve this, disable access to the WebLogic Server by internal users who donot go through the WebSEAL server.

2. Tivoli Access Manager Custom Realm listing should be set to false inproduction environments. Set this property to true only when testing to verifythat a realm is operational.

3. To use the WebLogic Server system and guest users through WebSEAL, youmust to create a dummy guest in Tivoli Access Manager, and set the real Guestand System password to match the configured_user password.


Note, however, this means that if you want to allow the guest user to log inwithout going through WebSEAL (such as an access an intranet), you will needto expose the configured_user password.

4. Be aware that both Tivoli Access Manager and WebLogic Server keep track offailed authentication attempts. Each product maintains a security configurationsetting that specifies the maximum number of allowable failed attempts beforethe user account is locked out. The user will be locked out by the lesser of thetwo settings. For example, if WebLogic Server is configured to allow five loginfailures but Tivoli Access Manager is configured to allow only three loginfailures, the user will be locked out after three login failures.

Troubleshooting tipsTopic index:v “Single sign-on failure using forms-based login”v “Authorization service won’t start on HP-UX”v “WebLogic Server throws memory exception”

Single sign-on failure using forms-based loginWhen users have authenticated through forms-based login, and attempt to access aresource for which they do not have permission, the following error message mayappear:Could not Sign On message from WebSEAL

This can occur because even though the users could actually be authenticated, theydo not have permission to access the Servlet in the Web container.

If this error occurs when using Basic Authentication, the users will be re-promptedfor the authentication details, instead of seeing the page described above. This isdefault WebLogic Server behavior and would be seen if the users access the pageeither directly or through WebSEAL.

Authorization service won’t start on HP-UXOn HP-UX 11i only, if the Tivoli Access Manager authorization service does notstart, check that the SHLIB_PATH environment variable is set correctly. This variablemust include the location of the IBM Global Security Toolkit (GSKIT) libraries. Thelocation can be either /usr/lib or /opt/ibm/gsk5/lib.

If SHLIB_PATH is not set, enter:export SHLIB_PATH=/opt/ibm/gsk5/lib

If SHLIB_PATH is set but does not contain either of the two directories, add one ofthe directories to the path.

WebLogic Server throws memory exceptionProblem: A java.lang.OutofMemory exception is thrown.

Explanation: When running a large number of Access Manager for WebLogicServer sessions, BEA WebLogic Server may run out of heap space.

Solution: Increase the maximum heap size option for the Java Virtual Machine(JVM) in the startWebLogic script. For example:%JAVA_HOME%\bin\java -ms64m -mx128m

Chapter 4. Administration tasks 37

Consult the BEA product documentation for recommended heap size, based onapplication architecture and the number of memory-intensive processes running onthe host system. Applications should be stress-tested to determine the appropriateheap size for their environment. See the following URL for performance tuningconsiderations for thread counts and heap size:http://edocs.bea.com/wls/docs61/perform/index.html

Limitations1. Tivoli Access Manager for WebLogic does not support recursive group

membership (groups within groups).2. Centralized control of user access to WebLogic’s J2EE resources is limited to

moving users between groups that have been assigned to roles in applicationdeployment descriptors.

3. Tivoli Access Manager for WebLogic does not implement thejava.security.ACL interface. Note that Tivoli Access Manager ACLs do notcorrespond to WebLogic Server ACLs.


Chapter 5. Removal instructions

This chapter describes how to unconfigure and remove IBM Tivoli Access Managerfor WebLogic Server.

Complete the instructions in one of the following sections:v “Removing from Solaris”v “Removing from Windows”v “Removing from AIX” on page 40v “Removing from HP-UX” on page 40v “Removing from Linux” on page 41

Removing from SolarisUse pkgrm to remove the Tivoli Access Manager for WebLogic on Solaris files.Complete the following instructions:1. Log in as root.2. Use the WebLogic Server console to unconfigure the PDRealm.3. To remove Tivoli Access Manager for WebLogic, enter the following command:

# pkgrm PDWLS

A prompt appears asking you to confirm the removal of the selected package.4. Enter the letter y.

A status message lists each file as it is removed. After the postremove script runs, astatus message indicates that the removal of the software package was successful.The pkgrm utility exits.

Removal of the Tivoli Access Manager for WebLogic package is complete.

If you want to remove the IBM Tivoli Access Manager Base prerequisites (TivoliAccess Manager Base runtime environment, Tivoli Access Manager Base Javaruntime environment, and the optional Tivoli Access Manager applicationdevelopment kit) follow the instructions in the IBM Tivoli Access Manager BaseInstallation Guide.

Removing from WindowsUse the Windows Add/Remove Programs icon interface to remove the TivoliAccess Manager for WebLogic files. Complete the following instructions:1. Log in as a Windows user with administrator privilege.2. Use the WebLogic Server console to unconfigure the PDRealm.3. Double-click the Add/Remove Programs icon.4. Select Access Manager for WebLogic Application Server.5. Click Change/Remove.

The Choose Setup Language dialog box appears.6. Select a language and click OK.7. Select the Remove radio button. Click Next.


The Confirm File Deletion dialog box appears.8. Click OK.

The Tivoli Access Manager for WebLogic files are removed.The Maintenance Complete dialog box appears.

9. Click Finish.

Removal of Tivoli Access Manager for WebLogic is complete.


Removing from AIXUse the SMIT utility to remove the Tivoli Access Manager for WebLogic for AIXpackage. Complete the following instructions:1. Log in as root.2. Use the WebLogic Server console to unconfigure the PDRealm.3. Start SMIT. Select Software Installation and Maintenance.4. Select Software Maintenance and Utilities.5. Select Remove Installed Software.6. Click the List button next to SOFTWARE name.

The Multi-Select List appears. The package name PDWLS is displayed.7. Select the PDWLS package: Access Manager for WebLogic.

The Remove Installed Software dialog box appears.8. Change the value of the PREVIEW only field to no.9. Accept the default value of no for all other fields. Click OK.

10. The Are You Sure message window appears. Click OK.A status message appears indicating that the software is being deinstalled.Another status message lists all packages that were removed.

11. Click Done.The Remove Installed Software dialog box appears.

12. Click Cancel. Click Exit to exit SMIT.

Removal of Tivoli Access Manager for WebLogic is complete.


Removing from HP-UXUse swremove to remove the Tivoli Access Manager for WebLogic files. Completethe following instructions:1. Log in as root.2. Use the WebLogic Server console to unconfigure the PDRealm.


3. To remove Tivoli Access Manager for WebLogic, enter the following command:# swremove PDWLS

A series of status messages appear. A status message appears indicating thatthe analysis phase has succeeded. The swremove utility removes the TivoliAccess Manager for WebLogic files from the hard disk.

When the removal is complete, the swremove utility exits.

Removal of Tivoli Access Manager for WebLogic on HP-UX is now complete.


Removing from LinuxUse rpm to remove the Tivoli Access Manager for WebLogic files. Complete thefollowing instructions:1. Log in as root.2. Use the WebLogic Server console to unconfigure the PDRealm.3. To remove Tivoli Access Manager for WebLogic, enter the following command:

# rpm -e PDWLS-PD-4.1.0-0.i386.rpm

The files are removed. The rpm utility exits.

Removal of Tivoli Access Manager for WebLogic on Linux is now complete.


Chapter 5. Removal instructions 41

Appendix. Notices

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

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

IBM Director of LicensingIBM Corporation500 Columbus AvenueThornwood, NY 10594U.S.A

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

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

The following paragraph does not apply to the United Kingdom or any othercountry where such provisions are inconsistent with local law:INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THISPUBLICATION “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHEREXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIEDWARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESSFOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express orimplied warranties in certain transactions, therefore, this statement may not applyto you.

This information could include technical inaccuracies or typographical errors.Changes are periodically made to the information herein; these changes will beincorporated in new editions of the publication. IBM may make improvementsand/or changes in the product(s) and/or the program(s) described in thispublication at any time without notice.

Any references in this information to non-IBM Web sites are provided forconvenience only and do not in any manner serve as an endorsement of those Websites. The materials at those Web sites are not part of the materials for this IBMproduct and use of those Web sites is at your own risk.

IBM may use or distribute any of the information you supply in any way itbelieves appropriate without incurring any obligation to you.


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

IBM Corporation2Z4A/10111400 Burnet RoadAustin, TX 78758USA

Such information may be available, subject to appropriate terms and conditions,including in some cases, payment of a fee.

The licensed program described in this information and all licensed materialavailable for it are provided by IBM under terms of the IBM Customer Agreement,IBM International Program License Agreement, or any equivalent agreementbetween us.

Any performance data contained herein was determined in a controlledenvironment. Therefore, the results obtained in other operating environments mayvary significantly. Some measurements may have been made on development-levelsystems and there is no guarantee that these measurements will be the same ongenerally available systems. Furthermore, some measurement may have beenestimated through extrapolation. Actual results may vary. Users of this documentshould verify the applicable data for their specific environment.

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

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

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

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

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

AIXDB2IBMIBM logo


SecureWayTivoliTivoli logo

Microsoft, Windows, Windows NT, and the Windows logo are trademarks ofMicrosoft Corporation in the United States, other countries, or both.

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

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

Other company, product, and service names may be trademarks or service marksof others.

Appendix. Notices 45

Glossary

Aaccess control. In computer security, the process ofensuring that the resources of a computer system canbe accessed only by authorized users in authorizedways.

access control list (ACL). In computer security, a listthat is associated with an object that identifies all thesubjects that can access the object and their accessrights. For example, an access control list is a list that isassociated with a file that identifies the users who canaccess the file and identifies the users’ access rights tothat file.

access permission. The access privilege that applies tothe entire object.

action. An access control list (ACL) permissionattribute. See also access control list.

ACL. See access control list.

administration service. An authorization API runtimeplug-in that can be used to perform administrationrequests on a Tivoli Access Manager resource managerapplication. The administration service will respond toremote requests from the pdadmin command toperform tasks, such as listing the objects under aparticular node in the protected object tree. Customersmay develop these services using the authorizationADK.

attribute list. A linked list that contains extendedinformation that is used to make authorizationdecisions. Attribute lists consist of a set of name = valuepairs.

authentication. (1) In computer security, verification ofthe identity of a user or the user’s eligibility to accessan object. (2) In computer security, verification that amessage has not been altered or corrupted. (3) Incomputer security, a process that is used to verify theuser of an information system or of protected resources.See also multi-factor authentication, network-basedauthentication, and step-up authentication.

authorization. (1) In computer security, the rightgranted to a user to communicate with or make use ofa computer system. (2) The process of granting a usereither complete or restricted access to an object,resource, or function.

authorization rule. See rule.

authorization service plug-in. A dynamically loadablelibrary (DLL or shared library) that can be loaded by

the Tivoli Access Manager authorization API runtimeclient at initialization time in order to performoperations that extend a service interface within theAuthorization API. The service interfaces that arecurrently available include Administration, ExternalAuthorization, Credentials modification, Entitlementsand PAC manipulation interfaces. Customers maydevelop these services using the authorization ADK.

BBA. See basic authentication.

basic authentication. A method of authentication thatrequires the user to enter a valid user name andpassword before access to a secure online resource isgranted.

bind. To relate an identifier to another object in aprogram; for example, to relate an identifier to a value,an address or another identifier, or to associate formalparameters and actual parameters.

blade. A component that provides application-specificservices and components.

business entitlement. The supplemental attribute of auser credential that describes the fine-grainedconditions that can be used in the authorization ofrequests for resources.

CCA. See certificate authority.

CDAS. See Cross Domain Authentication Service.

CDMF. See Cross Domain Mapping Framework.

certificate. In computer security, a digital documentthat binds a public key to the identity of the certificateowner, thereby enabling the certificate owner to beauthenticated. A certificate is issued by a certificateauthority.

certificate authority (CA). An organization that issuescertificates. The certificate authority authenticates thecertificate owner’s identity and the services that theowner is authorized to use, issues new certificates,renews existing certificates, and revokes certificatesbelonging to users who are no longer authorized to usethem.

CGI. See common gateway interface.


cipher. Encrypted data that is unreadable until it hasbeen converted into plain data (decrypted) with a key.

common gateway interface (CGI). An Internetstandard for defining scripts that pass information froma Web server to an application program, through anHTTP request, and vice versa. A CGI script is a CGIprogram that is written in a scripting language, such asPerl.

configuration. (1) The manner in which the hardwareand software of an information processing system areorganized and interconnected. (2) The machines,devices, and programs that make up a system,subsystem, or network.

connection. (1) In data communication, an associationestablished between functional units for conveyinginformation. (2) In TCP/IP, the path between twoprotocol applications that provides reliable data streamdelivery service. In the Internet, a connection extendsfrom a TCP application on one system to a TCPapplication on another system. (3) In systemcommunications, a line over which data can be passedbetween two systems or between a system and adevice.

container object. A structural designation thatorganizes the object space into distinct functionalregions.

cookie. Information that a server stores on a clientmachine and accesses during subsequent sessions.Cookies allow servers to remember specific informationabout clients.

credentials. Detailed information, acquired duringauthentication, that describes the user, any groupassociations, and other security-related identityattributes. Credentials can be used to perform amultitude of services, such as authorization, auditing,and delegation.

credentials modification service. An authorizationAPI runtime plug-in which can be used to modify aTivoli Access Manager credential. Credentialsmodification services developed externally bycustomers are limited to performing operation to addand remove from the credentials attribute list and onlyto those attributes that are considered modifiable.

cross domain authentication service (CDAS). AWebSEAL service that provides a shared librarymechanism that allows you to substitute the defaultWebSEAL authentication mechanisms with a customprocess that returns a Tivoli Access Manager identity toWebSEAL. See also WebSEAL.

cross domain mapping framework (CDMF). Aprogramming interface that allows a developer tocustomize the mapping of user identities and thehandling of user attributes when WebSEALe-Community SSO function are used.

Ddaemon. A program that runs unattended to performcontinuous or periodic systemwide functions, such asnetwork control. Some daemons are triggeredautomatically to perform their task; others operateperiodically.

directory schema. The valid attribute types and objectclasses that can appear in a directory. The attributetypes and object classes define the syntax of theattribute values, which attributes must be present, andwhich attributes may be present for the directory.

distinguished name (DN). The name that uniquelyidentifies an entry in a directory. A distinguished nameis made up of attribute:value pairs, separated bycommas.

digital signature. In e-commerce, data that isappended to, or is a cryptographic transformation of, adata unit and that enables the recipient of the data unitto verify the source and integrity of the unit and torecognize potential forgery.

DN. See distinguished name.

domain. (1) A logical grouping of users, systems, andresources that share common services and usuallyfunction with a common purpose. (2) That part of acomputer network in which the data processingresources are under common control. See also domainname.

domain name. In the Internet suite of protocols, aname of a host system. A domain name consists of asequence of subnames that are separated by a delimitercharacter. For example, if the fully qualified domainname (FQDN) of a host system isas400.rchland.vnet.ibm.com, each of the following is adomain name: as400.rchland.vnet.ibm.com,vnet.ibm.com, ibm.com.

EEAS. See External Authorization Service.

encryption. In computer security, the process oftransforming data into an unintelligible form in such away that the original data either cannot be obtained orcan be obtained only by using a decryption process.

entitlement. A data structure that containsexternalized security policy information. Entitlementscontain policy data or capabilities that are formatted ina way that is understandable to a specific application.

entitlement service. An authorization API runtimeplug-in which can be used to return entitlements froman external source for a principal or set of conditions.Entitlements are normally application specific data thatwill be consumed by the resource manager application


in some way or added to the principal’s credentials foruse further on in the authorization process. Customersmay develop these services using the authorizationADK.

external authorization service. An authorization APIruntime plug-in that can be used to make applicationor environment specific authorization decisions as partof the Tivoli Access Manager authorization decisionchain. Customers may develop these services using theauthorization ADK.

Ffile transfer protocol (FTP). In the Internet suite ofprotocols, an application layer protocol that usesTransmission Control Protocol (TCP) and Telnetservices to transfer bulk-data files between machines orhosts.

Gglobal signon (GSO). A flexible single sign-onsolution that enables the user to provide alternativeuser names and passwords to the back-end Webapplication server. Global signon grants users access tothe computing resources they are authorized to use —through a single login. Designed for large enterprisesconsisting of multiple systems and applications withinheterogeneous, distributed computing environments,GSO eliminates the need for users to manage multipleuser names and passwords. See also single signon.

GSO. See global signon.

Hhost. A computer that is connected to a network (suchas the Internet or an SNA network) and provides anaccess point to that network. Also, depending on theenvironment, the host may provide centralized controlof the network. The host can be a client, a server, orboth a client and a server simultaneously.

HTTP. See Hypertext Transfer Protocol.

hypertext transfer protocol (HTTP). In the Internetsuite of protocols, the protocol that is used to transferand display hypertext documents.

IInternet protocol (IP). In the Internet suite ofprotocols, a connectionless protocol that routes datathrough a network or interconnected networks and actsas an intermediary between the higher protocol layersand the physical network.

Internet suite of protocols. A set of protocolsdeveloped for use on the Internet and published as

Requests for Comments (RFCs) through the InternetEngineering Task Force (IETF).

interprocess communication (IPC). (1) The process bywhich programs communicate data to each other andsynchronize their activities. Semaphores, signals, andinternal message queues are common methods ofinterprocess communication. (2) A mechanism of anoperating system that allows processes to communicatewith each other within the same computer or over anetwork.

IP. See Internet Protocol.

IPC. See Interprocess Communication.

Jjunction. An HTTP or HTTPS connection between afront-end WebSEAL server and a back-end Webapplication server. WebSEAL uses a junction to provideprotective services on behalf of the back-end server.

Kkey. In computer security, a sequence of symbols thatis used with a cryptographic algorithm for encryptingor decrypting data. See private key and public key.

key database file. See key ring.

key file. See key ring.

key pair. In computer security, a public key and aprivate key. When the key pair is used for encryption,the sender uses the public key to encrypt the message,and the recipient uses the private key to decrypt themessage. When the key pair is used for signing, thesigner uses the private key to encrypt a representationof the message, and the recipient uses the public key todecrypt the representation of the message for signatureverification.

key ring. In computer security, a file that containspublic keys, private keys, trusted roots, and certificates.

LLDAP. See Lightweight Directory Access Protocol.

lightweight directory access protocol (LDAP). Anopen protocol that (a) uses TCP/IP to provide access todirectories that support an X.500 model and (b) doesnot incur the resource requirements of the morecomplex X.500 Directory Access Protocol (DAP).Applications that use LDAP (known asdirectory-enabled applications) can use the directory asa common data store and for retrieving informationabout people or services, such as e-mail addresses,public keys, or service-specific configurationparameters. LDAP was originally specified in RFC

Glossary 49

1777. LDAP version 3 is specified in RFC 2251, and theIETF continues work on additional standard functions.Some of the IETF-defined standard schemas for LDAPare found in RFC 2256.

lightweight third party authentication (LTPA). Anauthentication framework that allows single sign-onacross a set of Web servers that fall within an Internetdomain.

LTPA. See lightweight third party authentication.

Mmanagement domain. The default domain in whichTivoli Access Manager enforces security policies forauthentication, authorization, and access control. Thisdomain is created when the policy server is configured.See also domain.

management server. Obsolete. See policy server.

metadata. Data that describes the characteristics ofstored data.

migration. The installation of a new version or releaseof a program to replace an earlier version or release.

multi-factor authentication. A protected object policy(POP) that forces a user to authenticate using two ormore levels of authentication. For example, the accesscontrol on a protected resource can require that theusers authenticate with both user name/password anduser name/token passcode. See also protected objectpolicy.

multiplexing proxy agent (MPA). A gateway thataccommodates multiple client access. These gatewaysare sometimes known as Wireless Access Protocol(WAP) gateways when clients access a secure domainusing a WAP. Gateways establish a single authenticatedchannel to the originating server and tunnel all clientrequests and responses through this channel.

Nnetwork-based authentication. A protected objectpolicy (POP) that controls access to objects based on theinternet protocol (IP) address of the user. See alsoprotected object policy.

PPAC. See privilege attribute certificate.

permission. The ability to access a protected object,such as a file or directory. The number and meaning ofpermissions for an object are defined by the accesscontrol list (ACL). See also access control list.

policy. A set of rules that are applied to managedresources.

policy server. The Tivoli Access Manager server thatmaintains the location information about other serversin the secure domain.

polling. The process by which databases areinterrogated at regular intervals to determine if dataneeds to be transmitted.

POP. See protected object policy.

portal. An integrated Web site that dynamicallyproduces a customized list of Web resources, such aslinks, content, or services, available to a specific user,based on the access permissions for the particular user.

privilege attribute certificate. A digital document thatcontains a principal’s authentication and authorizationattributes and a principal’s capabilities.

privilege attribute certificate service. Anauthorization API runtime client plug-in whichtranslates a PAC of a predetermined format in to aTivoli Access Manager credential, and vice-versa. Theseservices could also be used to package or marshall aTivoli Access Manager credential for transmission toother members of the secure domain. Customers maydevelop these services using the authorization ADK.See also privilege attribute certificate.

protected object. The logical representation of anactual system resource that is used for applying ACLsand POPs and for authorizing user access. See alsoprotected object policy and protected object space.

protected object policy (POP). A type of securitypolicy that imposes additional conditions on theoperation permitted by the ACL policy to access aprotected object. It is the responsibility of the resourcemanager to enforce the POP conditions. See also accesscontrol list, protected object, and protected object space.

protected object space. The virtual objectrepresentation of actual system resources that is usedfor applying ACLs and POPs and for authorizing useraccess. See also protected object and protected object policy.

private key. In computer security, a key that is knownonly to its owner. Contrast with public key.

public key. In computer security, a key that is madeavailable to everyone. Contrast with private key.

Qquality of protection. The level of data security,determined by a combination of authentication,integrity, and privacy conditions.


Rregistry. The datastore that contains access andconfiguration information for users, systems, andsoftware.

replica. A server that contains a copy of the directoryor directories of another server. Replicas back upservers in order to enhance performance or responsetimes and to ensure data integrity.

resource object. The representation of an actualnetwork resource, such as a service, file, and program.

response file. A file that contains a set of predefinedanswers to questions asked by a program and that isused instead of entering those values one at a time.

role activation. The process of applying the accesspermissions to a role.

role assignment. The process of assigning a role to auser, such that the user has the appropriate accesspermissions for the object defined for that role.

routing file. An ASCII file that contains commandsthat control the configuration of messages.

RSA encryption. A system for public-keycryptography used for encryption and authentication. Itwas invented in 1977 by Ron Rivest, Adi Shamir, andLeonard Adleman. The system’s security depends onthe difficulty of factoring the product of two largeprime numbers.

rule. One or more logical statements that enable theevent server to recognize relationships among events(event correlation) and to execute automated responsesaccordingly.

run time. The time period during which a computerprogram is executing. A runtime environment is anexecution environment.

Sscalability. The ability of a network system to respondto increasing numbers of users who access resources.

schema. The set of statements, expressed in a datadefinition language, that completely describe thestructure of a database. In a relational database, theschema defines the tables, the fields in each table, andthe relationships between fields and tables.

secure sockets layer (SSL). A security protocol thatprovides communication privacy. SSL enablesclient/server applications to communicate in a way thatis designed to prevent eavesdropping, tampering, andmessage forgery. SSL was developed by NetscapeCommunications Corp. and RSA Data Security, Inc.

security management. The management disciplinethat addresses an organization’s ability to control accessto applications and data that are critical to its success.

self-registration. The process by which a user canenter required data and become a registered TivoliAccess Manager user, without the involvement of anadministrator.

service. Work performed by a server. A service can bea simple request for data to be sent or stored (as withfile servers, HTTP servers, e-mail servers, and fingerservers), or it can be more complex work such as thatof print servers or process servers.

silent installation. An installation that does not sendmessages to the console but instead stores messagesand errors in log files. Also, a silent installation can useresponse files for data input. See also response file.

single signon (SSO). The ability of a user to logononce and access multiple applications without havingto logon to each application separately. See also globalsignon.

SSL. See Secure Sockets Layer.

SSO. See Single Signon.

step-up authentication. A protected object policy(POP) that relies on a preconfigured hierarchy ofauthentication levels and enforces a specific level ofauthentication according to the policy set on a resource.The step-up authentication POP does not force the userto authenticate using multiple levels of authenticationto access any given resource but requires the user toauthenticate at a level at least as high as that requiredby the policy protecting a resource.

suffix. A distinguished name that identifies the topentry in a locally held directory hierarchy. Because ofthe relative naming scheme used in LightweightDirectory Access Protocol (LDAP), this suffix applies toevery other entry within that directory hierarchy. Adirectory server can have multiple suffixes, eachidentifying a locally held directory hierarchy.

Ttoken. (1) In a local area network, the symbol ofauthority passed successively from one data station toanother to indicate the station temporarily in control ofthe transmission medium. Each data station has anopportunity to acquire and use the token to control themedium. A token is a particular message or bit patternthat signifies permission to transmit. (2) In local areanetworks (LANs), a sequence of bits passed from onedevice to another along the transmission medium.When the token has data appended to it, it becomes aframe.

Glossary 51

trusted root. In the Secure Sockets Layer (SSL), thepublic key and associated distinguished name of acertificate authority (CA).

Uuniform resource identifier (URI). The characterstring used to identify content on the Internet,including the name of the resource (a directory and filename), the location of the resource (the computerwhere the directory and file name exist), and how theresource can be accessed (the protocol, such as HTTP).An example of a URI is a uniform resource locator, orURL.

uniform resource locator (URL). A sequence ofcharacters that represent information resources on acomputer or in a network such as the Internet. Thissequence of characters includes (a) the abbreviatedname of the protocol used to access the informationresource and (b) the information used by the protocolto locate the information resource. For example, in thecontext of the Internet, these are abbreviated names ofsome protocols used to access various informationresources: http, ftp, gopher, telnet, and news; and thisis the URL for the IBM home page:http://www.ibm.com.

URI. See uniform resource identifier.

URL. See uniform resource locator.

user. Any person, organization, process, device,program, protocol, or system that uses a serviceprovided by others.

user registry. See registry.

Vvirtual hosting. The capability of a Web server thatallows it to appear as more than one host to theInternet.

WWeb Portal Manager (WPM). A Web-based graphicalapplication used to manage Tivoli Access Manager Baseand WebSEAL security policy in a secure domain. Analternative to the pdadmin command line interface, thisGUI enables remote administrator access and enablesadministrators to create delegated user domains andassign delegate administrators to these domains.

WebSEAL. A Tivoli Access Manager blade. WebSEALis a high performance, multi-threaded Web server thatapplies a security policy to a protected object space.WebSEAL can provide single sign-on solutions andincorporate back-end Web application server resourcesinto its security policy.

WPM. See Web Portal Manager.


Index

Aaccess control list

attaching to management object 24Access Manager

application development kit 10authorization API 10creating user accounts 23documentation 2Java runtime 25Java runtime environment 9, 19management object 24pdjrtecfg 19policy server 8, 22runtime environment 9secure domain 21security model 1upgrading Version 3.8 10upgrading Version 3.9 10WebSEAL 9

ACLSee access control list

AIXinstalling on 14removing from 40

application development kit 10authentication

Access Manager 3of external users 4using WebSEAL 4without WebSEAL 4

authorizationdeclarative 35group to role mapping 5integrated 3programmatic 35using deployment descriptors 5

authorization API 10aznapi.conf.file 30

Bbasic authentication

configured user 4

Ccaching realm

configuring 30specifying properties 31

CLASSPATHpdjrtecfg 20setting for startWebLogic 25setting for startWebLogic with language pack 26

configuration filecopying to WebLogic directory 21

configured user 4, 24, 36connection.pool 29creating

user accounts 23

creating (continued)users

using pdadmin 36WebSEAL junction

using pdadmin 33credential.cache.entry.lifetime 31credential.cache.max.entries 31credential.cache.num.buckets 31custom realm

configuring 27creating a new 27sample configuration file 28specifying properties 28specifying Realm Class Name 27specifying system user name 27testing 34

Ddeclarative authorization 35DefaultConfg.txt 28demonstration application 35deployment descriptors 5disk requirements 8

Ggenpass 24group.dn 29group.mapping.cache.entry.lifetime 32group.mapping.cache.max.entries 32GSKIT

setting SHLIB_PATH 16

HHP-UX

installing on 15removing from 40

Iinstallation 13

on AIX 14on HP-UX 15on Linux 16on Solaris 13on Windows 17

JJava

runtime on AIX 9Java 2 Enterprise Edition 2, 5Java runtime

library extensions directory 25junction

WebSEAL 3


junctionsconfiguring 32

Llanguage pack

non-English 26limitations

group within group 38java.security.ACL interface 38managing J2EE resources 38

Linuxinstalling on 16removing from 41setting LD_PRELOAD 16

listing serversusing pdadmin 23

Mmanagement object

attaching ACL to 24mapping

group to role 5memory requirements 8

Ppdadmin

creating a WebSEAL junction 33creating configured user 24creating user accounts 23creating users 36listing servers 23showing user settings 34

pdadmin_context_user 23, 24pdadmin.password 29pdadmin.user.name 28pdjrtecfg

command line 19setting CLASSPATH 20

pdrealm.registry.listing 29pdrealm.tracing 29pkgadd 13pkgrm 39policy server 8

specifying location 22prerequisites

software 8problem determination 37programmatic authorization 35properties

caching realm 31custom realm 28sample configuration file 28

RRealm property

pdadmin.user.name 28Realm Property

aznapi.conf.file 30connection.pool 29credential.cache.entry.lifetime 31credential.cache.max.entries 31

Realm Property (continued)credential.cache.num.buckets 31group.dn 29group.mapping.cache.entry.lifetime 32group.mapping.cache.max.entries 32pdadmin.password 29pdrealm.registry.listing 29pdrealm.tracing 29user.dn 29webseal.sso.configured 28wls.admin.user 29wls.admin.user.password.expiry 30wls.configurable.system.user 30

related publications viiiremoval instructions

AIX 40HP-UX 40Linux 41Solaris 39Windows 39

removingAccess Manager Java files 25

removing Tivoli Access Manager for WebLogichow to 39

rolesmapping 5

rpm 16, 41

Ssample configuration file

custom realm 28secure domain

joining 21Security Service Provider Interface 2servers

obtaining a list of 23SHLIB_PATH

setting on HP-UX 16single sign-on 9

testing with demonstration application 36WebSEAL 3

SMIT 14, 40Solaris


SSL communicationspecifying settings for 22svrsslcfg 22

startWebLogiccommand location 25

startWebLogic, Setting CLASSPATH for 25supported platforms 7svrsslcfg 2, 21

command line 22SvrSslCfg

command line 21swinstall 15swremove 40

Ttroubleshooting

authentication 37authorization service 37out of memory problem 37


Uupgrading

Access Manager for WebLogic 10WebLogic Server 10, 12WebSEAL 12

usage tips 36user account

activating 24user accounts

creating with pdadmin 23user identity

Tivoli Access Manager for WebLogic server 22user registry

centralized management 2user.dn 29

WWebLogic Server

compatibility mode 2, 7console 27Security Service Provider Interface 7service packs 7specifying listening port 27upgrading 12upgrading Version 6.1 10Version 7.0 support 7

WebSEAL 1, 9authentication 4configured user 4, 24junction 3single sign-on 3, 9, 32

WebSEAL junctionsconfiguring 32

webseal.sso.configured 28Windows


wls.admin.user 29wls.admin.user.password.expiry 30wls.configurable.system.user 30

Index 55

��

Printed in U.S.A.

SC32-1137-01

ibm tivoli access manager for weblogic server: user.s guide · ibm tivoli access manager...

Documents