IBM Tivoli Access Manager for WebSphere Application Server. User s Guide. Version 4.1 SC

Transcription

1 IBM Tioli Access Manager for WebSphere Application Serer User s Guide Version 4.1 SC

2

3 IBM Tioli Access Manager for WebSphere Application Serer User s Guide Version 4.1 SC

4 Note Before using this information and the product it supports, read the information in Appendix B, Notices, on page 75. Second Edition (August 2003) This edition replaces SC Copyright International Business Machines Corporation 2002, All rights resered. US Goernment Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

5 Contents Preface ii Who should read this book ii What this book contains ii Publications iii Release information iii Base information iii WebSEAL information iii Web security information ix Deeloper references ix Technical supplements x Related publications x Accessing publications online xii Ordering publications xii Accessibility xii Contacting software support xii Conentions used in this book xiii Typeface conentions xiii Operating system differences xiii Chapter 1. Introduction and oeriew Integrating Tioli Access Manager with WebSphere Application Serer Jaa 2 Enterprise Edition role-based security Mapping of principals and groups to roles Centralizing policy management for multiple WebSphere serers Chapter 2. Installation instructions Software contents Supported platforms Disk and memory requirements Software prerequisites WebSphere Application Serer Tioli Access Manager Base Jaa Runtime Enironment Xerces XML parser User registry prerequisites Upgrading from a preious release Installing Tioli Access Manager for WebSphere Installing on Solaris Installing on AIX Installing on HP-UX Installing on Linux Installing on Windows Chapter 3. Configuration procedures Configuring the initial installation Part 1: Configure the Tioli Access Manager Jaa runtime Part 2: Create a user, action, and action group Part 3: Join a secure domain Part 4: Migrate WebSphere security settings Part 5: Add the pdwas admin group to the administration ACL Part 6: Enable WebSphere security Configuring additional installations Part A-1: Configure the Tioli Access Manager Jaa runtime Part A-2: Join a secure domain Copyright IBM Corp. 2002, 2003 iii

6 Chapter 4. Migrating security roles How to migrate security roles Migration utility limitations Troubleshooting tips Use of log files Users not attached to created ACLs Migration fails on Windows files with short name Web Portal Manager unable to attach an ACL to an object Warning that user wsadmin is a member of pdwas-admin Client authentication lost due to session expiration Migration utility messages not displayed in correct language Unable to access WebSphere sample applications Chapter 5. Administration tasks WebSphere Adanced Edition Single Serer Tioli Access Manager administration tools Specifying runtime properties Limit simultaneous connections Enable static role caching Define static roles Configure dynamic role caching Specify logging mechanism type Specify logging leel Specify root object space name Specify document type definition directory Configuring additional authorization serers Adding an object class to the console Troubleshooting tips WebSphere administratie serer does not start WebSphere serer does not start after configuration WebSphere serer does not start after unconfiguration Chapter 6. Tutorial: How to enable security How to use the tutorial Part 1: Add security to a WebSphere application Part 2: Add users to the LDAP user registry Part 3: Enable WebSphere Application Serer security Part 4: Deploy the application Part 5: Test security for the deployed application Part 6: Install Tioli Access Manager for WebSphere Part 7: Migrate the application to Tioli Access Manager Part 8: Test security for the deployed application Part 9: Change roles Part 10: Test security for the deployed application Chapter 7. Remoal instructions Remoing from Solaris Remoing from Windows Remoing from AIX Remoing from HP-UX Remoing from Linux Appendix A. Command reference pdwascfg migrateear Appendix B. Notices Trademarks i IBM Tioli Access Manager for WebSphere Application Serer: User s Guide

7 Glossary Index Contents

8 i IBM Tioli Access Manager for WebSphere Application Serer: User s Guide

9 Preface Who should read this book What this book contains Welcome to IBM Tioli Access Manager for WebSphere Application Serer (Tioli Access Manager for WebSphere). This product extends Tioli Access Manager to support applications written for IBM WebSphere Application Serer. IBM Tioli Access Manager (Tioli Access Manager) is the base software that is required to run applications in the IBM Tioli Access Manager product suite. It enables the integration of IBM Tioli Access Manager applications that proide a wide range of authorization and management solutions. Sold as an integrated solution, these products proide an access control management solution that centralizes network and application security policy for e-business applications. Note: IBM Tioli Access Manager is the new name of the preiously released software entitled Tioli SecureWay Policy Director. Also, for users familiar with the Tioli SecureWay Policy Director software and documentation, the management serer is now referred to as the policy serer. The IBM Tioli Access Manager for WebSphere Application Serer User s Guide proides installation, configuration, and administration instructions. This document also proides a tutorial on configuring centralized security policy for WebSphere applications. The target audience for this administration guide includes: Security administrators Network system administrators IT architects Readers should be familiar with: Internet protocols, including HTTP, TCP/IP, file transfer protocol (FTP), and telnet Deployment and management of WebSphere Application Serer systems and applications Security management, including authentication and authorization If you are using Secure Sockets Layer (SSL) communication, you also should be familiar with SSL protocol, key exchange (public and priate), digital signatures, cryptographic algorithms, and certificate authorities. This document contains the following chapters: Chapter 1, Introduction and oeriew Presents an oeriew of the Tioli Access Manager Access Manager components that proide authorization serices to WebSphere Application Serer. Chapter 2, Installation instructions Describes how to install Tioli Access Manager for WebSphere. Chapter 3, Configuration procedures Copyright IBM Corp. 2002, 2003 ii

10 Describes how to configure Tioli Access Manager for WebSphere. Chapter 4, Migrating security roles Describes how to use the Tioli Access Manager for WebSphere migration utility to migrate Jaa 2 Enterprise Edition security roles to Tioli Access Manager user and groups. Chapter 5, Administration tasks Describes how to perform administration tasks that manage Tioli Access Manager for WebSphere. Chapter 6, Tutorial: How to enable security Describes how to add security to a WebSphere Application Serer application. Also describes how to migrate security information to Tioli Access Manager and how to test that security has been successfully enabled. Chapter 7, Remoal instructions Describes how to remoe Tioli Access Manager for WebSphere. Publications The Tioli Access Manager library is organized into the following categories: Release information Base information WebSEAL information Web security information on page ix Deeloper references on page ix Technical supplements on page x Release information IBM Tioli Access Manager Read Me First Card GI (am41_readme.pdf) Proides information for installing and getting started using Tioli Access Manager. IBM Tioli Access Manager Release Notes SC (am41_relnotes.pdf) Proides late-breaking information, such as software limitations, workarounds, and documentation updates. Base information IBM Tioli Access Manager Base Installation Guide SC (am41_install.pdf) Explains how to install, configure, and upgrade Tioli Access Manager software, including the Web Portal Manager interface. IBM Tioli Access Manager Base Administrator s Guide SC (am41_admin.pdf) Describes the concepts and procedures for using Tioli Access Manager serices. Proides instructions for performing tasks from the Web Portal Manager interface and by using the pdadmin command. WebSEAL information IBM Tioli Access Manager WebSEAL Installation Guide SC (amweb41_install.pdf) iii IBM Tioli Access Manager for WebSphere Application Serer: User s Guide

11 Proides installation, configuration, and remoal instructions for the WebSEAL serer and the WebSEAL application deelopment kit. IBM Tioli Access Manager WebSEAL Administrator s Guide SC (amweb41_admin.pdf) Proides background material, administratie procedures, and technical reference information for using WebSEAL to manage the resources of your secure Web domain. Web security information IBM Tioli Access Manager for WebSphere Application Serer User s Guide SC (amwas41_user.pdf) Proides installation, remoal, and administration instructions for Tioli Access Manager for IBM WebSphere Application Serer. IBM Tioli Access Manager for WebLogic Serer User s Guide SC (amwls41_user.pdf) Proides installation, remoal, and administration instructions for Tioli Access Manager for BEA WebLogic Serer. IBM Tioli Access Manager Plug-in for Edge Serer User s Guide SC (amedge41_user.pdf) Describes how to install, configure, and administer the plug-in for IBM WebSphere Edge Serer application. IBM Tioli Access Manager Plug-in for Web Serers User s Guide SC (amws41_user.pdf) Proides installation instructions, administration procedures, and technical reference information for securing your Web domain using the plug-in for Web serers. Deeloper references IBM Tioli Access Manager Authorization C API Deeloper s Reference SC (am41_authc_deref.pdf) Proides reference material that describes how to use the Tioli Access Manager authorization C API and the Access Manager serice plug-in interface to add Tioli Access Manager security to applications. IBM Tioli Access Manager Authorization Jaa Classes Deeloper s Reference SC (am41_authj_deref.pdf) Proides reference information for using the Jaa language implementation of the authorization API to enable an application to use Tioli Access Manager security. IBM Tioli Access Manager Administration C API Deeloper s Reference SC (am41_adminc_deref.pdf) Proides reference information about using the administration API to enable an application to perform Tioli Access Manager administration tasks. This document describes the C implementation of the administration API. IBM Tioli Access Manager Administration Jaa Classes Deeloper s Reference SC (am41_adminj_deref.pdf) Proides reference information for using the Jaa language implementation of the administration API to enable an application to perform Tioli Access Manager administration tasks. IBM Tioli Access Manager WebSEAL Deeloper s Reference SC (amweb41_deref.pdf) Preface ix

12 Proides administration and programming information for the Cross-domain Authentication Serice (CDAS), the Cross-domain Mapping Framework (CDMF), and the Password Strength Module. Technical supplements IBM Tioli Access Manager Command Reference GC (am41_cmdref.pdf) Proides information about the command line utilities and scripts proided with Tioli Access Manager. IBM Tioli Access Manager Error Message Reference SC (am41_error_ref.pdf) Proides explanations and recommended actions for the messages produced by Tioli Access Manager. IBM Tioli Access Manager Problem Determination Guide GC (am41_pdg.pdf) Proides problem determination information for Tioli Access Manager. IBM Tioli Access Manager Performance Tuning Guide SC (am41_perftune.pdf) Proides performance tuning information for an enironment consisting of Tioli Access Manager with the IBM Directory serer defined as the user registry. Related publications This section lists publications related to the Tioli Access Manager library. The Tioli Software Library proides a ariety of Tioli publications such as white papers, datasheets, demonstrations, redbooks, and announcement letters. The Tioli Software Library is aailable on the Web at: The Tioli Software Glossary includes definitions for many of the technical terms related to Tioli software. The Tioli Software Glossary is aailable, in English only, from the Glossary link on the left side of the Tioli Software Library Web page IBM Global Security Toolkit Tioli Access Manager proides data encryption through the use of the IBM Global Security Toolkit (GSKit). GSKit is included on the IBM Tioli Access Manager Base CD for your particular platform. The GSKit package installs the ikeyman key management utility, gsk5ikm, which enables you to create key databases, public-priate key pairs, and certificate requests. The following document is aailable on the Tioli Information Center Web site in the same section as the IBM Tioli Access Manager product documentation: Secure Sockets Layer Introduction and ikeyman User s Guide (gskikm5c.pdf) Proides information for network or system security administrators who plan to enable SSL communication in their Tioli Access Manager enironment. IBM DB2 Uniersal Database IBM DB2 Uniersal Database is required when installing IBM Directory Serer, z/os, and OS/390 LDAP serers. DB2 is proided on the product CDs for the following operating system platforms: x IBM Tioli Access Manager for WebSphere Application Serer: User s Guide

13 IBM AIX Microsoft Windows Sun Solaris Operating Enironment DB2 information is aailable at: IBM Directory Serer IBM Directory Serer, Version 4.1, is included on the IBM Tioli Access Manager Base CD for all platforms except Linux for zseries. You can obtain the IBM Directory Serer software for Linux for S/390 at: If you plan to use IBM Directory Serer as your user registry, see the information proided at: IBM WebSphere Application Serer IBM WebSphere Application Serer, Adanced Single Serer Edition 4.0.3, is included on the Web Portal Manager CDs and installed with the Web Portal Manager interface. For information about IBM WebSphere Application Serer, see: IBM Tioli Access Manager for Business Integration IBM Tioli Access Manager for Business Integration, aailable as a separately orderable product, proides a security solution for IBM MQSeries, Version 5.2, and IBM WebSphere MQ for Version 5.3 messages. IBM Tioli Access Manager for Business Integration allows WebSphere MQSeries applications to send data with priacy and integrity by using keys associated with sending and receiing applications. Like WebSEAL and IBM Tioli Access Manager for Operating Systems, IBM Tioli Access Manager for Business Integration, is one of the resource managers that use the authorization serices of IBM Tioli Access Manager for e-business. The following documents associated with IBM Tioli Access Manager for Business Integration Version 4.1 are aailable on the Tioli Information Center Web site: IBM Tioli Access Manager for Business Integration Administrator s Guide (SC ) IBM Tioli Access Manager for Business Integration Release Notes (GI ) IBM Tioli Access Manager for Business Integration Read Me First (GI ) IBM Tioli Access Manager for Operating Systems IBM Tioli Access Manager for Operating Systems, aailable as a separately orderable product, proides a layer of authorization policy enforcement on UNIX systems in addition to that proided by the natie operating system. IBM Tioli Access Manager for Operating Systems, like WebSEAL and IBM Tioli Access Manager for Business Integration, is one of the resource managers that use the authorization serices of IBM Tioli Access Manager for e-business. The following documents associated with IBM Tioli Access Manager for Operating Systems Version 4.1 are aailable on the Tioli Information Center Web site: Preface xi

