IBM Tivoli Access Manager for WebSphere Application Server ...publib.boulder.ibm.com/tividd/td/ITAME/GC32-0850-00/en_US/PDF/... · IBM Tivoli Access Manager for WebSphere Application

IBM Tivoli Access Managerfor WebSphere Application Server

User’s GuideVersion 3.9

GC32-0850-00

IBM Tivoli Access Managerfor WebSphere Application Server

User’s GuideVersion 3.9

GC32-0850-00

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

Second Edition (April 2002)

This edition replaces SC32-0832-00

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

Contents

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

IBM Tivoli Access Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . viRelated publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . viiiAccessing publications online. . . . . . . . . . . . . . . . . . . . . . . . . . . . . xOrdering publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xProviding feedback about publications. . . . . . . . . . . . . . . . . . . . . . . . . . x

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

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

Chapter 1. Introducing IBM Tivoli Access Manager for WebSphere Application Server . . 1Introducing Access Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1Integrating Access Manager with IBM WebSphere Application Server . . . . . . . . . . . . . . . . 2J2EE role-based security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4Mapping of principals and groups to roles . . . . . . . . . . . . . . . . . . . . . . . . . 4Centralizing policy management for multiple WebSphere servers . . . . . . . . . . . . . . . . . . 7

Chapter 2. Installing IBM Tivoli Access Manager for WebSphere . . . . . . . . . . . 11Software contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11Supported platforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11Disk and memory requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11Software prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

WebSphere Application Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12Access Manager Base . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13Java Runtime Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13Xerces XML parser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

User registry prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14Installing IBM Tivoli Access Manager for WebSphere . . . . . . . . . . . . . . . . . . . . . 15

Installing Access Manager for WebSphere on Solaris . . . . . . . . . . . . . . . . . . . . . 15Installing Access Manager for WebSphere on AIX. . . . . . . . . . . . . . . . . . . . . . 16Installing Access Manager for WebSphere on HP-UX . . . . . . . . . . . . . . . . . . . . 17Installing Access Manager for WebSphere on Linux . . . . . . . . . . . . . . . . . . . . . 18Installing Access Manager for WebSphere on Windows . . . . . . . . . . . . . . . . . . . . 19

Configuring Access Manager for WebSphere . . . . . . . . . . . . . . . . . . . . . . . . 20Configuring the initial Access Manager for WebSphere installation . . . . . . . . . . . . . . . . 21Configuring additional Access Manager for WebSphere installations . . . . . . . . . . . . . . . 24

pdwascfg script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

Chapter 3. Migrating security roles to IBM Tivoli Access Manager for WebSphere . . . 29How to migrate security roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29Migration utility limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31Troubleshooting tips . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32migrateEAR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

Chapter 4. Administering IBM Tivoli Access Manager for WebSphere . . . . . . . . . 37Using Access Manager with WebSphere Advanced Edition Single Server . . . . . . . . . . . . . . . 37Using Access Manager administration tools. . . . . . . . . . . . . . . . . . . . . . . . . 37Specifying Access Manager for WebSphere properties . . . . . . . . . . . . . . . . . . . . . 38

Limiting simultaneous connections . . . . . . . . . . . . . . . . . . . . . . . . . . 38Enabling static role caching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

© Copyright IBM Corp. 2002 iii

Defining static roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39Configuring dynamic role caching . . . . . . . . . . . . . . . . . . . . . . . . . . . 39Specifying logging mechanism type . . . . . . . . . . . . . . . . . . . . . . . . . . 39Specifying logging level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40Specifying root object space name . . . . . . . . . . . . . . . . . . . . . . . . . . . 41Specifying document type definition directory . . . . . . . . . . . . . . . . . . . . . . . 41

Configuring WebSphere console to recognize Access Manager groups . . . . . . . . . . . . . . . . 41

Chapter 5. Tutorial: How to enable security . . . . . . . . . . . . . . . . . . . . 43Tutorial overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431: Adding security to a WebSphere application . . . . . . . . . . . . . . . . . . . . . . . 442: Adding users to the LDAP user registry . . . . . . . . . . . . . . . . . . . . . . . . . 493: Enabling WebSphere Application Server security . . . . . . . . . . . . . . . . . . . . . . 504: Deploying the application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 515: Testing security for the deployed application . . . . . . . . . . . . . . . . . . . . . . . 526: Install and configure Access Manager for WebSphere. . . . . . . . . . . . . . . . . . . . . 537: Migrating the application to Access Manager . . . . . . . . . . . . . . . . . . . . . . . 538: Testing security for the deployed application . . . . . . . . . . . . . . . . . . . . . . . 559: Changing roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5510: Testing security for the deployed application . . . . . . . . . . . . . . . . . . . . . . . 55

Chapter 6. Removing IBM Tivoli Access Manager for WebSphere . . . . . . . . . . 57Removing Access Manager for WebSphere on Solaris . . . . . . . . . . . . . . . . . . . . . 57Removing Access Manager for WebSphere on Windows . . . . . . . . . . . . . . . . . . . . 57Removing Access Manager for WebSphere on AIX . . . . . . . . . . . . . . . . . . . . . . 58Removing Access Manager for WebSphere on HP-UX . . . . . . . . . . . . . . . . . . . . . 59Removing Access Manager for WebSphere on Linux . . . . . . . . . . . . . . . . . . . . . . 59

Appendix. Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61Trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

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

Preface

Welcome to IBM® Tivoli® Access Manager for WebSphere Application Server(Access Manager for WebSphere). This product extends Access Manager to supportapplications written for IBM® WebSphere™ Application Server.

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

The IBM Tivoli Access Manager for WebSphere Application Server User’s Guide providesinstallation, configuration, and administration instructions. This document alsoprovides a tutorial on configuring centralized security policy for WebSphereapplications.

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 WebSphere Application Server systems and

applicationsv Security management, including authentication and authorization

If you are using 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, “Introducing Access Manager for WebSphere”

Presents an overview of the Access Manager components that provideauthorization services to WebSphere Application Server.

v Chapter 2, “Installing Access Manager for WebSphere”Describes how to install and configure Access Manager for WebSphere.

v Chapter 3, “Migrating security roles to Access Manager”Describes how to use the Access Manager for WebSphere migration utility tomigrate Java 2 Enterprise Edition security roles to Access Manager user andgroups.

v Chapter 4, “Administering Access Manager for WebSphere”Describes how to perform administration tasks that are used to manage AccessManager for WebSphere.

© Copyright IBM Corp. 2002 v

v Chapter 5, “Tutorial: How to enable security”Describes how to add security to a WebSphere Application Server application.Also describes how to migrate security information to Access Manager and howto test that security has been successfully enabled.

v Chapter 6, “Removing Access Manager for WebSphere”Describes how to remove Access Manager for Websphere.

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

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

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

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

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

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

v IBM Tivoli Access Manager for e-business Release Notes

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

Base informationv IBM Tivoli Access Manager Base Installation Guide

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

v IBM Tivoli Access Manager Base Administrator’s Guide

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

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

GC23-4796 (am39_zinstall.pdf)

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

Explains how to install and configure Access Manager Base for Linux on thezSeries platform.

WebSEAL informationv IBM Tivoli Access Manager WebSEAL Installation Guide

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

v IBM Tivoli Access Manager WebSEAL Administrator’s Guide

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

v IBM Tivoli Access Manager WebSEAL Developer’s Reference

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Preface vii

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

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

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

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

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

v IBM Tivoli Access Manager WebSEAL Developer’s Reference

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

Technical supplementsv IBM Tivoli Access Manager Performance Tuning Guide

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

v IBM Tivoli Access Manager Capacity Planning Guide

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

v IBM Tivoli Access Manager Error Message Reference

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

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

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

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

IBM DB2® Universal Database™

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

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

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

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

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

Windows® operating systems.v IBM SecureWay Directory Release Notes

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

v IBM SecureWay Directory Readme Addendum

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

v IBM SecureWay Directory Server Readme

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

v IBM SecureWay Directory Client Readme

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

v SSL Introduction and iKeyman User’s Guide

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

v IBM SecureWay Directory Configuration Schema

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

v IBM SecureWay Directory Tuning Guide

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

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

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

Preface ix

IBM WebSphere Application ServerIBM WebSphere Application Server Standard Edition, Version 4.0.2, is installedwith the Web portal manager interface. For information about IBM WebSphereApplication Server, see the following Web site:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

you are locatedv What information to gather before contacting support

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

Typeface conventionsThe following typeface conventions are used in this book:

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

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

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

Preface xi

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

Chapter 1. Introducing IBM Tivoli Access Manager forWebSphere Application Server

IBM Tivoli Access Manager for WebSphere Application Server (Access Manager forWebSphere) is an extension of Access Manager Version 3.9 that providescontainer-based authorization and centralized policy management for IBMWebSphere Application Server applications.

Access Manager for WebSphere integrates with WebSphere Application ServerVersion 4.0.2 and makes authorization decisions on incoming requests for access toprotected resources.

By deploying Access Manager for WebSphere, a network administrator can useAccess Manager to provide centralized management of security policy both forWebSphere Application Server resources and for resources that are unrelated toWebSphere Application Server.

Access Manager features include management of common identities, user profiles,and authorization mechanisms. Access Manager provides a graphical user interfaceutility, the Access Manager Web Portal Manager, that can be used as a single pointof security management for both Java 2 Enterprise Edition (J2EE) compliant andnon-J2EE-compliant resources.

WebSphere Application Server, Advanced Edition 4.0.2, supports the J2EE securityclasses and APIs. Access Manager for WebSphere supports WebSphere applicationsthat use the J2EE security classes. Access Manager provides this support withoutrequiring any coding or deployment changes to the applications.

Introducing Access ManagerAccess Manager for WebSphere integrates with WebSphere containers and enablesthem to use the security services provided by an Access Manager secure domain.The Access Manager secure domain must be deployed prior to installation ofAccess Manager for WebSphere.

Users who are new to Access Manager should review the Access Manager securitymodel before deploying an Access Manager secure domain.

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

Access Manager features state-of-the-art security policy management. In addition,Access Manager supports authentication, authorization, data security, and resourcemanagement capabilities. You use Access Manager in conjunction with standardInternet-based applications to build highly secure and well-managed intranets andextranets.

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

© Copyright IBM Corp. 2002 1

Access Manager supports a wide range of authentication mechanisms. Note,however, that WebSphere performs its own authentication steps before usingAccess Manager for WebSphere.

v An authorization frameworkThe Policy Authorization Service, accessed through standard Java 2 EnterpriseEdition authorization classes, provides permit and deny decisions on accessrequests for native Access Manager servers and third-party applications.

You can learn more about Access Manager, including information necessary tomake deployment decisions, by reviewing the documentation distributed withTivoli Access Manager Version 3.9. Start with the following guides:v IBM Tivoli Access Manager Base Installation Guide, GC32-0735

This guide describes how to plan, install, and configure an Access Managersecure domain. A series of easy installation scripts enable you to quickly deploya fully functional secure domain. These scripts are very useful when prototypingthe deployment of a secure domain.

v Tivoli Access Manager Base Administration Guide, GC32-0680This document presents an overview of the Access Manager security model formanaging protected resources. This guide describes how to configure the AccessManager servers that make access control decisions. In addition, detailedinstructions describe how to perform important tasks such as declaring securitypolicies, defining protected object namespaces, and administering user andgroup profiles.

The Access Manager documentation is included on the Tivoli Access Manager BaseVersion 3.9 CD, and is also available from the Tivoli Customer Support web site.For more information, see “Accessing publications online” on page x.

Integrating Access Manager with IBM WebSphere Application ServerAccess Manager for WebSphere integrates with IBM WebSphere Application ServerAdvanced Edition Version 4.0.2.

When a user (principal) attempts to access a protected resource, WebSphereperforms the following tasks:v Authenticates the Principal.v When security is specified in the deployment descriptor for an application

(declarative security), a WebSphere container determines if the current principalidentity has been granted any of the required roles.

v When application developer has added security code directly into theapplication (programmatic security), a WebSphere container uses AccessManager to perform the necessary role membership checks.

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

Figure 1 illustrates the following sequence of events:1. When a WebSphere application with J2EE security is run, and the user tries to

