tivoli policy director for websphere application server...

Tivoli Policy Director forWebSphere Application ServerUser GuideVersion 3.8 SC32-0832-00

Tivoli SecureWay Policy Director for WebSphere Application Server User Guide (January 2002)

Copyright Notice

© Copyright IBM Corporation 2002. All rights reserved. May only be used pursuantto a Tivoli Systems Software License Agreement, an IBM Software LicenseAgreement, or Addendum for Tivoli Products to IBM Customer or LicenseAgreement. No part of this publication may be reproduced, transmitted, transcribed,stored in a retrieval system, or translated into any computer language, in any formor by any means, electronic, mechanical, magnetic, optical, chemical, manual, orotherwise, without prior written permission of IBM Corporation. IBM Corporationgrants you limited permission to make hardcopy or other reproductions of anymachine-readable documentation for your own use, provided that each suchreproduction shall carry the IBM Corporation copyright notice. No other rightsunder copyright are granted without prior written permission of IBM Corporation.The document is not intended for production and is furnished “as is” withoutwarranty of any kind. All warranties on this document are hereby disclaimed,including the warranties of merchantability and fitness for a particularpurpose.

U.S. Government Users Restricted Rights—Use, duplication or disclosure restrictedby GSA ADP Schedule Contract with IBM Corporation.

Trademarks

IBM, the IBM logo, Tivoli, the Tivoli logo, AIX, Cross-Site, NetView, OS/2, PlanetTivoli, RS/6000, Tivoli Certified, Tivoli Enterprise, Tivoli Enterprise Console, TivoliReady, and TME are trademarks or registered trademarks of International BusinessMachines Corporation or Tivoli Systems Inc. in the United States, other countries,or both.

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

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

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

Notices

References in this publication to Tivoli Systems or IBM products, programs, orservices do not imply that they will be available in all countries in which TivoliSystems or IBM operates. Any reference to these products, programs, or services isnot intended to imply that only Tivoli Systems or IBM products, programs, orservices can be used. Subject to valid intellectual property or other legallyprotectable right of Tivoli Systems or IBM, any functionally equivalent product,program, or service can be used instead of the referenced product, program, orservice. The evaluation and verification of operation in conjunction with otherproducts, except those expressly designated by Tivoli Systems or IBM, are theresponsibility of the user. Tivoli Systems or IBM may have patents or pendingpatent applications covering subject matter in this document. The furnishing of thisdocument does not give you any license to these patents. You can send licenseinquiries, in writing, to the IBM Director of Licensing, IBM Corporation, NorthCastle Drive, Armonk, New York 10504-1785, U.S.A.

© Copyright International Business Machines Corporation 2001. All rights reserved.US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADPSchedule Contract with IBM Corp.

iiiTivoli Policy Director for WebSphere Application Server User Guide

iv Version 3.8

Contents

Preface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ixWho Should Read This Book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix

What This Book Contains. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix

Publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . x

Tivoli SecureWay Policy Director Library . . . . . . . . . . . . . . . . . . . . . . . x

Prerequisite Publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . x

Accessing Publications Online . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi

Ordering Publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi

Providing Feedback about Publications . . . . . . . . . . . . . . . . . . . . . . . . . xi

Contacting Customer Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xii

Conventions Used in This Book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xii

Typeface Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xii

Chapter 1. Introducing Policy Director for WebSphere 1Introducing Policy Director . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

Integrating Policy Director with WebSphere Application Server . . . . . . . . . . . 3

J2EE Role-Based Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Mapping of Principals and Groups to Roles . . . . . . . . . . . . . . . . . . . . . . . . . . 6

Centralizing Policy Management for Multiple WebSphere Servers . . . . . . . . 11

Chapter 2. Installing Policy Director for WebSphere 15Software Contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Supported Platforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Installation Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Software Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Prerequisites for Policy Director for WebSphere Application Server . . . 17

Prerequisites for the Migration Utility . . . . . . . . . . . . . . . . . . . . . . . . . 19

vTivoli Policy Director for WebSphere Application Server User Guide

Xerces XML Parser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

User Registry Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

Installing Policy Director for WebSphere . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

Configuring Policy Director for WebSphere . . . . . . . . . . . . . . . . . . . . . . . . . 24

Uninstalling Policy Director for WebSphere Application Server . . . . . . . . . . 27

Chapter 3. Migrating Security Roles to Policy Director 29How to Migrate Security Roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

Migration Utility Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Migration Utility Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

Troubleshooting Tips . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

Migration Utility Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

Migration Utility Installation Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

Migration Utility Run Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

Uninstalling the Migration Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

Chapter 4. Administering Policy Director forWebSphere. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

Using Policy Director with Advanced Edition Single Server . . . . . . . . . . . . . 43

Using Policy Director Administration Tools . . . . . . . . . . . . . . . . . . . . . . . . . 44

Specifying Policy Director for WebSphere Properties . . . . . . . . . . . . . . . . . . 45

Limiting Simultaneous Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

Enabling Static Role Caching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

Defining Static Roles. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

Configuring Dynamic Role Caching. . . . . . . . . . . . . . . . . . . . . . . . . . . 46

Specifying Logging Mechanism Type . . . . . . . . . . . . . . . . . . . . . . . . . 47

Specifying Logging Level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

Specifying Root Object Space Name . . . . . . . . . . . . . . . . . . . . . . . . . . 48

Specifying Document Type Definition Directory . . . . . . . . . . . . . . . . . 49

vi Version 3.8

Configuring WebSphere Console to Recognize Policy Director Groups. . . . . 49

Chapter 5. Enabling Security: A Tutorial . . . . . . . . . . . . . . . . 51Tutorial Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

1: Adding Security to a WebSphere Application . . . . . . . . . . . . . . . . . . . . . . 52

2: Add Users to the LDAP User Registry. . . . . . . . . . . . . . . . . . . . . . . . . . . 58

3: Enabling WebSphere Application Server Security . . . . . . . . . . . . . . . . . . . 60

4: Deploying The Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

5: Testing Security For the Deployed Application. . . . . . . . . . . . . . . . . . . . . 64

6: Migrating the Application to Policy Director . . . . . . . . . . . . . . . . . . . . . . 65

7: Enabling the Policy Director Authorization Component . . . . . . . . . . . . . . 66

8: Testing Security for the Deployed Application . . . . . . . . . . . . . . . . . . . . . 67

9: Changing Roles. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68

10: Testing Security for the Deployed Application . . . . . . . . . . . . . . . . . . . . 68

viiTivoli Policy Director for WebSphere Application Server User Guide

viii Version 3.8

Preface

Welcome to Tivoli®

Policy Director for WebSphere ApplicationServer. This product extends Policy Director to support applicationswritten for IBM® WebSphere™ Application Server. This guideprovides installation, configuration, and administration instructions.This document also provides a tutorial on configuring centralizedsecurity policy for WebSphere applications.

Who Should Read This BookThe target audience for this administration guide includes:

¶ Security administrators

¶ System installation and deployment administrators

¶ Network system administrators

¶ IT architects

What This Book ContainsThis document contains the following chapters:

¶ Chapter 1, “Introducing Policy Director for WebSphere”

Presents an overview of the Policy Director components thatprovide authorization services to WebSphere Application Server.

¶ Chapter 2, “Installing Policy Director for WebSphere”

Describes how to install and configure Policy Director forWebSphere Application Server.

¶ Chapter 3, “Migrating Security Roles to Policy Director”

Describes how to use the Policy Director for WebSphereApplication Server migration utility to migrate Java 2 EnterpriseEdition security roles to Policy Director user and groups.

¶ Chapter 4, “Administering Policy Director for WebSphere”

Describes how to perform administration tasks that are used tomanage Policy Director for WebSphere Application Server.

ixTivoli Policy Director for WebSphere Application Server User Guide

¶ Chapter 5, “Enabling Security: A Tutorial”

Describes how to add security to a WebSphere ApplicationServer application. Also describes how to migrate securityinformation to Policy Director and how to test that security hasbeen successfully enabled.

PublicationsThis section lists publications in the Tivoli SecureWay PolicyDirector library and any other related documents. It also describeshow to access Tivoli publications online, how to order Tivolipublications, and how to make comments on Tivoli publications.

Tivoli SecureWay Policy Director LibraryThe following documents are available in the Tivoli SecureWayPolicy Director library:

¶ Tivoli SecureWay Policy Director Base Installation Guide,GC32-0735

¶ Tivoli SecureWay Policy Director Base Administration Guide,GC32-0680

¶ Tivoli SecureWay Policy Director Web Portal ManagerAdministration Guide, GC32-0737

¶ Tivoli SecureWay Policy Director Administration API DeveloperReference, GC32-0813

Prerequisite PublicationsTo be able to use the information in this book effectively, you musthave some prerequisite knowledge, which you can get from thefollowing books:



¶ Getting Started with WebSphere Application Server Version 4.0,SC09-4581

What This Book Contains

x Version 3.8

¶ Building Business Solutions with WebSphere Version 4.0,SC09-4432

Accessing Publications OnlineYou can access many Tivoli publications online at the TivoliCustomer Support Web site:

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

These publications are available in PDF or HTML format, or both.Translated documents are also available for some products.

Ordering PublicationsYou can order many Tivoli publications online at the following Website:

http://www.ibm.com/shop/publications/order

You can also order by telephone by calling one of these numbers:

¶ In the United States: 800-879-2755

¶ In Canada: 800-426-4968

¶ In other countries, for a list of telephone numbers, see thefollowing Web site:

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

Providing Feedback about PublicationsWe are very interested in hearing about your experience with Tivoliproducts and documentation, and we welcome your suggestions forimprovements. If you have comments or suggestions about ourproducts and documentation, contact us in one of the followingways:

¶ Send an e-mail to [email protected].

¶ Complete our customer feedback survey at the following Website:

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

Publications

xiTivoli Policy Director for WebSphere Application Server User Guide

Contacting Customer SupportIf you have a problem with any Tivoli product, you can contactTivoli Customer Support. See the Tivoli Customer Support Handbookat the following Web site:

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

The handbook provides information about how to contact TivoliCustomer Support, depending on the severity of your problem, andthe following information:

¶ Registration and eligibility

¶ Telephone numbers and e-mail addresses, depending on thecountry you are in

¶ What information you should gather before contacting support

Conventions Used in This BookThis book uses several conventions for special terms and actions,operating system-dependent commands and paths, and margingraphics.

Typeface ConventionsThe following typeface conventions are used in this book:

Bold Lowercase and mixed-case commands, commandoptions, and flags that appear within text appear likethis, in bold type.

Graphical user interface elements (except for titles ofwindows and dialogs) and names of keys also appearlike this, in bold type.

Italic Variables, values you must provide, new terms, andwords and phrases that are emphasized appear likethis, in italic type.

Monospace Commands, command options, and flags that appearon a separate line, code examples, output, andmessage text appear like this, in monospace type.