14 Accessibility IBM Tioli Access Manager for Operating Systems Installation Guide (SC ) IBM Tioli Access Manager for Operating Systems Administration Guide (SC ) IBM Tioli Access Manager for Operating Systems Problem Determination Guide (SC ) IBM Tioli Access Manager for Operating Systems Release Notes (GI ) IBM Tioli Access Manager for Operating Systems Read Me First (GI ) Accessing publications online The publications for this product are aailable online in Portable Document Format (PDF) or Hypertext Markup Language (HTML) format, or both in the Tioli Software Library: To locate product publications in the library, click the Product manuals link on the left side of the Library page. Then, locate and click the name of the product on the Tioli Software Information Center page. Product publications include release notes, installation guides, user s guides, administrator s guides, and deeloper s references. Note: To ensure proper printing of PDF publications, select the Fit to page check box in the Adobe Acrobat Print window (which is aailable when you click File Print). Ordering publications You can order many IBM Tioli publications online at: publications/cgibin/pbi.cgi Contacting software support You can also order by telephone: In the United States: In Canada: In other countries, for a list of telephone numbers, see Accessibility features help a user who has a physical disability, such as restricted mobility or limited ision, to use software products successfully. With this product, you can use assistie technologies to hear and naigate the interface. You also can use the keyboard instead of the mouse to operate all features of the graphical user interface. Before contacting IBM Tioli Software support with a problem, refer to the IBM Tioli Software support Web site at: If you need additional help, contact software support by using the methods described in the IBM Software Support Guide at the following Web site: xii IBM Tioli Access Manager for WebSphere Application Serer: User s Guide

15 The guide proides the following information: Registration and eligibility requirements for receiing support Telephone numbers and addresses, depending on the country in which you are located A list of information you should gather before contacting customer support Conentions used in this book This reference uses seeral conentions for special terms and actions and for operating system-dependent commands and paths. Typeface conentions The following typeface conentions are used in this reference: Bold Lowercase commands or mixed case commands that are difficult to distinguish from surrounding text, keywords, parameters, options, names of Jaa classes, and objects are in bold. Italic Variables, titles of publications, and special words or phrases that are emphasized are in italic. Monospace Code examples, command lines, screen output, file and directory names that are difficult to distinguish from surrounding text, system messages, text that the user must type, and alues for arguments or command options are in monospace. Operating system differences This book uses the UNIX conention for specifying enironment ariables and for directory notation. When using the Windows command line, replace $ariable with %ariable% for enironment ariables and replace each forward slash (/) with a backslash (\) in directory paths. If you are using the bash shell on a Windows system, you can use the UNIX conentions. Preface xiii

16 xi IBM Tioli Access Manager for WebSphere Application Serer: User s Guide

17 Chapter 1. Introduction and oeriew IBM Tioli Access Manager for WebSphere Application Serer (Tioli Access Manager for WebSphere) is an extension of IBM Tioli Access Manager (Tioli Access Manager) that proides container-based authorization and centralized policy management for IBM WebSphere Application Serer applications. Tioli Access Manager for WebSphere can be integrated with WebSphere Application Serer and makes authorization decisions on incoming requests for access to protected resources. By deploying Tioli Access Manager for WebSphere, a network administrator can use Tioli Access Manager to proide centralized management of security policy both for WebSphere Application Serer resources and for resources that are unrelated to WebSphere Application Serer. Tioli Access Manager proides management of common identities, user profiles, and authorization mechanisms. Tioli Access Manager also proides a graphical user interface utility, the Tioli Access Manager Web Portal Manager, that can be used as a single point of security management both for resources that are compliant with Jaa 2 Enterprise Edition (J2EE) and for resources that not compliant with J2EE. WebSphere Application Serer, Adanced Edition, (WebSphere) supports the J2EE security classes and APIs. Tioli Access Manager for WebSphere supports WebSphere applications that use the J2EE security classes. Tioli Access Manager for WebSphere proides this support without requiring any coding or deployment changes to the applications. Tioli Access Manager for WebSphere can be integrated with WebSphere containers to enable them to use the security serices proided by a Tioli Access Manager secure domain. The secure domain must be deployed prior to installation of Tioli Access Manager for WebSphere. Users who are new to Tioli Access Manager should reiew the Tioli Access Manager security model before deploying a Tioli Access Manager secure domain. A brief summary is presented here. Tioli Access Manager is a complete authorization and network security policy management solution that proides end-to-end protection of resources oer geographically dispersed intranets and extranets. Tioli Access Manager features state-of-the-art security policy management. In addition, Tioli Access Manager supports authentication, authorization, data security, and resource management capabilities. You use Tioli Access Manager in conjunction with standard Internet-based applications to build highly secure and well-managed intranets and extranets. At its core, Tioli Access Manager proides: An authentication framework Copyright IBM Corp. 2002,

18 Tioli Access Manager supports a wide range of authentication mechanisms. Note, howeer, that WebSphere performs its own authentication steps before using Tioli Access Manager for WebSphere. An authorization framework The Tioli Access Manager authorization serice, accessed through standard J2EE authorization classes, proides permit and deny decisions on access requests for natie Tioli Access Manager serers and third-party applications. You can learn more about Tioli Access Manager, including information necessary to make deployment decisions, by reiewing the product documentation. Start with the following guides: IBM Tioli Access Manager Base Installation Guide This guide describes how to plan, install, and configure a Tioli Access Manager secure domain. A series of easy installation scripts enable you to quickly deploy a fully functional secure domain. These scripts are ery useful when prototyping the deployment of a secure domain. IBM Tioli Access Manager Base Administrator s Guide This document presents an oeriew of the Tioli Access Manager security model for managing protected resources. This guide describes how to configure the Tioli Access Manager serers that make access control decisions. In addition, detailed instructions describe how to perform important tasks such as declaring security policies, defining protected object namespaces, and administering user and group profiles. The Tioli Access Manager documentation is aailable from the IBM Tioli Customer Support Web site. Integrating Tioli Access Manager with WebSphere Application Serer Tioli Access Manager for WebSphere extends the Tioli Access Manager security model to work with applications built for IBM WebSphere Application Serer Adanced Edition. The security model is used in the following way: When a user (principal) attempts to access a protected resource, WebSphere performs the following tasks: Authenticates the principal. When security is specified in the deployment descriptor for an application (declaratie security), a WebSphere container determines which roles are required to access the resource, and uses Tioli Access Manager for WebSphere to determine if the current principal has been granted any of the required roles. When an application deeloper has added security code directly into the application (programmatic security), a WebSphere container uses Tioli Access Manager to perform the necessary role membership checks. 2 IBM Tioli Access Manager for WebSphere Application Serer: User s Guide

19 Figure 1. Tioli Access Manager deployed with WebSphere Application Serer Figure 1 illustrates the following sequence of eents: 1. When a WebSphere application with J2EE security is run, and the user tries to access a protected resource, WebSphere authenticates the user, using the user registry. For example, in Figure 1 WebSphere Adanced Edition, multiple serer ersion, authenticates against an IBM Directory user registry. The user registry is shared with Tioli Access Manager. (For WebSphere Adanced Edition Single Serer, the authentication is against host-based security.) 2. When the user requests access to a protected method or resource, the WebSphere container uses information from the J2EE application deployment descriptor to determine the required role membership. 3. The WebSphere container uses the integrated Tioli Access Manager module to request an authorization decision ( granted or denied ) from the Tioli Access Manager authorization serer. The WebSphere container also passes additional context information, when present, to the authorization serer. The optional context information can include cell name, host name, and serer name. If the Tioli Access Manager policy database has policies specified for any of the context information, the authorization serer can use this information when making the authorization decision. 4. The authorization serer consults the Tioli Access Manager user definitions in the shared user registry. (The user registry is shared with WebSphere, unless WebSphere Adanced Edition Single Serer is used). The authorization serer then consults the permissions that hae been defined for the specified user Chapter 1. Introduction and oeriew 3

20 within the Tioli Access Manager protected object namespace. The protected object namespace is included in the policy database shown in Figure The Tioli Access Manager authorization serer returns the access decision to the WebSphere container. 6. WebSphere Application Serer either grants or denies access to the protected method or resource. Jaa 2 Enterprise Edition role-based security Jaa 2 Enterprise Edition (J2EE) security uses the concept of a principal to represent the identity of an entity that performs actiities. 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 banking application defines roles and maps methods to them. The entry granted in the table below indicates that the role can access the specified method. Table 1. Mapping of methods to roles Methods Roles getbalance deposit closeaccount Teller granted granted Cashier granted Super granted The roles that hae been defined aboe can then be mapped to principals, groups, or both. The entry Inoke in the table cells below indicates that the principal or group can inoke any methods that hae been granted to that role. Table 2. Method inocation permissions for principals or groups Roles Principal/Group Teller Cashier Superisor TellerGroup Inoke CashierGroup Inoke SuperisorGroup Frank (a principal) Inoke Inoke In the table aboe, the principal Frank can inoke the getbalance and closeaccount methods but cannot inoke the deposit method, because this method has not been granted to either the Cashier or Superisor role. Mapping of principals and groups to roles Prior to application runtime, the Tioli Access Manager for WebSphere migration utility is run to populate the Tioli Access Manager protected object namespace. The migration utility obtains information about roles and methods from the J2EE application deployment descriptors. At application runtime, when a user requests access to a protected resource, the following information is passed to the WebSphere container: 4 IBM Tioli Access Manager for WebSphere Application Serer: User s Guide

21 Principal The authenticated identity of the user. RoleName The name of a role. AppName The name of the application. CellName The name of a grouping of host systems on the network. HostName The name of a host system contained in CellName. SererName The name of a serer that is hosted by HostName. The role names are deried from the method-to-role mappings in the deployment descriptors. By default, Tioli Access Manager s access check is performed based on the RoleName and AppName. The access check can easily be extended to take into account CellName, HostName and SererName. These alues are optional, and are ealuated only when they are defined. Tioli Access Manager access control lists (ACLs) determine which J2EE application roles hae been assigned to a principal. The migration utility attaches ACLs to the AppName in the protected object namespace. Figure 2 below illustrates the following sequence of eents: 1. Before application runtime, the Tioli Access Manager for WebSphere migration utility accesses the J2EE application deployment descriptor to extract information on roles and role-to-principal or role-to-group mapping. 2. The migration utility conerts the information into the Tioli Access Manager format, and passes it to the Tioli Access Manager policy serer. 3. The policy serer adds entries to the protected object namespace to represent the roles defined for the application. When role-to-principal or role-to-group mappings hae been defined in the deployment descriptor, the appropriate principals or groups are added to the ACLs that are attached to the new objects. Chapter 1. Introduction and oeriew 5

22 Figure 2. Mapping of roles to the Tioli Access Manager protected object space The Tioli Access Manager security model uses the definitions stored in the protected object namespace to build a hierarchy of resources to which ACLs can be attached. These ACLs define the mapping of roles to users or groups. Figure 3 below illustrates how ACLs can be applied to the protected object namespace that describes a role. The protected object namespace for all WebSphere applications consists of a top-leel protected object called WebAppSerer. The WebAppSerer object has a child object called deployedresources. Together, these two object names sere as a top-leel prefix to all J2EE roles defined in WebSphere applications. 6 IBM Tioli Access Manager for WebSphere Application Serer: User s Guide

23 Roles are defined in the next leel in the hierarchy, as a resource named for the role: RoleName. Directly under this object is the resource representing the application: AppName. Underneath the AppName protected object are seeral optional resources that can be defined to more precisely control access to roles. The optional resources are CellName, HostName, and SererName. Figure 3. Attaching ACLs to objects in the protected object namespace. In Figure 3 aboe, ACL 1 grants user1 access to the specified RoleName, inany application anywhere in the network. User2 and group1 are denied access. In the Tioli Access Manager security model, these access settings are inherited by the objects defined underneath RoleName in the protected object space hierarchy. This inheritance occurs by default. Thus, in Figure 3, the access settings are inherited by the objects representing AppName/CellName/HostName/SererName. Sometimes security policy requires that the access settings for objects located underneath the ACL attachment point must differ from the inherited access settings. In this case, the Tioli Access Manager administrator defines a new ACL containing the required access settings. The administrator then attaches the new ACL to the object at the specified point of control. This new ACL oerrides the inherited access settings. For example, security policy might dictate that user1 should not be granted RoleName permission when the application is run on a specific serer on a specific host within a specific cell. To enforce this policy, the administrator defines a more restrictie ACL, as represented in Figure 3 by ACL 2. This ACL denies access to user1, user2, and grp1. The administrator then attaches this ACL to the SererName object that represents the serer to which access must be restricted. Figure 3 shows the attachment of ACL 2 to SererName. Note that ACL 2 applies only to the specified serer. When more than one SererName object is defined underneath HostName, ACL 2 applies only to the SererName object to which it is attached. All other SererName objects at this leel in the hierarchy continue to inherit the access settings defined in ACL 1 and attached to RoleName. Chapter 1. Introduction and oeriew 7