access a protected resource, WebSphere Application Server authenticates theuser, using the user registry. For example, in Figure 1 WebSphere AdvancedEdition (multiple server version) authenticates against an IBM SecureWayDirectory user registry. The user registry is shared with Access Manager. ForWebSphere Advanced Edition Single Server (AEs), the authentication is againsthost-based security.

2. When the user requests access to a protected method or resource, theWebSphere container uses information from the J2EE application deploymentdescriptor to determine the required role membership.

3. The WebSphere container uses the integrated Access Manager module torequest an authorization decision (“granted” or “denied”) from the AccessManager authorization server.The WebSphere container also passes additional context information, whenpresent, to the authorization server. The optional context information caninclude cell name, host name, and server name. If the Access Manager policydatabase has policy specified for any of the context information, theAuthorization Server can use this information when making the authorizationdecision.

4. The authorization server consults the Access Manager user definitions in theshared user registry. (The user registry is shared with WebSphere, unlessWebSphere AEs is used). The authorization server then consults thepermissions that have been defined for the specified user within the Access

WebSphere

User

Authentication

WebSphere container

integrated with

Access Manager

J2EE Application Deployment Descriptor

WebSphere Application Server

Advanced Edition 4.0.2

IBM SecureWay

LDAP Server

Access Manager

Authorization Server

Access Manager

Policy Database

Access Manager

Policy Server

Access Manager

Policy DatabasePolicy

Database

Replication

Solid arrows

indicate

usage of

a module

by another

module

Figure 1. Access Manager integrates with WebSphere Application Server

Chapter 1. Introducing IBM Tivoli Access Manager for WebSphere Application Server 3

Manager protected object namespace. The protected object namespace isincluded in the policy database shown in Figure 1.

5. The Access Manager authorization server returns the access decision to theWebSphere container.

6. WebSphere Application Server either grants or denies access to the protectedmethod or resource.

J2EE role-based securityJ2EE security uses the concept of a principal to represent the identity of an entitythat performs activities. Entities can be people (users) or processes. In addition,J2EE uses the concept of a role as described below.

Methods are mapped to roles. The following table from a sample bankingapplication defines roles and maps methods to them. The entry granted in thetable below indicates that the role can access the specified method.

Roles Methods

getBalance deposit closeAccount

Teller granted granted

Cashier granted

Super granted

The roles that have been defined above can then be mapped to principals and/orgroups. The entry Invoke in the table cells below indicates that theprincipal/group can invoke any methods that have been granted to that role.

Principal/Group Roles

Teller Cashier Supervisor

TellerGroup Invoke

CashierGroup Invoke

SupervisorGroup

Frank (a principal) Invoke Invoke

In the table above, the principal Frank can invoke the getBalance andcloseAccount methods but cannot invoke the deposit method, because this methodhas not been granted to either the Cashier or Supervisor role.

Mapping of principals and groups to rolesPrior to application runtime, the Access Manager migration utility is run topopulate the Access Manager protected object namespace. The migration utilityobtains information about roles and methods from the J2EE applicationdeployment descriptors.

At application runtime, when a user requests access to a protected resource, theWebSphere container is passed the following information:v Principal

The authenticated identity of the user.v RoleName


The name of a role.v AppName

The name of the application.v CellName

The name of a grouping of host systems on the network.v HostName

The name of a host system contained in CellName.v ServerName

The name of a server that is hosted by HostName.

The role names are derived from the method-to-role mappings in the deploymentdescriptors. By default, Access Manager’s access check is performed based on theRoleName and AppName. The access check can easily be extended to take intoaccount CellName, HostName and ServerName. These values are optional, andare evaluated only when they are defined.

Access Manager access control lists (ACLs) determine which J2EE application rolesa principal has been assigned. The migration utility attaches ACLs to the<AppName> in the protected object namespace.

Figure 2 illustrates the following sequence of events:

Access Manager

Policy Server

J2EE Application Deployment Descriptor

Access Manager


/

"WebAppServer"

"deployedResources"

<RoleName>

<AppName>

<CellName>

<HostName>

<ServerName>

Access Manager Protected Object Namespace

Access Manager

Access Control Lists

(ACLs) determine

which J2EE

application roles a

user has been

granted

<CellName>, <HostName>,

and <ServerName> are

optional levels of granularity

Solid arrows

indicate

usage of

a module

by another

module

WebSphere Application Server

Advanced Edition 4.0.2Access Manager

Migration Utility

Figure 2. Mapping of roles to the Access Manager protected object space.


1. Before application runtime, the Access Manager migration utility accesses theJ2EE application deployment descriptor to extract information on roles androle-to-principal/group mapping.

2. The migration utility converts the information into the Access Manager format,and passes it to the Access Manager policy server.

3. The Access Manager policy server adds entries to the protected objectnamespace to represent the roles defined for the application. Whenrole-to-principal/group mappings have been defined in the deploymentdescriptor, the appropriate principals/groups are added to the ACLs that areattached to the new objects.

The Access Manager security model uses the definitions stored in the protectedobject namespace to build a hierarchy of resources to which ACLs can be attached.These ACLs define the mapping of roles to users/groups.

Figure 3 below illustrates how ACLs can be applied to the protected objectnamespace that describes a role. The protected object namespace for all WebSphereapplications consists of a top-level Access Manager protected object calledWebAppServer. The WebAppServer object has a child object calleddeployedResources. Together, these two object names serve as a top-level prefix toall J2EE roles defined in WebSphere applications.

Roles are defined in the next level in the hierarchy, as a resource named for therole: <RoleName>. Directly under this object is the resource representing theapplication: <AppName>. Underneath the <AppName> protected object are severaloptional resources that can be defined to more precisely control access to roles. Theoptional resources are <CellName>, <HostName>, and <ServerName>.

In Figure 3 above, ACL 1 grants user1 access to the specified <RoleName>, in anyapplication anywhere in the network. User2 and group1 are denied access.

In the Access Manager security model, these access settings are inherited by theobjects defined underneath <RoleName> in the protected object space hierarchy.This inheritance occurs by default. Thus, in Figure3, the access settings are

/

"WebAppServer"

"deployedResources"

<RoleName>

<AppName>

<CellName>

<HostName>

<ServerName>

Access Manager Protected Object Namespace

ACL 1

user1

user2

grp1

i

---

---

ACL 2

user1

user2

grp1

---

---

---

Figure 3. Attaching Access Manager ACLs to objects in the protected object namespace.


inherited by the objects representing<AppName>/<HostName>/<CellName>/<ServerName>.

Sometimes security policy requires that the access settings for objects locatedunderneath the ACL attachment point must differ from the inherited accesssettings. In this case, the Access Manager administrator defines a new ACLcontaining the required access settings. The administrator then attaches the newACL to the object at the specified point of control. This new ACL overrides theinherited access settings.

For example, security policy might dictate that user1 should not be granted<RoleName> permission when the application is run on a specific server on aspecific host within a specific cell. To enforce this policy, the administrator definesa more restrictive ACL, as represented in Figure 3 by ACL 2. This ACL deniesaccess to user1, user2, and grp1. The administrator then attaches this ACL to the<ServerName> object that represents the server to which access must be restricted.

Figure 3 shows the attachment of ACL 2 to <ServerName>. Note that ACL 2 appliesonly to the specified server. When more than one <ServerName> object is definedunderneath <HostName>, ACL 2 applies only to the <ServerName> object to whichit is attached. All other <ServerName> objects at this level in the hierarchy continueto inherit the access settings defined in ACL 1 and attached to <RoleName>.

For more information on the use of ACLs in the Access Manager protected objectnamespace, see the IBM Tivoli Access Manager Base Administration Guide.

Centralizing policy management for multiple WebSphere serversAccess Manager provides centralized management of security policies. AccessManager can manage security policy across multiple WebSphere ApplicationServers. In addition, Access Manager uses the same model to manage securityacross non-WebSphere applications.

After the roles and principal/group mappings described in a J2EE application’sdeployment descriptors have been migrated to Access Manager, and the users andgroups have been registered with Access Manager, you can use the AccessManager management tools to manage further changes to the security definitions.Use the Access Manager Web portal manager to manage changes in securitydefinitions related to the mapping of roles to principals/groups. Use theWebSphere console to make other security-related changes. Note that changes torole mappings made through the WebSphere console will not be visible to theAccess Manager security model.

Use the following Access Manager tools to manage security policy:v Access Manager Web portal manager

The Web Portal Manager is the Access Manager management console. Thisconsole provides a graphical user interface for managing the Access Managerusers, actions, and resources that are defined in the Access Manager protectedobject namespace. The console can be used for creating and managing ACLs.The console can also be used to manage user and group definitions in the userregistry.For more information, see the IBM Tivoli Access Manager Base AdministrationGuide.

v pdadmin


The pdadmin utility is a command-line based utility for managing the AccessManager security model. This powerful utility can be used to manage all aspectsof the Access Manager protected object namespace, including users, objects,resources, and ACLs. Also, pdadmin can manage user and group entries in userregistries. Administrators can use this utility within scripts or programs toautomate administration tasks.For more information, see the IBM Tivoli Access Manager Base AdministrationGuide.

v Access Manager C Administration APIAccess Manager provides a programmatic interface to the administration tasksaccomplished by pdadmin and the Web Portal Manager. Application developerscan use this API to perform administration tasks that are specific to theapplication.For more information, see the IBM Tivoli Access Manager Administration C APIDeveloper Reference.

WebSphere Advanced

Edition 4.0.2

Access

Manager

for WebSphere

IBM SecureWay

Directory LDAP

Server

Policy

Administration

Machine C Machine D

Machine F

Access Manager


Access

Manager

Policy Database

Machine E

Access Manager

Policy Server

Access Manager

Policy Database

Access Manager

Authorization

Server

Access

Manager Policy

Database

WebSphere

Advanced Edition

4.0.2

WebSphere Advanced

Edition 4.0.2

Machine A

Access Manager

Web Portal

Manager

Machine G

Machine B

Access

Manager

pdadmin

utility

Policy Database

replication

Solid arrows

indicate

usage of

a module

by another

module

Access

Manager for

WebSphere

Figure 4. Access Manager provides centralized administration for multiple WebSphereApplication Servers


Figure 4 above illustrates Access Manager’s management of security acrossmultiple WebSphere servers. The Access Manager Web portal manager has beeninstalled with WebSphere Application Server 4.0.2 on Machine A. The pdadminutility is shown on a non-WebSphere system, Machine B.

Both the Web portal manager and pdadmin use the Access Manager policy serveron Machine D to administer security policy.

The Access Manager authorization server can be installed on a separate systemfrom WebSphere 4.0.2. In Figure 4, Machine E hosts WebSphere Application Server.This server has an Access Manager for WebSphere module that has been integratedinto the WebSphere container responsible for authorization decisions. TheWebSphere container obtains authorization decisions from the Access Managerauthorization server on Machine F.

The Access Manager authorization server can also be installed on the same systemas the WebSphere Application Server, as shown on Machine G. The Access Managerfunctionality is identical to that provided when the servers are on separate systems(as shown on Machine E and Machine F). Co-location of the Access Managerauthorization server with the WebSphere Application Server optimizesperformance when making authorization decisions. This configuration isrecommended.

Note that the Access Manager policy database is replicated from Machine D to bothMachine F and Machine G. This replication increases performance and providesfailover capability.

Figure 4 also shows that the Access Manager servers and the WebSphere serversshare an LDAP user registry on Machine C. Figure 4 assumes that WebSphereAdvanced Edition (multiserver) is being used. The user registry is not shared whenusing WebSphere Advanced Edition Single Server.



Chapter 2. Installing IBM Tivoli Access Manager forWebSphere

This chapter contains the following topics:v “Software contents”v “Supported platforms”v “Software prerequisites” on page 12v “Installing IBM Tivoli Access Manager for WebSphere” on page 15v “Configuring Access Manager for WebSphere” on page 20

Software contentsIBM Tivoli Access Manager for WebSphere Application Server (Access Manager forWebSphere) provides a component that integrates with WebSphere ApplicationServer, and takes responsibility for all mappings of roles to principals/groups.

Access Manager for WebSphere also provides a migration utility that can be usedto import role-to-principal/group mappings from a Java 2 Enterprise Edition (J2EE)deployment descriptor into an Access Manager security schema. This utility canmigrate data from either compressed or expanded WebSphere 4.0 EnterpriseArchive (EAR) files.