Contacting Customer Support

xii Version 3.8

Names of files and directories, text strings you musttype, when they appear within text, names of Javamethods and classes, and HTML and XML tags alsoappear like this, in monospace type.

Conventions Used in This Book

xiiiTivoli Policy Director for WebSphere Application Server User Guide

Conventions Used in This Book

xiv Version 3.8

Introducing Policy Director forWebSphere

Tivoli Policy Director for WebSphere Application Server is anextension of Policy Director Version 3.8 that providescontainer-based authorization and centralized policy management forIBM WebSphere Application Server applications.

Policy Director for WebSphere Application Server integrates withWebSphere Application Server Version 4.0.2 and makes authorizationdecisions on incoming requests for access to protected resources.

By deploying Policy Director for WebSphere Application Server, anetwork administrator can use Policy Director to provide centralizedmanagement of security policy both for WebSphere ApplicationServer resources and for resources that are unrelated to WebSphereApplication Server.

Policy Director features include management of common identities,user profiles, and authorization mechanisms. Policy Director providesa graphical user interface utility, the Policy Director Web PortalManager, that can be used as a single point of security managementfor both Java 2 Enterprise Edition (J2EE) compliant andnon-J2EE-compliant resources.

WebSphere Application Server, Advanced Edition 4.0.2, supports theJ2EE security classes and APIs. Policy Director for WebSphereApplication Server supports WebSphere applications that use the

1

1Tivoli Policy Director for WebSphere Application Server User Guide

1.In

trod

ucin

gP

olicy

Directo

rfo

rW

ebS

ph

ere

J2EE security classes. Policy Director provides this support withoutrequiring any coding or deployment changes to the applications.

Introducing Policy DirectorPolicy Director for WebSphere Application Server integrates withWebSphere containers and enables them to use the security servicesprovided by a Policy Director secure domain. The Policy Directorsecure domain must be deployed prior to installation of PolicyDirector for WebSphere Application Server.

Users who are new to Policy Director should review the PolicyDirector security model before deploying a Policy Director securedomain.

Policy Director is a complete authorization and network securitypolicy management solution that provides end-to-end protection ofresources over geographically dispersed intranets and extranets.

Policy Director features state-of-the-art security policy management.In addition, Policy Director supports authentication, authorization,data security, and resource management capabilities. You use PolicyDirector in conjunction with standard Internet-based applications tobuild highly secure and well-managed intranets and extranets.

At its core, Policy Director provides:

¶ An authentication framework

Policy Director supports a wide range of authenticationmechanisms. Note, however, that WebSphere performs its ownauthentication steps before using Policy Director for WebSphereApplication Server.

¶ An authorization framework

The Policy Authorization Service, accessed through standardJava 2 Enterprise Edition authorization classes, provides permitand deny decisions on access requests for native Policy Directorservers and third-party applications.

You can learn more about Policy Director, including informationnecessary to make deployment decisions, by reviewing the

2 Version 3.8

documentation distributed with Tivoli SecureWay Policy DirectorVersion 3.8. Start with the following guides:


This guide describes how to plan, install, and configure a PolicyDirector secure domain. A series of easy installation scriptsenable you to quickly deploy a fully functional secure domain.These scripts are very useful when prototyping the deploymentof a secure domain.


This document presents an overview of the Policy Directorsecurity model for managing protected resources. This guidedescribes how to configure the Policy Director servers that makeaccess control decisions. In addition, detailed instructionsdescribe how to perform important tasks such as declaringsecurity policies, defining protected object namespaces, andadministering user and group profiles.

The Policy Director documentation is included on the TivoliSecureWay Policy Director Base Version 3.8 CD-ROM, and is alsoavailable from the Tivoli Customer Support web site. For moreinformation, see “Accessing Publications Online” on page xi.

Integrating Policy Director with WebSphereApplication Server

Policy Director for WebSphere Advanced Server integrates withWebSphere Application Server Advanced Edition Version 4.0.2.

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 anapplication (declarative security), a WebSphere containerdetermines if the current principal identity has been granted anyof the required roles.

Introducing Policy Director


1.In

trod

ucin

gP

olicy

Directo

rfo

rW

ebS

ph

ere

¶ When application developer has added security code directly intothe application (programmatic security), a WebSphere containeruses Policy Director to perform the necessary role membershipchecks.

Figure 1 illustrates the following sequence of events:

1. When a WebSphere application with J2EE security is run, andthe user tries to access a protected resource, WebSphereApplication Server authenticates the user. For WebSphereAdvanced Edition (multiple server version), the authentication isagainst an IBM SecureWay Directory Version 3.2.1 LDAP userregistry. The LDAP user registry is shared with Policy Director.For WebSphere Advanced Edition Single Server (AEs), theauthentication is against host-based security.

WebSphere

User

Authentication

WebSphere container

integrated with

Policy Director

J2EE Application Deployment Descriptor

WebSphere Application Server

Advanced Edition 4.0.2

IBM SecureWay

LDAP Server

Policy Director

Authorization Server

Policy Director

Policy Database

Policy Director

Management Server

Policy Director

Policy DatabasePolicy

Database

Replication

Solid arrows

indicate

usage of

a module

by another

module

Figure 1. Policy Director integrates with WebSphere Application Server

Integrating Policy Director with WebSphere Application Server

4 Version 3.8

2. When the user requests access to a protected method or resource,the WebSphere container uses information from the J2EEapplication deployment descriptor to determine the required rolemembership.

3. The WebSphere container uses the integrated Policy Directormodule to request an authorization decision (“granted” or“denied”) from the Policy Director authorization server.

The WebSphere container also passes additional contextinformation, when present, to the authorization server. Theoptional context information can include cell name, host name,and server name. If the Policy Director policy database haspolicy specified for any of the context information, theAuthorization Server can use this information when making theauthorization decision.

4. The authorization server consults the Policy Director userdefinitions in the IBM SecureWay Directory 3.2.1 LDAP userregistry. (The LDAP user registry is shared with WebSphere,unless WebSphere AEs is used). The authorization server thenconsults the permissions that have been defined for the specifieduser within the Policy Director protected object namespace. Theprotected object namespace is included in the policy databaseshown in Figure 1.

5. The Policy Director authorization server returns the accessdecision to the WebSphere container.

6. WebSphere Application Server either grants or denies access tothe protected method or resource.

J2EE Role-Based SecurityJ2EE security uses the concept of a principal to represent theidentity of an entity that performs activities. Entities can be people(users) or processes. In addition, J2EE uses the concept of a role asdescribed below.

Methods are mapped to roles. The following table from a samplebanking application defines roles and maps methods to them. Theentry granted in the table below indicates that the role can access

Integrating Policy Director with WebSphere Application Server


1.In

trod

ucin

gP

olicy

Directo

rfo

rW

ebS

ph

ere

the specified method.

Roles Methods

getBalance deposit closeAccount

Teller granted granted

Cashier granted

Super granted

The roles that have been defined above can then be mapped toprincipals and/or groups. The entry Invoke in the table cells belowindicates that the principal/group can invoke any methods that havebeen granted to that role.

Principal/Group Roles

Teller Cashier Supervisor

TellerGroup Invoke

CashierGroup Invoke

SupervisorGroup

Frank (a principal) Invoke Invoke

In the table above, the principal Frank can invoke the getBalanceand closeAccount methods but cannot invoke the deposit method,because this method has not been granted to either the Cashier orSupervisor role.

Mapping of Principals and Groups to RolesPrior to application runtime, the Policy Director migration utility isrun to populate the Policy Director protected object namespace. Themigration utility obtains information about roles and methods fromthe J2EE application deployment descriptors.

At application runtime, when a user requests access to a protectedresource, the WebSphere container is passed the followinginformation:

¶ Principal

The authenticated identity of the user.

J2EE Role-Based Security

6 Version 3.8

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

¶ ServerName

The name of a server that is hosted by HostName.

The role names are derived from the method-to-role mappings in thedeployment descriptors. By default, Policy Director’s access check isperformed based on the RoleName and AppName. The accesscheck can easily be extended to take into account CellName,HostName and ServerName. These values are optional, and areevaluated only when they are defined.

Policy Director access control lists (ACLs) determine which J2EEapplication roles a principal has been assigned. The migration utilityattaches ACLs to the <AppName> in the protected object namespace.

Mapping of Principals and Groups to Roles


1.In

trod

ucin

gP

olicy

Directo

rfo

rW

ebS

ph

ere

Figure 2 illustrates the following sequence of events:

1. Before application runtime, the Policy Director migration utilityaccesses the J2EE application deployment descriptor to extractinformation on roles and role-to-principal/group mapping.

Figure 2. Mapping of roles to the Policy Director protected object space.


8 Version 3.8

2. The migration utility converts the information into the PolicyDirector format, and passes it to the Policy Director managementserver.

3. The Policy Director management server adds entries to theprotected object namespace to represent the roles defined for theapplication. When role-to-principal/group mappings have beendefined in the deployment descriptor, the appropriateprincipals/groups are added to the ACLs that are attached to thenew objects.

The Policy Director security model uses the definitions stored in theprotected object namespace to build a hierarchy of resources towhich ACLs can be attached. These ACLs define the mapping ofroles to users/groups.

Figure 3 below illustrates how ACLs can be applied to the protectedobject namespace that describes a role. The protected objectnamespace for all WebSphere applications consists of a top-levelPolicy Director protected object called WebAppServer. TheWebAppServer object has a child object called deployedResources.Together, these two object names serve as a top-level prefix to allJ2EE roles defined in WebSphere applications.

Roles are defined in the next level in the hierarchy, as a resourcenamed for the role: <RoleName>. Directly under this object is theresource representing the application: <AppName>. Underneath the<AppName> protected object are several optional resources that canbe defined to more precisely control access to roles. The optionalresources are <CellName>, <HostName>, and <ServerName>.



1.In

trod

ucin

gP

olicy

Directo

rfo

rW

ebS

ph

ere

In Figure 3 above, ACL 1 grants user1 access to the specified<RoleName>, in any application anywhere in the network. User2and group1 are denied access.

In the Policy Director security model, these access settings areinherited by the objects defined underneath <RoleName> in theprotected object space hierarchy. This inheritance occurs by default.Thus, in Figure3, the access settings are inherited by the objectsrepresenting<AppName>/<HostName>/<CellName>/<ServerName>.

Sometimes security policy requires that the access settings forobjects located underneath the ACL attachment point must differfrom the inherited access settings. In this case, the Policy Directoradministrator defines a new ACL containing the required accesssettings. The administrator then attaches the new ACL to the objectat the specified point of control. This new ACL overrides theinherited access settings.

For example, security policy might dictate that user1 should not begranted <RoleName> permission when the application is run on aspecific server on a specific host within a specific cell. To enforce

/

"WebAppServer"

"deployedResources"

<RoleName>