24 For more information on the use of ACLs in the protected object namespace, see the IBM Tioli Access Manager Base Administrator s Guide. Centralizing policy management for multiple WebSphere serers Tioli Access Manager proides centralized management of security policies. Tioli Access Manager can manage security policy across multiple WebSphere Application Serers. In addition, Tioli Access Manager uses the same model to manage security across non-websphere applications. After the roles and principal or group mappings described in a J2EE application s deployment descriptors hae been migrated to Tioli Access Manager, and the users and groups hae been registered with Tioli Access Manager, you can use the Tioli Access Manager management tools to manage further changes to the security definitions. Use the Tioli Access Manager Web Portal Manager to manage changes in security definitions related to the mapping of roles to principals or groups. Use the WebSphere console to make other security-related changes. Note that changes to role mappings made through the WebSphere console will not be isible to the Tioli Access Manager security model. Use the following Tioli Access Manager tools to manage security policy: Tioli Access Manager Web Portal Manager The Web Portal Manager is the Tioli Access Manager management console. This console proides a graphical user interface for managing the Tioli Access Manager users, actions, and resources that are defined in the Tioli Access Manager protected object 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 user registry. pdadmin The pdadmin utility is a command-line based utility for managing the Tioli Access Manager security model. This powerful utility can be used to manage all aspects of the Tioli Access Manager protected object namespace, including users, objects, resources, and ACLs. Also, pdadmin can manage user and group entries in user registries. Administrators can use this utility within scripts or programs to automate administration tasks. For more information, see the IBM Tioli Access Manager Base Administrator s Guide. Tioli Access Manager Administration API Tioli Access Manager proides a programmatic interface to the administration tasks accomplished by pdadmin and the Web Portal Manager. Application deelopers can use acorjaa API to perform administration tasks that are specific to the application. For more information, see the IBM Tioli Access Manager Administration C API Deeloper s Reference or IBM Tioli Access Manager Administration Jaa Classes Deeloper s Reference. 8 IBM Tioli Access Manager for WebSphere Application Serer: User s Guide

25 Figure 4. Tioli Access Manager proides centralized administration of multiple serers. Figure 4 aboe illustrates Tioli Access Manager s management of security across multiple WebSphere serers. The Web Portal Manager has been installed with WebSphere Application Serer on Machine A. The pdadmin utility is shown on a non-websphere system, Machine B. Both the Web Portal Manager and pdadmin use the policy serer on Machine D to administer security policy. The Tioli Access Manager authorization serer can be installed on a system that is separate from the WebSphere system. In Figure 4, Machine E hosts WebSphere Application Serer. This serer has a Tioli Access Manager for WebSphere module that has been integrated into the WebSphere container responsible for authorization decisions. The WebSphere container obtains authorization decisions from the Tioli Access Manager authorization serer on Machine F. The authorization serer can also be installed on the same system as the WebSphere Application Serer, as shown on Machine G. The Tioli Access Manager functionality is identical to that proided when the serers are on separate systems (as shown on Machine E and Machine F). Co-location of the authorization serer Chapter 1. Introduction and oeriew 9

26 with the WebSphere Application Serer optimizes performance when making authorization decisions. This configuration is recommended. Note that the Tioli Access Manager policy database is replicated from Machine D to both Machine F and Machine G. This replication increases performance and proides failoer capability. Figure 4 also shows that the Tioli Access Manager serers and the WebSphere serers share an LDAP user registry on Machine C. Figure 4 assumes that WebSphere Adanced Edition (multiserer) is being used. The user registry is not shared when using WebSphere Adanced Edition Single Serer. 10 IBM Tioli Access Manager for WebSphere Application Serer: User s Guide

27 Chapter 2. Installation instructions Software contents Supported platforms This chapter contains the following topics: Software contents Supported platforms Disk and memory requirements Software prerequisites on page 12 User registry prerequisites on page 14 Upgrading from a preious release on page 15 Installing Tioli Access Manager for WebSphere on page 16 Tioli Access Manager for WebSphere proides a component that can be integrated with WebSphere Application Serer, and takes responsibility for all mappings of roles to principals or groups. Tioli Access Manager for WebSphere also proides a migration utility that can be used to import role-to-principal or role-to-group mappings from a Jaa 2 Enterprise Edition (J2EE) deployment descriptor into an Tioli Access Manager security schema. This utility can migrate data from either compressed or expanded WebSphere Enterprise Archie (EAR) files. The Tioli Access Manager for WebSphere distribution contains the following software: Tioli Access Manager for WebSphere Jaa classes A configuration script called pdwascfg, for the Jaa classes A migration utility called migrateear. Sample tutorial code that demonstrates the use of the migration utility and the Jaa classes Tioli Access Manager for WebSphere is supported on the following platforms: AIX and 5.1 Redhat Linux 7.1 and 7.2 Solaris Operating Enironment (Solaris) 2.7 and 2.8 HP-UX 11.0 and 11i Microsoft Windows 2000 Adanced Serer, Serice Pack 2 Disk and memory requirements Tioli Access Manager for WebSphere has the following disk and memory requirements: 64 MB RAM This is the amount of memory needed in addition to the memory requirements specified by WebSphere Application Serer and by any other Tioli Access Manager components. The amount of memory needed by other Tioli Access Copyright IBM Corp. 2002,

28 Manager components will depend on which Tioli Access Manager components are installed on the host system. For more information, see the IBM Tioli Access Manager Base Installation Guide. 100 MB disk space This requirement is aboe and beyond the disk space required by WebSphere Application Serer and by any other Tioli Access Manager components. Software prerequisites The following sections discuss the prerequisites for the integration of Tioli Access Manager for WebSphere with a WebSphere Application Serer enironment. WebSphere Application Serer Tioli Access Manager Base on page 13 Jaa Runtime Enironment on page 13 Xerces XML parser on page 14 WebSphere Application Serer The Tioli Access Manager for WebSphere component requires one of the following WebSphere Application Serer products to be installed on the host system: IBM WebSphere Application Serer, Adanced Edition Version 4.0, with FixPack 3 (Version 4.0.3). or IBM WebSphere Application Serer 4.0, Adanced Edition Single Serer, with FixPack 3, (Version 4.0.3). Note: The Single Serer edition requires specific configuration steps. See WebSphere Adanced Edition Single Serer on page 41. Before you can install Tioli Access Manager for WebSphere you must install WebSphere Application Serer Version The WebSphere Application Serer, Adanced Edition, must be configured to use a user registry that will be shared with Tioli Access Manager. The WebSphere users and groups must be imported into Tioli Access Manager. Note: The requirement to share a user registry does not apply to WebSphere Application Serer, Adanced Edition Single Serer. The Single Serer edition uses host-based security. Documentation on installation of the IBM WebSphere Application Serer Version 4.0 is aailable at: If you are new to IBM WebSphere Application Serer, consult the Getting Started with IBM WebSphere Application Serer Version 4.0 guide. This guide is aailable at the Web site aboe. To obtain the WebSphere Application Serer Adanced Edition 4.0 Fixpack 3: 1. Go to the IBM Software Support Web site: 2. Enter the following string in the Search field: WebSphere Application Serer 4.0 FixPak 3 (Version 4.0.3) 12 IBM Tioli Access Manager for WebSphere Application Serer: User s Guide

29 3. Download the FixPack image for your operating system. 4. Reiew the software prerequisites for Version Adanced Edition. Note that operating system patches may be required on some platforms: Tioli Access Manager Base Tioli Access Manager for WebSphere requires at least one Tioli Access Manager component to be installed on the local host, and requires that a Tioli Access Manager secure domain be established. Typically, the secure domain is distributed across multiple systems. Required component on the local host Tioli Access Manager for WebSphere requires that the Tioli Access Manager Base Jaa runtime component be installed on the local computer that hosts the WebSphere Application Serer. This is the minimum Tioli Access Manager Base software prerequisite for supporting Tioli Access Manager for WebSphere. Tioli Access Manager for WebSphere does not require any additional Tioli Access Manager components on the local computer that hosts the WebSphere Application Serer. Optional components on the local host While you are not required to add any additional Tioli Access Manager components on the local host, you can optimize performance by installing the Tioli Access Manager authorization serer on the same host as the WebSphere Application Serer. The authorization serer has a prerequisite on the Tioli Access Manager runtime enironment. Both of these components are distributed as part of the Tioli Access Manager Base product. Note: The authorization serer is not currently aailable on Linux. Tioli Access Manager secure domain Tioli Access Manager for WebSphere must be able to access a Tioli Access Manager secure domain. The authorization component must be able to contact a Tioli Access Manager policy serer. For best performance, it is recommended that one or more Tioli Access Manager authorization serers also be installed in the secure domain. Thus, after you hae installed the IBM WebSphere Application Serer, you must establish a secure domain before installing Tioli Access Manager for WebSphere. To establish a secure domain, you must install and configure the policy serer. Typically this is not run on the same host as the WebSphere Application Serer. You can install and configure an authorization serer either on the WebSphere Application Serer host or on a different system. For more information on installing and configuring an Tioli Access Manager secure domain, including the Tioli Access Manager Base Jaa runtime, see the IBM Tioli Access Manager Base Installation Guide. Jaa Runtime Enironment The computer system that hosts Tioli Access Manager for WebSphere must hae the following Jaa Runtime Enironment software installed: Table 3. Supported ersions of the Jaa Runtime Enironment Operating System Jaa Runtime Enironment Chapter 2. Installation instructions 13

30 Table 3. Supported ersions of the Jaa Runtime Enironment (continued) AIX IBM Jaa Runtime Enironment Version 1.3 Linux Windows HP-UX Solaris Sun Jaa Runtime Enironment Version 1.3 The Jaa Runtime Enironment is installed and configured as part of the IBM WebSphere Application Serer installation. Tioli Access Manager for WebSphere uses the same Jaa runtime enironment. Note: Tioli Access Manager for WebSphere also makes use of the Tioli Access Manager Jaa runtime. The Tioli Access Manager Jaa runtime extends the Version 1.3 Jaa runtime. Xerces XML parser The Tioli Access Manager for WebSphere migration utility requires access to the Xerces parser. This parser is distributed as the file Xerces.jar and is included in the WebSphere Application Serer Version product. You will need to ensure that the migrateear script is configured to access the correct directory. This is done by ensuring that the enironment ariable WAS_HOME is set to the WebSphere Application Serer installation directory. User registry prerequisites Tioli Access Manager for WebSphere operates as part of a Tioli Access Manager secure domain. The policy serer for the secure domain uses a user registry to manage user and group information. Tioli Access Manager for WebSphere supports all of the user registry types that are supported by Tioli Access Manager Base: IBM Directory iplanet Directory Lotus Domino Actie Directory For a complete list of supported ersions of each user registry type, see the IBM Tioli Access Manager Base Installation Guide. The user registry prerequisites for each installation are also based on the ersion of WebSphere Application Serer that is used with Tioli Access Manager for WebSphere. WebSphere Application Serer, Adanced Edition, Version 4.0 FixPack 3 (4.0.3) There are two prerequisites for use of user registries that must be satisfied before installing Tioli Access Manager for WebSphere: The Tioli Access Manager policy serer and the WebSphere Application Serer must be configured to use the same user registry. For example, they must access the same IBM Directory LDAP user registry. Any existing users and groups defined for WebSphere Application Serer must be imported into the Tioli Access Manager user directory, to become Tioli Access Manager users and groups. Importing here means adding 14 IBM Tioli Access Manager for WebSphere Application Serer: User s Guide

31 extended Tioli Access Manager attributes, along with the existing user and group definitions, into the Tioli Access Manager security schema. Users can be imported into the Tioli Access Manager user registry manually using the pdadmin command. Tioli Access Manager secure domains that use IBM Directory LDAP can make use of the Directory bulk load feature. For more information on using the pdadmin command to import users manually, see the IBM Tioli Access Manager Base Administrator s Guide. For more information on the bulk loading of IBM Directory users, see the IBM Tioli Access Manager Performance Tuning Guide. WebSphere Application Serer, Adanced Edition Single Serer, Version 4.0, Fixpack 3 (4.0.3) WebSphere Adanced Edition Single Serer does not use any external user registry. Instead, it works with host-based security. Each user account on the host system must hae an equialent entry in the user registry used by Tioli Access Manager. Note that any changes made oer time to the host-based security must also be made to the user registry used by Tioli Access Manager. Upgrading from a preious release Tioli Access Manager for WebSphere can be upgraded from the following preious releases: IBM Tioli Access Manager for WebSphere Application Serer, Version 3.9 Tioli Policy Director for WebSphere Application Serer, Version 3.8 The upgrade process consists simply of remoing the preious release and then installing Tioli Access Manager for WebSphere Version 4.1. The configuration information is retained in the WebSphere Application Serer configuration files. To upgrade Tioli Access Manager for WebSphere, complete the following steps: 1. Remoe the preious release. Follow the remoal instructions for your operating system in the appropriate user guide: IBM Tioli Access Manager for WebSphere Application Serer User s Guide, Version 3.9 Tioli Policy Director for WebSphere Application Serer User Guide, Version Upgrade the prerequisite Tioli Access Manager base packages and secure domain from Version 3.8 or Version 3.9 to Version 4.1. Determine which Tioli Access Manager base packages are installed on the computer that hosts Tioli Access Manager for WebSphere. Each deployment includes at a minimum the Tioli Access Manager Jaa runtime. Depending on the topology of the Tioli Access Manager secure domain, the host computer might also include: Tioli Access Manager runtime enironment Tioli Access Manager policy serer Tioli Access Manager authorization serer When the local computer system does not include the policy serer or authorization serer, you must first upgrade the secure domain on the computer system that hosts those serers. When the policy serer and authorization serer are upgraded to Version 4.1, you can then upgrade the Tioli Access Manager Jaa runtime package on the local computer. Chapter 2. Installation instructions 15