The Access Manager for WebSphere distribution contains one installation packagefor each supported platform. The package includes the following software:v Access Manager for WebSphere Java classesv A configuration script pdwascfg for the Java classesv A migration utilityv Sample tutorial code that demonstrates the use of the migration utility and the

Java classes

Supported platformsAccess Manager for WebSphere is supported on the following platforms:v AIX 4.3.3 and 5.1v Redhat Linux 7.1v Solaris 2.7 and 2.8v HP-UX 11.0v Windows 2000 Advanced Server, Service Pack 2

Disk and memory requirementsAccess Manager for WebSphere has the following disk and memory requirements:v 64 MB RAM

This is the amount of memory needed in addition to the memory requirementsspecified by IBM WebSphere Application Server and by any other AccessManager components. The amount of memory needed by other Access Manager


components will depend on which Access Manager components are installed onthe host system. For more information, see the IBM Tivoli Access Manager BaseInstallation Guide.

v 100 MB disk spaceThis requirement is above and beyond the disk space required by IBMWebSphere Application Server and by any other Access Manager components.

Software prerequisitesThe following sections discuss the prerequisites for the integration of AccessManager for WebSphere with a WebSphere Application Server environment.v “WebSphere Application Server”v “Access Manager Base” on page 13v “Java Runtime Environment” on page 13v “Xerces XML parser” on page 14

WebSphere Application ServerThe Access Manager for WebSphere component requires one of the followingWebSphere Application Server products to be installed on the host system:v IBM WebSphere Application Server, Advanced Edition Version 4.0, PTF 2 (4.0.2)

OR

v IBM WebSphere Application Server 4.0, Advanced Edition Single Server (AEs),Version 4.0, PTF 2 (4.0.2).

Note: The Single Server edition requires specific configuration steps. See “UsingAccess Manager with WebSphere Advanced Edition Single Server” onpage 37.

Before you can install Access Manager for WebSphere you must install IBMWebSphere Application Server Version 4.0 PTF 2 (4.0.2).

The WebSphere Application Server, Advanced Edition, must be configured to use auser registry that will be shared with Access Manager. The WebSphere users andgroups must be imported into Access Manager.

Note: The requirement to share a user registry does not apply to WebSphereApplication Server, Advanced Edition Single Server. The Single Serveredition uses host-based security.

Documentation on installation of the IBM WebSphere Application Server Version4.0 is available at the following URL:

http://www-4.ibm.com/software/webservers/appserv/doc/v40/ae/infocenter/was/nav_pdf.html

If you are new to IBM WebSphere Application Server, consult the Getting Startedwith IBM WebSphere Application Server Version 4.0 guide. This guide is available atthe URL above.

To obtain the Version 4.0.2 PTF, consult the WebSphere product Web site at thefollowing URL:http://www-3.ibm.com/software/webservers/


Access Manager BaseRequired component on the local host

Access Manager for WebSphere requires that the Access Manager Base Javaruntime component be installed on the local computer that hosts the WebSphereApplication Server. This is the minimum Access Manager Base softwareprerequisite for supporting Access Manager for WebSphere.

The Access Manager for WebSphere does not require any additional AccessManager components on the local computer that hosts the WebSphere ApplicationServer.

Optional components on the local host

While you are not required to add any additional Access Manager components onthe local host, you can optimize performance by installing the Access Managerauthorization server on the same host as the WebSphere Application Server. Theauthorization server has a prerequisite on the Access Manager runtimeenvironment. Both of these components are distributed as part of the Tivoli AccessManager Base product.

Access Manager secure domain

Access Manager for WebSphere must be able to access an Access Manager securedomain. The authorization component must be able to contact an Access Managerpolicy server and an Access Manager authorization server. Thus, after you haveinstalled the IBM WebSphere Application Server, you must establish an AccessManager secure domain before installing Access Manager for WebSphere.

To establish an Access Manager secure domain, you must install and configure theAccess Manager policy server. Typically this is not run on the same host as theWebSphere Application Server. You will also need to install and configure anAccess Manager authorization server, either on the WebSphere Application Serverhost, or on a different system.

For more information on installing and configuring an Access Manager securedomain, including the Access Manager Base Java runtime, see the IBM Tivoli AccessManager Base Installation Guide. This guide is distributed on the IBM Tivoli AccessManager Base Version 3.9 CD. It is also available online. See “Accessingpublications online” on page x.

Java Runtime EnvironmentThe computer system that hosts Access Manager for WebSphere must have thefollowing Java Runtime Environment (JRE) software installed:

Operating System Java Runtime Environment

AIX IBM JRE Version 1.3

Linux

Windows

Solaris Sun JRE Version 1.3

Chapter 2. Installing IBM Tivoli Access Manager for WebSphere 13

Note that the Java Runtime Environment is installed and configured as part of theIBM WebSphere Application Server installation. Access Manager for WebSphereuses the same JRE.

Xerces XML parserThe Access Manager for WebSphere migration utility requires access to the Xerces1.4.2 parser. This parser is distributed as the file Xerces.jar, and is included in theWebSphere Application Server Version 4.0.2 product. You will need to ensure thatthe migration run script is configured to access the correct directory. This is doneby ensuring that the environment variable WAS_HOME is set to the WebSphereApplication Server installation directory.

User registry prerequisitesAccess Manager for WebSphere operates as part of an Access Manager securedomain. The Access Manager policy server for the secure domain uses a userregistry to manage user and group information.

Access Manager for WebSphere supports all of the user registry types that aresupported by Access Manager Base:v IBM SecureWay Directoryv iPlanet Directoryv Lotus Dominov Active Directory

For a complete list of supported versions of each user registry type, see the IBMTivoli Access Manager Base Installation Guide.

The user registry prerequisites for each installation are also based on the version ofWebSphere Application Server that is used with Access Manager for WebSphere.v WebSphere Application Server, Advanced Edition, Version 4.0 PTF 2 (4.0.2)

There are two prerequisites for use of user registries that must be satisfied beforeinstalling Access Manager for WebSphere:1. The Access Manager policy server and the WebSphere Application Server

must be configured to use the same user registry. For example, they mustaccess the same IBM SecureWay Directory LDAP user registry.

2. Any existing users and groups defined for WebSphere Application Servermust be imported into the Access Manager user directory, to become AccessManager users and groups. Importing here means adding extended AccessManager attributes, along with the existing user and group definitions, intothe Access Manager security schema.Users can be imported into the Access Manager user registry manually usingthe pdadmin command. Access Manager domains that use IBM SecureWayDirectory LDAP can make use of the SecureWay Directory bulk load feature.For more information on using the pdadmin command to import usersmanually, see the IBM Tivoli Access Manager Base Administration Guide.For more information on the bulk loading of IBM SecureWay Directory users,see the IBM Tivoli Access Manager Performance Tuning Guide.

v WebSphere Application Server, Advanced Edition Single Server (AEs), Version4.0


WebSphere AEs does not use any external user registry. Instead, it works withhost-based security. Each user account on the host system must have anequivalent entry in the user registry used by Access Manager.Note that any changes made over time to the host-based security must also bemade to the user registry used by Access Manager.

Installing IBM Tivoli Access Manager for WebSphereThis section describes how to install Access Manager for WebSphere, includingboth the authorization component and the migration utility.

Complete the instructions that apply to your operating system:v “Installing Access Manager for WebSphere on Solaris”v “Installing Access Manager for WebSphere on AIX” on page 16v “Installing Access Manager for WebSphere on HP-UX” on page 17v “Installing Access Manager for WebSphere on Linux” on page 18v “Installing Access Manager for WebSphere on Windows” on page 19

Installing Access Manager for WebSphere on SolarisThe Access Manager for WebSphere installation separates file extraction frompackage configuration. Use pkgadd to install software packages on Solaris. Thenuse pdwascfg to configure Access Manager.

Note: If you have already installed and configured Access Manager for WebSphereand need to reinstall it, you must first unconfigure and remove it. See“Removing Access Manager for WebSphere on Solaris” on page 57.

To install Access Manager for WebSphere on Solaris complete the followinginstructions:1. Log in as user root.2. Verify that you have satisfied the prerequisites for installing Access Manager

for WebSphere.To review software dependencies, see “Software prerequisites” on page 12.

3. Verify that the Access Manager policy server and the WebSphere Applicationserver are configured to use the same user registry.

Note: This step does not apply to WebSphere AEs.

To review user registry dependencies, see “User registry prerequisites” onpage 14.

4. Verify that WebSphere Application Server users and groups have beenimported from the user registry into the Access Manager user registry schema.You can use the Access Manager pdadmin command to manually import users.For example, the syntax for importing an LDAP user is:pdadmin> user import <UserID> <Distinguished_Name_of_the_user_in_LDAP>

For more information on pdadmin, see the IBM Tivoli Access Manager BaseAdministration Guide.

For large numbers of users in an IBM SecureWay Directory LDAP environment,consider using the LDAP bulk import feature. For more information see theIBM Tivoli Access Manager Performance Tuning Guide.


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

package:# pkgadd -d . PDWAS

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

8. Next, configure Access Manager for WebSphere. Go to “Configuring AccessManager for WebSphere” on page 20.

Installing Access Manager for WebSphere on AIXThe Access Manager for WebSphere installation separates file extraction frompackage configuration. Use SMIT to install software packages on AIX. Then usepdwascfg to configure Access Manager for WebSphere.

Note: If you have already installed and configured Access Manager for WebSphereand need to reinstall it, you must first unconfigure and remove the AccessManager for WebSphere package. See “Removing Access Manager forWebSphere on AIX” on page 58.

To install Access Manager for WebSphere on AIX complete the followinginstructions:1. Log in as root.2. Verify that you have satisfied the prerequisites for installing Access Manager





4. Verify that WebSphere Application Server users and groups have beenimported from the user registry into the Access Manager user registry schema.You can use the Access Manager pdadmin command to manually importusers. For example, the syntax for importing an LDAP user is:pdadmin> user import <UserID> <Distinguished_Name_of_the_user_in_LDAP>


For large numbers of users in an IBM SecureWay Directory LDAPenvironment, consider using the LDAP bulk import feature. For moreinformation see the IBM Tivoli Access Manager Performance Tuning Guide.

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

# smit


The SMIT utility starts.7. 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.

8. 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.9. Click the List button for SOFTWARE to install.

A Multi-select List window displays the list of IBM Tivoli Access Managersoftware packages.

10. Select the Access Manager for WebSphere Application Server package. ClickOK.

11. The Install and Update Software from LATEST Available Software dialog boxappears.

12. Verify that the default value of yes is present in the field labeledAUTOMATICALLY install requisite software.

13. Set other fields to values appropriate to your installation. In most cases, youcan accept the default values. Click OK.

14. A message box appears asking if you are sure you want to install thispackage. Click OK.The package files are installed. Several status messages are displayed. A finalstatus message indicates success upon completion of file extraction.

15. Click Done. Click Cancel to exit SMIT.16. Next, configure Access Manager for WebSphere. Go to: “Configuring Access

Manager for WebSphere” on page 20.

Installing Access Manager for WebSphere on HP-UXThe Access Manager for WebSphere installation separates file extraction frompackage configuration. Use swinstall to install software packages on HP-UX. Thenuse pdwascfg to configure Access Manager for WebSphere.

Note: If you have already installed and configured Access Manager for WebSphereand need to reinstall it, you must first unconfigure and remove it. See“Removing Access Manager for WebSphere on HP-UX” on page 59.

To install Access Manager for WebSphere on HP-UX, complete the following steps:1. Log in as user root.2. Verify that you have satisfied the prerequisites for installing Access Manager









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

6. Change directory to hp.7. Enter the following command to install the Access Manager for WebSphere

package:# swinstall -s /<temp_directory> PDWAS

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

8. Next, configure Access Manager for WebSphere. Go to: “Configuring AccessManager for WebSphere” on page 20.

Installing Access Manager for WebSphere on LinuxThe Access Manager for WebSphere installation separates file extraction frompackage configuration. Use rpm to install software packages on Linux. Then usepdwascfg to configure Access Manager.

Note: If you have already installed and configured Access Manager for WebSphereand need to reinstall it, you must first unconfigure and remove it. See“Removing Access Manager for WebSphere on Linux” on page 59.

To install Access Manager for WebSphere on Linux complete the followinginstructions:1. Log in as user root.2. Verify that you have satisfied the prerequisites for installing Access Manager