<AppName>

<CellName>

<HostName>

<ServerName>

Policy Director Protected Object Namespace

ACL 1

user1

user2

grp1

i

---

---

ACL 2

user1

user2

grp1

---

---

---

Figure 3. Attaching Policy Director ACLs to objects in the protected objectnamespace.


10 Version 3.8

this policy, the administrator defines a more restrictive ACL, asrepresented in Figure 3 by ACL 2. This ACL denies access to user1,user2, and grp1. The administrator then attaches this ACL to the<ServerName> object that represents the server to which accessmust be restricted.

Figure 3 shows the attachment of ACL 2 to <ServerName>. Notethat ACL 2 applies only to the specified server. When more than one<ServerName> object is defined underneath <HostName>, ACL 2applies only to the <ServerName> object to which it is attached. Allother <ServerName> objects at this level in the hierarchy continueto inherit the access settings defined in ACL 1 and attached to<RoleName>.

For more information on the use of ACLs in the Policy Directorprotected object namespace, see the Tivoli SecureWay PolicyDirector Base Administration Guide.

Centralizing Policy Management for MultipleWebSphere Servers

Policy Director provides centralized management of security policies.Policy Director can manage security policy across multipleWebSphere Application Servers. In addition, Policy Director uses thesame model to manage security across non-WebSphere applications.

After the roles and principal/group mappings described in a J2EEapplication’s deployment descriptors have been migrated to PolicyDirector, and the users and groups have been registered with PolicyDirector, you can use the Policy Director management tools tomanage further changes to the security definitions. Use the PolicyDirector Web Portal Manager to manage changes in securitydefinitions related to the mapping of roles to principals/groups. Usethe WebSphere console to make other security-related changes. Notethat changes to role mappings made through the WebSphere consolewill not be visible to the Policy Director security model.

Use the following Policy Director tools to manage security policy:

¶ Policy Director Web Portal Manager



1.In

trod

ucin

gP

olicy

Directo

rfo

rW

ebS

ph

ere

The Web Portal Manager is the Policy Director managementconsole. This console provides a graphical user interface formanaging the Policy Director users, actions, and resources thatare defined in the Policy Director protected object namespace.The console can be used for creating and managing ACLs. Theconsole can also be used to manage user and group definitionsin the LDAP user registry.

For more information, see the Tivoli SecureWay Policy DirectorWeb Portal Manager Administration Guide.

¶ pdadmin

The pdadmin utility is a command-line based utility formanaging the Policy Director security model. This powerfulutility can be used to manage all aspects of the Policy Directorprotected object namespace, including users, objects, resources,and ACLs. Also, pdadmin can manage user and group entries inLDAP user registries. Administrators can use this utility withinscripts or programs to automate administration tasks.

For more information, see the Tivoli SecureWay Policy DirectorBase Administration Guide.

¶ Policy Director Administration API

Policy Director provides a programmatic interface to theadministration tasks accomplished by pdadmin and the WebPortal Manager. Application developers can use this API toperform administration tasks that are specific to the application.

For more information, see the Tivoli SecureWay Policy DirectorAdministration API Developer Reference.

Centralizing Policy Management for Multiple WebSphere Servers

12 Version 3.8

Figure 4 above illustrates Policy Director’s management of securityacross multiple WebSphere servers. The Policy Director Web PortalManager has been installed with WebSphere Application Server 4.0.2on Machine A. The pdadmin utility is shown on a non-WebSpheresystem, Machine B.

Both the Web Portal Manager and pdadmin use the Policy Directormanagement server on Machine D to administer security policy.

The Policy Director authorization server can be installed on aseparate system from WebSphere 4.0.2. In Figure 4, Machine E hosts

WebSphere Advanced

Edition 4.0.2

Policy Director

for WebSphere

IBM SecureWay

Directory LDAP

Server

Policy

Administration

Machine C Machine D

Machine F

Policy Director

Authorization Server

Policy Director

Policy

Database

Machine E

Policy Director

Management Server

Policy Director

Policy

Database

Policy Director

Authorization

Server

Policy Director

Policy

Database

WebSphere

Advanced Edition

4.0.2

WebSphere Advanced

Edition 4.0.2

Machine A

Policy Director

Web Portal

Manager

Machine G

Machine B

Policy

Director

pdadmin

utility

Policy Database

replication

Solid arrows

indicate

usage of

a module

by another

module

Policy Director

for WebSphere

Figure 4. Policy Director provides centralized administration for multiple WebSphereApplication Servers



1.In

trod

ucin

gP

olicy

Directo

rfo

rW

ebS

ph

ere

WebSphere Application Server. This server has a Policy Director forWebSphere module that has been integrated into the WebSpherecontainer responsible for authorization decisions. The WebSpherecontainer obtains authorization decisions from the Policy Directorauthorization server on Machine F.

The Policy Director authorization server can also be installed on thesame system as the WebSphere Application Server, as shown onMachine G. The Policy Director functionality is identical to thatprovided when the servers are on separate systems (as shown onMachine E and Machine F). Co-location of the Policy Directorauthorization server with the WebSphere Application Serveroptimizes performance when making authorization decisions. Thisconfiguration is recommended.

Note that the Policy Director policy database is replicated fromMachine D to both Machine F and Machine G. This replicationincreases performance and provides failover capability.

Figure 4 also shows that the Policy Director servers and theWebSphere servers share the LDAP user registry on Machine C.Note that hat this must be an IBM SecureWay Director Version 3.2.1LDAP server. Figure 4 assumes that WebSphere Advanced Edition(multiserver) is being used. The LDAP user registry is not sharedwhen using WebSphere Advanced Edition Single Server.


14 Version 3.8

Installing Policy Director forWebSphere

This chapter contains the following topics:

¶ “Software Contents”

¶ “Supported Platforms” on page 16

¶ “Installation Packages” on page 16

¶ “Software Prerequisites” on page 16

¶ “Installing Policy Director for WebSphere” on page 23

¶ “Configuring Policy Director for WebSphere” on page 24

Software ContentsPolicy Director for WebSphere Application Server provides acomponent that integrates with WebSphere Application Server, andtakes responsibility for all mappings of roles to principals/groups.

Policy Director for WebSphere Application Server also provides amigration utility that can be used to import role-to-principal/groupmappings from a Java 2 Enterprise Edition (J2EE) deploymentdescriptor into a Policy Director security schema. This utility canmigrate data from either compressed or expanded WebSphere 4.0Enterprise Archive (EAR) files.

2


2.In

stalling

Po

licyD

irector

for

Web

Sp

here

The Policy Director for WebSphere Application Server distributioncontains one installation package for each supported platform. Thispackage includes the following software:

¶ Policy Director for WebSphere Application Server Java classes

¶ An installation script and a configuration script for the Javaclasses

¶ The migration utility

¶ An installation script for the migration utility

¶ Sample tutorial code that demonstrates the use of the migrationutility and the Java classes

Supported PlatformsPolicy Director for WebSphere Application Server is supported onthe following platforms:

¶ AIX 4.3.3

¶ Redhat Linux 7.1

¶ Solaris 2.7 and 2.8

¶ Windows 2000 Advanced Server, Service Pack 2

Installation PackagesInstallation packages are available as a software download from thefollowing URL:http://www.tivoli.com/secure/support/downloads/secureway/policy_dir/downloads.html

A valid login and password is required to access the Tivoli CustomerSupport software download site.

Software PrerequisitesPolicy Director for WebSphere Application Server has prerequisiteson the software described in the following sections:

Software Contents

16 Version 3.8

¶ “Prerequisites for Policy Director for WebSphere ApplicationServer”

¶ “Prerequisites for the Migration Utility” on page 19

Prerequisites for Policy Director for WebSphereApplication Server

The following sections discuss the prerequisites for the integration ofPolicy Director for WebSphere Application Server with a WebSphereApplication Server environment.

¶ “WebSphere Application Server”

¶ “Policy Director Management Server and Authorization Server”on page 18

WebSphere Application ServerThe Policy Director for WebSphere Application Server componentrequires one of the following WebSphere Application Serverproducts to be installed on the host system:

¶ IBM WebSphere Application Server, Advanced Edition Version4.0, PTF 2 (4.0.2)

OR

¶ IBM WebSphere Application Server 4.0, Advanced EditionSingle Server (AEs), Version 4.0, PTF 2 (4.0.2).

Note: The Single Server edition requires specific configurationsteps. See “Using Policy Director with Advanced EditionSingle Server” on page 43.

Before you can install Policy Director for WebSphere ApplicationServer you must install IBM WebSphere Application Server Version4.0 PTF 2 (4.0.2).

The WebSphere Application Server, Advanced Edition, must beconfigured to use an IBM SecureWay Directory Version 3.2.1 LDAPserver. The LDAP server will be shared with Policy Director, and theusers and groups must be imported into Policy Director.

Software Prerequisites


2.In

stalling

Po

licyD

irector

for

Web

Sp

here

Note: This LDAP requirement does not apply to WebSphereApplication Server, Advanced Edition Single Server. TheSingle Server edition uses host-based security.

Documentation on installation of the IBM WebSphere ApplicationServer Version 4.0 is available at the following URL:http://www-4.ibm.com/software/webservers/appserv/doc/v40/ae/infocenter/was/nav_pdf.html

If you are new to IBM WebSphere Application Server, consult theGetting Started with IBM WebSphere Application Server Version 4.0guide. This guide is available at the URL above.

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

Policy Director Management Server and AuthorizationServer

The Policy Director for WebSphere Application Server does notrequire any additional Policy Director components on the localcomputer that hosts the WebSphere Application Server. While youare not required to add any additional Policy Director components,you can optimize performance by installing the Policy Directorauthorization server on the same host as the WebSphere ApplicationServer. The authorization server has a prerequisite on the PolicyDirector runtime environment. Both of these components aredistributed as part of the Tivoli SecureWay Policy Director Baseproduct.

Policy Director for WebSphere Application Server must be able toaccess a Policy Director secure domain. The authorizationcomponent must be able to contact a Policy Director managementserver and a Policy Director authorization server. Thus, after youhave installed the IBM WebSphere Application Server, you mustestablish a Policy Director secure domain before installing PolicyDirector for WebSphere Application Server.

To establish a Policy Director secure domain, you must install andconfigure the Policy Director management server. Typically this isnot run on the same host as the WebSphere Application Server. You


18 Version 3.8

will also need to install and configure a Policy Director authorizationserver, either on the WebSphere Application Server host, or on adifferent system.

For more information on installing and configuring a Policy Directorsecure domain, see the Tivoli SecureWay Policy Director BaseInstallation Guide. This guide is distributed on the Tivoli SecureWayPolicy Director Base Version 3.8 CD-ROM. It is also availableonline. See “Accessing Publications Online” on page xi.