32 When the local computer contains the policy serer and authorization serer, you can upgrade all Tioli Access Manager base packages at one time. For instructions on upgrading Tioli Access Manager base packages and the secure domain, see IBM Tioli Access Manager Base Installation Guide. Complete the instructions in that document before continuing to the next step. 3. Install the current ersion of Tioli Access Manager for WebSphere. Follow the steps in Installing Tioli Access Manager for WebSphere. You do not need to configure the software after installing it. Installing Tioli Access Manager for WebSphere This section describes how to install Tioli Access Manager for WebSphere, including both the authorization component and the migration utility. Complete the instructions that apply to your operating system: Installing on Solaris Installing on AIX on page 17 Installing on HP-UX on page 18 Installing on Linux on page 19 Installing on Windows on page 20 Installing on Solaris The Tioli Access Manager for WebSphere installation separates file extraction from package configuration. Use pkgadd to install software packages on Solaris. Then use pdwascfg to configure Tioli Access Manager for WebSphere. Note: If you hae already installed and configured Tioli Access Manager for WebSphere and need to reinstall it, you must first unconfigure and remoe it. See Remoing from Solaris on page 63. To install Tioli Access Manager for WebSphere on Solaris complete the following instructions: 1. Log in as user root. 2. Verify that you hae satisfied the prerequisites for installing Tioli Access Manager for WebSphere. To reiew software dependencies, see Software prerequisites on page Verify that the Tioli Access Manager policy serer and the WebSphere Application Serer are configured to use the same user registry. Note: This step does not apply to WebSphere Adanced Edition Single Serer. To reiew user registry dependencies, see User registry prerequisites on page Verify that WebSphere Application Serer users and groups hae been imported from the user registry into the Tioli Access Manager user registry schema. You can use the Tioli 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 16 IBM Tioli Access Manager for WebSphere Application Serer: User s Guide

33 For more information on pdadmin, see the IBM Tioli Access Manager Base Administrator s Guide. For large numbers of users in an IBM Directory LDAP enironment, consider using the LDAP bulk import feature. For more information see the IBM Tioli Access Manager Performance Tuning Guide. 5. Mount the IBM Tioli Access Manager Web Security CD on /cdrom/cdrom0. 6. Change directory to /cdrom/cdrom0/solaris. 7. Enter the following command to install the Tioli Access Manager for WebSphere package: # pkgadd -d. PDWAS When prompted to continue, type y and press Enter. Files are extracted from the CD and installed on the hard disk. A message indicates that installation of the Tioli Access Manager for WebSphere package was successful. The pkgadd utility exits. 8. Next, configure Tioli Access Manager for WebSphere. Go to Chapter 3, Configuration procedures, on page 23 for instructions. Installing on AIX The Tioli Access Manager for WebSphere installation separates file extraction from package configuration. Use SMIT to install software packages on AIX. Then use pdwascfg to configure Tioli Access Manager for WebSphere. Note: If you hae already installed and configured Tioli Access Manager for WebSphere and need to reinstall it, you must first unconfigure and remoe the Tioli Access Manager for WebSphere package. See Remoing from AIX on page 64. To install Tioli Access Manager for WebSphere on AIX complete the following instructions: 1. Log in as root. 2. Verify that you hae satisfied the prerequisites for installing Tioli Access Manager for WebSphere. To reiew software dependencies, see Software prerequisites on page Verify that the Tioli Access Manager policy serer and the WebSphere Application Serer are configured to use the same user registry. Note: This step does not apply to WebSphere Adanced Edition Single Serer. To reiew user registry dependencies, see User registry prerequisites on page Verify that WebSphere Application Serer users and groups hae been imported from the user registry into the Tioli Access Manager user registry schema. You can use the Tioli 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 Tioli Access Manager Base Administrator s Guide. Chapter 2. Installation instructions 17

34 For large numbers of users in an IBM Directory LDAP enironment, consider using the LDAP bulk import feature. For more information see the IBM Tioli Access Manager Performance Tuning Guide. 5. Insert the IBM Tioli Access Manager Web Security CD into the CD drie. 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. On AIX 4.3 systems, select Install and Update Software from LATEST Aailable Software. On AIX 5.1 systems, select Install Software. 8. When prompted for input deice: On AIX 4.3, enter the location where the CD is mounted 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 window displays the list of IBM Tioli Access Manager software packages. 10. Select the Access Manager for WebSphere Application Serer package. Click OK. 11. The Install and Update Software from LATEST Aailable Software dialog box opens. 12. Verify that the default alue of yes is present in the field labeled AUTOMATICALLY install requisite software. 13. Set other fields to alues appropriate to your installation. In most cases, you can accept the default alues. Click OK. 14. A message box asks if you are sure you want to install this package. Click OK. The package files are installed. Seeral status messages are displayed. A final status message indicates success upon completion of file extraction. 15. Click Done. Click Cancel to exit SMIT. 16. Next, configure Tioli Access Manager for WebSphere. Go to: Chapter 3, Configuration procedures, on page 23 for instructions. Installing on HP-UX The Tioli Access Manager for WebSphere installation separates file extraction from package configuration. Use swinstall to install software packages on HP-UX. Then use pdwascfg to configure Tioli Access Manager for WebSphere. Note: If you hae already installed and configured Tioli Access Manager for WebSphere and need to reinstall it, you must first unconfigure and remoe it. See Remoing from HP-UX on page 65. To install Tioli Access Manager for WebSphere on HP-UX, complete the following steps: 1. Log in as user root. 18 IBM Tioli Access Manager for WebSphere Application Serer: User s Guide

35 2. Verify that you hae satisfied the prerequisites for installing Tioli Access Manager for WebSphere. To reiew software dependencies, see Software prerequisites on page Verify that the Tioli Access Manager policy serer and the WebSphere Application Serer are configured to use the same user registry. Note: This step does not apply to WebSphere Adanced Edition Single Serer. To reiew user registry dependencies, see User registry prerequisites on page Verify that WebSphere Application Serer users and groups hae been imported from the user registry into the Tioli Access Manager user registry schema. You can use the Tioli 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 Tioli Access Manager Base Administrator s Guide. For large numbers of users in an IBM Directory LDAP enironment, consider using the LDAP bulk import feature. For more information see the IBM Tioli Access Manager Performance Tuning Guide. 5. Insert the IBM Tioli Access Manager Web Security CD in the drie. Use the following commands to mount the CD: # nohup /usr/sbin/pfs_mountd & # nohup /usr/sbin/pfsd & # /usr/sbin/pfs_mount mount_deice mount_point For example: # /usr/sbin/pfs_mount /de/dsk/c0t0d0 /cdrom 6. Change directory to hp. 7. Enter the following command to install the Tioli Access Manager for WebSphere package: # swinstall -s /temp_directory PDWAS A message indicates that the analysis phase has succeeded. Another message indicates that the execution phase is beginning. Files are extracted from the CD and installed on the hard disk. A message indicates that the execution phase has succeeded. The swinstall utility exits. 8. Next, configure Tioli Access Manager for WebSphere. Go to: Chapter 3, Configuration procedures, on page 23 for instructions. Installing on Linux The Tioli Access Manager for WebSphere installation separates file extraction from package configuration. Use rpm to install software packages on Linux. Then use pdwascfg to configure Tioli Access Manager for WebSphere. Note: If you hae already installed and configured Tioli Access Manager for WebSphere and need to reinstall it, you must first unconfigure and remoe it. See Remoing from Linux on page 66. Chapter 2. Installation instructions 19

36 To install Tioli Access Manager for WebSphere on Linux complete the following instructions: 1. Log in as user root. 2. Verify that you hae satisfied the prerequisites for installing Tioli Access Manager for WebSphere. To reiew software dependencies, see Software prerequisites on page Verify that the Tioli Access Manager policy serer and the WebSphere Application Serer are configured to use the same user registry. Note: This step does not apply to WebSphere Adanced Edition Single Serer. To reiew user registry dependencies, see User registry prerequisites on page Verify that WebSphere Application Serer users and groups hae been imported from the user registry into the Tioli Access Manager user registry schema. You can use the Tioli 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 Tioli Access Manager Base Administrator s Guide. For large numbers of users in an IBM Directory LDAP enironment, consider using the LDAP bulk import feature. For more information see the IBM Tioli Access Manager Performance Tuning Guide. 5. Mount the IBM Tioli Access Manager Web Security CD. 6. Change directory to /mount_point/linux. 7. Enter the following command to install the Tioli Access Manager for WebSphere package: # rpm -i PDWAS-PD i386.rpm When prompted to continue, type y and press Enter. Files are extracted from the CD and installed on the hard disk. The rpm utility exits. 8. Next, configure Tioli Access Manager for WebSphere. Go to Chapter 3, Configuration procedures, on page 23 for instructions. Installing on Windows The Tioli Access Manager for WebSphere installation separates file extraction from package configuration. Use an InstallShield setup.exe to install the Tioli Access Manager for WebSphere files. Use pdwascfg to configure Tioli Access Manager for WebSphere. Note: If you hae already installed and configured Tioli Access Manager for WebSphere and need to reinstall it, you must first unconfigure and remoe it. See Remoing from Windows on page 63. To install and configure Tioli Access Manager for WebSphere on Windows complete the following instructions: 1. Log in to the Windows domain as a user with Windows administrator priileges. 20 IBM Tioli Access Manager for WebSphere Application Serer: User s Guide

37 2. Verify that you hae satisfied the prerequisites for installing Tioli Access Manager for WebSphere. To reiew software dependencies, see Software prerequisites on page Verify that the Tioli Access Manager policy serer and the WebSphere Application Serer are configured to use the same user registry. Note: This step does not apply to WebSphere Adanced Edition Single Serer. To reiew user registry dependencies, see User registry prerequisites on page Verify that WebSphere Application Serer users and groups hae been imported from the user registry into the Tioli Access Manager user registry schema. You can use the Tioli 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 Tioli Access Manager Base Administrator s Guide. For large numbers of users in an IBM Directory LDAP enironment, consider using the LDAP bulk import feature. For more information see the IBM Tioli Access Manager Performance Tuning Guide. 5. Insert the IBM Tioli Access Manager Web Security CD into the CD drie. 6. Run the Tioli Access Manager for WebSphere InstallShield setup program by double-clicking on the following file, where the letter E: in the following command represents the CD drie: E:\Windows\AccessManager\Disk Images\Disk1\PDWAS\Disk Images\Disk 1\setup.exe The Choose Setup Language dialog box opens. 7. Select the appropriate language and click OK. The InstallShield program starts and the Welcome dialog box opens. 8. Click Next. The License Agreement dialog box opens. 9. Click Yes to accept the License Agreement. The Choose Destination Location dialog box opens. 10. Accept the default or specify an alternatie location. Click Next. The files are extracted to the disk. A message indicates that the files hae been installed. 11. Click Finish to exit the setup program. 12. Next, configure Tioli Access Manager for WebSphere. Go to Chapter 3, Configuration procedures, on page 23 for instructions. Chapter 2. Installation instructions 21

38 22 IBM Tioli Access Manager for WebSphere Application Serer: User s Guide

39 Chapter 3. Configuration procedures The configuration steps for Tioli Access Manager for WebSphere differ depending on whether you are configuring the first Tioli Access Manager for WebSphere system into a Tioli Access Manager secure domain or you are adding an additional Tioli Access Manager for WebSphere system. Each Tioli Access Manager for WebSphere system is configured into the secure domain by using the pdwascfg utility. Security information for J2EE applications must be migrated to the Tioli Access Manager policy database. Tioli Access Manager for WebSphere proides a migration utility to do this. Note that this needs to be performed only on systems that hae J2EE applications with EAR files that specify the security policy. In addition, there are seeral configuration steps that are required only when configuring the first Tioli Access Manager for WebSphere system into a gien Tioli Access Manager secure domain. Continue to one of the following sections: Configuring the initial installation Configuring additional installations on page 30 Configuring the initial installation This section describes how to configure the first Tioli Access Manager for WebSphere installation. Tioli Access Manager for WebSphere proides utilities to expedite the configuration process. The configuration steps use these utilities, plus the Tioli Access Manager administratie utility pdadmin and the WebSphere console. A number of the steps need be performed only the first time Tioli Access Manager for WebSphere is configured into a specific Tioli Access Manager secure domain. The configuration instructions are described in the following sections: Part 1: Configure the Tioli Access Manager Jaa runtime on page 24 Part 2: Create a user, action, and action group on page 24 Part 3: Join a secure domain on page 25 Part 4: Migrate WebSphere security settings on page 26 Part 5: Add the pdwas admin group to the administration ACL on page 29 Part 6: Enable WebSphere security on page 29 The configuration steps for initial configuration into a secure domain are summarized in the diagram below. Copyright IBM Corp. 2002,