3. Verify that the Access Manager policy server and the WebSphere ApplicationServer are configured to use the same user registry.







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 Access Manager for WebSphere

package:# rpm -i PDWAS-PD-3.9.0.0.i386.rpm

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

8. Next, configure Access Manager for WebSphere. Go to “Configuring AccessManager for WebSphere” on page 20.

Installing Access Manager for WebSphere on WindowsThe Access Manager for WebSphere installation separates file extraction frompackage configuration. Use an InstallShield setup.exe to install the Access Managerfor WebSphere files. Next, use pdwascfg to configure Access Manager forWebSphere.

Note: If you have already installed and configured Access Manager for WebSphereand need to reinstall it, you must first unconfigure and remove it. See“Removing Access Manager for WebSphere on Windows” on page 57.

To install and configure Access Manager for WebSphere on Windows complete thefollowing instructions:1. Log in to the Windows domain as a user with Windows administrator

privileges.2. Verify that you have satisfied the prerequisites for installing Access Manager





4. Verify that WebSphere Application Server users and groups have beenimported from the user registry into the Access Manager user registry schema.


You can use the Access Manager pdadmin command to manually importusers. For example, the syntax for importing an LDAP user is:pdadmin> user import <UserID> <Distinguished_Name_of_the_user_in_LDAP>


For large numbers of users in an IBM SecureWay Directory LDAPenvironment, consider using the LDAP bulk import feature. For moreinformation see the IBM Tivoli Access Manager Performance Tuning Guide.

5. Insert the IBM Tivoli Access Manager Web Security CD into the CD drive.6. Run the Access Manager for WebSphere 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\PDWAS\Disk Images\Disk 1\setup.exe

The Choose Setup Language dialog box appears.7. Run the Access Manager for WebSphere InstallShield setup program by

double-clicking on the setup.exefile.The Choose Setup Language dialog box appears.

8. Select the appropriate language and click OK.The InstallShield program starts and the Welcome dialog box appears.

9. Click Next.The License Agreement dialog box appears.

10. Click Yes to accept the License Agreement.The Choose Destination Location dialog box appears.

11. Accept the default or specify an alternative location. Click Next.The files are extracted to the disk. A message appears indicating that the fileshave been installed.

12. Click Finish to exit the setup program.13. Next, configure Access Manager for WebSphere. Go to: “Configuring Access

Manager for WebSphere”.

Configuring Access Manager for WebSphereConfiguration of Access Manager for WebSphere consists of two sets of actions.These sets of actions can be summarized as follows:1. Configuration of the authorization component

v Complete this configuration on each WebSphere Application Server that hostssecured applications.

v Use the pdwascfg configuration utility to configure the Access Manager forWebSphere authorization component.This utility sets the CLASSPATH variable, and calls the Java classcom.tivoli.mts.SvfSslCfg to configure the SSL communication between theAccess Manager for WebSphere authorization component and both theAccess Manager policy server and the Access Manager authorization server.This utility also creates a user identity for the Access Manager for WebSphereclasses on the host system (computer).

v During initial configuration only, use the Access Manager administrativeutilities to establish the necessary administrative user.


2. Migration of security information from J2EE applications EAR files to theAccess Manager policy database.v You need to perform this configuration only on systems that have J2EE

application EAR files containing security information that must be migratedto the Access Manager policy database

v Use the migrate utility to complete the configuration.v Complete the migration of the admin.ear file during initial configuration of

Access Manager for Websphere.

Continue to one of the following sections:v “Configuring the initial Access Manager for WebSphere installation”v “Configuring additional Access Manager for WebSphere installations” on page 24

Configuring the initial Access Manager for WebSphereinstallation

To configure the initial installation of Access Manager for WebSphere, complete thefollowing steps.1. Verify that you have already configured the Access Manager Java runtime to

access the Java runtime that is distributed with IBM WebSphere ApplicationServer. This configuration step is typically performed during configuration ofthe Access Manager Java runtime.

Note: The Access Manager Java runtime is a software prerequisite for AccessManager for WebSphere.

If you have not configured the Access Manager Java runtime to access theJava runtime that is distributed with IBM WebSphere Application Server, do itnow. Complete the following steps:a. Verify that environment variable WAS_HOME is set to the IBM WebSphere

Application Server home directory.b. Change directory to the following location:

(UNIX) /opt/PolicyDirector/sbin

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

c. Enter the following command:(UNIX) pdjrtecfg -action config -java_home $WAS_HOME/java/jre

(Windows) pdjrtecfg -action config -java_home %WAS_HOME%\java\jre

2. Create an Access Manager administrative user for WebSphere ApplicationServer.Use either pdadmin or the Access Manager Web portal manager to create thenew user. For example, use pdadmin as follows:C:> pdadmin -a sec_master -p <myPassword>

Substitute the correct password for the sec_master account for your AccessManager secure domain.

pdadmin> user create wsadmin cn=wsadmin,o=<organization>,c=<country> wsadmin wsadmin myPassword

Substitute values for organization and country that are valid for your LDAPuser registry.

3. Assemble the following information:v The name of the user account you want to create as a user identity for the

Access Manager for WebSphere application. For example, pdpermadmin.


v The password for the sec_master account.v The fully qualified domain name for the computer that hosts the Access

Manager policy server.v The fully qualified domain name for the computer that hosts the Access

Manager authorization server.

An example of the assembled information:[ cn=pdpermadmin myPassWord pdmgrserver.mysubnet.ibm.com pdacldserver.mysubnet.ibm.com ]

4. Verify that the correct version of the Java Runtime Environment will beaccessed when pdwascfg is run. This version should match the one specifiedduring the configuration of the Access Manager Java runtime.v On Windows systems, verify that the %PATH% variable lists the Java

Runtime Environment supplied by WebSphere Application Server as thefirst one in the path.

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

The response should be:/opt/WebSphere/AppServer/java/jre/bin/java

If the version is not correct, reset the PATH variable so that the correct Javapath is first.

5. Run the pdwascfg utility. Use the information you collected in the previousstep to supply the command line options to pdwascfg.Use the steps that apply to your operating system:v For UNIX operating systems:

For example, using the example information from the previous step, enterthe following at a command prompt:

# pwdwascfg -action config -remote_acl_user cn=pdpermadmin -sec_master_pwd myPassWord-pdmgrd_host pdmgrserver.mysubnet.ibm.com -pdacld_host pdacldserver.mysubnet.ibm.com

v For Windows:a. Open an MSDOS window and enter:

> PDWAScfg.bat

The bat file will echo the usage message for PDWAScfg.b. Following the usage message, enter the following command (as one

continuous command line), using the example information from theprevious step:

> java PDWAScfg -action config -remote_acl_user cn=pdpermadmin -sec_master_pwd myPassWord -pdmgrd_hostpdmgrserver.mysubnet.ibm.com -pdacld_host pdacldserver.mysubnet.ibm.com

6. Verify that the pdwascfg command successfully created the PdPerm propertiesfile.On Unix systems:/opt/WebSphere/AppServer/java/jre/PdPerm.properties

On Windows:C:\WebSphere\AppServer\java\jre\PdPerm.properties

7. Create a new Access Manager action and action group:v Create a new Access Manager action group called WebAppServer.

pdadmin> action group create WebAppServer


v Create the new Access Manager for WebSphere action, designated by theletter i.pdadmin> action create i invoke invoke WebAppServer

8. Ensure that the WAS_HOME environment variable is set as follows:(UNIX) WAS_HOME=/opt/WebSphere/AppServer

(Windows) WAS_HOME=C:\WebSphere\AppServer

This variable must be set in order for the migration utility to access the correctxerces.jar file and the correct version of the Java runtime.

9. Assemble the following information, which you will need to specify as inputparameters to the migration utility:v The name of the EAR file to migrate. For this initial use of the migration

utility, you must migrate the administration EAR file:UNIX: /opt/WebSphere/AppServer/config/admin.ear

Windows: C:\WebSphere\AppServer\config\admin.ear

v The location of the PDPerm.properties file. This must be expressed as aUniform Resource Indicator.For example:file:/C:/WebSphere/AppServer/java/jre/PdPerm.properties

v The name of the Access Manager administration account. This should besec_master.

v The password for the sec_master account.v The name of the WebSphere administrative user account. This should match

the account you created above.For example:wsadmin

v The LDAP distinguished name suffix for the user account.For example:o=ibm,c=us

10. Run the migration utility to migrate the data contained in admin.EAR.The migration utility is:v (UNIX) /opt/pdwas/bin/migrateEAR.shv (Windows) C:\Program Files\Tivoli\pdwas\bin\migrateEAR.bat

Use the steps that apply to your operating system:v For UNIX operating systems:

For example, using the information from the previous step, enter thefollowing at a command prompt (as one continuous command):

migrateEAR -c file://WebSphere/AppServer/java/jre/PdPerm.properties-j /opt/WebSphere/AppServer/config/admin.EAR -a sec_master -p sec_master_password -w wsadmin-d o=ibm,c=us


> migrateEAR.bat

The bat file will echo the usage message for migrateEAR.b. Following the usage message, enter the following command (as one

continuous command), using the example information from the previousstep:


> java migrateEAR -c file:/c:/WebSphere/AppServer/java/jre/PdPerm.properties-j \opt\WebSphere\AppServer\config\admin.ear -a sec_master -p sec_master_password

-w wsadmin -d o=ibm,c=us

The migration utility logs output to a log file. The name of the log file isdisplayed. For example, pdwas_migrate.log. You can examine the contents ofthe log file to verify that all roles were migrated.

If the log file does not appear, the migration utility encountered a problem. Ifthis occurs, verify that you supplied the correct URI to the -c option, and thecorrect filename to the -j option.

For more information on the migration utility, see Chapter 3, “Migratingsecurity roles to IBM Tivoli Access Manager for WebSphere” on page 29. Toreview the migration utility syntax, see the reference page: “migrateEAR” onpage 34.

11. Use pdadmin to add the pdwas-admin group to the appropriate ACL, asfollows (as one continuous command):

pdadmin> acl modify _WebAppServer_deployedResources_AdminRole_admin_ACL set group pdwas-adminT[WebAppServer]i

12. Go to the WebSphere console and enable WebSphere security. You can reviewa summary of how to enable WebSphere security in the tutorial chapter of thisguide. See “3: Enabling WebSphere Application Server security” on page 49.For complete instructions on enabling WebSphere security, see the WebSphereApplication Server documentation.

13. Stop and restart WebSphere Application Server.

Configuring additional Access Manager for WebSphereinstallations

This section describes how to configure additional Access Manager for WebSphereinstallations into an Access Manager secure domain.

The instructions in this section assume the following:v You have successfully completed the instructions in “Configuring the initial

Access Manager for WebSphere installation” on page 21.By completing the above instructions, you will have previously migratedsecurity information from the admin.ear file to Access Manager.

v You have installed Access Manager for WebSphere on a different (additional)host system from the initial host system that you previously configured. You arenow ready to configure Access Manager for WebSphere on that additional hostsystem.

Note: Do not use the instructions in this section unless you have previouslycompleted the section “Configuring the initial Access Manager forWebSphere installation” on page 21.

These instructions do not describe how to migrate security information fromadditional EAR files. You can complete the migration of any additional EAR filesseparate from completing the configuration instructions in this section. For moreinformation on migrating EAR files, see Chapter 3, “Migrating security roles toIBM Tivoli Access Manager for WebSphere” on page 29.

To configure an additional Access Manager for WebSphere installation, completethe following steps:


1. Assemble the following information:v The password for the sec_master account.v The fully qualified domain name for the computer that hosts the Access

Manager policy server.v The fully qualified domain name for the computer that hosts the Access

Manager authorization server.

An example of the assembled information:[ myPassWordpdmgrserver.mysubnet.ibm.compdacldserver.mysubnet.ibm.com ]

2. Run the pdwascfg utility.Use the information you collected in the previous step to supply the commandline options to pdwascfg.v For UNIX operating systems:

# pwdwascfg -action config -remote_acl_user cn=pdperm2admin -sec_master_pwd myPassWord-pdmgrd_host pdmgrserver.mysubnet.ibm.com -pdacld_host pdacldserver.mysubnet.ibm.com


MSDOS> PDWAScfg.bat