Policy Director Fixpack 3 for Version 3.8Each Policy Director management server or authorization serversystem must be updated with Fixpack 3 for Version 3.8. You mustobtain and install the Fixpack for your operating system.

The fixpack is titled FixPack 3.8-POL-0003.

Download and install the Policy Director Fixpack 3 from thefollowing URL:https://www.tivoli.com/secure/support/patches/Tivoli_SecureWay_Policy_Director_.html

You will need a login and password from Tivoli Customer Supportto access this web page.

Prerequisites for the Migration UtilityThe software prerequisites for the migration utility are described inthe following sections:

¶ “Policy Director Version 3.8 Runtime Environment”

¶ “Policy Director Fixpack 3 for Version 3.8”

¶ “Java Runtime Environment” on page 21

Policy Director Version 3.8 Runtime EnvironmentThe Policy Director for WebSphere Application Server migrationutility installs and runs in a Policy Director secure domain. You mustestablish a Policy Director secure domain before installing the PolicyDirector for WebSphere Application Server migration utility.



2.In

stalling

Po

licyD

irector

for

Web

Sp

here

The Policy Director for WebSphere Application Server migrationutility requires the Policy Director Version 3.8 runtime environmentcomponent to be installed and configured on the same system as themigration utility.

The runtime environment in turn requires that a Policy Directorsecure domain is already established. The Policy Director securedomain is established when you install the Tivoli SecureWay PolicyDirector management server. This management server is distributedon the Tivoli SecureWay Policy Director Base CD-ROM for youroperating system.

The following software must be installed and configured either onthe same system that hosts the Policy Director for WebSphereApplication Server migration utility or on a remote system:

¶ Tivoli SecureWay Policy Director Management Server, Version3.8

¶ IBM SecureWay Directory Version 3.2.1 LDAP server.

Thus, within the Policy Director secure domain there are twodeployment scenarios for the Policy Director for WebSphereApplication Server migration utility:

1. On the same system as the Tivoli SecureWay Policy DirectorManagement Server

2. On a different system from the Tivoli SecureWay Policy DirectorManagement Server

In the first scenario, all of the other Policy Director prerequisites forthe migration utility are satisfied during the installation andconfiguration of the management server. When you deploy themigration utility into this configuration, you can simply install thePolicy Director for WebSphere Application Server migration utilitywithout installing any further Policy Director Base packages.

Note: Policy Director Fixpack 3 for Version 3.8 is required in thisscenario. See “Policy Director Fixpack 3 for Version 3.8” onpage 19.

In the second scenario, you must first configure the computer into anexisting Policy Director secure domain, and then install the Policy


20 Version 3.8

Director for WebSphere Application Server migration utility. Toconfigure the computer into the Policy Director secure domain, youmust install and configure the following software:

¶ Tivoli SecureWay Policy Director Runtime Environment, Version3.8

¶ Policy Director Fixpack 3 for Version 3.8

After you have configured the above prerequisites, you can installand configure the migration utility.

Java Runtime EnvironmentThe computer system that hosts the migration utility must have thefollowing Java Runtime Environment (JRE) software installed:

Operating System Java Runtime Environment

AIX IBM JRE Version 1.3

Linux

Windows

Solaris Sun JRE Version 1.2.2Note: This is used only for the PolicyDirector migration utility. WebSpheredoes not use this version.

Xerces XML ParserThe Policy Director for WebSphere Application Server migrationutility requires access to the Xerces 1.4.2 parser. This parser isdistributed as the file Xerces.jar, and is included in the WebSphereApplication Server Version 4.0.2 product. You will need to eithercopy this file to the migration utility directory or update themigration run script to include its location.

User Registry PrerequisitesThe user registry prerequisites are based on the version ofWebSphere Application Server that is used with Policy Director forWebSphere Application Server.



2.In

stalling

Po

licyD

irector

for

Web

Sp

here

¶ WebSphere Application Server, Advanced Edition, Version 4.0PTF 2 (4.0.2)

There are two prerequisites for use of LDAP user registries thatmust be satisfied before installing Policy Director for WebSphereApplication Server:

1. The Policy Director management server and the WebSphereApplication Server must be configured to use the same IBMSecureWay Directory Version 3.2.1 LDAP user registry.

Policy Director for WebSphere Application Servers operatesas part of a Policy Director secure domain. The PolicyDirector management server for the secure domain uses anLDAP user registry to manage user and group information.

2. Any existing users and groups defined for WebSphereApplication Server must be “imported” into the PolicyDirector LDAP schema, to become Policy Director users andgroups. “Importing” here means adding extended PolicyDirector attributes, along with the existing user and groupdefinitions, into the Policy Director security schema.

Users can be imported into the Policy Director LDAPschema either manually or by using the IBM SecureWayDirectory LDAP bulk load feature.

For more information on using the pdadmin command toimport users manually, see the Tivoli SecureWay PolicyDirector Base Administration Guide.

For more information on the bulk loading of users, see theTivoli SecureWay Policy Director Performance and TuningGuide.

¶ WebSphere Application Server, Advanced Edition Single Server(AEs), Version 4.0

WebSphere AEs does not use an LDAP user registry. Instead, itworks with host-based security. Each user account on the hostsystem must have an equivalent entry in the LDAP user registryused by Policy Director.

Note that any changes made over time to the host-based securitymust also be made to the LDAP user registry used by PolicyDirector.

User Registry Prerequisites

22 Version 3.8

Installing Policy Director for WebSphereThis section describes how to install Policy Director for WebSphereApplication Server, including both the authorization component andthe migration utility.

1. Log in a user with administrator privileges. On UNIX system,log in as root.

2. Download the Policy Director for WebSphere Application Serverfiles as described in “Installation Packages” on page 16.

3. Unpack the distribution files into a temporary directory.

¶ The UNIX distributions are contained in a tar file.

¶ The Windows distribution is contained in a ZIP file.

4. Verify that you have satisfied the prerequisites for installingPolicy Director for WebSphere Application Server. Theprerequisites include the following:

¶ Installation of IBM WebSphere Application Server.

¶ Establishment of a Tivoli Policy Director Version 3.8 securedomain.

Note that this step requires the installation of a PolicyDirector authorization server. For optimal performance, it isrecommended that you install the authorization server on thesystem that hosts WebSphere Application Server.

For more information on the installation and configuration ofthe authorization server and its prerequisites, see the TivoliSecureWay Policy Director Base Installation Guide.

To review software dependencies, see “Software Prerequisites” onpage 16.

5. Verify that the Policy Director Version 3.8 management serverand the WebSphere Application server are configured to use thesame LDAP user registry.

Note: This step does not apply to WebSphere AEs.

Installing Policy Director for WebSphere


2.In

stalling

Po

licyD

irector

for

Web

Sp

here

6. Verify that WebSphere Application Server users and groups havebeen imported from the LDAP user registry into the PolicyDirector LDAP user registry schema.

You can use the Policy Director pdadmin command to manuallyimport users. The syntax is:pdadmin> user import <UserID><Distinguished Name of the user in LDAP>


For large numbers of users, consider using the LDAP bulkimport feature. For more information see the Tivoli SecureWayPolicy Director Performance Tuning Guide

7. Configure the Policy Director for WebSphere Application Serverauthorization component.

Note that the authorization component must be installed on eachWebSphere Application Server that hosts secured applications.The migration utility does not need to be installed on everysystem that hosts WebSphere Application Server. It needs to beinstalled only on a Policy Director system that has access to eachEAR file that needs to be migrated.

Go to “Configuring Policy Director for WebSphere”.

Note: If you have already installed and configured Policy Directorfor WebSphere Application Server and need to reinstall it,you must first uninstall it.

Configuring Policy Director for WebSphereTo configure the Policy Director for WebSphere Application Serverauthorization component, complete the following steps:

1. Run the installation script for the Policy Director for WebSphereApplication Server libraries.

The installation script is located in the following subdirectoriesunder the temporary directory where you unpacked thedistribution files.UNIX: ../websphere/install_PDPerm.shWindows: ..\websphere\install_PDPerm.bat

Installing Policy Director for WebSphere

24 Version 3.8

The installation script simply copies the libraries to theWebSphere lib directory and copies a configuration script to theWebSphere home directory.

Note that the location of the WebSphere home directory isdetermined from the WAS_HOME environment variable. On UNIXsystems, $WAS_HOME is typically /opt/WebSphere/AppServer.