40 Figure 5. Configuration tasks for initial installation of Tioli Access Manager for WebSphere. Complete the instructions in each of the numbered parts in this section. Part 1: Configure the Tioli Access Manager Jaa runtime Configure the Tioli Access Manager Jaa runtime to extend the Jaa runtime that is distributed with IBM WebSphere Application Serer. Note: The Tioli Access Manager Jaa runtime is a software prerequisite for Tioli Access Manager for WebSphere. Complete the following steps: 1. Verify that enironment ariable WAS_HOME is set to the IBM WebSphere Application Serer home directory. 2. Change directory to the following location: (UNIX) /opt/policydirector/sbin (Windows) C:\Program Files\Tioli\Policy Director\sbin 3. Enter the following command: (UNIX) pdjrtecfg -action config -jaa_home $WAS_HOME/jaa/jre (Windows) pdjrtecfg -action config -jaa_home %WAS_HOME%\jaa\jre Note: Ensure that the location of the jaa binary that appears first in your PATH ariable matches the location of the jaa binary that you specify to the pdjrtecfg option -jaa_home pathname. Part 2: Create a user, action, and action group Perform seeral Tioli Access Manager administratie tasks to create the necessary user, action, and action group. Use either the Tioli Access Manager command line utility, pdadmin, or the Tioli Access Manager Web Portal Manager. The following instructions describe how to use pdadmin. 1. From a command line, start pdadmin as administratie user sec_master: pdadmin -a sec_master -p mypassword 24 IBM Tioli Access Manager for WebSphere Application Serer: User s Guide

41 Substitute the correct password for the sec_master account for your secure domain. 2. Create a Tioli Access Manager administratie user for WebSphere Application Serer. For example, the following instructions create a new user wsadmin. The following command must be entered as one continuous command line: pdadmin> user create wsadmin cn=wsadmin,o=organization,c=country wsadmin wsadmin mypassword Substitute alues for organization and country that are alid for your LDAP user registry. Make the wsadmin account alid: pdadmin> user modify wsadmin account-alid yes 3. Create a new Tioli Access Manager action group called WebAppSerer: pdadmin> action group create WebAppSerer 4. Create a new Tioli Access Manager action, designated by the letter i: pdadmin> action create i inoke inoke WebAppSerer Part 3: Join a secure domain Complete the following steps: 1. Stop WebSphere Application Serer. 2. Assemble the following information: The name of the user account you want to use as a user identity for the Tioli Access Manager for WebSphere application. The example commands in these instructions use the identity pdpermadmin. You can choose any name you want. Note: You can use an existing identity within the Tioli Access Manager secure domain, or you can create a new identity. In most cases, you will create a new, unique identity to represent the Tioli Access Manager for WebSphere component on the host system that you are currently configuring. The password for the sec_master account. The fully qualified domain name for the computer that hosts the policy serer. For example: pdmgrserer.mysubnet.ibm.com The fully qualified domain name for the computer that hosts the authorization serer. For example: pdacldserer.mysubnet.ibm.com 3. Verify that the correct ersion of the Jaa runtime enironment will be accessed when pdwascfg is run. This ersion should match the one specified during the configuration of the Tioli Access Manager Jaa runtime enironment. On Windows systems, erify that the %PATH% ariable lists the Jaa runtime enironment supplied by WebSphere Application Serer as the first one in the path. For example, when WebSphere Application Serer is installed in the default location, the %PATH% setting typically is: c:\websphere\appserer\jaa\jre\bin\jaa On UNIX systems, enter the following command: # which jaa When WebSphere Application Serer is installed in the default location, the response should be: Solaris, Linux, HP-UX Chapter 3. Configuration procedures 25

42 /opt/websphere/appserer/jaa/jre/bin/jaa AIX /usr/websphere/appserer/jaa/jre/bin/jaa If the ersion is not correct, reset the PATH ariable so that the correct Jaa path is first. 4. Ensure the the PDWAS_HOME enironment ariable is set to the Tioli Access Manager for WebSphere installation directory. Change directory to: (UNIX) /opt/pdwas/sbin (Windows) C:\Program Files\Tioli\pdwas\sbin 5. Run the pdwascfg utility. Use the information you collected in the preious step to supply the command line options to pdwascfg. Note: The example commands below assume that you are creating a new Tioli Access Manager user account called pdpermadmin. If the account pdpermadmin already exists, replace the name of the user with the complete DN. For example, replace: -remote_acl_user pdpermadmin with the option: -remote_acl_user cn=pdpermadmin,o=your_organization,c=your_country For example, using the example parameters assembled preiously, enter the following command, as one continuous command line: pdwascfg -action config -remote_acl_user pdpermadmin -sec_master_pwd mypassword -pdmgrd_host pdmgrserer.mysubnet.ibm.com -pdacld_host pdacldserer.mysubnet.ibm.com The pdwascfg utility does the following tasks: Sets the CLASSPATH ariable. Calls the Jaa class com.tioli.mts.srsslcfg to configure the SSL communication between the Tioli Access Manager for WebSphere authorization component and both the policy serer and the authorization serer. Creates a user identity for the Tioli Access Manager for WebSphere application on the host system. 6. Verify that the pdwascfg command successfully created the PdPerm properties file. Solaris, Linux, HP-UX /opt/websphere/appserer/jaa/jre/pdperm.properties AIX /usr/websphere/appserer/jaa/jre/pdperm.properties Windows C:\WebSphere\AppSerer\jaa\jre\PdPerm.properties Note: The aboe path names assume the default installation directory for WebSphere Application Serer. If you installed in a non-default location, adjust the path names accordingly. Part 4: Migrate WebSphere security settings Migrate application security policy from the WebSphere admin.ear deployment descriptor file to the Tioli Access Manager policy datatbase. 26 IBM Tioli Access Manager for WebSphere Application Serer: User s Guide

43 Complete the following steps: 1. Ensure that the WAS_HOME enironment ariable is set as follows: Solaris, Linux HP-UX WAS_HOME=/opt/WebSphere/AppSerer AIX WAS_HOME=/usr/WebSphere/AppSerer Windows WAS_HOME=C:\WebSphere\AppSerer This ariable must be set in order for the migration utility to access the correct xerces.jar file and the correct ersion of the Jaa runtime. The paths shown aboe are correct when WebSphere Application Serer is installed in the default location. If you hae installed WebSphere Application Serer in a different location, adjust the paths accordingly. 2. Assemble the following information, which you will need to specify as input parameters to the migration utility: Chapter 3. Configuration procedures 27

44 Table 4. Input parameters needed for the migration utility The name of the EAR file to migrate. For this initial use of the migration utility, you must migrate the administration EAR file: Solaris, Linux, HP-UX /opt/websphere/appserer/config/admin.ear AIX /usr/websphere/appserer/config/admin.ear Windows C:\WebSphere\AppSerer\config\admin.ear The location of the PDPerm.properties file. This file is located in a directory under the WebSphere Application Serer installation directory. The following list shows the default location on each operating system. Note: The file location must be expressed as a Uniform Resource Indicator. Solaris, Linux, HP-UX file:/opt/websphere/appserer/jaa/jre/pdperm.properties AIX file:/usr/websphere/appserer/jaa/jre/pdperm.properties Windows file:/c:\websphere\appserer\jaa\jre\pdperm.properties When WebSphere Application Serer is not installed in the default location on Windows systems, use %WAS_HOME% to indicate the installation directory: file:/%was_home%\jaa\jre\pdperm.properties The name of the Tioli Access Manager administration account. This should be sec_master. The password for the sec_master account. The name of the WebSphere administratie user account. This should match the account you created aboe. For example: wsadmin The LDAP distinguished name (DN) suffix under which both the Tioli Access Manager policy serer and WebSphere Application Serer store user information. This should match the DN suffix used when you created the wsadmin user. The example shown in Part 2: Create a user, action, and action group on page 24 created wsadmin with following DN: cn=wsadmin,o=ibm,c=us In this case the DN suffix is: o=ibm,c=us This alue should be gien as the argument to the d option to the migrateear utility. Note: You can use pdadmin to display the DN for wsadmin on your system: pdadmin> user show wsadmin 3. Change directory to the location of the migration utility: (UNIX) /opt/pdwas/bin (Windows) C:\Program Files\Tioli\pdwas\bin 4. Run the migration utility to migrate the data contained in admin.ear. Using the parameters that you assembled in the preious step, enter the following text at a command prompt, as one continuous command line: 28 IBM Tioli Access Manager for WebSphere Application Serer: User s Guide

45 Table 5. Command line inocation of the migration utility UNIX migrateear -j /opt/websphere/appserer/config/admin.ear -a sec_master -p sec_master_password -w wsadmin -d "o=ibm,c=us" -c file:/opt/websphere/appserer/jaa/jre/pdperm.properties Note that the default location of the PdPerm.properties file on AIX is: /usr/websphere/appserer/jaa/jre/pdperm.properties Windows migrateear -j %WAS_HOME%\config\admin.ear -a sec_master -p sec_master_password -w wsadmin -d "o=ibm,c=us" -c file:/%was_home%\jaa\jre\pdperm.properties The migration utility logs output to a log file. The name of the log file is displayed. For example, pdwas_migrate.log. You can examine the contents of the log file to erify that all roles were migrated. If the log file does not appear, the migration utility encountered a problem. If this occurs, erify that you supplied the correct Uniform Resource Indicator to the -c option, and the correct filename to the -j option. The migration utility requires access to admin.ear. By default, the application assembly tool contains URL references to the location of the Document Type Definitions (DTD) standard. Thus, lookups for the deployment descriptor DTDs require a connection 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 to point to the local DTD. Attention: You will need to run the migration utility at least one more time before using Tioli Access Manager for WebSphere. You will need to run it against the EAR file for each application that you are securing. You will be directed to do this after completing Part 6: Enable WebSphere security. For more information on the migration utility, see Chapter 4, Migrating security roles, on page 33. To reiew the migration utility syntax, see the reference page, migrateear on page 71. Part 5: Add the pdwas admin group to the administration ACL Complete the following steps: 1. Use pdadmin to add the pdwas-admin group to the appropriate ACL. Enter the following text as one continuous command: pdadmin> acl modify _WebAppSerer_deployedResources_AdminRole_admin_ACL set group pdwas-admin T[WebAppSerer]i 2. If your secure domain contains more than one authorization serer, use pdadmin to perform a serer replicate to ensure that all authorization serers are immediately updated with the ACL changes. 3. Restart the WebSphere Application Serer. Part 6: Enable WebSphere security Complete the following steps: Chapter 3. Configuration procedures 29

46 1. Go to the WebSphere console and enable WebSphere security. You can reiew a summary of how to enable WebSphere security in the tutorial chapter of this guide. See Part 3: Enable WebSphere Application Serer security on page 54. For complete instructions on enabling WebSphere security, see the WebSphere Application Serer documentation. 2. Stop and restart WebSphere Application Serer. 3. Before using Tioli Access Manager for WebSphere, you must migrate the application EAR file for each application that needs to be secured. Follow the instructions in Chapter 4, Migrating security roles, on page 33. Configuring additional installations This section describes how to configure additional Tioli Access Manager for WebSphere installations into a Tioli Access Manager secure domain. The instructions in this section assume the following: You hae successfully completed the instructions in Configuring the initial installation on page 23. By completing the aboe instructions, you will hae preiously migrated security information from the admin.ear file to Tioli Access Manager. You hae installed Tioli Access Manager for WebSphere on a different (additional) host system from the initial host system that you preiously configured. You are now ready to configure Tioli Access Manager for WebSphere on that additional host system. Note: Do not use the instructions in this section unless you hae preiously completed the section Configuring the initial installation on page 23. These instructions do not describe how to migrate security information from additional EAR files. You can complete the migration of any additional EAR files separate from completing the configuration instructions in this section. For more information on migrating EAR files, see Chapter 4, Migrating security roles, on page 33. The configuration steps are summarized in the following diagram: Figure 6. Configuration tasks for additional Tioli Access Manager for WebSphere systems The configuration steps are described in the following sections: Part A-1: Configure the Tioli Access Manager Jaa runtime on page 31 Part A-2: Join a secure domain on page IBM Tioli Access Manager for WebSphere Application Serer: User s Guide