The bat file will echo the usage message for PDWAScfg.b. Following the usage message, enter the following command (as one


MSDOS> java PDWAScfg -action config -remote_acl_user cn=pdperm2admin -sec_master_pwd myPassWord-pdmgrd_host pdmgrserver.mysubnet.ibm.com -pdacld_host pdacldserver.mysubnet.ibm.com


pdwascfg scriptConfigures the Access Manager authorization component for WebSphereApplication Server.

Usagejava PDWAScfg -action { unconfig | config-remote_acl_user <userDN>-sec_master_pwd <Password>-pdmgrd_host <Access_Manager_policy_server_hostname>-pdacld_host <Access_Manager_authorization_server_hostname>[-pdmgrd_port <Access_Manager_policy_server_port>][-pdacld_port <Access_Manager_authorization_server_port>] }[-help][-operations][-rspfile <fully_qualified_file_name>][-usage][-?]

Parameters-action

The action for this command to perform. It is either configuration orunconfiguration. The valid values for this option are config or unconfig. Thisoption is required.

-helpLists each option name and a one line description if no option is specified. Ifother options are specified, it lists each option specified and their one linedescription. This is an optional option.

-operationsList each of the option names one after another with no description. This is anoptional option.

-rspfileFully qualified name of the response file to use during silent installation. Thisis an optional option. The response file will be property based, option=valuepair. The options will be in a pdwas stanza.

-usageDisplays the usage for this command along with an example. This is anoptional option.

-? Same as usage. This is an optional option.

-remote_acl_userThis item is used with the action config option. This is the full DN of theremote acl user, used for the SSL connection with the Access Managerauthorization server.

-sec_master_pwdThis item is used with the action config option. This is the password of thesec_master user.

-pdmgrd_hostThis item is used with the action config option. This contains the hostname ofthe Access Manager policy server.

-pdacld_hostThis item is used with the action config option. This contains the hostname ofthe Access Manager authorization server.


-pdmgrd_portThis is an optional configuration item used with the action config. The portnumber of the Access Manager policy server can be specified if it has beenconfigured as different from the standard port.

-pdacld_portThis is an optional configuration item used with the actionconfig. The portnumber of the Access Manager authorization server can be specified if it hasbeen configured as different from the standard port. Note that pdmgrd_portmust also be specified if this option is used



Chapter 3. Migrating security roles to IBM Tivoli AccessManager for WebSphere

IBM Tivoli Access Manager for WebSphere Application Server (Access Manager forWebSphere) provides a migration utility that automatically converts security roledefinitions to Access Manager protected objects. The role definitions are read fromthe WebSphere application deployment descriptors and migrated to the AccessManager protected object space. This chapter describes how to use the utility.

Topic index:v “How to migrate security roles”v “Migration utility limitations” on page 31v “Troubleshooting tips” on page 32v “migrateEAR” on page 34

How to migrate security rolesThese instructions are intended to be used after completion of an initialconfiguration of Access Manager for WebSphere. The initial configuration of AccessManager for WebSphere includes the initial use of the migration utility.

Note: If you have not yet run the migration utility during the initial configurationof Access Manager for WebSphere, do not use this section. See “Configuringthe initial Access Manager for WebSphere installation” on page 21.

To migrate J2EE application security roles to Access Manager for WebSphere,complete the following steps:1. Verify that you are logged in as root on UNIX systems or as a user with

administrative privileges on Windows systems.2. The migration utility requires access to the deployment descriptors for the

applications that have been secured. By default, the application assembly toolcontains URL references to the location of the Document Type Definitions(DTD) standard. Thus, lookups for the deployment descriptor DTDs require aconnection to the internet. If the host computer is not connected to the internet,use a local copy of the DTD. In this case, update the deployment descriptors topoint to the local DTD.

3. Ensure that the $WAS_HOME environment variable is set as follows:(UNIX) WAS_HOME=/opt/WebSphere/AppServer

(Windows) WAS_HOME=C:\WebSphere\AppServer

This variable must be set in order for the migration utility to access the correctxerces.jar file and the correct version of the Java runtime.

4. Assemble the following information, which you will need to specify as inputparameters to the migration utility:v The name of the EAR file to migrate.

/opt/WebSphere/AppServer/secureApp.EAR

v The location of the PDPerm.properties file. This must be expressed as aUniform Resource Indicator.For example:


file://opt/WebSphere/AppServer/java/jre/PdPerm.properties



the account you created during the initial configuration of Access Managerfor WebSphere.For example:wsadmin

v The user registry domain suffix for the user account.For example, with an LDAP user registry:o=ibm,c=us

5. Ensure that you have the most recent EAR file for the application. Ensure thatthe EAR file has all the expected user to role mappings. If you are uncertain ifall role mappings are present, export the application.See the IBM WebSphere Application Server documentation for instructions onexporting EAR files.

6. Run the migration utility to migrate the application data.The migration utility is pathname is:v /opt/pdwas/bin/migrateEAR.sh (UNIX)v C:\Program Files\Tivoli\pdwas\bin\migrateEAR.bat (Windows)

Use the information you assembled in the previous steps to supply thenecessary command line parameters. For example:


For example, using the example information from the previous step, enterthe following at a command prompt (as one continuous command line):

# migrateEAR -c file://opt/WebSphere/AppServer/java/jre/PdPerm.properties -j/opt/WebSphere/AppServer/config/<your_application.ear> -a sec_master -p sec_master_password-w wsadmin -d o=ibm,c=us


> migrateEAR.bat



> java migrateEAR -c file:/c:/WebSphere/AppServer/java/jre/PdPerm.properties -jc:\WebSphere\AppServer\config\<your_application.ear> -a sec_master -p sec_master_password -w wsadmin-d o=ibm,c=us




To review the migration utility syntax, see the reference page: “migrateEAR” onpage 34.

7. Repeat the previous steps for each Enterprise Archive (EAR) file that containsroles definitions that must be migrated to Access Manager.There is no need to run the migration utility against J2EE applications that donot have security information in their deployment descriptors.

Note: Run the migration utility only once for each unique EAR file. Whenthere are multiple copies of any EAR file, you do not need to run themigration utility for each copy.

8. Choose one of the following actions:v If you are using WebSphere Application Server Advanced Edition Single

Server (AEs), go to the next step.v If you are using WebSphere Application Server Advanced Edition (not the

Single Server), the migration is complete. Do not perform the next step.9. When using Access Manager for WebSphere with WebSphere Single Server

Edition (AEs), you must use pdadmin to manually add users to the ACLs thatthe migration utility created. Example pdadmin commands to add users aredescribed in “Migration utility limitations”.You can also review how to add users to ACLs in the sample applicationdescribed in the tutorial chapter Chapter 5, “Tutorial: How to enable security”on page 43. See the example commands in “7: Migrating the application to

Access Manager” on page 53.

Migration utility limitationsThe migration utility has the following limitations:v The migration utility is designed only to migrate the roles in EAR files to the

Access Manager protected object space. Do not use the migration utility as amaintenance utility for roles. After migrating an EAR file, use either the AccessManager Web portal manager or the Access Manager pdadmin utility to manageroles.

v The migration utility migrates only the user and roles specified in the EAR file.Ensure that you are using the latest EAR file for your application.

v When an EAR file is migrated, the contents of the EAR file reflect theconfiguration of the application when it was installed. Changes made to thedeployment descriptors of an application from within WebSphere are not madeto the EAR file. Always be sure to check that the EAR file accurately reflects theapplication configuration before migrating the security roles. For example, besure that the application name is correct. An application name can be changed atapplication deployment, or later through the WebSphere console. This changewill not be reflected in the EAR file. When the EAR file is not modified to reflectthe new name, the wrong Access Manager protected objects will be created.

v After the migration utility has been run once against an EAR file, it isrecommended that you do not run it again when changes are made to an EARfile. The following problems can occur when an EAR is created and migrated tothe Access Manager protected object space, and then is migrated again.– On the second or subsequent migrations, if an existing role has been removed

from the EAR, it will not be removed from the Access Manager protectedobject space.

– On the second or subsequent migrations, changes to the EAR file mightrequire the migration utility to instruct Access Manager to delete an ACLdefinition. In some cases, Access Manager may prevent this deletion. Note

Chapter 3. Migrating security roles to IBM Tivoli Access Manager for WebSphere 31

that the migration of an EAR file to the Access Manager protected objectspace results in the creation of ACLs that are attached to objects. If theadministrator has manually attached the ACL definition to other protectedobjects, Access Manager prevents removal of the ACL. Thus, even if theoriginal object that was created by the first run of the migration utility nolonger exists, the ACL cannot be deleted.

v Use pdadmin to modify roles. You can use pdadmin to add additional roles.v When using the migration utility with WebSphere Application Server Single

System Edition (AEs), you must manually add the users to the ACLs that werecreated by the migration utility.

Note: This only applies to WebSphere AEs. This limitation does not affectWebSphere AE.

Use pdadmin to add the users to the ACL. The following example shows how toadd users to an ACL, based on the sample application described in section “7:Migrating the application to Access Manager” on page 53 in the tutorial chapter.

c:> pdadmin -a sec_master -p <myPassword>pdadmin> acl list(Find the ACL that starts with _WebAppServer_deployedResources_GoodGuys_)

pdadmin> acl modify _WebAppServer_deployedResources_GoodGuys_simpleSessionApp_ACL add useruser1 T[WebAppServer]i




pdadmin> exit

Troubleshooting tipsWhen troubleshooting problems with the migration utility, use the log files thatWebSphere and Access Manager provide:v Configure logging for the Access Manager authorization server. Difficulties with

accessing objects in the protected object namespace are logged here. Note thatlog information generated by requests from the Access Manager authorizationcomponent is logged here. Note also that this log is not the same as theWebsphere logs. For more information, see the IBM Tivoli Access Manager BaseAdministration Guide.

v Activity by the migration utility is logged in the file pdwas_migrate.log. This fileis located in the directory where the migration utility is run. The last logmessage normally describes what the migration utility was attempting to domost recently. Therefore, in most cases it will indicate where an error wasgenerated.

The following errors can occur during use of the migration utility:v Problem: The admin.ear file does not contain any user information, just role

mappings. This results in no users getting attached to the created ACLS.Solution: Use pdadmin to add the group pdwas-admin to the ACL. Enter thefollowing command as one continuous command line:

pdadmin> acl modify _WebAppServer_deployedResources_AdminRole_admin_ACL set group pdwas-adminT[WebAppServer]i


See “7: Migrating the application to Access Manager” on page 53 for an exampleof running the migration utility against both admin.ear and an application EARfile.

v The migration utility does not work on filenames containing a tilde (~). This cancause problems when attempting to migrate a Windows short file name.

v The Web portal manager may be unable to attach an ACL to objects that containspaces in the object name.As a workaround, use pdadmin to attach the ACL.If possible, before running the migration utility, ensure that there are no spacesin the definitions listed in the deployment descriptors. Verify that the applicationname does not contain spaces.

v When the migration utility is run, you may see a WARNING message,indicating that user wsadmin is a member of the group pdwas-admin. Thiswarning is expected and is displayed for security purposes only. The purpose ofthis warning is to identify the user as a current member of the pdwas-admingroup, so that the administrator can verify the accuracy of the list of userscontained in this important administration group.

v Access Manager provides a default SSL timeout value for connections to theAccess Manager policy server. When this timeout value is exceeded duringexecution of the migration utility, you may see the following messages:The server lost the client’s authentication,probably because of session expiration.

When this message occurs, run the migration utility again using the -t<minutes> option. The migration utility uses a default of 60 minutes. This valueshould be no greater than the current SSL timeout between the authorizationAPI client and the management server.

You can determine the SSL timeout value by examining the parameterssl-v3-timeout, located under the [ssl] stanza in the Access Managerconfiguration file ivmgrd.conf. The default value for ssl-v3-timeout is 7200seconds (120 minutes). When this default value is set, ensure that the SSLtimeout set by the migration utility -t flag is at least 60 minutes.

For more information, see the IBM Tivoli Access Manager Base AdministrationGuide.


migrateEARThe migration utility is a Java class that is run as a command line utility. Theutility requires a number of input values to be specified as command lineparameters.

Usagejava com.tivoli.pdas.migrate.Migrate-j <absolute_pathname_to_application_EAR_file>-c URI_location_of_PDPerm.properties-a Access_Manager_administrative_user-p administrative_user_password-w Websphere_administrative_user-d user_registry_domain_suffix[ -r root_object_space_and_action_group_name ][ -t Secure_Sockets_Layer_timeout ]

Parameters-a Access_Managar_administrative_user

This administrative user must have the privileges required to create users,objects, and ACLs.

For example, -a sec_master.

This parameter is optional. When the parameter is not specified, the user isprompted to supply the administrative user name at runtime.

-c URI_location_of_PDperm.propertiesThe location (Uniform Resource Indicator) of the PDPerm.properties file that isconfigured by the pdwascfg utility. For example, on UNIX systems, the usualURI for this is file://opt/WebSphere/AppServer/java/jre/PDPerm.properties.

-d user_registry_domain_suffixThe domain suffix used by the user registry. For example, for LDAP userregistries this is the domain suffix, such as:o=ibm,c=us

-j <absolute_pathname_to_application_EAR_file>The Java 2 Enterprise Edition application archive file. Optionally, this can alsobe an EAR directory.

For example, -j /tmp/test_application.EAR

-p administrative_user_passwordThe password for the administrative user specified in the previous commandline parameter. For example, -p myPassword.

This parameter is optional. When it is not specified, the user is prompted tosupply the password for the administrative user name at runtime.

-r root_object_space_and_action_group_name

The root object space name is the name of the root of the protected objectnamespace hierarchy that will be created for WebSphere Application Server.

This parameter is optional.

The default value for the root object space is WebAppServer.

The action group name matches the root object space name. Thus, the actiongroup name is automatically set when the root object space name is specified.


Note: This action group must exist before migrate is run. See Step 7 in“Configuring the initial Access Manager for WebSphere installation” onpage 21.

-t Secure_Sockets_Layer_timeout

The number of minutes for the SSL timeout. This parameter is used todisconnect and reconnect the SSL context between the Access Managerauthorization server and management server before the default connectiontimes out.

The default is 60 minutes. The minimum is 10 minutes. The maximum shouldnot exceed the Access Manager ssl-v3-timeout value. The default value forssl-v3-timeout is 120 minutes.

This parameter is optional. If you are not familiar with administration of thisvalue, you can safely use the default value.

-w WebSphere_administrative_user

This is the user name that was configured in the WebSphere Application Serversecurity user registry field as the administrator. Access as this user is needed tocreate or update the Access Manager object space.

When the Websphere administrative user does not already exist in the AccessManager object space, it is created or imported. In this case, a randompassword is generated for the user and the account is set to invalid. Thispassword will need to be changed to something known and the account set tovalid.

The protected object that is created is:/WebAppServer/deployedResources/AdminRole/admin

The ACL that is created is:_WebAppServer_deployedResources_AdminRole_admin

The administrative user is added to group pdwas-admin with the followingACL attributes:v T -- traverse permissionv i -- invoke permissionv <WebAppServer> -- the action group name. WebAppServer is the default

name.Note that this action group name (and the matching root object space) canbe overwritten when the migration utility is run with the -r option.The group pdwas-admin will need to be added to the admin role if migratingthe admin.ear file.



Chapter 4. Administering IBM Tivoli Access Manager forWebSphere

This chapter contains the following topics:v “Using Access Manager with WebSphere Advanced Edition Single Server”v “Using Access Manager administration tools”v “Specifying Access Manager for WebSphere properties” on page 38v “Configuring WebSphere console to recognize Access Manager groups” on

page 41

Using Access Manager with WebSphere Advanced Edition SingleServer

IBM WebSphere Application Server provides a version of Advanced Edition thatsupports a single server. This version is designed to run WebSphere withhost-based security instead of an external user registry.

This version of WebSphere Application Server is very useful for developing andprototyping applications and for demonstration of WebSphere Application Serverfeatures and capabilities. The system registry cannot be modified from theWebSphere console.

Access Manager supports a number of external user registry types. When AccessManager is used with WebSphere Advanced Edition Single Server, the AccessManager administrator must create equivalent user registry entries for eachrelevant user account on the system that hosts WebSphere. This means that theuser definitions in the user registry must be created manually.

Note that when users are mirrored into the Access Manager user registry from theoperating system entry, the Access Manager user identity (ID) must match theoperating system user ID. On Windows systems, this ID does not include thedomain name.

Note also that the Access Manager for WebSphere migration utility, when usedwith WebSphere Advanced Edition Single Server, does not automatically add usersto ACLs that it creates. The administrator must manually add the users. For moreinformation, see “Migration utility limitations” on page 31.

Use of IBM Tivoli Access Manager for WebSphere Application Server (AccessManager for WebSphere) with the WebSphere Advanced Edition Single Server isnot recommended for production systems.

See “User registry prerequisites” on page 14.

Using Access Manager administration toolsDo not use the WebSphere Application Server console to modify attributes forusers or roles. These changes will not be reflected in the Access Manager policydatabase.


All administration of user and role configuration information must be performedthrough one of the Access Manager administration tools:v The pdadmin command line utilityv The Access Manager Web portal manager graphical user interface

Access Manager also provides an administration API that can be used to performadministration tasks programmatically.

For more information on the Access Manager administration tools, see thefollowing guides:v For pdadmin and for the graphical user interface, see the IBM Tivoli Access

Manager Base Administration Guide.v For the programmatic API, see the IBM Tivoli Access Manager Administration C

API Developer Reference.

For more information on obtaining Access Manager documentation, see“Publications” on page vi.

Specifying Access Manager for WebSphere propertiesAccess Manager for WebSphere uses a Java property file that containsconfiguration parameters. The property file is not created by default but can beused to modify configurable parameters.

The Java property file should be created in the following location:UNIX: /opt/pdwas/etc/PDWAS.propertiesWindows: C:\Program Files\Tivoli\pdwas\etc\PDWAS.properties

Use this file to specify the following settings:v “Limiting simultaneous connections”v “Enabling static role caching”v “Defining static roles” on page 39v “Configuring dynamic role caching” on page 39v “Specifying logging mechanism type” on page 39v “Specifying logging level” on page 40v “Specifying root object space name” on page 41v “Specifying document type definition directory” on page 41

Limiting simultaneous connectionsLimits the number of simultaneous connections to Access Manager. The default iszero (0), which allows an unlimited number of connections. For example:com.tivoli.pdwas.MaxPDConnections=0

Set this value if SSL exceptions occur. Large number of simultaneous connectionscan cause limitations with the Solaris Operating Environment Java Virtual Machine(JVM).

Enabling static role cachingEnables or disables static role caching. Static role caching is enabled by default.com.tivoli.pdwas.EnableStaticRoleCaching=true


Defining static rolesDefines additional static roles that are not defined in the WebSphere ApplicationServer admin.ear file.com.tivoli.pdwas.StaticRoleCache.Roles=AdminRole

Configuring dynamic role cachingThis section describes the following settings:v “Enabling dynamic role caching”v “Specifying maximum number of users”v “Specifying principal lifetime”v “Specifying role lifetime”v “Specifying number of cache tables”

Enabling dynamic role cachingEnable or disable dynamic role caching. Dynamic role caching is enabled bydefault.com.tivoli.pdwas.EnableDynamicRoleCaching=true

Specifying maximum number of usersThe maximum number of users that the cache supports before a cache cleanup isperformed. This parameter is used when dynamic role caching is enabled. Thedefault number of users is 10000.com.tivoli.pdwas.DynamicRoleCache.MaxUsers=10000

Specifying principal lifetimeThe period of time in minutes that a principal entry is stored in the cache. Thisparameter is used when dynamic role caching is enabled. The default time is 5minutes.com.tivoli.pdwas.DynamicRoleCache.PrincipalLifeTime=5

The term principal here refers to the Access Manager credential returned from aunique LDAP user.

Specifying role lifetimeThe period of time in seconds that a role is stored in a user’s role list before it isdiscarded. This parameter is used when dynamic role caching is enabled. Thedefault is 20 seconds.com.tivoli.pdwas.DynamicRoleCache.RoleLifetime=20

Specifying number of cache tablesThe number of tables used internally by the dynamic role cache. This parameter isused when dynamic role caching is enabled. The default is 20.

When a large number of threads use the cache, increase the value to tune andoptimize cache performance.com.Tivoli.pdwas.DynamicRoleCache.NumBuckets=20

Specifying logging mechanism typeSpecifies the underlying logging mechanism. Valid entries are WAS or STDOUT. Thedefault is STDOUT.

Chapter 4. Administering IBM Tivoli Access Manager for WebSphere 39

When WAS is specified, the WebSphere Application Server tracing framework isused. In this case, the normal WebSphere procedure for enabling or disablingtracing should be used.

When STDOUT is specified, the enabling and disabling of tracing is performed usingproperties contained in the PDWAS.properties file (this file).com.tivoli.pdwas.LoggingType=STDOUT

Specifying logging levelSets the logging level for Access Manager for WebSphere components. Thisparameter is used when the logging mechanism type is set to STDOUT.

The format for specifying the logging level is:com.tivoli.pdwas.<component>.LogLevel=<value>

The supported <components> are:v websphere.PDWASAuthzManagerv cache.StaticRoleCachev cache.DynamicRoleCachev cache.GenericCachev cache.PurgeTask

When the component is not specified, or a part of the component name is notspecified, a wildcard is set for the logging level for multiple matching of AccessManager for WebSphere components.

For example, specifying com.tivoli.pdwas.cache.LogLevel sets the caching levelfor all cache components. Likewise, specifying com.tivoli.pdwas.LogLevel sets thelogging level for all Access Manager for WebSphere components.

The values for these properties can be expressed as either an integer or as acomma-separated list of level. The integer represents a bit map.

The comma-separated list can have the following values:FATALERRORWARNINGNOTICEENTRYEXITDEBUG

The FATAL level is the least significant bit of the bit map and the DEBUG level is themost significant bit.

For example, to turn on all logging for websphere.PDWASAuthzManager, either of thefollowing entries could be used (they are both equivalent):com.tivoli.pdwas.websphere.PDWASAuthzManager.LogLevel =FATAL, ERROR, WARNING, NOTICE, ENTRY, EXIT, DEBUG

com.tivoli.pdwas.websphere.PDWASAuthzManager.LogLevel =127

Note that both an integer value and string values can be used together. The highestlog level is enabled. For example, the following entry enables both FATAL andERROR:


com.tivoli.pdwas.websphere.PDWASAuthzManager.LogLevel =1,ERROR

Specifying root object space nameChanges the name of the root object space and the group permission name. Thedefault value is WebAppServer. This parameter can be set to any value.com.tivoli.pdwas.RootObjectSpaceName=WebAppServer

If you change the default name, ensure that the name matches the name usedwhen the Access Manager migration utility is run. If the names do not match,Access Manager will not successfully locate protected resources. For moreinformation, see “migrateEAR” on page 34.

Specifying document type definition directoryConfigures the location of the Document Type Definition (DTD) files that arerequired in order to use Access Manager for WebSphere.

The DTD application_1_2.dtd is required. This DTD is distributed with AccessManager for WebSphere, and is installed by the configuration script into theWebSphere lib directory.

The WebSphere lib directory is the default location of this file.

This value must be configured as an absolute path. For example, on UNIX:com.tivoli.pdwas.DTDDirectory= /opt/pdwas/etc

On Windows:com.tivoli.pdwas.DTDDirectory=c:\Program Files\Tivoli\pdwas\etc

Configuring WebSphere console to recognize Access Manager groupsThe WebSphere Application Server console can be used to specify security policyfor applications running in the WebSphere environment. The WebSphereApplication Server console can specify security policy for enterprise applicationsand other web resources, based on the entities stored in the user directory.

Access Manager adds to the user registry the object class accessGroup. AccessManager administrators can use the pdadmin command or the Web PortalManager to create new groups. These new groups will be of object classaccessGroup.

The WebSphere Application Server console is not configured by default torecognize objects of the class accessGroup as user registry groups. You canconfigure the WebSphere Application Server console to add this object class to thelist of object classes which represent user registry groups.

Complete the following instructions:1. From the WebSphere console, access the advanced settings for configuring

security.2. Modify the Group Filter field. Add the following entry:

(objectclass=accessGroup)

For example, the Group Filter field would then look like:

Chapter 4. Administering IBM Tivoli Access Manager for WebSphere 41

(&(cn=%w)(|(objectclass=groupOfNames)(objectclass=groupOfUniqueNames)(objectclass=accessGroup)))

3. Modify the Group Member ID Map field. Add the following entry:accessGroup:member

For example, the Group Member ID Map field would then look like:groupOfNames:member;groupOfUniqueNames:uniqueMember;accessGroup:member

4. Stop and restart WebSphere Application Server as instructed by the console.


Chapter 5. Tutorial: How to enable security

This chapter provides a tutorial that describes how to add security to an exampleapplication. The tutorial is based on a WebSphere tutorial that helps you learnabout various aspects of WebSphere application assembly, configuration, anddeployment. The WebSphere tutorial accompanies example code that is shipped aspart of the WebSphere product.

You do not need to consult the WebSphere tutorial to use this Access Managertutorial. This Access Manager tutorial provides an application EAR file which hasbeen built from the WebSphere example code by following the WebSphere tutorialinstructions.

The WebSphere tutorial is available at the following URL:http://www-4.ibm.com/software/webservers/appserv/doc/v40/ae/infocenter/was/0607.html

The example program that ships with IBM Tivoli Access Manager for WebSphereApplication Server (Access Manager for WebSphere) is built from the tutorialinstructions in Sections 6.71, 6.7.2, and 6.7.3 at the above URL. The material in thischapter replaces the tutorial in Section 6.7.4 at the above URL.

Tutorial overviewThis tutorial focuses on showing you how to add security to the application EARfile, add users to the LDAP user registry, enable WebSphere security, deploy andtest the sample application, migrate the application to Access Manager, enable theAccess Manager authorization component, and test the application security underAccess Manager. The tutorial also shows how to make a simple change to a role,and then test that the result is recognized during access checking.

These instructions assume the following:v WebSphere Application Server has been installed to use an IBM SecureWay

Director LDAP user registry.v Security has not been enabled for Websphere.

You can run this tutorial either before or after completing the initial installationand configuration of Access Manager for WebSphere. If you have not yet installedAccess Manager for WebSphere, the tutorial will instruct you when to install it.

These instructions assume the following about Access Manager for WebSphere:v If Access Manager for WebSphere has been installed and configured, it uses the

same IBM SecureWay LDAP user registry.v The Access Manager for WebSphere migration utility has been run against

admin.ear. Note that this step is included in the instructions for the initialconfiguration of Access Manager for WebSphere.

Complete the instructions in each of the following sections:v “1: Adding security to a WebSphere application” on page 44v “2: Adding users to the LDAP user registry” on page 49v “3: Enabling WebSphere Application Server security” on page 49v “4: Deploying the application” on page 51


v “5: Testing security for the deployed application” on page 52v “6: Install and configure Access Manager for WebSphere” on page 53v “7: Migrating the application to Access Manager” on page 53v “8: Testing security for the deployed application” on page 55v “9: Changing roles” on page 55v “10: Testing security for the deployed application” on page 55

1: Adding security to a WebSphere application1. Start the WebSphere application assembly tool. Click Start->Programs->IBM

WebSphere -> Application Server v4.0 AE -> Application Assembly Tool orrun C:\WebSphere\AppServer\bin\assembly

Click Cancel at the Welcome screen.2. Copy the sample application file simpleSession.ear from the directory where

it was extracted to C:\temp\assembly\simpleSession.ear

3. Open the sample application EAR file. Click File -> OpenC:\temp\assembly\simpleSession.ear

4. Right click on Security Roles. Click New.5. Select the General tab. Add:

Name: GoodGuys

6. Select the Bindings tab. Click Add user.Name: user1

Click OK.7. Repeat the previous step to add the following users:

Name: user2Name: user3Name: user4

Click OK when all users are added.


8. Expand EJB Modules. Expand EBJ11. Right click on Method Permissions.Select New. Add:Name: MyMethodPermissions

a. Method: Click Add.v Select Home (*)

v Select Remote (*)

Click OK.b. Roles: Click Add. Select GoodGuys. Click OK.

Figure 5. Modifying the Security Role Properties to Add Users to Groups.

Chapter 5. Tutorial: How to enable security 45

9. Expand Web Modules. Double-click SimpleSessionWar.a. Click the Advanced tab.b. Check the Login Configuration box.c. Specify the Authorization Method: Basic.d. Specify the Realm Name: Getting Started

e. Click Apply.10. Expand Web Modules. Expand SimpleSessionWar. Right click

SecurityConstraints. Select New.a. For Security Constraint Name, enter GoodGuys.b. Roles:

v Click Add.v Select GoodGuys.v Click OK.

c. For Transport Guarantee, select None.d. Click OK.

Figure 6. Adding a security role to the method permissions


11. Right click on Web modules -> SimpleSessionWar -> SecurityConstraints->GoodGuys -> Web Resource Collections.a. Select New.b. For Web Resource Name, enter SecureMe.c. For HTTP Methods, click Add. Select GET. Click OK.d. For HTTP Methods, click Add. Select POST. Click OK.e. For URLS, click Add. Enter: “/SimpleSession”. Click OK.f. Click OK.

Figure 7. The Security Constraints of a Web module


12. Save the new EAR file. Select File->Save As and enter:C:\temp\assembly\SimpleSessionSecure.ear

13. Select File-> Generate Code for Deployment.a. Set working directory to C:\temp.b. Click Generate Now.

c. Fix any errors.14. Exit the Application Assembly tool. Continue to the next section “2: Adding

users to the LDAP user registry” on page 49.

Figure 8. Configuring the Web Resource Collections of the Security Constraints of a Webmodule

Figure 9. Generating code for deployment.


2: Adding users to the LDAP user registryUse the Access Manager pdadmin utility to add the users you declared in theprevious section (user1, user2, user3, and user4) to the LDAP user registry.

This section demonstrates common pdadmin commands for adding users. Forcomplete information on all pdadmin options, see the Tivoli SecureWay AccessManager Base Administration Guide.1. Log in as the Access Manager administrator:

C:> pdadmin -a sec_master -p <myPassword>

Substitute the correct password for the sec_master account for your AccessManager secure domain.

2. If you have already installed Access Manager for WebSphere, and completedthe initial configuration, skip this step. Go to the next step.If you have not yet installed Access Manager for WebSphere, create aWebSphere administration user:pdadmin> user create wsadmin cn=wsadmin,o=<organization>,c=<country> wsadmin wsadmin myPassword

Substitute values for organization and country that are valid for your LDAPuser registry.

3. Create user accounts for each of the new users. Assign passwords. Thefollowing examples show sample commands, where the organization is ibm andthe country is au, and all users receive the password myPassword.pdadmin> user create user1 cn=user1,o=ibm,c=us user1user1 myPasswordpdadmin> user create user2 cn=user2,o=ibm,c=us user2user2 myPasswordpdadmin> user create user3 cn=user3,o=ibm,c=us user3user3 myPasswordpdadmin> user create user4 cn=user4,o=ibm,c=us user4user4 myPassword

4. Enable all the accounts:pdadmin> user modify wsadmin account-valid yespdadmin> user modify user1 account-valid yespdadmin> user modify user2 account-valid yespdadmin> user modify user3 account-valid yespdadmin> user modify user4 account-valid yes

5. Exit the pdadmin utility:pdadmin> quit

6. Return to the WebSphere console to enable security. Continue to “3: EnablingWebSphere Application Server security”.

3: Enabling WebSphere Application Server security1. Start the WebSphere Administration Server:

c:\websphere\appserver\bin\adminserver

2. When the server has started, start the WebSphere Admin Client:c:\websphere\appserver\bin\adminclient

3. Select Console->Security Center.4. Select the General tab. Check the Enable Security box.5. Select the Authentication tab.

a. Select LTPA. Set the following LTPA settings:


v Token Expiry: 120v Domain: Your domain name. For example:

mydomain.ibm.com

b. Check the LDAP check box. Assign the LDAP settings:

LDAP Settings Value

Security Server ID cn=wsadmin,o=ibm,c=us

Security Server Password myPassword

Host ldapserver.mydomain.ibm.com

Directory Type SecureWay

Base DN o=ibm,c=us

Bind DN cn=root

Bind Password myPassword

c. Click OK.

6. Right click on WebSphere Admin Domain -> Nodes -> <Hostname>

7. Select Restart.8. Continue to “4: Deploying the application” on page 51.

Figure 10. Enabling security through the Security Center


4: Deploying the application1. Verify that the WebSphere Admin Server is running.2. Start the WebSphere Admin Client:

C:\websphere\appserver\bin\adminclient

3. Log in as user pdpermadmin with password myPassword.4. Select WebSphere Admin Domain -> Enterprise Applications.5. Right click and select Install Enterprise Application.

a. Check Install Application button.b. Set the path:

c:\temp\assembly\simpleSessionSecure.ear

c. Click Next. A dialog box prompts you to deny access to all unprotectedmethods. Click yes.

d. Click Select.e. Verify that all users are listed

user1 user2 user3 user4

f. Click OK.g. You can now select Next at each of a series of dialog boxes that appear. The

dialog boxes are titled:v Mapping Users to Rolesv Mapping EJB RunAs Role to Userv Binding Enterprise Bean to JNDI Namesv Mapping EJB References to Resourcesv Specifying the Default Datasources for EJB Modulesv Specifying Data Sources for Individual CMP Beansv Selecting Virtual Hosts for Web Modulesv Selecting Application Server

h. When the dialog box Completing the Application Installation Wizardappears, click Finish.

Figure 11. Denying access to unprotected methods


i. Click Yes to generate code. Click OK.j. Click OK to exit the dialog box.

6. If the default server is running, stop it now. If the default server is not running,continue to the next step.To stop the default server:v Select WebSphere Admin Domain -> Nodes -> <hostname> -> Application

Servers -> Default Server

v Right click on the default server.v Select Stop.v Click OK to exit the dialog box.

7. Start the Default Server.v Select WebSphere Admin Domain -> Nodes -> <hostname> -> Application

Servers -> Default Server

v Right click on the default server.v Select Start.v Click OK to exit the dialog box.

8. Exit the WebSphere Advanced Administration Console.9. Continue to “5: Testing security for the deployed application”.

5: Testing security for the deployed applicationServlet

1. Start your web browser.2. Go to the following URL. Substitute your system name for hostname:

http://<hostname>:9080/gettingstarted3/SimpleSession?msg=Test

3. You should be prompted to enter a user name and password. Enter one of thevalid user names: user1 or user2 or user3 or user4. Enter the correct password.You should see a results page.

4. Restart your web browser.5. Go to the same URL. When prompted to enter a user name and password,

enter an invalid user name or password.You should see a failure page.

Thick Client

1. Use the launchclient program to start your secure application. Enter thefollowing command as one single line:

C:> c:\websphere\appserver\bin\launchclient c:\websphere\appserver\installedApps\SimpleSessionApp.ear

2. You should receive a login prompt, requesting a a user name and password.3. Enter a valid user name and password. For example, user1.

You should see text indicating a successful login.4. Restart your web browser.5. Use the launchclient program to start your secure application, as shown in

Step 1 above. When prompted to enter a user name and password, enter aninvalid user name or password.You should see text indicating a login failure.

6. Continue to the next section.


6: Install and configure Access Manager for WebSphereIf you have already installed and configured Access Manager for WebSphere, skipthis section. Go to the next section.

You are now ready to install and configure the Access Manager for WebSpheresoftware.

Follow the instructions in Chapter 2, “Installing IBM Tivoli Access Manager forWebSphere” on page 11

After installing the Access Manager for WebSphere files, complete the initialconfiguration described in “Configuring the initial Access Manager for WebSphereinstallation” on page 21, with the following exception:v You have already created the WebSphere administrative user, wsadmin, during

this tutorial, in “2: Adding users to the LDAP user registry” on page 49. Thusyou do not need to do this during the initial configuration. Therefore, skip Step1 in “Configuring the initial Access Manager for WebSphere installation” onpage 21.

7: Migrating the application to Access ManagerThese instructions assume that you have completed the initial installation andconfiguration of Access Manager for WebSphere, as described in “Configuring theinitial Access Manager for WebSphere installation” on page 21. The initialinstallation and configuration included the migration of the admin.ear file.

Note: If you have not completed an initial installation and configuration of AccessManager for WebSphere, complete it now. See the instructions in“Configuring the initial Access Manager for WebSphere installation” onpage 21.

1. Assemble the following information, which you will need to specify as inputparameters to the migration utility:v The name of the EAR file to migrate.

c:\temp\assembly\simpleSession.ear

v The location of the PDPerm.properties file. This must be expressed as aUniform Resource Indicator.For example, on UNIX:file://opt/WebSphere/AppServer/java/jre/PdPerm.properties



the account you created during the initial configuration of Access Managerfor WebSphere.For example:wsadmin

v The user registry domain information. For example, the LDAP distinguishedname suffix for the user account.For example:o=ibm,c=us

2. Run the migration utility to migrate the application data.


The migration utility is pathname is:v /opt/pdwas/bin/migrateEAR.sh (UNIX)v C:\Program Files\Tivoli\pdwas\bin\migrateEAR.bat (Windows)

Use the information you assembled in the previous steps to supply thenecessary command line parameters. For example:


For example, using the example information from the previous step, enterthe following at a command prompt (as one continuous command):

migrateEAR -c file://opt/WebSphere/AppServer/java/jre/PdPerm.properties -j/temp/assembly/simpleSession.ear -a sec_master -p sec_master_password -w wsadmin

-d o=ibm,c=us


> migrateEAR.bat



> java migrateEAR -c file:/c:/WebSphere/AppServer/java/jre/PdPerm.properties -jc:\temp\assembly\simpleSession.ear -a sec_master -p sec_master_password -w wsadmin

-d o=ibm,c=us



3. When the script completes, choose one of the following actions:v If using WebSphere AEs (Single Server edition) continue to the next step.v If using WebSphere Application Server Advanced Edition (not the Single

Server edition), the migration is complete. Go the next section: “8: Testingsecurity for the deployed application” on page 55

4. When using the migration utility with WebSphere Application Server SingleSystem Edition (AEs), you must manually add the users to the ACLs that werecreated by the migration utility.

Note: This only applies to WebSphere AEs. This limitation does not affectWebSphere AE.

Use pdadmin to add the users to the ACL. The following example shows howto add users to an ACL:

c:> pdadmin -a sec_master -p <myPassword>pdadmin> acl list(Find the ACL that starts with _WebAppServer_deployedResources_GoodGuys_)


pdadmin> acl modify _WebAppServer_deployedResources_GoodGuys_simpleSessionApp_ACL add user


user2 T[WebAppServer]ipdadmin> acl modify _WebAppServer_deployedResources_GoodGuys_simpleSessionApp_ACL add useruser3 T[WebAppServer]ipdadmin> acl modify _WebAppServer_deployedResources_GoodGuys_simpleSessionApp_ACL add useruser4 T[WebAppServer]ipdadmin> exit

5. Continue to the next section: “8: Testing security for the deployed application”.

8: Testing security for the deployed application1. Verify that security is now working for the application. Repeat the steps for

both Servlet and Thick Client in “5: Testing security for the deployedapplication” on page 52.

2. When security has been verified continue to “9: Changing roles”.

9: Changing rolesUse the Access Manager pdadmin utility to change a role definition by removing auser.1. Start pdadmin:

pdadmin -a sec_master -p myPassword

2. Modify the ACL for the SimpleSession application to remove the name ofuser4. Enter the acl modify command below as one long command line:

pdadmin> acl modify _WebAppServer_deployedResources_GoodGuys_SimpleSessionApp_ACL remove user user4

3. Replicate to the server and exit the utility:pdadmin> server replicatepdadmin> quit

4. Continue to “10: Testing security for the deployed application”.

10: Testing security for the deployed application1. Verify that security is now working for the application. Repeat the steps for

both Servlet and Thick Client in “5: Testing security for the deployedapplication” on page 52.Note that when you enter the name of a valid user, you must enter eitheruser1, user2, or user3.When you want to enter the name of an invalid user, enter user4.

2. Verify that user4 is not able to log in.

You have now completed the tutorial.



Chapter 6. Removing IBM Tivoli Access Manager forWebSphere

Remove IBM Tivoli Access Manager for WebSphere Application Server (AccessManager for WebSphere) by changing the necessary configuration files andremoving the authorization component.

Go to the section for your operating system:v “Removing Access Manager for WebSphere on Solaris”v “Removing Access Manager for WebSphere on Windows”v “Removing Access Manager for WebSphere on AIX” on page 58v “Removing Access Manager for WebSphere on HP-UX” on page 59v “Removing Access Manager for WebSphere on Linux” on page 59

Removing Access Manager for WebSphere on SolarisComplete the following instructions:1. Log in as root.2. Run the pdwascfg utility to unconfigure the Access Manager for WebSphere

authorization component:# pdwascfg -action unconfig

3. Stop and restart the WebSphere Application Server.4. To remove Access Manager for WebSphere, enter the following command:

# pkgrm PDWAS

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

A status message lists each file as it is removed. After the postremove scriptruns, a status message indicates that the removal of the software package wassuccessful. The pkgrm utility exits.

6. If you want to remove the supporting Access Manager components at this time,use the operating system removal utility to remove the Access Managerauthorization server and the Access Manager Base runtime environment andAccess Manager Java Runtime.For complete removal instructions, see the IBM Tivoli Access Manager BaseInstallation Guide.

Removal of the Access Manager for WebSphere package is complete.

Removing Access Manager for WebSphere on WindowsComplete the following instructions:1. Log in as a Windows user with administrator privilege.2. Run the pdwascfg utility to unconfigure the Access Manager for WebSphere

authorization component:pdwascfg -action unconfig

3. Stop and restart the WebSphere Application Server.4. Click the Add/Remove Programs icon.


5. Select Access Manager for WebSphere.6. Click Change/Remove.

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

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

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

10. Click Finish.11. If you want to remove the supporting Access Manager components at this

time, use the operating system removal utility to remove the Access Managerauthorization server and the Access Manager Base runtime environment andAccess Manager Java Runtime.For complete removal instructions, see the IBM Tivoli Access Manager BaseInstallation Guide.

Removal of Access Manager for WebSphere is complete.

Removing Access Manager for WebSphere on AIXComplete the following instructions:1. Log in as root.2. Run the pdwascfg utility to unconfigure the Access Manager for WebSphere


3. Stop and restart the WebSphere Application Server.4. Start SMIT. Select Software Installation and Maintenance.5. Select Software Maintenance and Utilities.6. Select Remove Installed Software.7. Click the List button next to SOFTWARE name.

The Multi-Select List appears. The PDWAS package name is displayed.8. Select the Access Manager for WebSphere package.

The Remove Installed Software dialog box appears.9. Change the value of the PREVIEW only field to no.

10. Accept the default value of no for all other fields. Click OK.11. 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.

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

13. Click Cancel. Click Exit to exit SMIT.14. If you want to remove the supporting Access Manager components at this

time, use the operating system removal utility to remove the Access Managerauthorization server and the Access Manager Base runtime environment andAccess Manager Java Runtime.For complete removal instructions, see the IBM Tivoli Access Manager BaseInstallation Guide.


Removal of Access Manager for WebSphere is complete.

Removing Access Manager for WebSphere on HP-UXComplete the following instructions:1. Log in as root.2. Run the pdwascfg utility to unconfigure the Access Manager for WebSphere



# swremove PDWAS

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

When the removal is complete, the swremove utility exits.5. If you want to remove the supporting Access Manager components at this time,

use the operating system removal utility to remove the Access Managerauthorization server and the Access Manager Base runtime environment andAccess Manager Java runtime.For complete removal instructions, see the IBM Tivoli Access Manager BaseInstallation Guide.

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

Removing Access Manager for WebSphere on LinuxComplete the following instructions:1. Log in as root.2. Run the pdwascfg utility to unconfigure the Access Manager for WebSphere



# rpm -e PDWAS-PD

The files are removed. The rpm utility exits.5. If you want to remove the supporting Access Manager components at this time,

use the operating system removal utility to remove the Access Manager JavaRuntime.For complete removal instructions, see the IBM Tivoli Access Manager BaseInstallation Guide.

Removal of the Access Manager for WebSphere package is complete.

Chapter 6. Removing IBM Tivoli Access Manager for WebSphere 59


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.

COPYRIGHT LICENSE:

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


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

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

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

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

AIXDB2IBMIBM logoSecureWayTivoliTivoli 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 63


Index

Aaccess control lists 5Access Manager

administration API 8, 38authorization framework 2authorization server 9configuring 20integrating with WebSphere 2policy database

replicating 9policy server 6, 13removing 57secure domain 13security model 1

Access Manager Java runtimeconfiguring 21

access settinginheritance 6overriding 7

actioncreating 22

action groupcreating 22

admin.ear 21, 23administration API 8, 38administration tools

pdadmin 38Web portal manager 38

administrative userWebSphere

creating 21Advanced Edition 3authorization decision 3

Bbulk loading of users 14

Ccache tables

specifying 39CLASSPATH

setting 20com.tivoli.mts.SvrSslCfg 20configuration parameters

specifying 38configuring

Access Manager 20additional systems 21, 24dynamic role caching 39initial system 21

creatingAccess Manager action 22Access Manager action group 22WebSphere administrative user 21

Customer Support xi

Ddeclarative security 2deployment descriptors 3, 6, 29, 31disk requirements 11Document Type Definition

specifying 41documentation library viDTD 29, 41dynamic role caching

configuring 39

EEAR files 21, 31

Ggroups 4

Hhost-based security 15, 37

Iimporting users 14installation packages 11Installing Access Manager

AIX 16HP-UX 17Linux 18Solaris 15Windows 19

InstallShield 19invoke action

creating 23

JJ2EE security 4Java property file 38Java Runtime Environment

prerequisite versions 13

Llogging level

specifying 40supported values 40

logging mechanismspecifying 39

Mmapping

groups to roles 4principals to roles 4


mapping (continued)user to roles 30

maximum number of usersspecifying 39

memory requirements 11migrateEAR

reference page 34migration

summary 21migration utility

initial use 23limitations 31logging 24, 30overview 29reference page 34tutorial 53using 29

Oonline publications xoperating systems

supported versions 11

Ppdadmin

adding users 49changing roles 55creating administrative user 21importing users 14summary 8

pdjrtecfg 21PDPerm.properties 23, 29pdwas_migrate.log 24pdwas-admin group

adding to ACL 24PDWAS.properties 38pdwascfg

reference page 26using 22

pkgadd 15policy management

centralizing 7principal life time

specifying 39principals 4programmatic security 2publications

ordering x

Rremoving

AIX 58HP-UX 59Linux 59Solaris 57Windows 57

removing Access Manager 57requirements

disk space 11memory 11

role lifetimespecifying 39

role mappings 30

role-based security 4roles 4root object space name

specifying 41rpm 18, 59

SSecureWay Directory 14security

declarative 2programmatic 2

simultaneous connectionslimiting 38

Single Serveradding users to ACLs 31host-based security 37

SMIT 16software contents 11software prerequisites

Access Manager Base 13ssl timeout value 32static role caching

enabling 38static roles

defining 39supported platforms 11swinstall 17swremove 59

TTivoli Customer Support xitroubleshooting tips 32tutorial

adding security 44adding user to LDAP 49changing roles 55enabling security 43overview 43testing security

Servlet 52Thick Client 52

using migration utility 53

Uuser registry

LDAP 14prerequisites 14shared 3, 12

usersmapping to roles 30

WWAS_HOME

setting 21, 23, 29Web portal manager 7, 38WebSphere

Admin Client 51administration server 49administrative user 30Advanced Edition

Single Server 12, 37


WebSphere (continued)Bindings 44documentation URL 12EJB Modules 44managing multiple servers 7Security Constraints 46Security Roles 44Single Server

host-based security 15migration steps 31

tutorialdeploying application 51

Web Modules 46WebSphere Advanced Edition 3WebSphere console

configuring Access Manager groups 41WebSphere security

enabling 24, 49wsadmin 30

XXerces parser 14xerces.jar 14XML parser

prerequisite 14

Index 67


Printed in the United States of Americaon recycled paper containing 10%recovered post-consumer fiber.

GC32-0850-00

Documents

IBM Tivoli Access Manager for WebSphere Application Server ...publib.boulder.ibm.com/tividd/td/ITAME/GC32-0850-00/en_US/PDF/... · IBM Tivoli Access Manager for WebSphere Application