Here is a complete sample UNIX installation script:@echo offcp bin/* $WAS_HOME/bincp lib/* $WAS_HOME/lib

2. Create a Policy Director user identity for the Policy Director forWebSphere Application Server component. Use either pdadminor the Policy Director Web Portal Manager to create the newuser.

The tutorial chapter of this guide contains a pdadmin commandline for creating a Policy Director user identity for PolicyDirector for WebSphere Application Server. Refer to the step thatcreates the user pdwasadmin in the section entitled “2: AddUsers to the LDAP User Registry” on page 58.

Note that you must create a separate Policy Director user foreach different host system on which Policy Director forWebSphere Application Server operates.

Note also that the user should be a user other than the configuredWebSphere administrative user.

3. Add the new user to the remote-acl-users group.

Membership in this group is required in order to use SecureSocket Layer (SSL) to send requests to the Policy Directormanagement server.

4. Assemble the following information:

¶ The name of the user account you just created.

¶ The password for the user account.

¶ The fully qualified domain name for the computer that hoststhe Policy Director management server.

Configuring Policy Director for WebSphere


2.In

stalling

Po

licyD

irector

for

Web

Sp

here

¶ The fully qualified domain name for the computer that hoststhe Policy Director authorization server.

An example of the assembled information:[ cn=pdadmin,o=ibm,c=au myPassWordpdmgrserver.mysubnet.ibm.compdacldserver.mysubnet.ibm.com ]

5. Run the PDPerm configuration script.

The PDPerm configuration script is located in the binsubdirectory under the WebSphere home directory:UNIX: $WAS_HOME/bin/configure_PDPerm.shWindows: %WAS_HOME%\bin\configure_PDPerm.bat

This script sets the CLASSPATH variable, and calls the Javaclass com.tivoli.mts.SvrSslCfg to configure the SSLcommunication between the authorization component and boththe Policy Director management server and the Policy Directorauthorization server.

The script takes as input parameters the values you assembled inthe previous step.

Following is a sample configuration script for UNIX. Note thatthe command to set CLASSPATH is one continuous command:echo $#if [ "$#” -ne 4 ]; thenecho “USAGE: $0 <PDAdmin user> <Password><PDMgrd Hostname> <PDACLd Hostname>”elseexport CLASSPATH=$WAS_HOME/java/lib/src.zip:$WAS_HOME/lib/PDPerm.jar:$WAS_HOME/lib/ibmjcefw.jar:$WAS_HOME/lib/ibmjceprovider.jar:$WAS_HOME/lib/US_export_policy.jar:$WAS_HOME/lib/ibmjsse.jar:$WAS_HOME/lib/ibmpkcs.jar:$WAS_HOME/lib/jaas.jar:$WAS_HOME/lib/local_policy.jar$WAS_HOME/java/bin/java -classpath $CLASSPATHcom.tivoli.mts.SvrSslCfg $1 $2 $3 $4fi

Following is an example invocation of the configuration script.The command is issued one command line:


26 Version 3.8

configure_PDPerm “cn=pdadmin,o=ibm,c=au” myPassWordpdmgrserver.mysubnet.ibm.com pdacldserver.mysubnet.ibm.com

6. If this is the first time you are configuring Policy Director forWebSphere Application Server, and you have not previously runthe migration utility, run it now. Go to Chapter 3, “MigratingSecurity Roles to Policy Director” on page 29.

Note: You must run the migration utility before continuing pastthis step. If you do not run the migration utility at thistime, the changes you will make in the next step willprevent the WebSphere server from starting.

7. Edit the following WebSphere property files:

¶ sas.server.prop

¶ sas.server.prop.future

The file locations are:UNIX:

$WAS_HOME/properties/sas.server.prop$WAS_HOME/properties/sas.server.prop.future

Windows:%WAS_HOME%\properties\sas.server.prop%WAS_HOME%\properties\sas.server.prop.future

Note: When sas.server.prop.future is zero length, you donot need to edit it. You must modify it only when it alreadyexists.

Insert the following line, as one continuous line:com.ibm.websphere.security.authorizationTable=com.tivoli.pdas.websphere.PDWASAuthzManager

8. Stop and restart WebSphere Application Server.

Uninstalling Policy Director for WebSphereApplication Server

Remove Policy Director for WebSphere Application Server bychanging the necessary configuration files and removing theauthorization component.

Complete the following steps:



2.In

stalling

Po

licyD

irector

for

Web

Sp

here

1. Edit the following WebSphere property files:

¶ sas.server.prop

Edit sas.server.prop in the following location:UNIX:

$WAS_HOME/properties/sas.server.propWindows:%WAS_HOME%\properties\sas.server.prop

¶ sas.server.prop.future

When sas.server.prop.future is non-zero is size, edit it in thefollowing location:UNIX:

$WAS_HOME/properties/sas.server.prop.futureWindows:

%WAS_HOME%\properties\sas.server.prop.future

In each of the files, remove the line:com.ibm.websphere.security.authorizationTable=com.tivoli.pdas.websphere.PDWASAuthzManager

2. Stop and restart the WebSphere Application Server.

3. Remove the following files from the WebSphere home directory$WAS_HOME (UNIX) or %WAS_HOME% (Windows):bin/configure_PDPerm.shlib/application_1_2.dtdlib/jaas.jar (See note below)lib/PDPerm.jarlib/PDWASAuthzManager.jar

Note: Do not remove lib/jaas.jar if it is used by WebSphereApplication Server for purposes other than integrationwith Policy Director.

4. When the migration utility is installed on the system, remove italso. See the instructions in “Uninstalling the Migration Utility”on page 40.

5. If you want to remove the supporting Policy Directorcomponents at this time, use the operating system removal utilityto remove the Policy Director authorization server and the PolicyDirector Base runtime environment.

For complete removal instructions, see the Tivoli SecureWayPolicy Director Base Installation Guide.

Uninstalling Policy Director for WebSphere Application Server

28 Version 3.8

Migrating Security Roles toPolicy Director

Policy Director for WebSphere Application Server provides amigration utility that automatically converts security role definitionsto Policy Director protected objects. The role definitions are readfrom the WebSphere application deployment descriptors andmigrated to the Policy Director protected object space. This chapterdescribes how to use the utility.

Topic index:

¶ “How to Migrate Security Roles”

¶ “Migration Utility Prerequisites” on page 31

¶ “Migration Utility Limitations” on page 32

¶ “Troubleshooting Tips” on page 34

¶ “Migration Utility Syntax” on page 36

¶ “Migration Utility Installation Script” on page 38

¶ “Migration Utility Run Script” on page 39

¶ “Uninstalling the Migration Utility” on page 40

How to Migrate Security RolesTo migrate J2EE application security roles to Policy Director,complete the following steps:

3


3.M

igratin

gS

ecurity

Ro

lesto

Po

licyD

irector

1. Verify that you are logged in as root on UNIX systems or as auser with administrative privileges on Windows systems.

2. Verify that you have met the migration utility prerequisites thatapply to this installation. See “Migration Utility Prerequisites”on page 31.

3. Review the migration utility limitations. See “Migration UtilityLimitations” on page 32.

4. Verify that you understand the migration utility syntax. See“Migration Utility Syntax” on page 36.

5. Change directory to the temporary directory where youunpacked the Policy Director for WebSphere Application Serverfiles.

6. Run the migration utility installation script:UNIX: ./migrate/install.shWindows: .\migrate\install.bat

You may choose to edit this script before running it. See“Migration Utility Installation Script” on page 38.

7. Edit the migration utility run script to set the XML_PARSER_PATHvariable to the location of the Xerces XML parser. By default,the script looks in the migration directory.

Note that this parser must be the version that is distributed withIBM WebSphere Application Server, Advanced Edition, Version4.0. If you are using this copy of the parser, set the environmentvariable accordingly. For example:XML_PARSER_PATH=$WAS_HOME/lib/Xerces.jar

8. Edit the migration utility run script to migrate the followingEnterprise Archive file:$WAS_HOME/config/admin.EAR

Note that on Windows platforms, admin.EAR is a directory.

You must edit the run script to supply the name of this EARfile or directory. Follow the instructions in the section entitled“Migration Utility Run Script” on page 39.

How to Migrate Security Roles

30 Version 3.8

9. Run the migration utility run script that you edited in theprevious step.

You must supply the appropriate input parameters. The inputparameters are specified in “Migration Utility Run Script” onpage 39.

10. Repeat the previous two steps for each Enterprise Archive(EAR) file that contains roles definitions that must be migratedto Policy Director.

Note: Be sure to run the migration utility against at least oneapplication EAR file. This step is necessary in order tofinish configuring administrator permissions. Thepermissions are needed to start the WebSphere server.

There is no need to run the migration utility against J2EEapplications that do not have security information in theirdeployment descriptors.

Note: Run the migration utility only once for each unique EARfile. When there are multiple copies of any EAR file,you do not need to run the migration utility for eachcopy.

Migration Utility PrerequisitesThe migration utility has specific prerequisites. Some prerequisitesdo not apply to all installations. Determine if the followingrequirements apply to your installation. Ensure that all applicablerequirements are met.

¶ Installation requirements

The migration utility requires that the Policy Director runtimeenvironment be installed and configured into a Policy Directorsecure domain. Review the installation requirements section:“Prerequisites for the Migration Utility” on page 19.

¶ Deployment descriptors

The migration utility requires access to the deploymentdescriptors for the applications that have been secured. Bydefault, the application assembly tool contains URL references to

How to Migrate Security Roles


3.M

igratin

gS

ecurity

Ro

lesto

Po

licyD

irector

the location of the Document Type Definitions (DTD) standard.Thus, lookups for the deployment descriptor DTDs require aconnection to the internet. If the host computer is not connectedto the internet, use a local copy of the DTD. In this case, updatethe deployment descriptors to point to the local DTD.

¶ Pre-loading the standard C library on Linux

On Linux only, you must preload the correct stdc++ library, dueto conflicts in symbols. Pre-loading this library ensures that thecorrect symbols are used.

Ensure that your Linux run script contains the following code:export LD_PRELOAD=/usr/lib/libstdc++-libc6.1-2.so.3

¶ Using JRE 1.2.2 on Solaris.

On Solaris only, you must use Sun Version 1.2.2 of the JavaRuntime Environment (JRE). All other platforms use IBM JREVersion 1.3.

This limitation is caused by a problem between the version ofthe Sun workshop with which the JRE Version 1.3 is compiledand the version of the workshop with which the IBM GlobalSecurity Toolkit (GSKit) 4.0.3.197 is compiled. The IBM GlobalSecurity Toolkit is a prerequisite for Policy Director.

This limitation will be removed by the next release of PolicyDirector. The next release of Policy Director will use GSKitVersion 5.0, which is fully compatible with JRE 1.3.

Note: JRE Version 1.2.2 is not used by the WebSphereApplication Server. It is used solely by the PolicyDirector migration utility.

Migration Utility LimitationsThe migration utility has the following limitations:

¶ The migration utility is designed only to migrate the roles inEAR files to the Policy Director protected object space. Do notuse the migration utility as a maintenance utility for roles. Aftermigrating an EAR file, use either the Policy Director Web PortalManager or the Policy Director pdadmin utility to manage roles.

Migration Utility Prerequisites

32 Version 3.8

¶ When an EAR file is migrated, the contents of the EAR filereflect the configuration of the application when it was installed.Changes made to the deployment descriptors of an applicationfrom within WebSphere are not made to the EAR file. Alwaysbe sure to check that the EAR file accurately reflects theapplication configuration before migrating the security roles. Forexample, be sure that the application name is correct. Anapplication name can be changed at application deployment, orlater through the WebSphere console. This change will not bereflected in the EAR file. When the EAR file is not modified toreflect the new name, the wrong Policy Director protectedobjects will be created.

¶ After the migration utility has been run once against an EARfile, it is recommended that you do not run it again whenchanges are made to an EAR file. The following problems canoccur when an EAR is created and migrated to the PolicyDirector protected object space, and then is migrated again.

v On the second or subsequent migrations, if an existing rolehas been removed from the EAR, it will not be removed fromthe Policy Director protected object space.

v On the second or subsequent migrations, changes to the EARfile might require the migration utility to instruct PolicyDirector to delete an ACL definition. In some cases, PolicyDirector may prevent this deletion. Note that the migration ofan EAR file to the Policy Director protected object spaceresults in the creation of ACLs that are attached to objects. Ifthe administrator has manually attached the ACL definition toother protected objects, Policy Director prevents removal ofthe ACL. Thus, even if the original object that was created byfirst run of the migration utility no longer exists, the ACLcannot be deleted.

¶ Use pdadmin to modify roles. You can use pdadmin to addadditional roles.

Migration Utility Limitations


3.M

igratin

gS

ecurity

Ro

lesto

Po

licyD

irector

Troubleshooting TipsWhen troubleshooting problems with the migration utility, use thelog files that WebSphere and Policy Director provide:

¶ Use the WebSphere error message log to determine WebSphereserver behavior. The log file name is specific to the WebSphereserver. The default server log file name isdefault_server_stdout.text. Entries in this file can be usefulfor troubleshooting the Policy Director authorization component.For more information, consult the WebSphere Application Server4.0.2 documentation.

¶ Configure logging for the Policy Director authorization server.Difficulties with accessing objects in the protected objectnamespace are logged here. Note that log information generatedby requests from the Policy Director authorization component islogged here. Note also that this log is not the same as theWebsphere logs. For more information, see the Tivoli SecureWayPolicy Director Base Administration Guide.

¶ Activity by the migration utility is logged in the fileJ2EE_Migration.log. This file is located in the directory wherethe migration utility is run. The last log message normallydescribes what the migration utility was attempting to do mostrecently. Therefore, in most cases it will indicate where an errorwas generated.

The following errors can occur during use of the migration utility:

¶ Problem: WebSphere server will not start after the migrationutility has been run against admin.ear.

Explanation: The migration utility is designed to be run againstboth admin.ear and at least one application EAR file. If you tryto start WebSphere before migrating an application EAR file,WebSphere will not start because the administrator permissionsare incomplete.

Solution: To solve the problem, run the migration utility againstan application EAR file. This step ensures that administratorpermissions are fully configured.

Troubleshooting Tips

34 Version 3.8

See “6: Migrating the Application to Policy Director” on page 65for an example of running the migration utility against bothadmin.ear and an application EAR file.

¶ The migration utility does not work on filenames containing atilde (~). This can cause problems when attempting to migrate aWindows short file name.

¶ The Web Portal Manager may be unable to attach an ACL toobjects that contain spaces in the object name.

As a workaround, use pdadmin to attach the ACL.

If possible, before running the migration utility, ensure that thereare no spaces in the definitions listed in the deploymentdescriptors. Verify that the application name does not containspaces.

¶ When the migration utility is run, you may see a WARNINGmessage, indicating that user wsadmin is a member of the grouppdwas-admin. This warning is expected and is displayed forsecurity purposes only. The purpose of this warning is to identifythe user as a current member of the pdwas-admin group, so thatthe administrator can verify the accuracy of the list of userscontained in this important administration group.

¶ Policy Director provides a default SSL timeout value forconnections to the Policy Director management server. Whenthis timeout value is exceeded during execution of the migrationutility, you may see the following messages:The server lost the client’s authentication,probably because of session expiration.

When this message occurs, run the migration utility again usingthe -t <minutes> option. The migration utility uses a default of60 minutes. This value should be no greater than the currentSSL timeout between the authorization API client and themanagement server.

You can determine the SSL timeout value by examining theparameter ssl-v3-timeout, located under the [ssl] stanza inthe Policy Director configuration file ivmgrd.conf. The defaultvalue for ssl-v3-timeout is 7200 seconds (120 minutes). When



3.M

igratin

gS

ecurity

Ro

lesto

Po

licyD

irector

this default value is set, ensure that the SSL timeout set by themigration utility -t flag is at least 60 minutes.


Migration Utility SyntaxThe migration utility is a Java class that is run as a command lineutility. The utility requires a number of input values to be specifiedas command line parameters.

The syntax of the migration utility is as follows:java com.tivoli.pdas.migrate.Migrate -jApplication.EAR -a “Policy Director admin user”-p “admin password” -w “websphere_admin_user”-d “DNSuffix” [ -r “root object space name” ][ -t “SSL timeout” ]

All input parameters except -r and -t are required.

The input parameters are:

¶ -j Application-specific Enterprise Archive (EAR) file

The Java 2 Enterprise Edition application archive file.Optionally, this can also be an EAR directory.

For example, -j test_application.EAR

¶ -a Policy Director administrative user

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

For example, -a sec_master.

This parameter is optional. When the parameter is not specified,the user is prompted to supply the administrative user name atruntime.

¶ -p Password for the administrative user

The password for the administrative user specified in theprevious command line parameter. For example, -p myPassword.

This parameter is optional. When it is not specified, the user isprompted to supply the password for the administrative username at runtime.


36 Version 3.8

¶ -w WebSphere administrative user

This is the username that was configured in the WebSphereApplication Server security LDAP field as the administrator.Access as this user is needed to create or update the PolicyDirector object space.

When the Websphere administrative user does not already existin the Policy Director object space, it is created or imported. Inthis case, a random password is generated for the user and theaccount is set to invalid. Note that this account does not requireauthentication.

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

The ACL that is created is:_WebAppServer_deployedResources_AdminRole_admin

The administrative user is added to group was-admin with thefollowing ACL attributes:

v T -- traverse permission

v i -- invoke permission

v <WebAppServer> -- the action group name. WebAppServer isthe default name.

Note that this action group name (and the matching rootobject space) can be overwritten when the migration utility isrun with the -r option.

¶ -d LDAP Distinguished Name suffix

The Distinguished Name (DN) where the Policy Directoradministrative user and the pdwas-admin group will be added ifrequired.

The DN suffix also specifies where to import the user from ifthe user is not already a Policy Director user.

If it cannot import the user it will create it in that DN.

Note that the group is added if it does not already exist.

¶ -r Root object space and action group name

Migration Utility Syntax


3.M

igratin

gS

ecurity

Ro

lesto

Po

licyD

irector

The root object space name is the name of the root of theprotected object namespace hierarchy that will be created forWebSphere Application Server.

This parameter is optional.

The default value for the root object space is WebAppServer.

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

¶ -t Secure Socket Layer (SSL) timeout

The number of minutes for the SSL timeout. This parameter isused to disconnect and reconnect the SSL context between thePolicy Director authorization server and management serverbefore the default connection times out.

The default is 60 minutes. The minimum is 10 minutes. Themaximum should not exceed the Policy Directorssl-v3-timeout value. The default value for ssl-v3-timeoutis 120 minutes.

This parameter is optional. If you are not familiar withadministration of this value, you can safely use the default value.

Migration Utility Installation ScriptPolicy Director for WebSphere Application Server provides aninstallation script for the migration utility files. The script will belocated in the temporary directory where you unpacked the softwaredownload package:UNIX: ./migrate/install.shWindows: .\migrate\install.bat

This script copies the migration files from the installation directoryinto the migration directory. The default migration directory is:UNIX: /opt/PDWAS/migrationWindows: C:\Program Files\Tivoli\PDWAS\migration\

You are not required to run the installation script. You can choose tocopy the migration files manually to a different location. You canchoose to edit the installation script to specify a different location.

Migration Utility Syntax

38 Version 3.8

If you change the location of the migration files, you must updatethe migration run script with the path to the new location. You mustalso update the PATH environment variable to include the path whereyou place the PDPopulate shared library.

Here is a sample UNIX installation script for the migration utility:export PDWAS_DIR=”/opt/PDWAS/migration”mkdir -p $PDWAS_DIRcp * $PDWAS_DIR/rm -rf $PDWAS_DIR/install.sh

Migration Utility Run ScriptA migration utility run script that is provided with Policy Directorfor WebSphere Application Servers. This script is provided as aguideline for users when running the migration utility. You shouldreview this script and modify it to contain values appropriate foryour installation.

The migration run script is located in the migrate subdirectoryunder the temporary directory where you unpacked the PolicyDirector for WebSphere Application Server files. The following tableshows the name of the script on each of the supported platforms:

Migration Run Script

Operating System Filename

Solaris ./migrate/run_Solaris.sh

AIX ./migrate/run_AIX.sh

Linux ./migrate/run_LINUX_X86.sh

Windows .\migrate\run_WIN32.bat

The migration run script accomplishes the following tasks:

¶ Sets environment variables for the location of the necessary JavaJAR files:

v Xerces XML parser

This must point to the correct version of the parser.

v Java Runtime Environment (JRE) jar file

This must point to the correct version of the JRE.

Migration Utility Installation Script


3.M

igratin

gS

ecurity

Ro

lesto

Po

licyD

irector

v JRE directory

v Policy Director for WebSphere Application Server JAR file

¶ Specify the CLASSPATH environment variable.

¶ Specify the LD_LIBRARY_PATH environment variable.

This variable must include the directories containing thepdadmin utility and the migration utility libraries.

¶ Execute the migration classes with the correct command lineparameters.

The following code sample is a complete UNIX run script:export XML_PARSER_PATH=/opt/PDWAS/migration/xerces.jarexport JDK_PATH=/opt/jdk1.2.2/src.jarexport JDK_DIR=/opt/jdk1.2.2export PDWAS_JAR=/opt/PDWAS/migration/migrate.jarexport CLASSPATH=”$JDK_PATH:$XML_PARSER_PATH:$PDWAS_JAR”

export LD_LIBRARY_PATH=”/opt/IBMldapc/lib:/opt/PDWAS/migration:/opt/PolicyDirector/lib”

$JDK_DIR/bin/java -classpath $CLASSPATHcom.tivoli.pdwas.migrate.Migrate -jFibApplication_deployed.ear -w WASAdmin2-p myPassword -d o=ibm,c=au -a sec_master

Uninstalling the Migration UtilityThe migration utility provides a simple uninstallation script. Thisscript removes all files from the $PDWAS_DIR (UNIX) or%PDWAS_DIR% (Windows) directory.

1. Run the uninstall script:UNIX: /opt/PDWAS/migration/uninstall.sh

Windows: C:\Program Files\PDWAS\migration\uninstall.bat

2. To perform a complete install of Policy Director for WebSphereApplication Server, see the directions in “Uninstalling PolicyDirector for WebSphere Application Server” on page 27.

3. The migration utility has a prerequisite on the Policy Directorruntime environment. When the runtime environment is no

Migration Utility Run Script

40 Version 3.8

longer needed, you can remove it by following the uninstallationinstructions in the Tivoli SecureWay Policy Director BaseInstallation Guide.

Uninstalling the Migration Utility


3.M

igratin

gS

ecurity

Ro

lesto

Po

licyD

irector

Uninstalling the Migration Utility

42 Version 3.8

Administering Policy Director forWebSphere

This chapter contains the following topics:

¶ “Using Policy Director with Advanced Edition Single Server”

¶ “Using Policy Director Administration Tools” on page 44

¶ “Specifying Policy Director for WebSphere Properties” onpage 45

¶ “Configuring WebSphere Console to Recognize Policy DirectorGroups” on page 49

Using Policy Director with Advanced EditionSingle Server

IBM WebSphere Application Server provides a version of AdvancedEdition that supports a single server. This version is designed to runWebSphere with host-based security instead of an LDAP userregistry.

This version of WebSphere Application Server is very useful fordeveloping and prototyping applications and for demonstration ofWebSphere Application Server features and capabilities. The systemregistry cannot be modified from the WebSphere console.

Policy Director uses an LDAP user registry. When Policy Director isused with WebSphere Advanced Edition Single Server, the Policy

4


4.A

dm

inisterin

gP

olicy

Directo

rfo

rW

ebS

ph

ere

Director administrator must create equivalent LDAP user registryentries for each relevant user account on the system that hostsWebSphere. This means that the user definitions in the LDAP userregistry must be created manually.

Note that when users are mirrored into the Policy Director userregistry from the operating system entry, the Policy Director useridentity (ID) must match the operating system user ID. On Windowssystems, this ID does not include the domain name.

Use of Policy Director for WebSphere Application Server with theWebSphere Advanced Edition Single Server is not recommended forproduction systems.

See “User Registry Prerequisites” on page 21.

Using Policy Director Administration ToolsDo not use the WebSphere Application Server console to modifyattributes for users or roles. These changes will not be reflected inthe Policy Director policy database.

All administration of user and role configuration information must beperformed through one of the Policy Director administration tools:

¶ The pdadmin command line utility

¶ The Policy Director Web Portal Manager graphical user interface

Policy Director also provides an Administration API that can be usedto perform administration tasks programmatically.

For more information on the Policy Director administration tools, seethe following guides:

¶ For pdadmin, see the Tivoli SecureWay Policy Director BaseAdministration Guide.

¶ For the graphical user interface, see the Tivoli SecureWay PolicyDirector Web Portal Manager Administration Guide.

¶ For the programmatic API, see the Tivoli SecureWay PolicyDirector Administration API Developer Reference.

Using Policy Director with Advanced Edition Single Server

44 Version 3.8

For more information on obtaining Policy Director documentation,see “Publications” on page x.

Specifying Policy Director for WebSphereProperties

Policy Director for WebSphere Application Server uses a Javaproperty file that contains configuration parameters. The property fileis not created by default but can be used to modify configurableparameters.

The Java property file should be created in the following location:UNIX: $WAS_HOME/properties/PDWAS.propertiesWindows: %WAS_HOME%\properties\PDWAS.properties

Use this file to specify the following:

¶ “Limiting Simultaneous Connections”

¶ “Enabling Static Role Caching” on page 46

¶ “Defining Static Roles” on page 46

¶ “Configuring Dynamic Role Caching” on page 46

¶ “Specifying Logging Mechanism Type” on page 47

¶ “Specifying Logging Level” on page 47

¶ “Specifying Root Object Space Name” on page 48

¶ “Specifying Document Type Definition Directory” on page 49

Limiting Simultaneous ConnectionsLimits the number of simultaneous connections to Policy Director.The default is zero (0), which allows an unlimited number ofconnections. For example:com.tivoli.pdwas.MaxPDConnections=0

Set this value if SSL exceptions occur. Large number ofsimultaneous connections can cause limitations with the SolarisJVM.

Using Policy Director Administration Tools


4.A

dm

inisterin

gP

olicy

Directo

rfo

rW

ebS

ph

ere

Enabling Static Role CachingEnables or disables static role caching. Static role caching is enabledby default.com.tivoli.pdwas.EnableStaticRoleCaching=true

Defining Static RolesDefines additional static roles that are not defined in the WebSphereApplication Server admin.ear file.com.tivoli.pdwas.StaticRoleCache.Roles=AdminRole

Configuring Dynamic Role Caching

Enabling Dynamic Role CachingEnable or disable dynamic role caching. Dynamic role caching isenabled by default.com.tivoli.pdwas.EnableDynamicRoleCaching=true

Specifying Maximum Number of UsersThe maximum number of users that the cache supports before acache cleanup is performed. This parameter is used when dynamicrole caching is enabled. The default number of users is 10000.com.tivoli.pdwas.DynamicRoleCache.MaxUsers=10000

Specifying Principal Life TimeThe period of time in minutes that a principal entry is stored in thecache. This parameter is used when dynamic role caching is enabled.The default time is 5 minutes.com.tivoli.pdwas.DynamicRoleCache.PrincipalLifeTime=5

The term principal here refers to the Policy Director credentialreturned from a unique LDAP user.

Specifying Role LifetimeThe period of time in seconds that a role is stored in a user’s rolelist before it is discarded. This parameter is used when dynamic rolecaching is enabled. The default is 20 seconds.com.tivoli.pdwas.DynamicRoleCache.RoleLifetime=20

Specifying Policy Director for WebSphere Properties

46 Version 3.8

Specifying Number of Cache TablesThe number of tables used internally by the dynamic role cache.This parameter is used when dynamic role caching is enabled. Thedefault is 20.

When a large number of threads use the cache, increase the value totune and optimize cache performance.com.Tivoli.pdwas.DynamicRoleCache.NumBuckets=20

Specifying Logging Mechanism TypeSpecifies the underlying logging mechanism. Valid entries are WAS orSTDOUT. The default is STDOUT.

When WAS is specified, the WebSphere Application Server tracingframework is used. In this case, the normal WebSphere procedure forenabling or disabling tracing should be used.

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

Specifying Logging LevelSets the logging level for Policy Director for WebSphere ApplicationServer components. This parameter is used when the loggingmechanism type is set to STDOUT.

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

The supported <components> are:

¶ websphere.PDWASAuthzManager

¶ cache.StaticRoleCache

¶ cache.DynamicRoleCache

¶ cache.GenericCache

¶ cache.PurgeTask



4.A

dm

inisterin

gP

olicy

Directo

rfo

rW

ebS

ph

ere

When the component is not specified, or a part of the componentname is not specified, a wildcard is set for the logging level formultiple matching of Policy Director for WebSphere ApplicationServer components.

For example, specifying com.tivoli.pdwas.cache.LogLevel setsthe caching level for all cache components. Likewise, specifyingcom.tivoli.pdwas.LogLevel sets the logging level for all PolicyDirector for WebSphere Application Server components.

The values for these properties can be expressed as either an integeror as a comma-separated list of level. The integer represents a bitmap.

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

The FATAL level is the least significant bit of the bit map and theDEBUG level is the most significant bit.

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

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

Note that both an integer value and string values can be usedtogether. The highest log level is enabled. For example, thefollowing entry enables both FATAL and ERROR:com.tivoli.pdwas.websphere.PDWASAuthzManager.LogLevel =1,ERROR

Specifying Root Object Space NameChanges the name of the root object space and the group permissionname. The default value is WebAppServer. This parameter can be setto any value.


48 Version 3.8

com.tivoli.pdwas.RootObjectSpaceName=WebAppServer

If you change the default name, ensure that the name matches thename used when the Policy Director migration utility is run. If thenames do not match, Policy Director will not successfully locateprotected resources. For more information, see “Migration UtilitySyntax” on page 36.

Specifying Document Type Definition DirectoryConfigures the location of the Document Type Definition (DTD)files that are required in order to use Policy Director for WebSphereApplication Server.

The DTD application_1_2.dtd is required. This DTD isdistributed with Policy Director for WebSphere Application Servers,and is installed by the configuration script into the WebSphere libdirectory.

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

This value must be configured as an absolute path. For example, onUNIX:com.tivoli.pdwas.DTDDirectory=/opt/WebSphere/AppServer/lib

On Windows:com.tivoli.pdwas.DTDDirectory=c:\WebSphere\AppServer\lib

Configuring WebSphere Console to RecognizePolicy Director Groups

The WebSphere Application Server console can be used to specifysecurity policy for applications running in the WebSphereenvironment. The WebSphere Application Server console can specifysecurity policy for enterprise applications and other web resources,based on the entities stored in the LDAP directory.

Policy Director adds to the LDAP user registry the object classaccessGroup. Policy Director administrators can use the pdadmincommand or the Web Portal Manager to create new groups. Thesenew groups will be of object class accessGroup.



4.A

dm

inisterin

gP

olicy

Directo

rfo

rW

ebS

ph

ere

The WebSphere Application Server console is not configured bydefault to recognize objects of the class accessGroup as LDAPgroups. You can configure the WebSphere Application Serverconsole to add this object class to the list of object classes whichrepresent LDAP groups.

Complete the following instructions:

1. From the WebSphere console, access the advanced settings forconfiguring 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 followingentry:accessGroup:member

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

4. Stop and restart WebSphere Application Server as instructed bythe console.

Configuring WebSphere Console to Recognize Policy Director Groups

50 Version 3.8

Enabling Security: A Tutorial

This chapter provides a tutorial that describes how to add security toan example application. The tutorial is based on a WebSpheretutorial that helps you learn about various aspects of WebSphereapplication assembly, configuration, and deployment. The WebSpheretutorial accompanies example code that is shipped as part of theWebSphere product.

You do not need to consult the WebSphere tutorial to use this PolicyDirector tutorial. This Policy Director tutorial provides an applicationEAR file which has been built from the WebSphere example code byfollowing the WebSphere tutorial instructions.

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

The example program that ships with Policy Director for WebSphereApplication Server is built from the tutorial instructions in Sections6.71, 6.7.2, and 6.7.3 at the above URL. The material in this chapterreplaces the tutorial in Section 6.7.4 at the above URL.

Tutorial OverviewThis tutorial focuses on showing you how to add security to theapplication EAR file, add users to the LDAP user registry, enableWebSphere security, deploy and test the sample application, migratethe application to Policy Director, enable the Policy Directorauthorization component, and test the application security under

5


5.E

nab

ling

Secu

rity:A

Tuto

rial

Policy Director. The tutorial also shows how to make a simplechange to a role, and then test that the result is recognized duringaccess checking.

These instructions assume the following:

¶ Policy Director has been installed and configured to use anLDAP user registry.

¶ WebSphere Application Server has been installed to use the sameLDAP user registry.

¶ Security has not been enabled for Websphere.

¶ The Policy Director for WebSphere Application Server migrationutility has not been run previously.

Complete the instructions in each of the following sections:

¶ “1: Adding Security to a WebSphere Application”

¶ “2: Add Users to the LDAP User Registry” on page 58

¶ “3: Enabling WebSphere Application Server Security” on page 60

¶ “4: Deploying The Application” on page 62

¶ “5: Testing Security For the Deployed Application” on page 64

¶ “6: Migrating the Application to Policy Director” on page 65

¶ “7: Enabling the Policy Director Authorization Component” onpage 66

¶ “8: Testing Security for the Deployed Application” on page 67

¶ “9: Changing Roles” on page 68

¶ “10: Testing Security for the Deployed Application” on page 68

1: Adding Security to a WebSphere Application1. Start the WebSphere application assembly tool. Click

Start->Programs->IBM WebSphere -> Application Serverv4.0 AE -> Application Assembly Tool or runC:\WebSphere\AppServer\bin\assembly

Click Cancel at the Welcome screen.

Tutorial Overview

52 Version 3.8

2. Copy the sample application file simpleSession.ear from thedirectory where it was extracted toC:\temp\assembly\simpleSession.ear

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

4. Right click on Security Roles. Click New.

5. Select the General tab. Add:Name: GoodGuys

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

Click OK.

7. Repeat the previous step to add the following users:Name: user2Name: user3Name: user4

Click OK when all users are added.

1: Adding Security to a WebSphere Application


5.E

nab

ling

Secu

rity:A

Tuto

rial

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

a. Method: Click Add.

¶ Select Home (*)

¶ Select Remote (*)

Click OK.

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

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


54 Version 3.8

9. Expand Web Modules. Double-click SimpleSessionWar.

a. Click the Advanced tab.

b. Check the Login Configuration box.

c. Specify the Authorization Method: Basic.

d. Specify the Realm Name: Getting Started

e. Click Apply.

10. Expand Web Modules. Expand SimpleSessionWar. Right clickSecurityConstraints. Select New.

a. For Security Context Name, enter GoodGuys.

b. Roles:

¶ Click Add.

¶ Select GoodGuys.

Figure 6. Adding A Security Role to the Method Permissions



5.E

nab

ling

Secu

rity:A

Tuto

rial

¶ Click OK.

c. For Transport Guarantee, select None.

d. Click OK.

11. Right click on Web modules -> SimpleSessionWar ->SecurityConstraints ->GoodGuys -> Web ResourceCollections.

a. Select New.

b. For Web Resource Name, enter SecureMe.

Figure 7. The Security Constraints of a Web Module


56 Version 3.8

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”. ClickOK.

f. Click OK.

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

13. Select File-> Generate Code for Deployment.

a. Set working directory to C:\temp.

Figure 8. Configuring the Web Resource Collections of the Security Constraints of aWeb Module



5.E

nab

ling

Secu

rity:A

Tuto

rial

b. Click Generate Now.

c. Fix any errors.

14. Exit the Application Assembly tool. Continue to the next section“2: Add Users to the LDAP User Registry”.

2: Add Users to the LDAP User RegistryUse the Policy Director pdadmin utility to add the users youdeclared in the previous section (user1, user2, user3, and user4) tothe LDAP user registry.

This section demonstrates common pdadmin commands for addingusers. For complete information on all pdadmin options, see theTivoli SecureWay Policy Director Base Administration Guide.

1. Log in as the Policy Director administrator:C:> pdadmin -a sec_master -p <myPassword>

Substitute the correct password for the sec_master account foryour Policy Director secure domain.

2. Create a WebSphere administration user:

Figure 9. Generating Code for Deployment.


58 Version 3.8

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

Substitute values for organization and country that are validfor your LDAP user registry.

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

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

5. Create and enable a Policy Director account for use by the localhost when establishing a secure connection with the PolicyDirector management server. Note that this account is assignedmembership in the remote-acl-users group:pdadmin> user create pdwasadmin cn=pdwasadmin,o=ibm,c=aupdwasadmin pdwasadmin myPassword remote-acl-userspdadmin> user modify pdwasadmin account-valid yes

6. Exit the pdadmin utility:pdadmin> quit

7. Return to the WebSphere console to enable security. Continue to“3: Enabling WebSphere Application Server Security” onpage 60.

2: Add Users to the LDAP User Registry


5.E

nab

ling

Secu

rity:A

Tuto

rial

3: Enabling WebSphere Application ServerSecurity

1. Start the WebSphere Administration Server:c:\websphere\appserver\bin\adminserver

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

3. Select Console->Security Center.

4. Select the General tab. Check the Enable Security box.

5. Select the Authentication tab.

a. Select LTPA. Set the following LTPA settings:

¶ Token Expiry: 120

¶ Domain: Your domain name. For example:mydomain.ibm.com

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

LDAP Settings Value

Security Server ID cn=pdwasadmin,o=ibm,c=au

Security Server Password myPassword

Host ldapserver.mydomain.ibm.com

Directory Type SecureWay

Base DN o=ibm,c=au

Bind DN cn=root

Bind Password myPassword

c. Click OK.

3: Enabling WebSphere Application Server Security

60 Version 3.8

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

7. Select Restart.

8. Continue to “4: Deploying The Application” on page 62.

Figure 10. Enabling Security through the Security Center

3: Enabling WebSphere Application Server Security


5.E

nab

ling

Secu

rity:A

Tuto

rial

4: Deploying The Application1. Verify that the WebSphere Admin Server is running.

2. Start the WebSphere Admin Client:C:\websphere\appserver\bin\adminclient

3. Log in as user pdwasadmin 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 allunprotected methods. Click yes.

d. Click Select.

e. Verify that all users are listed

Figure 11. Denying Access to Unprotected Methods

4: Deploying The Application

62 Version 3.8

user1 user2 user3 user4

f. Click OK. Click Next nine times.

g. You can now select Next at each of a series of dialog boxesthat appear. The dialog boxes are titled:

¶ Mapping Users to Roles

¶ Mapping EJB RunAs Role to User

¶ Binding Enterprise Bean to JNDI Names

¶ Mapping EJB References to Resources

¶ Specifying the Default Datasources for EJB Modules

¶ Specifying Data Sources for Individual CMP Beans

¶ Selecting Virtual Hosts for Web Modules

¶ Selecting Application Server

h. When the dialog box Completing the ApplicationInstallation Wizard appears, click Finish.

i. Click Yes to generate code. Click OK.

j. Click OK to exit the dialog box.

6. If the Default Server is running, stop it now. If the DefaultServer is not running, continue to the next step.

To stop the Default Server:

¶ Select WebSphere Admin Domain -> Nodes -><hostname> -> Application Servers -> Default Server

¶ Right click on the default server.

¶ Select Stop.

¶ Click OK to exit the dialog box.

7. Start the Default Server.



¶ Select Start.



5.E

nab

ling

Secu

rity:A

Tuto

rial


8. Exit the WebSphere Advanced Administration Console.

9. Continue to “5: Testing Security For the Deployed Application”.

5: Testing Security For the Deployed ApplicationServlet

1. Start your web browser.

2. Go to the following URL. Substitute your system name forhostname:http://<hostname>:9080/gettingstarted3/SimpleSession?msg=Test

3. You should be prompted to enter a user name and password.Enter one of the valid user names: user1 or user2 or user3 oruser4. Enter the correct password.

You should see a results page.

4. Restart your web browser.

5. Go to the same URL. When prompted to enter a user name andpassword, enter an invalid user name or password.

You should see a failure page.

Thick Client

1. Use the launchclient program to start your secure application.Enter the following command as one single line:c:> c:\websphere\appserver\bin\launchclientc:\websphere\appserver\installedApps\SimpleSessionApp.ear

2. You should receive a login prompt, requesting a a user name andpassword.

3. Enter a valid user name and password. For example, user1.

You should see text indicating a successful login.

4. Restart your web browser.


64 Version 3.8

5. Use the launchclient program to start your secure application,as shown in Step 1 above. When prompted to enter a user nameand password, enter an invalid user name or password.

You should see text indicating a login failure.

6. Continue to “6: Migrating the Application to Policy Director”.

6: Migrating the Application to Policy Director1. These instructions assume the following:

¶ The migration utility has been installed in the standardlocation:C:\Program Files\Tivoli\pdwas\migration

If you installed the migration utility in another directory,adjust the instructions in this section accordingly.

¶ The migration utility has not been run before.

¶ WebSphere Application Server is installed in the defaultlocation.

2. Change directory to the migration utility directory:cd C:\Progmram Files\Tivoli\pdwas\migration

3. Edit the script named run_WIN32.bat.

a. Replace the following line:set EAR_NAME=”Application.ear”

with the new line:set EAR_NAME=”c:\websphere\appserver\config\admin.ear”

b. Verify that the -p parameter is followed by the correctpassword.

c. Verify that the -w parameter is followed by the name of theadmin user wsadmin.

4. Execute the run_32 script.

5. Edit the run_WIN32.bat script and reset EAR_NAME to thename of your test application EAR file:

5: Testing Security For the Deployed Application


5.E

nab

ling

Secu

rity:A

Tuto

rial

set EAR_NAME=”c:temp\assembly\simpleSession.ear”

6. Execute the run_32 script.

7. When the script completes, continue to “7: Enabling the PolicyDirector Authorization Component”.

7: Enabling the Policy Director AuthorizationComponent

These instructions configure the authorization component. Theinstructions assume the Policy Director for WebSphere ApplicationServer component has been installed but not yet configured. Formore information on installation, see “Installing Policy Director forWebSphere” on page 23.

1. Change to the directory that contains the configuration script:cd C:\websphere\appserver\bin

2. Run the configuration script with the parameters as shown. Notethat you must substitute your host names and domain names asappropriate:C:> configure_PDPermission“cn=pdwasadmin,o=ibm,c=au” myPasswordpdmgrd.mydomain.ibm.com pdacld.mydomain.ibm.com

3. Change directory to the WebSphere properties directory:cd C:\websphere\appserver\properties

4. Edit the file sas.server.props. Add the following line, as onecontinuous line:com.ibm.websphere.security.authorizationTable=com.tivoli.pdwas.websphere.PDWASAuthzManager

5. Determine the size of the file sas.server.props.future. Ifthe size is not zero (0) bytes, add the following line, as onecontinuous line:com.ibm.websphere.security.authorizationTable=com.tivoli.pdwas.websphere.PDWASAuthzManager

6. Stop and start the Node server:

¶ Start the WebSphere Console.

6: Migrating the Application to Policy Director

66 Version 3.8

¶ Right click on WebSphere Admin Domain -> Nodes -><Hostname>

¶ Select Restart.

7. Stop and restart the Default Server:



¶ Select Stop.


¶ Click on the default server and select Start.


8. Exit the WebSphere Advanced Administration console.

9. Optionally, you can configure the WebSphere console torecognize Policy Director groups. This enables the WebSphereadministrator to view Policy Director groups when definingsecurity policy through the WebSphere console.

For instructions, see “Configuring WebSphere Console toRecognize Policy Director Groups” on page 49.

10. When the server restarts, continue to “8: Testing Security forthe Deployed Application”.

8: Testing Security for the Deployed Application1. Verify that security is now working for the application. Repeat

the steps for both Servlet and Thick Client in “5: TestingSecurity For the Deployed Application” on page 64.

2. When security has been verified continue to “9: Changing Roles”on page 68.

7: Enabling the Policy Director Authorization Component


5.E

nab

ling

Secu

rity:A

Tuto

rial

9: Changing RolesUse the Policy Director pdadmin utility to change a role definitionby removing a user.

1. Start pdadmin:pdadmin -a sec_master -p myPassword

2. Modify the ACL for the SimpleSession application to remove thename of user4. Enter the acl modify command below as onelong command line. Note that there is no space between theunderscore following GoodGuys and the beginning ofSimpleSessionApp_ACL:pdadmin> acl modify_WebAppServer_deployedResources_GoodGuys_SimpleSessionApp_ACL remove user user4

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

4. Continue to “10: Testing Security for the Deployed Application”.

10: Testing Security for the Deployed Application1. Verify that security is now working for the application. Repeat

the steps for both Servlet and Thick Client in “5: TestingSecurity For the Deployed Application” on page 64.

Note that when you enter the name of a valid user, you mustenter either user1, user2, or user3.

When you want to enter the name of an invalid user, enteruser4.

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

You have now completed the tutorial.

9: Changing Roles

68 Version 3.8

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

SC32-0832-00

tivoli policy director for websphere application server...

Documents