47 Part A-1: Configure the Tioli Access Manager Jaa runtime Configure the Tioli Access Manager Jaa runtime component to access the Jaa runtime that is distributed with IBM WebSphere Application Serer. Note: The Tioli Access Manager Jaa runtime is a software prerequisite for Tioli Access Manager for WebSphere. To configure the Tioli Access Manager Jaa runtime component, complete the following steps: 1. Verify that enironment ariable WAS_HOME is set to the IBM WebSphere Application Serer home directory. 2. Change directory to the following location: (UNIX) /opt/policydirector/sbin (Windows) C:\Program Files\Tioli\Policy Director\sbin 3. Enter the following command: (UNIX) pdjrtecfg -action config -jaa_home $WAS_HOME/jaa/jre (Windows) pdjrtecfg -action config -jaa_home %WAS_HOME%\jaa\jre Note: Ensure that the location of the jaa binary that appears first in your PATH ariable matches the location of the jaa binary that you specify to the pdjrtecfg option -jaa_home pathname. Part A-2: Join a secure domain Complete the following steps: 1. Assemble the following information: The name of the user account you want to use as a user identity for the Tioli Access Manager for WebSphere application. The example commands in these instructions use the identity pdperm2admin. You can choose any name you want. Note: You can use an existing identity with the Tioli Access Manager secure domain, or you can create a new identity. In most cases, you will create a new, unique identity to represent the Tioli Access Manager for WebSphere component on the host system that you are currently configuring. The password for the sec_master account. The fully qualified domain name for the computer that hosts the policy serer. For example: pdmgrserer.mysubnet.ibm.com The fully qualified domain name for the computer that hosts the authorization serer. For example: pdacldserer.mysubnet.ibm.com 2. Verify that the correct ersion of the Jaa Runtime Enironment will be accessed when pdwascfg is run. This ersion should match the one specified during the configuration of the Tioli Access Manager Jaa runtime. On Windows systems, erify that the %PATH% ariable lists the Jaa Runtime Enironment supplied by WebSphere Application Serer as the first one in the path. On UNIX systems, enter the following command: # which jaa Chapter 3. Configuration procedures 31

48 When WebSphere Application Serer is installed in the default location, the response should be: Solaris, Linux, HP-UX /opt/websphere/appserer/jaa/jre/bin/jaa AIX /usr/websphere/appserer/jaa/jre/bin/jaa If the ersion is not correct, reset the PATH ariable so that the correct Jaa path is first. 3. Change directory to: UNIX: /opt/pdwas/bin Windows: C:\Program Files\Tioli\pdwas\sbin 4. Run the pdwascfg utility. Use the information you collected in the preious step to supply the command line options to pdwascfg. Note: The example commands below assume that you are creating a new Tioli Access Manager user account called pdperm2admin. If the account pdperm2admin already exists, replace the user name with the complete DN. For example, replace: -remote_acl_user pdperm2admin with the option: -remote_acl_user cn=pdperm2admin,o=your_organization,c=country For example, using the example parameters assembled preiously, enter the following command, as one continuous command line: pdwascfg -action config -remote_acl_user pdperm2admin -sec_master_pwd mypassword -pdmgrd_host pdmgrserer.mysubnet.ibm.com -pdacld_host pdacldserer.mysubnet.ibm.com 5. Verify that the pdwascfg command successfully created the PdPerm properties file. Solaris, Linux, HP-UX /opt/websphere/appserer/jaa/jre/pdperm.properties AIX /usr/websphere/appserer/jaa/jre/pdperm.properties Windows C:\WebSphere\AppSerer\jaa\jre\PdPerm.properties Note: The aboe path names assume the default installation directory for WebSphere Application Serer. If you installed in a non-default location, adjust the path names accordingly. 32 IBM Tioli Access Manager for WebSphere Application Serer: User s Guide

49 Chapter 4. Migrating security roles How to migrate security roles Tioli Access Manager for WebSphere proides a migration utility that automatically conerts security role definitions to Tioli Access Manager protected objects. The role definitions are read from the WebSphere application deployment descriptors and migrated to the Tioli Access Manager protected object space. This chapter describes how to use the utility. Topic index: How to migrate security roles Migration utility limitations on page 36 Troubleshooting tips on page 37 These instructions are intended to be used after completion of an initial configuration of Tioli Access Manager for WebSphere. The initial configuration of Tioli Access Manager for WebSphere includes the initial use of the migration utility on the WebSphere administratie security file admin.ear. Note: If you hae not yet run the migration utility during the initial configuration of Tioli Access Manager for WebSphere, do not use this section. See Configuring the initial installation on page 23. To migrate J2EE application security roles to Tioli 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 administratie priileges on Windows systems. 2. The migration utility requires access to the deployment descriptors for the applications that hae been secured. By default, the application assembly tool contains URL references to the location of the Document Type Definitions (DTD) standard. Thus, lookups for the deployment descriptor DTDs require a connection 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 to point to the local DTD. 3. Ensure that the WAS_HOME enironment ariable is set as follows: Solaris, Linux HP-UX WAS_HOME=/opt/WebSphere/AppSerer AIX WAS_HOME=/usr/WebSphere/AppSerer Windows WAS_HOME=C:\WebSphere\AppSerer This ariable must be set in order for the migration utility to access the correct xerces.jar file and the correct ersion of the Jaa runtime. The paths shown aboe are correct when WebSphere Application Serer is installed in the default location. If you hae installed WebSphere Application Serer in a different location, adjust the paths accordingly. 4. Assemble the following information, which you will need to specify as input parameters to the migration utility: Copyright IBM Corp. 2002,

50 Table 6. Input parameters needed for the migration utility The name of the EAR file to migrate. For example: Solaris, Linux, HP-UX /opt/websphere/appserer/config/secureapp.ear AIX /usr/websphere/appserer/config/secureapp.ear Windows C:\WebSphere\AppSerer\config\secureApp.ear The location of the PDPerm.properties file. This file is located in a directory under the WebSphere Application Serer installation directory. The following list shows the default location on each operating system. Note: The file location must be expressed as a Uniform Resource Indicator. Solaris, Linux, HP-UX file:/opt/websphere/appserer/jaa/jre/pdperm.properties AIX file:/usr/websphere/appserer/jaa/jre/pdperm.properties Windows file:/c:\websphere\appserer\jaa\jre\pdperm.properties When WebSphere Application Serer is not installed in the default location on Windows systems, use %WAS_HOME% to indicate the installation directory: file:/%was_home%\jaa\jre\pdperm.properties The name of the Tioli Access Manager administration account. This should be sec_master. The password for the sec_master account. The name of the WebSphere administratie user account. This should match the account you created during the initial configuration of Tioli Access Manager for WebSphere. For example: wsadmin The LDAP distinguished name (DN) suffix under which both the Tioli Access Manager policy serer and WebSphere Application Serer store user information. This should match the DN suffix used when you created the wsadmin user. The example shown in Part 2: Create a user, action, and action group on page 24 created wsadmin with following DN: cn=wsadmin,o=ibm,c=us In this case the DN suffix is: o=ibm,c=us This alue should be gien as the argument to the d option to the migrateear utility. Note: You can use pdadmin to display the DN for wsadmin on your system: pdadmin> user show wsadmin 5. Ensure that you hae the most recent EAR file for the application. Ensure that the EAR file has all the expected user to role mappings. If you are uncertain if all role mappings are present, export the application. See the IBM WebSphere Application Serer documentation for instructions on exporting EAR files. 6. Change directory to the location of the migration utility: (UNIX) /opt/pdwas/bin 34 IBM Tioli Access Manager for WebSphere Application Serer: User s Guide

51 (Windows) C:\Program Files\Tioli\pdwas\bin 7. Run the migration utility to migrate the application data. Using the parameters that you assembled in the preious step, enter the following at a command prompt, as one continuous command line: Table 7. Command line inocation of the migration utility UNIX migrateear -j /opt/websphere/appserer/config/your_application.ear -a sec_master -p sec_master_password -w wsadmin -d "o=ibm,c=us" -c file:/opt/websphere/appserer/jaa/jre/pdperm.properties Note that the default location of the PdPerm.properties file on AIX is: /usr/websphere/appserer/jaa/jre/pdperm.properties Windows migrateear -j %WAS_HOME%\config\your_application.ear -a sec_master -p sec_master_password -w wsadmin -d "o=ibm,c=us" -c file:/%was_home%\jaa\jre\pdperm.properties The migration utility logs output to a log file. The name of the log file is displayed. For example, pdwas_migrate.log. You can examine the contents of the log file to erify that all roles were migrated. If the log file does not appear, the migration utility encountered a problem. If this occurs, erify that you supplied the correct Uniform Resource Indicator to the -c option, and the correct filename to the -j option. To reiew the migration utility syntax, see the reference page: migrateear on page Repeat the preious steps for each Enterprise Archie (EAR) file that contains roles definitions that must be migrated to Tioli Access Manager. There is no need to run the migration utility against J2EE applications that do not hae security information in their deployment descriptors. Note: Run the migration utility only once for each unique EAR file. When there are multiple copies of any EAR file, you do not need to run the migration utility for each copy. 9. Choose one of the following actions: If you are using WebSphere Application Serer Adanced Edition Single Serer, go to the next step. If you are using WebSphere Application Serer Adanced Edition (not the Single Serer), the migration is complete. Do not perform the next step. 10. When using Tioli Access Manager for WebSphere with WebSphere Single Serer Edition, you must use pdadmin to manually add users to the ACLs that the migration utility created. Example pdadmin commands to add users are described in Migration utility limitations on page 36. You can also reiew how to add users to ACLs in the sample application described in the tutorial, Chapter 6, Tutorial: How to enable security, on page 49. See the example commands in Part 7: Migrate the application to Tioli Access Manager on page 58. Chapter 4. Migrating security roles 35

52 Migration utility limitations The migration utility has the following limitations: The migration utility is designed only to migrate the roles in EAR files to the Tioli Access Manager protected object space. Do not use the migration utility as a maintenance utility for roles. After migrating an EAR file, use either the Web Portal Manager or the pdadmin utility to manage roles. 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. When an EAR file is migrated, the contents of the EAR file reflect the configuration of the application when it was installed. Changes made to the deployment descriptors of an application from within WebSphere are not made to the EAR file. Always be sure to check that the EAR file accurately reflects the application configuration before migrating the security roles. For example, be sure that the application name is correct. An application name can be changed at application deployment, or later through the WebSphere console. This change will not be reflected in the EAR file. When the EAR file is not modified to reflect the new name, the wrong protected objects will be created. After the migration utility has been run once against an EAR file, it is recommended that you do not run it again when changes are made to an EAR file. The following problems can occur when an EAR is created and migrated to the protected object space, and then is migrated again. On the second or subsequent migrations, if an existing role has been remoed from the EAR, it will not be remoed from the protected object space. On the second or subsequent migrations, changes to the EAR file might require the migration utility to instruct Tioli Access Manager to delete an ACL definition. In some cases, Tioli Access Manager may preent this deletion. Note that the migration of an EAR file to the Tioli Access Manager protected object space results in the creation of ACLs that are attached to objects. If the administrator has manually attached the ACL definition to other protected objects, Tioli Access Manager preents remoal of the ACL. Thus, een if the original object that was created by the first run of the migration utility no longer exists, the ACL cannot be deleted. Use pdadmin to modify roles. You can use pdadmin to add additional roles. When using the migration utility with WebSphere Application Serer Adanced Edition Single System Edition, you must manually add the users to the ACLs that were created by the migration utility. Note: This applies only to WebSphere Application Serer Adanced Edition Single System. This limitation does not affect WebSphere Application Serer Adanced Edition. Use pdadmin to add the users to the ACL. The following example shows how to add users to an ACL, based on the sample application described in section Part 7: Migrate the application to Tioli Access Manager on page 58 in the tutorial chapter. Note that each pdadmin command must be entered as one continuous command line. c:> pdadmin -a sec_master -p mypassword pdadmin> acl list (Find the ACL that starts with _WebAppSerer_deployedResources_GoodGuys_) pdadmin> acl modify _WebAppSerer_deployedResources_GoodGuys_simpleSessionApp_ACL add user user1 T[WebAppSerer]i pdadmin> acl modify _WebAppSerer_deployedResources_GoodGuys_simpleSessionApp_ACL add user user2 T[WebAppSerer]i 36 IBM Tioli Access Manager for WebSphere Application Serer: User s Guide

53 pdadmin> acl modify _WebAppSerer_deployedResources_GoodGuys_simpleSessionApp_ACL add user user3 T[WebAppSerer]i pdadmin> acl modify _WebAppSerer_deployedResources_GoodGuys_simpleSessionApp_ACL add user user4 T[WebAppSerer]i pdadmin> exit Troubleshooting tips This section contains the following topics: Use of log files Users not attached to created ACLs Migration fails on Windows files with short name Web Portal Manager unable to attach an ACL to an object Warning that user wsadmin is a member of pdwas-admin on page 38 Client authentication lost due to session expiration on page 38 Migration utility messages not displayed in correct language on page 38 Unable to access WebSphere sample applications on page 39 Use of log files When troubleshooting problems with the migration utility, use the log files that WebSphere and Tioli Access Manager proide: Configure logging for the Tioli Access Manager authorization serer. Difficulties with accessing objects in the protected object namespace are logged here. Note that log information generated by requests from the Tioli Access Manager authorization component is logged here. Note also that this log is not the same as the WebSphere logs. For more information, see the IBM Tioli Access Manager Base Administrator s Guide. Actiity by the migration utility is logged in the file pdwas_migrate.log. This file is located in the directory where the migration utility is run. The last log message normally describes what the migration utility was attempting to do most recently. Therefore, in most cases it will indicate where an error was generated. Users not attached to created ACLs Problem: The admin.ear file does not contain any user information, just role mappings. As a result, no users are attached to the created ACLs. Solution: Use pdadmin to add the group pdwas-admin to the ACL. Enter the following command as one continuous command line: pdadmin> acl modify _WebAppSerer_deployedResources_AdminRole_admin_ACL set group pdwas-admin T[WebAppSerer]i Migration fails on Windows files with short name Problem: The migration utility does not work on filenames containing a tilde (~). This can cause problems when attempting to migrate a Windows short file name. Solution: Rename the filenames to omit the tilde (~) Web Portal Manager unable to attach an ACL to an object Problem: The Web Portal Manager might be unable to attach an ACL to objects that contain spaces in the object name. Chapter 4. Migrating security roles 37

54 Workaround: As a workaround, use pdadmin to attach the ACL. Solution: If possible, before running the migration utility, ensure that there are no spaces in the definitions listed in the deployment descriptors. Verify that the application name does not contain spaces. Warning that user wsadmin is a member of pdwas-admin Problem: When the migration utility is run, you might see a WARNING message, indicating that user wsadmin is a member of the group pdwas-admin. Solution: This warning is expected and is displayed for security purposes only. The purpose of this warning is to identify the user as a current member of the pdwas-admin group, so that the administrator can erify the accuracy of the list of users contained in this important administration group. Client authentication lost due to session expiration Problem: Tioli Access Manager proides a default SSL timeout alue for connections to the Tioli Access Manager policy serer. When this timeout alue is exceeded during execution of the migration utility, you might see the following message: The serer lost the client s authentication, probably because of session expiration. Solution: When this message occurs, run the migration utility again using the -t minutes option. The migration utility uses a default of 60 minutes. This alue should be no greater than the current SSL timeout between the authorization API client and the policy serer. You can determine the SSL timeout alue by examining the parameter ssl-3-timeout, located under the [ssl] stanza in the Tioli Access Manager configuration file imgrd.conf. The default alue for ssl-3-timeout is 7200 seconds (120 minutes). When this default alue is set, ensure that the SSL timeout set by the migration utility -t flag is at least 60 minutes. For more information, see the IBM Tioli Access Manager Base Administrator s Guide. Migration utility messages not displayed in correct language Problem: On Windows systems, messages from the Tioli Access Manager for WebSphere migration utility are not displayed correctly for some languages, such as Brazilian Portuguese. Workaround: Modify DOS Windows properties: 1. Enter the following command at a DOS command prompt: MSDOS> chcp From the DOS window menu, select Properties. 3. Select Lucida Console. Note that Lucida Console is a True Type font. 4. Select OK. Select OK on the panel to apply the properties to the current window only. 5. You can now iew the output from the migration utility. 38 IBM Tioli Access Manager for WebSphere Application Serer: User s Guide

55 Unable to access WebSphere sample applications Problem: Sample applications proided by WebSphere Application Serer cannot be accessed after Tioli Access Manager for WebSphere security is enabled. Explanation: WebSphere Application Serer automatically installs and configures a default serer and sample applications. During the automatic installation, the name of the application, such as Sample Application, is internally changed to $hostname$_sampleapp. When the Tioli Access Manager for WebSphere user migrates the sample application EAR file, such as sampleapp.ear, a Tioli Access Manager object space entry is created for Sample Application. Howeer, WebSphere Application Serer uses $hostname$_sampleapp to display the application on the console, and to resole authorization requests. Workaround: Complete the following steps: 1. Modify the application.xml file in the sampleapp.ear file to change the display name to match the name that is presented on the WebSphere Application Serer administration console. To do this, use WebSphere Application Serer application assembly tool to change the application name and then sae the EAR file. For example, find the tag: <DisplayName>Sample Applicaton</DisplayName> and change it to: <DisplayName>$hostName$_sampleApp</DisplayName> Note: Substitute the name of the host system for the ariable $hostname$. For example, if the system host name is diamond, the DisplayName of the application should be diamond_sampleapp. 2. Run the migration utility on the modified EAR file. Chapter 4. Migrating security roles 39

56 40 IBM Tioli Access Manager for WebSphere Application Serer: User s Guide

57 Chapter 5. Administration tasks This chapter contains the following topics: WebSphere Adanced Edition Single Serer Tioli Access Manager administration tools Specifying runtime properties on page 42 Adding an object class to the console on page 46 Configuring additional authorization serers on page 45 Troubleshooting tips on page 47 WebSphere Adanced Edition Single Serer IBM WebSphere Application Serer proides a ersion of Adanced Edition that supports a single serer. This ersion is designed to run WebSphere with host-based security instead of an external user registry. This ersion of WebSphere Application Serer is ery useful for deeloping and prototyping applications and for demonstration of WebSphere Application Serer features and capabilities. The system registry cannot be modified from the WebSphere console. Tioli Access Manager supports a number of external user registry types. When Tioli Access Manager is used with WebSphere Adanced Edition Single Serer, the Tioli Access Manager administrator must create equialent user registry entries for each releant user account on the system that hosts WebSphere. This means that the user definitions in the user registry must be created manually. Note that when users are mirrored into the Tioli Access Manager user registry from the operating system entry, the Tioli Access Manager user identity (ID) must match the operating system user ID. On Windows systems, this ID does not include the domain name. Note also that the Tioli Access Manager for WebSphere migration utility, when used with WebSphere Adanced Edition Single Serer, does not automatically add users to access control lists that it creates. The administrator must manually add the users. For more information, see Migration utility limitations on page 36. Use of Tioli Access Manager for WebSphere with the WebSphere Adanced Edition Single Serer is not recommended for production systems. See User registry prerequisites on page 14. Tioli Access Manager administration tools Do not use the WebSphere Application Serer console to modify attributes for users or roles. These changes will not be reflected in the Tioli Access Manager policy database. All administration of user and role configuration information must be performed through one of the Tioli Access Manager administration tools: The pdadmin command line utility Copyright IBM Corp. 2002,

58 The Tioli Access Manager Web Portal Manager graphical user interface Specifying runtime properties Tioli Access Manager also proides an administration API that can be used to perform administration tasks programmatically. For more information on the Tioli Access Manager administration tools, see the following guides: For pdadmin and for the graphical user interface, see the IBM Tioli Access Manager Base Administrator s Guide. For the programmatic API, see the IBM Tioli Access Manager Administration C API Deeloper s Reference or IBM Tioli Access Manager Administration Jaa Classes Deeloper s Reference. Tioli Access Manager for WebSphere uses a Jaa property file that contains configuration parameters. The property file is not created by default but can be used to modify configurable parameters. The Jaa property file should be created in the following location: UNIX: /opt/pdwas/etc/pdwas.properties Windows: C:\Program Files\Tioli\pdwas\etc\PDWAS.properties The following sections describe how to modify property settings: Limit simultaneous connections Enable static role caching Define static roles on page 43 Configure dynamic role caching on page 43 Specify logging mechanism type on page 44 Specify logging leel on page 44 Specify root object space name on page 45 Specify document type definition directory on page 45 Limit simultaneous connections Limits the number of simultaneous connections to Tioli Access Manager. The default is zero (0), which allows an unlimited number of connections. For example: com.tioli.pdwas.maxpdconnections=0 Set this alue if SSL exceptions occur. Large number of simultaneous connections can cause limitations with the Solaris Jaa Virtual Machine (JVM). Enable static role caching Enables or disables static role caching. Static role caching is enabled by default. com.tioli.pdwas.enablestaticrolecaching=true Attention: The WebSphere administratie serer requires that static role caching be enabled. Do not disable static role caching. When static role caching is disabled, the WebSphere administratie serer will not start. 42 IBM Tioli Access Manager for WebSphere Application Serer: User s Guide

59 Define static roles Defines additional static roles that are not defined in the WebSphere Application Serer admin.ear file. com.tioli.pdwas.staticrolecache.roles=adminrole Configure dynamic role caching This section describes the following settings: Enable dynamic role caching Specify maximum number of users Specify principal lifetime Specify role lifetime Specify number of cache tables Enable dynamic role caching Enables or disables dynamic role caching. Dynamic role caching is enabled by default. com.tioli.pdwas.enabledynamicrolecaching=true Specify maximum number of users The maximum number of users that the cache supports before a cache cleanup is performed. This parameter is used when dynamic role caching is enabled. The default number of users is com.tioli.pdwas.dynamicrolecache.maxusers=10000 Specify principal lifetime The period of time in minutes that a principal entry is stored in the cache. This parameter is used when dynamic role caching is enabled. The default time is 5 minutes. com.tioli.pdwas.dynamicrolecache.principallifetime=5 The term principal here refers to the Tioli Access Manager credential returned from a unique LDAP user. Specify role lifetime The period of time in seconds that a role is stored in the role list for a user before it is discarded. This parameter is used when dynamic role caching is enabled. The default is 20 seconds. com.tioli.pdwas.dynamicrolecache.rolelifetime=20 Specify number of cache tables The number of tables used internally by the dynamic role cache. This parameter is used when dynamic role caching is enabled. The default is 20. When a large number of threads use the cache, increase the alue to tune and optimize cache performance. com.tioli.pdwas.dynamicrolecache.numbuckets=20 Chapter 5. Administration tasks 43

60 Specify logging mechanism type Specifies the underlying logging mechanism. Valid entries are WAS or STDOUT. The default is STDOUT. When WAS is specified, the WebSphere Application Serer tracing framework is used. In this case, the normal WebSphere procedure for enabling or disabling tracing should be used. When STDOUT is specified, the enabling and disabling of tracing is performed using properties contained in the PDWAS.properties file (this file). com.tioli.pdwas.loggingtype=stdout Specify logging leel Sets the logging leel for Tioli Access Manager for WebSphere components. This parameter is used when the logging mechanism type is set to STDOUT. The format for specifying the logging leel is: com.tioli.pdwas.component.logleel=alue The supported components are: websphere.pdwasauthzmanager cache.staticrolecache cache.dynamicrolecache cache.genericcache cache.purgetask When the component is not specified, or a part of the component name is not specified, a wildcard is set for the logging leel for multiple matching of Tioli Access Manager for WebSphere components. For example, specifying com.tioli.pdwas.cache.logleel sets the caching leel for all cache components. Likewise, specifying com.tioli.pdwas.logleel sets the logging leel for all Tioli Access Manager for WebSphere components. The alues for these properties can be expressed as either an integer or as a comma-separated list of leel. The integer represents a bit map. The comma-separated list can hae the following alues: FATAL ERROR WARNING NOTICE ENTRY EXIT DEBUG The FATAL leel is the least significant bit of the bit map and the DEBUG leel is the most significant bit. For example, to turn on all logging for websphere.pdwasauthzmanager, either of the following entries could be used. Note that the entries are equialent: com.tioli.pdwas.websphere.pdwasauthzmanager.logleel = FATAL, ERROR, WARNING, NOTICE, ENTRY, EXIT, DEBUG com.tioli.pdwas.websphere.pdwasauthzmanager.logleel = IBM Tioli Access Manager for WebSphere Application Serer: User s Guide

61 Note that both an integer alue and string alues can be used together. The highest log leel is enabled. For example, the following entry enables both FATAL and ERROR: com.tioli.pdwas.websphere.pdwasauthzmanager.logleel = 1,ERROR Specify root object space name Changes the name of the root object space and the group permission name. The default alue is WebAppSerer. This parameter can be set to any alue. com.tioli.pdwas.rootobjectspacename=webappserer If you change the default name, ensure that the name matches the name used when the Tioli Access Manager migration utility is run. If the names do not match, Tioli Access Manager will not successfully locate protected resources. For more information, see migrateear on page 71. Specify document type definition directory Configures the location of the Document Type Definition (DTD) files that are required in order to use Tioli Access Manager for WebSpheree. The DTD application_1_2.dtd is required. This DTD is distributed with Tioli Access Manager for WebSphere, and is installed by the configuration script into the WebSphere lib directory. The WebSphere lib directory is the default location of this file. This alue must be configured as an absolute path. For example, on UNIX: com.tioli.pdwas.dtddirectory=/opt/pdwas/etc On Windows: com.tioli.pdwas.dtddirectory=c:\program Files\Tioli\pdwas\etc Configuring additional authorization serers Tioli Access Manager secure domains can optionally contain more than one authorization serer. The configuration of multiple authorization serers may be useful for two reasons: Failoer capability, in case one authorization serer is not aailable Performance improement, when the olume of access requests is ery large Tioli Access Manager for WebSphere can be configured to access multiple authorization serers. Use the Jaa class com.tioli.pd.jcfg.srsslcfg to add additional authorization serers. The command syntax is: jaa com.tioli.pd.jcfg.srsslcfg -action addsr -authsr host_name:port_number:rank -cfg_file cfg_file Note: Enter the aboe command as one continuous command line. Table 8. Command parameters for adding an authorization serer Parameter action addsr Description Add serer information to the application serer (Tioli Access Manager for WebSphere) configuration file. Chapter 5. Administration tasks 45

62 Table 8. Command parameters for adding an authorization serer (continued) authsr A Tioli Access Manager authorization serer. The argument format is: host_name A string. The name of the host computer for the authorization serer port_number An integer alue. The port on which the authorization serer can be contacted. rank An integer alue. The priority of this authorization serer, relatie to other authorization serers. Authorization serers with a higher rank will be contacted first when the application serer is attempting to obtain an accept or deny decision for an access request. Failoer occurs in order of rank. cfg_file cfg_file The application serer (Tioli Access Manager for WebSphere) configuration file. The configuration file is PdPerm.properties. Note that this must be expressed as a Uniform Resource Indicator. When WebSphere Application Serer is installed in the default location, the full path is: Solaris, Linux, HP-UX file:/opt/websphere/appserer/jaa/jre/pdperm.properties AIX file:/usr/websphere/appserer/jaa/jre/pdperm.properties Windows file:/c:\websphere\appserer\jaa\jre\pdperm.properties When WebSphere Application Serer is not installed in the default location on Windows systems, use %WAS_HOME% to indicate the installation directory: file:/%was_home%\jaa\jre\pdperm.properties Adding an object class to the console The WebSphere Application Serer console can be used to specify security policies for applications running in the WebSphere enironment. The WebSphere Application Serer console can also specify security policies for other Web resources, based on the entities stored in the user directory. Tioli Access Manager adds to the user registry the object class accessgroup. Tioli Access Manager administrators can use the pdadmin command or the Web Portal Manager to create new groups. These new groups will be of object class accessgroup. The WebSphere Application Serer console is not configured by default to recognize objects of the class accessgroup as user registry groups. You can configure the WebSphere Application Serer console to add this object class to the list of object classes that represent user registry groups. Complete the following instructions: 46 IBM Tioli Access Manager for WebSphere Application Serer: User s Guide

63 Troubleshooting tips 1. From the WebSphere console, access the adanced 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: (&(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 Serer as instructed by the console. The section contains the following topics: WebSphere administratie serer does not start WebSphere serer does not start after configuration WebSphere serer does not start after unconfiguration on page 48 WebSphere administratie serer does not start Problem: After configuring Tioli Access Manager for WebSphere, the WebSphere administratie serer will not start, and throws a null exception. Explanation: The WebSphere administratie serer requires that Tioli Access Manager for WebSphere be configured to enable static role caching. When static role caching is disabled, the WebSphere administratie serer will not start. Solution: Enable static role caching. See Enable static role caching on page 42. WebSphere serer does not start after configuration Problem: After configuring Tioli Access Manager for WebSphere, the WebSphere Application Serer will not start. Explanation: There are two possible reasons: During Tioli Access Manager for WebSphere configuration, the new administratie group pdwas-admin was not added to the appropriate ACLs. During Tioli Access Manager for WebSphere configuration, the new administratie group pdwas-admin was added to the appropriate ACLs, but the ACLs were not updated to all authorization serers. This problem can only occur in secure domains that hae more than one authorization serer Solution: There are two possible solutions: If pdwas-admin was not added to the appropriate ACLs, add it now. See Part 5: Add the pdwas admin group to the administration ACL on page 29. Chapter 5. Administration tasks 47

64 If pdwas-admin was added to the appropriate ACLs, and the secure domain contains more than one authorization serer, and the authorization serers were not updated, update them now. See Part 5: Add the pdwas admin group to the administration ACL on page 29. WebSphere serer does not start after unconfiguration Problem: After unconfiguring Tioli Access Manager for WebSphere and the Tioli Access Manager Jaa runtime, the WebSphere Application Serer might not start. This problem occurs ery intermittently. WebSphere Application Serer fails to load the security collaborator, com.ibm.ejs.security.ejssecuritycollaborator. Workaround: Disable WebSphere Application Serer security and restart WebSphere Application Serer. 1. Go to the system running DB2. Log on as the user name with which DB2 was installed. For example: # su - db2inst1 A usage message is displayed 2. Enter the following commands as shown in bold font, where was40 is the name of the host system: db2 => connect to was40 user db2inst1 Enter current password for db2inst1: Database Connection Information Database Serer = DB2/LINUX SQL authorization ID = DB2INST1 Local database alias = WAS40 db2 => update ejsadmin.securitycfg_table set securityenabled = 0 DB20000I The SQL command completed successfully db2 => commit DB20000I The SQL command completed successfully 3. Start WebSphere Application Serer. 48 IBM Tioli Access Manager for WebSphere Application Serer: User s Guide

65 Chapter 6. Tutorial: How to enable security How to use the tutorial This chapter proides a tutorial that describes how to add security to an example application. The tutorial is based on a WebSphere tutorial that helps you learn about arious aspects of WebSphere application assembly, configuration, and deployment. The WebSphere tutorial accompanies example code that is included as part of the WebSphere product. You do not need to consult the WebSphere tutorial to use this Tioli Access Manager tutorial. This Tioli Access Manager for WebSphere tutorial proides an application EAR file that has been built from the WebSphere example code by following the WebSphere tutorial instructions. The WebSphere tutorial is aailable at: The example program that is included with Tioli Access Manager for WebSphere is built from the tutorial instructions in Sections 6.71, 6.7.2, and at the Web site listed aboe. The material in this chapter replaces the tutorial in Section at the Web site listed aboe. This tutorial focuses on showing you how to add security to the application EAR file, add users to the LDAP user registry, enable WebSphere security, deploy and test the sample application, migrate the application to Tioli Access Manager, enable the Tioli Access Manager for WebSphere authorization component, and test the application security under Tioli Access 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: WebSphere Application Serer has been installed to use an IBM Directory LDAP user registry. Security has not been enabled for WebSphere. You can run this tutorial either before or after completing the initial installation and configuration of Tioli Access Manager for WebSphere. If you hae not yet installed Tioli Access Manager for WebSphere, the tutorial will instruct you when to install it. These instructions assume the following about Tioli Access Manager for WebSphere: If Tioli Access Manager for WebSphere has been installed and configured, it uses the same IBM Directory LDAP user registry. The Tioli Access Manager for WebSphere migration utility has been run against admin.ear. Note that this step is included in the instructions for the initial configuration of Tioli Access Manager for WebSphere. If you hae not yet installed and configured Tioli Access Manager for WebSphere, complete the instructions in each of the following sections: Copyright IBM Corp. 2002,

66 Part 1: Add security to a WebSphere application Part 2: Add users to the LDAP user registry on page 54 Part 3: Enable WebSphere Application Serer security on page 54 Part 4: Deploy the application on page 56 Part 5: Test security for the deployed application on page 57 Part 6: Install Tioli Access Manager for WebSphere on page 58 Part 7: Migrate the application to Tioli Access Manager on page 58 Part 8: Test security for the deployed application on page 60 Part 9: Change roles on page 60 Part 10: Test security for the deployed application on page 60 If you hae completed configuration the initial installation of Tioli Access Manager for WebSphere, according to the instructions in Chapter 3, Configuration procedures, on page 23, you need to complete only the following sections: Part 1: Add security to a WebSphere application Part 2: Add users to the LDAP user registry on page 54 Note: You do not need to perform Step 2 in this part. This task was completed during initial configuration of Tioli Access Manager for WebSphere. Part 4: Deploy the application on page 56 Part 5: Test security for the deployed application on page 57 Part 7: Migrate the application to Tioli Access Manager on page 58 Part 8: Test security for the deployed application on page 60 Part 9: Change roles on page 60 Part 10: Test security for the deployed application on page 60 Part 1: Add security to a WebSphere application 1. Start the WebSphere application assembly tool. Click Start->Programs->IBM WebSphere -> Application Serer 4.0 AE -> Application Assembly Tool or run C:\WebSphere\AppSerer\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 -> Open C:\temp\assembly\simpleSession.ear 4. Right click 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 preious step to add the following users: Name: user2 Name: user3 Click OK when all users are added. 50 IBM Tioli Access Manager for WebSphere Application Serer: User s Guide

67 8. Expand EJB Modules. Expand EBJ11. Right click Method Permissions. Select New. Add: Name: MyMethodPermissions a. Method: Click Add. Select Home (*) Select Remote (*) Click OK. b. Roles: Click Add. Select GoodGuys. Click OK. Figure 7. Adding a security role to the method permissions 9. Expand Web Modules. Double-click SimpleSessionWar. a. Click the Adanced 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: Click Add. Select GoodGuys. Click OK. c. For Transport Guarantee, select None. d. Click OK. Chapter 6. Tutorial: How to enable security 51

68 Figure 8. The Security Constraints of a Web module 11. Right click 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. 52 IBM Tioli Access Manager for WebSphere Application Serer: User s Guide

69 Figure 9. Configuring Web Resource Collections 12. Sae the new EAR file. Select File->Sae 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. Figure 10. Generating code for deployment. c. Fix any errors. 14. Exit the Application Assembly tool. Continue to the next section Part 2: Add users to the LDAP user registry on page 54. Chapter 6. Tutorial: How to enable security 53

70 Part 2: Add users to the LDAP user registry Use the Tioli Access Manager pdadmin utility to add the users you declared in the preious section (user1, user2, and user3) to the LDAP user registry. Also add an additional user, user4. This section demonstrates common pdadmin commands for adding users. For complete information on all pdadmin options, see the IBM Tioli Access Manager Base Administrator s Guide. 1. Log in as the Tioli Access Manager administrator: C:> pdadmin -a sec_master -p mypassword Substitute the correct password for the sec_master account for your Tioli Access Manager secure domain. 2. If you hae already installed Tioli Access Manager for WebSphere, and completed the initial configuration, skip this step. Go to the next step. If you hae not yet installed Tioli Access Manager for WebSphere, create a WebSphere administration user. Enter the following command as one continuous command line: pdadmin> user create wsadmin cn=wsadmin,o=organization, c=country wsadmin wsadmin mypassword Substitute alues for organization and country that are alid for your LDAP user registry. 3. Create user accounts for each of the new users. Assign passwords. The following examples show sample commands, where the organization is ibm and the country is au, and all users receie the password mypassword. pdadmin> user create user1 cn=user1,o=ibm,c=us user1 user1 mypassword pdadmin> user create user2 cn=user2,o=ibm,c=us user2 user2 mypassword pdadmin> user create user3 cn=user3,o=ibm,c=us user3 user3 mypassword pdadmin> user create user4 cn=user4,o=ibm,c=us user4 user4 mypassword 4. Enable all the accounts: pdadmin> user modify wsadmin account-alid yes pdadmin> user modify user1 account-alid yes pdadmin> user modify user2 account-alid yes pdadmin> user modify user3 account-alid yes pdadmin> user modify user4 account-alid yes 5. Exit the pdadmin utility: pdadmin> quit 6. Return to the WebSphere console to enable security. Continue to Part 3: Enable WebSphere Application Serer security. Part 3: Enable WebSphere Application Serer security If you hae already installed Tioli Access Manager for WebSphere, and completed the initial configuration described in Chapter 3, Configuration procedures, on page 23, skip this part. You already enabled WebSphere Application Serer security in Part 6: Enable WebSphere security on page 29. Go to the next part Part 4: Deploy the application on page Start the WebSphere Administration Serer: c:\websphere\appserer\bin\adminserer 54 IBM Tioli Access Manager for WebSphere Application Serer: User s Guide

71 2. When the serer has started, start the WebSphere Administration Client: c:\websphere\appserer\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: Token Expiry: 120 Domain: Your domain name. For example: mydomain.ibm.com b. Check the LDAP check box. Assign the LDAP settings: Table 9. LDAP settings LDAP Settings Security Serer ID Security Serer Password Host Directory Type Base DN Bind DN Bind Password Value cn=wsadmin,o=ibm,c=us mypassword ldapserer.mydomain.ibm.com SecureWay o=ibm,c=us cn=root mypassword c. Click OK. Chapter 6. Tutorial: How to enable security 55

72 6. Right click on WebSphere Admin Domain -> Nodes -> Hostname 7. Select Restart. 8. Continue to Part 4: Deploy the application. Part 4: Deploy the application Figure 11. Enabling security through the Security Center 1. Verify that the WebSphere Administration Serer is running. 2. Start the WebSphere Administration Client: C:\websphere\appserer\bin\adminclient 3. Log in as user wsadmin 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 unprotected methods. Click yes. d. Click Select. e. Verify that all users are listed user1 user2 user3 f. Click OK. 56 IBM Tioli Access Manager for WebSphere Application Serer: User s Guide