authorization java classes developer’s...

IBM Tivoli Access Manager

Authorization Java ClassesDeveloper’s ReferenceVersion 4.1

SC32-1141-01

��

Note:Before using this information and the product it supports, read the information in Appendix B, “Notices”, on page 33.

Third Edition (August 2003)

This edition replaces SC32-1141-00.

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

Contents

Figures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . v

Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vii

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ixWho should read this book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ixWhat this book contains . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ixPublications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . x

Release information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xBase information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xWebSEAL information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xWeb security information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiDeveloper references . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiTechnical supplements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiiRelated publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiiAccessing publications online . . . . . . . . . . . . . . . . . . . . . . . . . . . . xivOrdering publications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiv

Accessibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xivContacting software support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xivConventions used in this book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv

Typeface conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvOperating system differences . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv

Chapter 1. Introducing the authorization API . . . . . . . . . . . . . . . . . . . . 1Authorization API components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1Building Java applications with the authorization API . . . . . . . . . . . . . . . . . . . . . 2

IBM Tivoli Access Manager software requirements. . . . . . . . . . . . . . . . . . . . . . 2JRE requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3Configuring the Java runtime component to a particular Java runtime environment . . . . . . . . . . 3Security requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

Deploying a Java authorization API application. . . . . . . . . . . . . . . . . . . . . . . . 4Gathering problem determination information . . . . . . . . . . . . . . . . . . . . . . . . 4

Enabling tracing on the policy server . . . . . . . . . . . . . . . . . . . . . . . . . . 4Enabling tracing on the authorization server . . . . . . . . . . . . . . . . . . . . . . . . 4Enabling tracing in the Java runtime component . . . . . . . . . . . . . . . . . . . . . . 4Gathering trace and message logs . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

Chapter 2. Understanding security in IBM Tivoli Access Manager . . . . . . . . . . . 7Using Java 2 security with IBM Tivoli Access Manager . . . . . . . . . . . . . . . . . . . . . 7Java Authentication and Authorization Service (JAAS) model . . . . . . . . . . . . . . . . . . . 8

Authenticating users and obtaining credentials . . . . . . . . . . . . . . . . . . . . . . . 8Authorizing access requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Configuring a Java application into the secure domain . . . . . . . . . . . . . . . . . . . . . 10Information needed for establishing SSL communications . . . . . . . . . . . . . . . . . . . 10SvrSslCfg usage syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11Configuring an application server in remote mode . . . . . . . . . . . . . . . . . . . . . 12Configuring an application server in local mode . . . . . . . . . . . . . . . . . . . . . . 13Unconfiguring an application server . . . . . . . . . . . . . . . . . . . . . . . . . . 13Adding a policy or authorization server . . . . . . . . . . . . . . . . . . . . . . . . . 13Removing a policy or authorization server . . . . . . . . . . . . . . . . . . . . . . . . 14Changing a policy or authorization server . . . . . . . . . . . . . . . . . . . . . . . . 14Replacing a certificate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14Setting the port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14Setting the database directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

© Copyright IBM Corp. 2002, 2003 iii

Setting the database refresh interval . . . . . . . . . . . . . . . . . . . . . . . . . . 15Setting the application listening mode . . . . . . . . . . . . . . . . . . . . . . . . . 15

Chapter 3. Configuring the authorization API . . . . . . . . . . . . . . . . . . . 17Configuring the Java Authentication and Authorization Service . . . . . . . . . . . . . . . . . . 17

Creating a login configuration file . . . . . . . . . . . . . . . . . . . . . . . . . . . 17Specify the login file location . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

Developing a resource manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18Making authorization decisions outside of Java 2 . . . . . . . . . . . . . . . . . . . . . . . 18Obtaining entitlements for a specified user . . . . . . . . . . . . . . . . . . . . . . . . . 19

Chapter 4. Java classes overview . . . . . . . . . . . . . . . . . . . . . . . . 21com.tivoli.mts.PDLoginModule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21com.tivoli.mts.PDPrincipal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21com.tivoli.mts.PDPermission. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22com.tivoli.mts.PDAttrs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22com.tivoli.mts.PDAttrValue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23com.tivoli.mts.PDAttrValueList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23com.tivoli.mts.PDAttrValues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23com.tivoli.mts.PDStatics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24com.tivoli.pd.jcfg.SvrSslCfg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

–action config . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26–action unconfig . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26–action addsvr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27–action rmsvr. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27–action chgsvr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27–action replcert . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27–action setport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27–action setdbdir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27–action setdbref . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28–action setdblisten . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

Chapter 5. Upgrade considerations . . . . . . . . . . . . . . . . . . . . . . . 29

Appendix A. Deprecated Java classes and methods . . . . . . . . . . . . . . . . 31

Appendix B. Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33Trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

iv IBM Tivoli Access Manager: Authorization Java Classes Developer’s Reference

Figures

1. JAAS login configuration file. . . . . . . . . . . . . . . . . . . . . . . . . . . . 172. Resource manager task example. . . . . . . . . . . . . . . . . . . . . . . . . . . 183. Example showing authorization outside of Java 2 . . . . . . . . . . . . . . . . . . . . . 194. Using the PDPrincipal.getEntitlements method. . . . . . . . . . . . . . . . . . . . . . 205. Processing protected objects returned . . . . . . . . . . . . . . . . . . . . . . . . . 20

© Copyright IBM Corp. 2002, 2003 v

vi IBM Tivoli Access Manager: Authorization Java Classes Developer’s Reference

Tables

1. Files associated with the Tivoli Access Manager Java runtime and ADK components . . . . . . . . . 22. Sample information used for SvrSslCfg examples . . . . . . . . . . . . . . . . . . . . . 123. Description of SvrSslCfg Parameters . . . . . . . . . . . . . . . . . . . . . . . . . 254. Deprecated Java Classes and Methods . . . . . . . . . . . . . . . . . . . . . . . . 31

© Copyright IBM Corp. 2002, 2003 vii

viii IBM Tivoli Access Manager: Authorization Java Classes Developer’s Reference

Preface

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

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

This reference contains information about how to use Tivoli Access Managerauthorization Java™ classes and methods. This document describes the Javaimplementation of the Tivoli Access Manager authorization API. See the IBM TivoliAccess Manager Administration C API Developer’s Reference for information regardingthe C implementation of these APIs.

Who should read this bookThis reference is for application programmers implementing programs in the Javaprogramming language that require the use of the authorization functionsprovided with the IBM Tivoli Access Manager product.

Readers should be familiar with the following:v PC and UNIX® operating systemsv Database architecture and conceptsv Security managementv Internet protocols, including HTTP, TCP/IP, File Transfer Protocol (FTP), and

Telnetv The user registry that Tivoli Access Manager is configured to usev Lightweight Directory Access Protocol (LDAP) and directory services, if used by

your user registryv Authentication and authorizationv Secure Sockets Layer (SSL) communications

What this book containsThis reference contains the following chapters and appendixes:v Chapter 1, “Introducing the authorization API”, on page 1

This chapter provides an overview of the authorization API and its components.v Chapter 2, “Understanding security in IBM Tivoli Access Manager”, on page 7

This chapter provides an overview of the Java classes and methods.v Chapter 3, “Configuring the authorization API”, on page 17

This chapter provides information on configuring the authorization API.v Chapter 4, “Java classes overview”, on page 21

© Copyright IBM Corp. 2002, 2003 ix

This chapter provides an overview of the Java classes and methods provided asart of the authorization API.

v Chapter 5, “Upgrade considerations”, on page 29This chapter outlines considerations for upgrading Java applications from aprevious version of Tivoli SecureWay® Policy Director or IBM Tivoli AccessManager.

v Appendix A, “Deprecated Java classes and methods”, on page 31This appendix provides a list of the Java classes and methods that have beendeprecated in this version of Tivoli Access Manager.

v Appendix B, “Notices”, on page 33This appendix provides copyright, legal, and trademark information.

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

Release informationv IBM Tivoli Access Manager Read Me First Card

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

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

Base informationv IBM Tivoli Access Manager Base Installation Guide

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

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

WebSEAL informationv IBM Tivoli Access Manager WebSEAL Installation Guide

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

x IBM Tivoli Access Manager: Authorization Java Classes Developer’s Reference

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

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

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

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

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

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

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

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

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

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

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

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

Preface xi

Technical supplementsv IBM Tivoli Access Manager Command Reference

GC32-1107-01 (am41_cmdref.pdf)Provides information about the command line utilities and scripts provided withTivoli Access Manager.

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

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

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

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

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

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

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

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

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

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

v Microsoft™ Windows™

v Sun Solaris Operating Environment

xii IBM Tivoli Access Manager: Authorization Java Classes Developer’s Reference

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


DB2 information is available at:

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

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

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

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

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

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

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

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

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

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

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

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

(SC23-4827-00)

Preface xiii

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The guide provides the following information:v Registration and eligibility requirements for receiving support

xiv IBM Tivoli Access Manager: Authorization Java Classes Developer’s Reference


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

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

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

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

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

v Telephone numbers and e-mail addresses, depending on the country in whichyou are located

v A list of information you should gather before contacting customer support

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

Typeface conventionsThe following typeface conventions are used in this reference:

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

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

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

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

Preface xv

xvi IBM Tivoli Access Manager: Authorization Java Classes Developer’s Reference

Chapter 1. Introducing the authorization API

The IBM Tivoli Access Manager (Tivoli Access Manager) Java runtime componentincludes the Java language version of a subset of the Tivoli Access Managerauthorization API. The authorization API consists of a set of classes and methodsthat provide Java applications with the ability to interact with Tivoli AccessManager to make authentication and authorization decisions.

Application developers can use the Javadoc information provided with the TivoliAccess Manager application developer kit (ADK) along with this book and otherJava reference materials, to add Tivoli Access Manager authorization and securityservices to new or existing Java applications. Application developers updating anexisting Tivoli Access Manager application should check Appendix A, “DeprecatedJava classes and methods”, on page 31 before making changes.

Note: If you are familiar with the authorization API Java classes provided in TivoliSecureWay Policy Director Version 3.8, see Chapter 5, “Upgradeconsiderations”, on page 29 for important information.

This chapter contains the following topics:v “Authorization API components”v “Building Java applications with the authorization API” on page 2v “Deploying a Java authorization API application” on page 4v “Gathering problem determination information” on page 4

Authorization API componentsThe authorization API Java classes are installed as part of the Tivoli AccessManager Java runtime component. These classes communicate directly with theTivoli Access Manager authorization server by establishing an authenticated,Secure Sockets Layer (SSL) session with the authorization server process. Theauthorization server services these requests in the same manner that it servicesrequests from the authorization C API.

Table 1 on page 2 lists the files related to the authorization API that are installed aspart of the Tivoli Access Manager Java runtime component. The Javadocinformation, even though it is installed as part of the Tivoli Access Manager ADKcomponent, is listed in the table for completeness.

© Copyright IBM Corp. 2002, 2003 1

Table 1. Files associated with the Tivoli Access Manager Java runtime and ADKcomponents

Directory File File Description

JAVA_HOME/lib/ext PD.jar The Java Archive (JAR) file containingthe classes and methods associatedwith both the authorization API andthe administration API.

ibmjsse.jar The JAR file encapsulating the JavaSecure Socket Extension (JSSE) supportwhich provides a Java implementationof SSL.

ibmjcefw.jaribmjceprovider.jarlocal_policy.jarUS_export_policy.jar

The JAR files comprising part of theJava Cryptography Extension (JCE).

ibmpkcs.jar The JAR file containing the Public KeyCryptography Standard (PKCS)support.

jaas.jar The JAR file encapsulating the JavaAuthentication and AuthorizationService (JAAS).

AM_BASE/nls/javadocs/pdjrte

index.html

(and many others)

Javadoc HTML documentation for theJava classes and methods providedwith the Tivoli Access Manager Javaruntime component.

Note: The PD.jar file replaces the PDPerm.jar file that was provided in TivoliSecureWay Policy Director Version 3.8.

To make the JAR files listed in Table 1 available to a particular JRE, see“Configuring the Java runtime component to a particular Java runtimeenvironment” on page 3.

Building Java applications with the authorization APITo develop Java applications that use the Tivoli Access Manager authorization API,you must install and configure the required software.

IBM Tivoli Access Manager software requirementsYou must install and configure an Tivoli Access Manager secure domain. If you donot have an Tivoli Access Manager secure domain installed, install one beforebeginning application development. The minimum installation consists of a singlesystem with the following Tivoli Access Manager components installed:v Tivoli Access Manager runtime environment (see Note 1 on page 3)v Tivoli Access Manager Java runtime componentv Tivoli Access Manager policy serverv Tivoli Access Manager authorization serverv Tivoli Access Manager ADK

If you already have an Tivoli Access Manager secure domain installed and want toadd a development system to the domain, the minimum Tivoli Access Managerinstallation consists of the following components:

2 IBM Tivoli Access Manager: Authorization Java Classes Developer’s Reference

v Tivoli Access Manager runtime environment (see Note 1 on page 3)v Tivoli Access Manager Java runtime componentv Tivoli Access Manager ADK

For Tivoli Access Manager installation instructions, refer to the section of the IBMTivoli Access Manager Base Installation Guide for your operating system platform.

Notes:

1. The Tivoli Access Manager runtime environment component is not needed fordeveloping or deploying an Tivoli Access Manager Java application. Theprerequisite checking for the Tivoli Access Manager ADK component is in errorand erroneously requires that the Tivoli Access Manager runtime component beinstalled, even if you are developing only Java applications and simply needthe Javadoc information and the example files from the ADK component.To save disk space, you can copy the Javadoc HTML information, consisting ofthe entire AM_BASE/nls/javadocs directory tree, to another location on yourdevelopment system and then uninstall the Tivoli Access Manager ADK andruntime components. Only the Tivoli Access Manager Java runtime componentis necessary for running Java applications.

2. If you intend to use the Tivoli Access Manager runtime environment for anadministration C API application, you also must install the IBM Directory clientif an LDAP or Lotus Domino server is being used as the user registry in thesecure domain.

JRE requirementsOn those operating system platforms that support the Tivoli Access Managerauthorization API Java classes and methods, the base installation CD contains anoptionally installable JRE. You also can choose to use any of the supported JREslisted in the IBM Tivoli Access Manager Release Notes for developing and deployingyour Tivoli Access Manager Java applications. After you have installed a suitableJRE, configure it for use with Tivoli Access Manager as outlined in the next section,“Configuring the Java runtime component to a particular Java runtimeenvironment”.

Configuring the Java runtime component to a particular Javaruntime environment

Configure the Tivoli Access Manager Java runtime component to use the properJRE on the system by using the pdjrtecfg command. The pdjrtecfg commandcopies the Tivoli Access Manager JAR files to the JAVA_HOME/lib/ext directory ofthe JRE, automatically making the Tivoli Access Manager classes and methodsavailable. The CLASSPATH in your environment does not need to be modified.The Tivoli Access Manager Java runtime component can be configured to severaldifferent JREs on the same system, if desired. See the IBM Tivoli Access ManagerCommand Reference for details.

Security requirementsThe PD.jar file is signed, but verification of the signing of JAR files is notsupported in this version of Tivoli Access Manager.

The SvrSslCfg Java class (com.tivoli.pd.jcfg.SvrSslCfg) must be used to createconfiguration files that are to be used by Java applications. See “Configuring a Javaapplication into the secure domain” on page 10 for details on using the SvrSslCfgclass.

Chapter 1. Introducing the authorization API 3

Note: The svrsslcfg command line interface and the SvrSslCfg Java utility are notinterchangeable. Do not use the svrsslcfg command line interface to createconfiguration files that are to be used with Java applications. Do not use theSvrSslCfg Java class to create configuration files for use by C applications.

Deploying a Java authorization API applicationOnce you have developed and tested your Java application that uses the TivoliAccess Manager authorization API, you can deploy the application to systems thatare configured as part of an Tivoli Access Manager secure domain. The TivoliAccess Manager Java runtime component is the only Tivoli Access Managercomponent that must be installed on a system to run an Tivoli Access ManagerJava application. The Tivoli Access Manager runtime component is not needed forrunning Java applications.

Note: Information on installing the Tivoli Access Manager Java runtimecomponent can be found in the IBM Tivoli Access Manager Base InstallationGuide.

Gathering problem determination informationWhen developing a Java application, you might encounter a problem with TivoliAccess Manager. To assist Tivoli support personnel in diagnosing your problem,gather problem determination information relating to your error.

Tivoli Access Manager components can be configured to log information to one ormore trace files. You can enable tracing for the policy server, the authorizationserver, the Java runtime component, or any system using the Tivoli AccessManager runtime environment.

Enabling tracing on the policy serverTo enable tracing on the policy server, edit the /etc/routing file, located in theinstallation directory for the Tivoli Access Manager policy server, and uncommentthe last line.

Shut down and restart the policy server daemon, pdmgrd.

Enabling tracing on the authorization serverTo enable tracing on the authorization server, edit the /etc/routing file, located inthe installation directory for the Tivoli Access Manager authorization server, anduncomment the last line.

Shut down and restart the authorization server daemon, pdacld.

Enabling tracing in the Java runtime componentTracing for the Tivoli Access Manager Java runtime component is controlled bysettings in the JAVA_HOME/PolicyDirector/PDJLog.properties file. To enabletracing, edit the properties file and update the following line to set isLogging totrue:baseGroup.PDJTraceLogger.isLogging=true

Gathering trace and message logsTrace and message log files for the policy server, authorization server, and TivoliAccess Manager runtime environment are written to the /log directory in the


Tivoli Access Manager installation directory. To determine the names of the tracelog files, you need to determine the process identifier, or PID, of the Tivoli AccessManager process.

Determine the PID for the policy or authorization server by checking theappropriate file:

Policy servercat ivmgrd.pid

Authorization servercat ivacld.pid

After determining the PID, look in the AM_BASE/log directory for trace files withnames of the form: PID.trace.log.*. Also collect the following message files in thesame directory::notice*.logfatal*.logwarning*.logerror*.log

Trace and message log files associated with the Tivoli Access Manager Javaruntime component are written to files in the /log directory with the followingnames:PDJTrace.log.*PDJFatal.log.*PDJWarning.log.*PDJError.log.*

Chapter 1. Introducing the authorization API 5

Chapter 2. Understanding security in IBM Tivoli AccessManager

The IBM Tivoli Access Manager (Tivoli Access Manager) authorization Java classesprovide an implementation of Java security code that is fully compliant with theJava 2 security model and the Java Authentication and Authorization Service(JAAS).

The Tivoli Access Manager authorization Java classes are described in thefollowing sections:v “Using Java 2 security with IBM Tivoli Access Manager” on page 7v “Java Authentication and Authorization Service (JAAS) model” on page 8

Using Java 2 security with IBM Tivoli Access ManagerThe Java 2 security architecture is policy-based, and allows for fine-grained accesscontrol. When code is loaded, it is assigned permissions based on the security policycurrently in effect. Each permission specifies a permitted access to a particularresource, such as read access to a specified file, or connect access to a specified hostand port. The policy specifies which permissions are available for code fromvarious signers and locations. The policy can be initialized from an externalconfiguration file.

Code can access a resource only if the permission that guards the resource givesthe code explicit permission. These new concepts of permission and policy enablethe Java 2 to offer fine-grained, highly configurable, flexible, and extensible accesscontrol. Such access control can now be specified for all Java code, includingapplications, beans, and servlets.

The Tivoli Access Manager authorization server provides an SSL-based accessmode for handling remote authorization calls. The Tivoli Access Manager Javaauthorization API uses this socket-based capability to provide functionalityequivalent to that provided in the authorization C API by theazn_decision_access_allowed() and azn_decision_access_allowed_ext() functions.

The azn_decision_access_allowed() function requires the following information:v Authentication informationv Resource namev Access mode

The Java 2 permission model provides the resource name and the access mode.The Java Authentication and Authorization Service (JAAS) extensions to the Java 2model provide the authentication information.

Tivoli Access Manager functions as a back-end for normal Java 2 permission checksby providing:v A custom JAAS LoginModule that manufactures authentication credentials.v A custom permission class that knows how to locate and call Tivoli Access

Manager.


Note: The Tivoli Access Manager authorization API Java classes only support useof the remote cache mode for accessing the Tivoli Access Managerauthorization database. Local cache mode is not supported.

Java Authentication and Authorization Service (JAAS) modelThe Java 2 permission model takes into account the following information:v The physical origin (the directory or URL) of the classes that are currently active.v The logical origin of those classes.v The identity of the organization that produced the classes, as proved by digital

signature.

This model serves well the browsers that first popularized Java, as it dealseffectively with the issues of mobile code.

JAAS augments the current Java 2 runtime to add knowledge of the user who istrying to run the application. This knowledge provides the authenticationinformation needed when implementing the security model.

JAAS augments the Java 2 security model to enable the following features:v Specification of permissions based on a user’s identity.v Enforcement of those permissions at application runtime.

These two features provide the authorization functionality needed whenimplementing the security model.

The following sections describe how Tivoli Access Manager authorization JavaClasses use the JAAS model:v “Authenticating users and obtaining credentials” on page 8v “Authorizing access requests” on page 9

Authenticating users and obtaining credentialsThe Tivoli Access Manager Java-based authentication feature is built around theJava Authentication and Authorization Services (JAAS) model.

Note: More information on the JAAS can be found at this Web site:http://java.sun.com/products/jaas

Tivoli Access Manager provides one JAAS LoginModule. You can use the modulein two different ways. You can use it to authenticate a user and obtain the user’scredentials. Alternatively, you can use it just to obtain the user’s credentials.

Authenticating with a user name and passwordIn order to authenticate a user, the LoginModule requires that the callingapplication provide the following:v A principal name, specified as either a short name or a X500Name (DN)v A password

The LoginModule authenticates the principal and returns the Tivoli AccessManager credential. The LoginModule expects the calling application to providethe following information:v The username, through a javax.security.auth.callback.NameCallback

v The password, through a javax.security.auth.callback.PasswordCallback.


http://java.sun.com/products/jaas

When the Tivoli Access Manager credential is successfully retrieved, the JAASLoginModule creates a Subject and a PDPrincipal.

Retrieving credentials without authenticatingTo retrieve credentials without authenticating, the calling application can call theJAAS Login Module with only a principal name as a short name or a X500Name(DN).

The LoginModule will expect the calling application to provide the usernamethrough a javax.security.auth.callback.NameCallback.

Using the login configuration fileYou can use an entry in the login configuration file to specify which of two loginmodes your application uses. You can configure the module to either require botha user name and a password, or just a user name.

This configuration takes the form of an optional keyword, nameOnly=true.

If nameOnly is omitted or specified to be false, both the user name and thepassword are required.

Authorizing access requestsThe Tivoli Access Manager authorization Java Classes are built around JAAS andthe Java 2 security model. The Tivoli Access Manager API closely follows the Java2 permission model.

Note: For more information on the Java 2 security model, see:http://java.sun.com/j2se/1.3/docs/guide/security/index.html

The Tivoli Access Manager authorization API Java classes provide a newpermission class named PDPermission. This class extends the abstract classcom.ibm.IBMPermission, which extends the abstract classjava.security.Permission. PDPermission has a static initializer that establishesthe SSL-protected socket communications protocol which is used to talk to TivoliAccess Manager.

An entry needs to be made in the JAAS policy file to insure that the JAAS securitycode calls the implies() method in the PDPermission class described below. Thisentry could be made specific to particular codebases, as desired.grant signedBy “xxx” codeBase “file:/E:/Program Files/aaa/bbb/ccc”principal com.tivoli.mts.PDPrincipal “*” {permission com.ibm.mts.PDPermission “ignoreme”;};

The contents of the action string ignoreme above are unimportant because thePDPermission class ignores them. This is because Tivoli Access Manager acts asthe repository for security policy. The intent of this entry is to get the Java securitycode to call the implies() method when some resource manager checks to see if apermission is held.

The PDPermission class implements two constructors plus the following methods:

implies()Checks whether Tivoli Access Manager grants the specified permissions.

equals()Determines if two PDPermission objects are equal.

Chapter 2. Understanding security in IBM Tivoli Access Manager 9

http://java.sun.com/j2se/1.3/docs/guide/security/index.html

getActions()Returns the canonical string representation of the actions.

hashCode()Returns the hash code value for the object.

The implies() method flow consists of the following steps:1. Use the static getSubject() method to retrieve the current Subject. (Subject

was created by the PDLoginModule class, and placed on the current thread ofexecution by the resource manager.)

2. If the Subject contains a Principal of type com.tivoli.mts.PDPrincipal, then theappropriate credentials are secured for the call to Tivoli Access Manager.

The example below illustrates one way a resource manager, such as a Web serveror Enterprise Java Beans container, would place the Subject on the current threadof execution.Subject.doAs(whoami, new java.security.PrivilegedAction() {public java.lang.Object run() {}});

At this point the PDPermission class has all the information required to make theauthorization call to Tivoli Access Manager.

Following is an example of a typical authorization check that invokes the TivoliAccess Manager through the PDPermission class implementation. ThecheckPermission() method returns quietly unless it fails, in which case it throws ajava.lang.SecurityException.PDPermission perm = new PDPermission(“/MyResourceManager/private”,

“[simple]rT[newActionGroup1]Z”);

SecurityManager.checkPermission(perm);

Configuring a Java application into the secure domainTivoli Access Manager uses a self-generated and self-signed certificate toauthenticate its Secure Sockets Layer (SSL) communications. The Tivoli AccessManager authorization API Java classes must be able to determine the certificatethat Tivoli Access Manager is using in order to establish its SSL communication.You also must establish an identity for the Java application. These areaccomplished by creating a configuration file, a keystore file, and an Tivoli AccessManager application name using the SvrSslCfg (com.tivoli.mts.SvrSslCfg) class.

Information needed for establishing SSL communicationsTo create the files necessary for establishing SSL communications in the securedomain, the SvrSslCfg class needs information about the secure domain as well asinformation related to the application.

The following information about the Tivoli Access Manager secure domain isneeded:

Security master passwordThe password associated with the Tivoli Access Manager sec_master user.

Policy server nameThe name of the system running the Tivoli Access Manager policy server,ivmgrd.


Authorization server nameThe name of the system running the Tivoli Access Manager authorizationserver, ivacld. This might be the same system as the policy server.

Policy server SSL port numberThe number of the port being used for SSL communications with thepolicy server. The default is 7135.

Authorization server SSL port numberThe number of the port being used for SSL communications with theauthorization server. The default is 7136.

To uniquely associate this SSL connection to the Java application being run, thefollowing information is needed also:

Configuration file URLThe URL to the configuration file to be manipulated by the SvrSslCfgclass. If not specified, the JAVA_HOME/PdPerm.properties file is used.

Keystore file URLThe URL to the keystore file to be manipulated by the SvrSslCfg class. Ifnot specified, the JAVA_HOME/lib/security/pdperm.ks file is used.

Tivoli Access Manager application nameThe name of the Tivoli Access Manager application name to be created andassociated with the SSL connection between this system and the TivoliAccess Manager servers.

The configuration and keystore files are sensitive files that should be protected.The contents of the configuration file is not externalized and is subject to changewithout notice in future releases of Tivoli Access Manager. Do not use theinformation in the configuration file directly.

Note: If either of these files becomes damaged, the configuration steps must berepeated. Creating backups of these two files is recommended.

SvrSslCfg usage syntaxThe use of the com.tivoli.pd.jcfg.SvrSslCfg class can be summarized as follows:java com.tivoli.pd.jcfg.SvrSslCfg -action { config | unconfig | addsvr |

rmsvr | chgsvr | setport |setdblisten | replcert }

-admin_id admin_user_ID-admin_pwd admin_password-appsvr_id application_server_name-port port_number-mode { local | remote }-policysvr policy_server_name:port:rank [,...]-authzsvr authorization_server_name:port:rank [,...]-cfg_file fully_qualified_name_of_configuration_file-key_file fully_qualified_name_of_keystore_file-appsvr_pwd application_server_password-host Host_name_of_application_server-dblisten { true | false }-dbdir name_of_directory_for_local_policy_database-dbrefresh refresh_interval_in_seconds-cfg_action { create | replace }

Detailed information on the SvrSslCfg class can be found in“com.tivoli.pd.jcfg.SvrSslCfg” on page 24 or in the Javadoc information in theTivoli Access Manager ADK component.


Compatibility Note: The com.tivoli.mts.SvrSslCfg class has been deprecated. Thenew com.tivoli.pd.jcfg.SvrSslCfg class does not supporteither of the positional parameter formats used in TivoliSecureWay Policy Director Version 3.8 or Tivoli AccessManager Version 3.9. Existing Java applications need to bemodified to use the new class as the old one will be removedin a future release.

The examples in this chapter use the information shown in Table 2.

Table 2. Sample information used for SvrSslCfg examples

Information Value

Administrator user ID sec_master

Administrator password secpw

Policy server, TCP/IP communications portnumber, and rank (default port is 7135)

ampolicy.myco.com:7135:1

Authorization server, TCP/IPcommunications port number, and rank(default port is 7136)

amazn.myco.com:7136:1

Host name of Java application system (usedin remote mode examples)

jsys.myco.com

TCP/IP port on which the application serverlistens for communications from the policyserver

999

Application server password pw

Tivoli Access Manager application ID PDPermissionjapp

The application ID must be unique. Otherinstances of the application running on thisor other systems must each be given aunique ID. A distinguished name can beused if an LDAP-based user registry is beingused by Tivoli Access Manager.

Configuration file c:\am\configfile

Keystore file c:\am\keystore

Configuring an application server in remote modeAfter obtaining the necessary information, use the SvrSslCfg class to create theTivoli Access Manager application name, the configuration file, and the keystorefile. Configuring an application server creates user and server information in theuser registry as well as creates local configuration and keystore files.

Based on the sample information shown in Table 2, the command to establish anSSL connection between japp.myco.com and the Tivoli Access Manager securedomain might be as follows:java com.tivoli.pd.jcfg.SvrSslCfg -action config \

-admin_id sec_master -admin_pwd secpw \-appsvr_id PDPermissionjapp -appsvr_pwd pw -host japp.myco.com \-mode remote -port 999 -policysvr ampolicy.myco.com:7135:1 \-authzsvr amazn.myco.com:7136:1 -cfg_file c:/am/configfile \-key_file c:/am/keystore -cfg_action create


The -cfg_action create option is used to initially create the configuration andkeystore files. Use -cfg_action replace if these files already exist. If the -cfg_actioncreate option is used and the configuration or keystore files already exist, anexception is thrown.

Compatibility Note: In Tivoli SecureWay Policy Director Version 3.8, thearguments for the deprecated com.tivoli.mts.SvrSslCfg classdid not allow the specification of the configuration andkeystore files and required that the account for theapplication be created on the policy server prior to invokingthe class. In Tivoli Access Manager. These are now supportedin one operation using the com.tivoli.pd.jcfg.SvrSslCfg class.

Configuring an application server in local modeAfter obtaining the necessary information, use the SvrSslCfg class to create theTivoli Access Manager application name, the configuration file, and the keystorefile.

Based on the sample information shown in Table 2 on page 12, the command toestablish an SSL connection between the Java application and Tivoli AccessManager secure domain in local mode might be as follows:java com.tivoli.pd.jcfg.SvrSslCfg -action config \

-admin_id sec_master -admin_pwd secpw \-appsvr_id PDPermissionjapp -host amazn.myco.com \-mode local -port 999 -policysvr ampolicy.myco.com:7135:1 \-authzsvr amazn.myco.com:7136:1 -cfg_file c:/am/configfile \-key_file c:/am/keystore -cfg_action create

The -cfg_action create option is used to initially create the configuration andkeystore files. Use -cfg_action replace if these files already exist. If the -cfg_actioncreate option is used and the configuration or keystore files already exist, anexception is thrown.

Compatibility Note: Local mode was not available in Tivoli SecureWay PolicyDirector Version 3.8 or Tivoli Access Manager Version 3.9.

Unconfiguring an application serverThe -action unconfig option removes the user and server information from theuser registry, deletes the local keystore file and removes information for thisapplication from the configuration file but does not delete the configuration file.java com.tivoli.pd.jcfg.SvrSslCfg -action unconfig \

-admin_id sec_master -admin_pwd secpw \-appsvr_id PDPermissionjapp -host japp.myco.com \-policysvr ampolicy.myco.com:7135:1 \-cfg_file c:/am/configfile -key_file c:/am/keystore

Only if the caller is unauthorized does an unconfiguration operation fail. Errorsencountered during an unconfiguration are ignored to ensure that allunconfiguration steps are attempted. This allows unconfiguration to succeed evenif local configuration information or information in the user registry wasaccidentally deleted.

Adding a policy or authorization serverThe -action addsvr option adds a policy or authorization server to the applicationserver’s configuration file.


To add a policy server:java com.tivoli.pd.jcfg.SvrSslCfg -action addsvr \

-admin_id sec_master -admin_pwd secpw \-policysvr ampolicy3.myco.com:7135:3 \-cfg_file c:/am/configfile

To add an authorization server:java com.tivoli.pd.jcfg.SvrSslCfg -action addsvr \

-admin_id sec_master -admin_pwd secpw \-authzsvr am2azn.myco.com:7136:2 \-cfg_file c:/am/configfile

Removing a policy or authorization serverThe -action rmsvr option to remove a policy or authorization server from theconfiguration file.

To remove a policy server:java com.tivoli.pd.jcfg.SvrSslCfg -action rmsvr \

-policysvr ampolicy.myco.com:7135:1 \-cfg_file c:/am/configfile

To remove an authorization server:java com.tivoli.pd.jcfg.SvrSslCfg -action rmsvr \

-authzsvr amazn.myco.com:7136:1 \-cfg_file c:/am/configfile

Changing a policy or authorization serverThe -action chgsvr option to change a policy or authorization server in theconfiguration file.java com.tivoli.pd.jcfg.SvrSslCfg -action chgsvr \

-policysvr ampolicy2.myco.com:7135:2 \-cfg_file c:/am/configfile

orjava com.tivoli.pd.jcfg.SvrSslCfg -action chgsvr \

-authzsvr amazn.myco.com:7136:1 \-cfg_file c:/am/configfile

Replacing a certificateThe certificate in the keystore expires based on the certificate lifetime set on thepolicy server. After the certificate expires, the -action replcert option must be usedto generate a new certificate. The new certificate replaces the existing certificate inthe application server’s keystore file. The -action replcert option also can be usedto invalidate an existing certificate, which is useful should a certificate becomecompromised.java com.tivoli.pd.jcfg.SvrSslCfg -action replcert \

-admin_id sec_master -admin_pwd secpw \-appsvr_id PDPermissionjapp -cfg_file c:/am/configfile

Setting the portUse the -action setport option to set the port on which the application serverlistens. This only updates the application server’s configuration file.java com.tivoli.pd.jcfg.SvrSslCfg -action setport \

-port 4321 -cfg_file c:/am/configfile


Setting the database directoryUse the -action setdbdir option on local-mode application servers to set thedirectory where a local copy of the policy database is stored. This only updates theapplication server’s configuration file.java com.tivoli.pd.jcfg.SvrSslCfg -action setdbdir \

-dbdir c:/production/policy -cfg_file c:/am/configfile

Setting the database refresh intervalUse the -action setdbref option on local-mode application servers to set the refreshinterval for the local copy of the policy database. The time interval is specified inseconds. This only updates the application server’s configuration file. Thefollowing example sets the interval to every 60 minutes.java com.tivoli.pd.jcfg.SvrSslCfg -action setdbref \

-dbrefresh 3600 -cfg_file c:/am/configfile

Setting the application listening modeUse the -action setdblisten option on local-mode application servers to indicatewhether or not the application listens for policy database update notifications. Thisonly updates the application server’s configuration file.java com.tivoli.pd.jcfg.SvrSslCfg -action setdblisten \

-dblisten true -cfg_file c:/am/configfile


Chapter 3. Configuring the authorization API

After establishing SSL communications within the IBM Tivoli Access Manager(Tivoli Access Manager) secure domain, you can configure and customize the wayauthentication and authorization decisions are made.

This chapter covers the following topics:v “Configuring the Java Authentication and Authorization Service”v “Developing a resource manager” on page 18v “Making authorization decisions outside of Java 2” on page 18

Configuring the Java Authentication and Authorization ServiceThis section describes how to set up and use a login configuration file with theTivoli Access Manager authorization API Java classes. The Tivoli Access Managerconfiguration steps follow the configuration methods supported by the JavaAuthentication and Authorization Service (JAAS).

This section does not provide an overview of all of the JAAS configuration options.Tto review the JAAS configuration information, see the following Web site:http://java.sun.com/products/jaas

Complete the instructions in the following sections:v “Creating a login configuration file” on page 17v “Specify the login file location” on page 18

Creating a login configuration fileUse the sample file shown in Figure 1 as the basis for creating a loginconfiguration file for use with Tivoli Access Manager. No default loginconfiguration file is shipped as part of Tivoli Access Manager.

Note that the last stanza allows applications that use pd-nopass in theirLoginContext constructor to simply supply usernames but not passwords. Formore information, see the Javadoc information for com.tivoli.mts.PDLoginModule.

//// config.pd: Login configuration file for PDLoginModule

pd-debug {com.tivoli.mts.PDLoginModule required debug=true;

};

pd {com.tivoli.mts.PDLoginModule required;

};

pd-nopass {com.tivoli.mts.PDLoginModule required nameOnly=true;};

Figure 1. JAAS login configuration file


http://java.sun.com/products/jaas

Specify the login file locationChoose one of the following ways to specify the location of the login file:v Point to the login configuration file from the

JAVA_HOME/jre/lib/security/java.security file.For example, a sample entry from the java.security file might look like this:login.config.url.1=file:d:/Java/j131ibm/jre/lib/security/config.pd

v Specify the appropriate -D option on the java command line invocation, such as:–Djava.security.auth.login.config=./config.pd

For more information, see the JAAS configuration documentation.

Developing a resource managerA resource manager is a Java application that uses the JAAS and the Tivoli AccessManager authorization API Java classes to make access control decisions. Thesample code in Figure 2 illustrates the tasks that the resource manager mustperform.

Making authorization decisions outside of Java 2The Tivoli Access Manager authorization API Java classes also support acompletely Java-compliant usage of the Tivoli Access Manager authorization checkthat is outside of the Java 2 and JAAS framework.

// Identify the configuration status and callback routinelc = new LoginContext(“pd-debug”, np);

// Drive the login() and commit() methods of the LoginModule classlc.login();whoami = lc.getSubject();System.out.println(whoami);

// Become that userSubject.doAsPrivileged(whoami, new java.security.PrivilegedAction() {

public java.lang.Object run() {boolean worked;java.security.Permission perm = new PDPermission(“/test/private”, “a”);try {

// sm is a reference to a SecurityManagersm.checkPermission(perm);worked = true;

}catch (AccessControlException e) {

if (VERBOSE) e.printStackTrace();worked = false;

}if (worked) {

System.out.println(“user “ + user + “ has\”\””+perm.getActions()+”\” permission(s) to target“+perm.getName());

} else {System.out.println(“user “ + user + “ DOES NOT HAVE

\”\””+perm.getActions()+”\” permission(s) to target“+perm.getName());

}}

}, (java.security.AccessControlContext)null ) ;

Figure 2. Resource manager task example


The PDPrincipal class has one constructor that takes a name and password andauthenticates to Tivoli Access Manager as part of the construction of the object. ThePDPrincipal class also has a constructor that simply takes a name.

A security check is performed on the current environment when one is using theno-password version of the constructor. The permission that must be held is:permission javax.security.auth.AuthPermission “createPDPrincipal”

If authorized, the constructor retrieves the authentication information from TivoliAccess Manager for that entity. The names that are supported on these constructorscan either be Tivoli Access Manager short names, or distinguished names.

After you have constructed a PDPrincipal object for the specified entity, constructa PDPermission with the name of the requested resource, the protected object, andthe requested action to be performed on that object.

Then invoke the PDPrincipal.implies(PDPermission) method to determine if thespecified access to the specified object is allowed by the specified entity.

The sample in Figure 3 shows an example of how to perform these tasks.

Obtaining entitlements for a specified userThe authorization API supports a service plug-in model that enables developers toadd modules that extend the capabilities of Tivoli Access Manager. Theentitlements service plug-in is the only type of plug-in that is callable from a Javaapplication at this time.

An entitlements service plug-in enables domain-specific authorization APIapplications to retrieve the entitlements for a user from a domain-specific policyrepository. An entitlements service allows a third-party application running in thesecure domain to call a specific entitlements service based on its service ID. If noservice ID is provided, the default entitlements service plug-in is called. Anentitlements service plug-in, like other authorization service plug-ins, must beinstalled and configured before use.

Tivoli Access Manager provides a default entitlement service called the TivoliAccess Manager protected objects entitlements service that is specific to the TivoliAccess Manager environment. This entitlements service plug-in accepts a single,multi-valued string attribute that specifies one or more root nodes for searchingthe Tivoli Access Manager protected object space along with an indicator of whataccess permissions are required. The plug-in returns a multi-valued attribute list ofprotected objects meeting the search criteria.

PDPrincipal whoIsIt = new PDPrincipal(“tom”, “letmein”.toCharArray());PDPermission whatTheyWant = new PDPermission(“/everything”, “abT”);boolean haveAccess = whoIsIt.implies(whatTheyWant);if (haveAccess) {

// let them proceed...} else {

// deny the requested access}

Figure 3. Example showing authorization outside of Java 2

Chapter 3. Configuring the authorization API 19

This entitlement service can be called from a Java application by using thePDPrincipal.getEntitlements method, which is equivalent to using theazn_entitlements_get_entitlements() function from a C application. Figure 4 showsa call to the protected objects entitlements service requesting a list of objects in the/AppData/AccountData and /AppData/EmployeeData object trees to which theprincipal has view and modify permission.

The protected objects entitlements service returns a multi-valued attribute listconsisting of byte arrays or Strings representing the protected objects to which theprincipal has the desired access permission. The sample code in Figure 5demonstrates printing the results.

Additional information on the entitlements service plug-in as well as the othertypes of authorization service plug-ins can be found in the IBM Tivoli AccessManager Authorization C API Developer’s Reference.

PDAttrs attrsIn = new PDAttrs();PDAttrs attrsOut = new PDAttrs();

// Does user have view and modify access to desired resources?

attrsIn.add(PDStatics.AZN_ENT_SVC_PD_POBJ_PATH,"/AppData/AccountData");

attrsIn.add(PDStatics.AZN_ENT_SVC_PD_POBJ_PATH,"/AppData/EmployeeData");

attrsIn.add(PDStatics.AZN_ENT_SVC_PD_POBJ_REQD_OPS,"vm");

attrsOut = principal.getEntitlements(PDStatics.AZN_ENT_SVC_PD_POBJ,attrsIn);

// Is user entitled to anything?

PDAttrValues results = attrsOut.get(PDStatics.AZN_ENT_SVC_PD_POBJ_MATCHES);

if ((results == null) || (results.isEmpty())) {System.out.println("Nothing found.");break major;

}

// Process String or byte array results...

Figure 4. Using the PDPrincipal.getEntitlements method

// Process results of getEntitlements

PDAttrValues results = attrsOut.get(PDStatics.AZN_ENT_SVC_PD_POBJ_MATCHES);

if ((results == null) ||(results.isEmpty())) {System.out.println("Nothing found");break major;}

java.util.Iterator iter = results.iterator();

while (iter.hasNext()) {Object value = ((PDAttrValue)iter.next()).getValue();

System.out.println(value.toString());}

Figure 5. Processing protected objects returned


Chapter 4. Java classes overview

This chapter discusses the IBM Tivoli Access Manager (Tivoli Access Manager)authorization API Java classes:v “com.tivoli.mts.PDLoginModule” on page 21v “com.tivoli.mts.PDPrincipal” on page 21v “com.tivoli.mts.PDPermission” on page 22v “com.tivoli.mts.PDAttrs” on page 22v “com.tivoli.mts.PDAttrValue” on page 23v “com.tivoli.mts.PDAttrValues” on page 23v “com.tivoli.mts.PDStatics” on page 24v “com.tivoli.pd.jcfg.SvrSslCfg” on page 24

See the Javadoc information in the Tivoli Access Manager ADK for detailedinformation about all of these classes and their associated methods.

com.tivoli.mts.PDLoginModuleThis class knows how to authenticate to Tivoli Access Manager using a user nameand password. This class expects to be run inside the JAAS framework.public class PDLoginModule implements

javax.security.auth.spi.LoginModule{

public PDLoginModule()public login()public logout()public abort()public commit()public initialize(javax.security.auth.Subject subject,

javax.security.auth.callback.CallbackHandlercallbackHandler,

java.util.Map sharedState,java.util.Map options)

}

com.tivoli.mts.PDPrincipalThis class represents the identity of an Tivoli Access Manager user.public class PDPrincipal implements java.security.Principal,

com.ibm.security.auth.PrincipalComparator,java.io.Serializable {

public PDPrincipal()public PDPrincipal(String name)public PDPrincipal(String name, char[] password)public PDPrincipal(String name, char[] password, URL configURL)public PDPrincipal(String name, URL configURL)public PDPrincipal(URL configURL)public PDPrincipal addGroupMemberships(String service ID,

String[] groups)public boolean equals(Object o)public PDAttrs getEntitlements(String serviceID, PDAttrs attrsIn)public String getName()public int hashCode()


public String toString()public boolean implies(javax.security.auth.Subject subject)public boolean implies(PDPermission perm)public boolean implies(PDPermission perm,

PDAttrs attrsIn,PDAttrs attrsOut)

}

com.tivoli.mts.PDPermissionThis class knows how to check Tivoli Access Manager for specified actions.Resource managers and applications can create a subclass or use PDPermissiondirectly to get a Permission class. The Permission class is passed to Tivoli AccessManager as part of ajava.security.SecurityManager.checkPermission(perm)method invocation.public class PDPermission {

public PDPermission(java.lang.String rname,java.lang.String actions)

public boolean implies(java.security.Permission p)public boolean implies(PDPrincipal princ)public boolean implies(PDPrincipal princ,

PDAttrs inputList,PDAttrs, outputList)

public boolean equals(Object obj)public String getActions()public int hashCode()}

com.tivoli.mts.PDAttrsThis class represents an attribute list. Attribute lists are data types used by theTivoli Access Manager C API. Each attribute consists of entries that have a nameand one or more values. The names are Strings, and the values can be eitherStrings, byte arrays, or longs.public class PDAttrs extends java.lang.Objectimplements java.lang.Cloneable, java.io.Serializable {

public PDAttrs(boolean allowDuplicates)public PDAttrs(boolean allowDuplicates,

int initialCapacity)public PDAttrs(boolean allowDuplicates,

int initialCapacity,float loadFactor)

public PDAttrs(int initialCapacity)public PDAttrs(int initialCapacity, float loadFactor)public PDAttrs(PDAttrs that)public java.util.Collection add(java.lang.String name,

byte[] value)public java.util.Collection add(java.lang.String name,

java.util.Collection vals)public java.util.Collection add(java.lang.String name,

java.lang.long value)public java.util.Collection add(java.lang.String name,

java.lang.String value)public void addAll(PDAttrs attrs)public boolean allowDups()public void clear()public java.lang.Object clone()public boolean delete(java.lang.String key)public byte[] encode()public java.util.Set entrySet()public boolean equals(java.lang.Object obj)


public int getQop()public java.util.Collection getValues(java.lang.String key)public int hashCode()public java.util.Set keySet()public void setQop(int qop)public int size()public java.lang.String toString()

}

com.tivoli.mts.PDAttrValueThis class represents the value of an Tivoli Access Manager attribute. A value maybe either a String, a byte array, or a long.public class PDAttrValue extends java.lang.Object

implements java.lang.Cloneable, java.io.Serializable{

public PDAttrValue(byte[] bytes)public PDAttrValue(java.lang.Long ulong)public PDAttrValue(java.lang.String string)public java.lang.Object clone()public boolean equals(java.lang.Object iobj)public int getType()public java.lang.Object getValue()public int hashcode()public java.lang.String toString()

}

com.tivoli.mts.PDAttrValueListThis class represents a collection of values for a particular attribute in a PDAttr.This implementation is an ArrayList, so duplicates are permitted in a particularPDAttrValueList object and the values are ordered. A value may be either a String,a byte array, or a long.public class PDAttrValueList extends java.util.ArrayList


public PDAttrValueList()public PDAttrValueList(java.util.Collection c)public PDAttrValueList(int size)public void add(int index, java.lang.Object element)public boolean add(java.lang.Object element)public boolean addAll(java.util.Collection c)public boolean addAll(int index, java.util.Collection c)public java.lang.Object clone();public boolean equals(java.lang.Object obj)public int hashcode()public java.lang.Object set(int index, java.lang.Object element)public java.lang.String toString()

}

com.tivoli.mts.PDAttrValuesThis class represents a collection of values for a particular attribute in a PDAttr.This implementation is a Set, so duplicates are not allowed in a particularPDAttrValues object, and the values are not ordered. If duplicate values orordering of values are needed, use the PDAttrValueList class instead.public class PDAttrValues extends java.util.HashSet


Chapter 4. Java classes overview 23

public PDAttrValues()public PDAttrValues(java.util.Collection c)public PDAttrValues(int initialCapacity)public PDAttrValues(int initialCapacity,

float loadFactor)public boolean add(java.lang.Object obj)public boolean add(PDAttrValue value)public boolean addAll(java.util.Collection c)public java.lang.Object clone()public byte[] encode()public boolean equals(java.lang.Object obj)public int hashCode()public java.lang.String toString()

}

com.tivoli.mts.PDStaticsThis is a class for various constants used in the PDPermission class and otherassociated classes.public class PDStatics extends java.lang.Object {

public static final java.lang.String AZN_MOD_SVC_RAD_2ABpublic static final java.lang.String

AZN_MOD_RAD_GROUP_NAMESpublic static final java.lang.String AZN_ENT_SVC_PD_POBJpublic static final java.lang.String

AZN_ENT_SVC_PD_POBJ_PATHpublic static final java.lang.String

AZN_ENT_SVC_PD_POBJ_REQD_OPSpublic static final java.lang.String

AZN_ENT_SVC_PD_POBJ_MATCHESpublic static final int QOP_NONEpublic static final int QOP_INTEGRITYpublic static final int QOP_PRIVACYpublic static final int AZN_VALTYPE_BUFFERpublic static final int AZN_VALTYPE_UTF8STRING

}

com.tivoli.pd.jcfg.SvrSslCfgThis class is used to configure, unconfigure, and modify the configurationinformation associated with a Tivoli Access Manager Java application server.public class SvrSslCfg extends java.lang.Object {

public static void main (java.lang.String[] argv)throws PDException

}

Compatibility Note: The com.tivoli.mts.SvrSslCfg class has been deprecated inIBM Tivoli Access Manager. Existing applications shouldchange to use the new com.tivoli.pd.jcfg.SvrSslCfg class asthe deprecated class will be removed in a future version ofthe product.

After the successful configuration of a Tivoli Access Manager Java applicationserver, a user account and server entries representing the Java application serverare created in the Tivoli Access Manager user registry. In addition, a configurationfile and a Java keystore file, which securely stores a client certificate, are createdlocally on the application server. This client certificate permits callers to make


authenticated use of Tivoli Access Manager services. Conversely, unconfigurationremoves the user and server entries from the user registry and cleans up the localconfiguration and keystore files.

The contents of an existing configuration file can be modified by using theSvrSslCfg class.

A complete list of the actions available in the SvrSslCfg class are outlinedfollowing the description of the parameters in Table 3.

Note: The following options are parsed and processed into the configuration file,but are otherwise ignored in this version of Tivoli Access Manager:v –portv –mode localv –dblistenv –dbdirv –dbrefresh

Table 3. Description of SvrSslCfg Parameters

SvrSslCfg Parameter Value

–admin_id user_ID A Tivoli Access Manager user with administrativeprivileges.

–admin_pwd password Password associated with the Tivoli Access Manageradministrative user specified.

–appsvr_id name The name of the application server.

–port nnnnn The TCP/IP port which the application server listens tofor policy server notifications.

–mode { local | remote } Indicates whether the application server processesrequests remotely or locally.

–policysvr hostname:port:rank[,hostname2:port2:rank2...]

A list of Tivoli Access Manager policy servers to whichthe application server can communicate. Format of thisentry is host name, TCP/IP port number, and numericrank, separated by colons. Multiple servers can bespecified by separating them with commas.

For example, the following indicates two policy servers,both using default TCP/IP port 7135, are available:

primary.myco.com:7135:1,secondary.myco.com:7135:2

–authzsvr hostname:port:rank[,hostname2:port2:rank2...]

A list of Tivoli Access Manager authorization servers towhich the application server can communicate. Format ofthis entry is host name, TCP/IP port number, andnumeric rank, separated by colons. Multiple servers canbe specified by separating them with commas.

For example, the following indicates 2 authorizationservers, both using default TCP/IP port 7136, areavailable::

secazn.myco.com:7135:2,primazn.myco.com:7135:1

–cfg_file file_name Fully qualified name of the configuration file on theapplication server.

–key_file file_name Fully qualified name of the keystore file on theapplication server.


Table 3. Description of SvrSslCfg Parameters (continued)

SvrSslCfg Parameter Value

–appsvr_pwd password The password for the user account in the user registryassociated with the application server. If specified, thepassword must meet the current password rules in effect.If omitted, a default password is automaticallygenerated.

–host host_name Host name of the application server.

–dblisten { true | false } Indicates whether or not the application server listens forpolicy database updates. Default is false.

–dbdir directory_name The name of the directory to be used for the local copyof the policy database. If omitted, the same directory asthe –key_file is used.

–dbrefresh nnnnn Indicates the time interval, in seconds, that theapplication server polls the policy server for policydatabase updates. Value must be greater than or equal tozero. Default is 7200 seconds, or every 2 hours.

–cfg_action { create | replace } Indicated whether the configuration and keystore filesshould be created on the application server or replaced.The default is replace. If the create option is specifiedbut the files already exist, an exception is raised.

–action configConfigures an application server. Configuring a server creates user and serverinformation in the user registry and creates local configuration and keystore fileson the application server. Use the –action unconfig option to reverse thisoperation.java com.tivoli.pd.jcfg.SvrSslCfg -action config

-admin_id admin_user_ID-admin_pwd admin_password-appsvr_id application_server_name-appsvr_pwd application_server_password-port port_number-mode { local | remote }-host Host_name_of_application_server-policysvr policy_server_name:port:rank [,...]-authzsvr authorization_server_name:port:rank [,...]-cfg_file fully_qualified_name_of_configuration_file-key_file fully_qualified_name_of_keystore_file-cfg_action { create | replace }

–action unconfigUnconfigures an application server. Removes the user and server information fromthe user registry, deletes the local keystore file and removes information for thisapplication from the configuration file but does not delete the configuration file.Only if the caller is unauthorized does an unconfiguration operation fail. Errorsencountered during an unconfiguration are ignored to ensure that allunconfiguration steps are attempted. This allows unconfiguration to succeed evenif local configuration information or information in the user registry wasaccidentally deleted.java com.tivoli.pd.jcfg.SvrSslCfg -action unconfig

-admin_id admin_user_ID-admin_pwd admin_password-appsvr_id application_server_name-host Host_name_of_application_server


-policysvr policy_server_name:port:rank [,...]-authzsvr authorization_server_name:port:rank [,...]-cfg_file fully_qualified_name_of_configuration_file-key_file fully_qualified_name_of_keystore_file

–action addsvrAdds a policy or authorization server to the application server’s configuration file.java com.tivoli.pd.jcfg.SvrSslCfg -action addsvr

-policysvr policy_server_name-authzsvr authorization_server_name-cfg_file fully_qualified_name_of_configuration_file

–action rmsvrRemoves a policy or authorization server from the application server’sconfiguration file.java com.tivoli.pd.jcfg.SvrSslCfg -action rmsvr


–action chgsvrChange a policy or authorization server in the application server’s configurationfile.java com.tivoli.pd.jcfg.SvrSslCfg -action chgsvr


–action replcertReplace a certificate in the application server’s keystore file.The certificate in thekeystore expires based on the certificate lifetime set on the policy server. After thecertificate expires, the -action replcert option must be used to generate a newcertificate. The -action replcert option also can be used to invalidate an existingcertificate, which is useful should a certificate become compromised.java com.tivoli.pd.jcfg.SvrSslCfg -action replcert

-admin_id admin_user_ID-admin_pwd admin_password-appsvr_id application_server_name-cfg_file fully_qualified_name_of_configuration_file

–action setportSets the port on which the application server listens for policy databasenotifications. This only updates the application server’s configuration file.java com.tivoli.pd.jcfg.SvrSslCfg -action setport

-port port_number-cfg_file fully_qualified_name_of_configuration_file

–action setdbdirSets the database directory. This only updates the application server’s configurationfile.java com.tivoli.pd.jcfg.SvrSslCfg -action setdbdir

-dbdir name_of_directory_for_local_policy_database-cfg_file fully_qualified_name_of_configuration_file


–action setdbrefSets the database refresh interval, in seconds. This only updates the applicationserver’s configuration file.java com.tivoli.pd.jcfg.SvrSslCfg -action setdbref

-dbrefresh refresh_interval_in_seconds-cfg_file fully_qualified_name_of_configuration_file

–action setdblistenSets the application listening mode. This only updates the application server’sconfiguration file.java com.tivoli.pd.jcfg.SvrSslCfg -action setdblisten

-dblisten { true | false }-cfg_file fully_qualified_name_of_configuration_file


Chapter 5. Upgrade considerations

Review Appendix A, “Deprecated Java classes and methods”, on page 31 beforemaking changes to an existing Java application. A number of classes and methodshave been deprecated in this version of IBM Tivoli Access Manager (Tivoli AccessManager).

Existing Java applications built using the authorization API provided in TivoliSecureWay® Policy Director Version 3.8 need to be aware of the following changesintroduced in Tivoli Access Manager.1. The authorization ADK is now called the Tivoli Access Manager ADK and only

contains the Javadoc information associated with the Java classes and methods.The authorization API Java classes and methods are provided as part of theTivoli Access Manager Java runtime component. Both of these components areinstallable from the Tivoli Access Manager base product CD.

2. The PD.jar file replaces the PDPerm.jar file that was provided in TivoliSecureWay Policy Director. The PD.jar file contains the definitions for both theauthorization Java classes as well as the administration Java classes.

3. You no longer need to copy the JAR files or make changes to the CLASSPATHenvironment variable to use Tivoli Access Manager Java classes and methods.The pdjrtecfg command line interface is used to make the Tivoli AccessManager JAR files available to one or more JREs on a system. See the IBMTivoli Access Manager Command Reference for information on the pdjrtecfgcommand.

4. In Tivoli SecureWay Policy Director, two pdadmin commands had to be enteredon the policy server before using the SvrSslCfg class to create configurationfiles. The SvrSslCfg class now automatically creates the desired PDPrincipalobject on the policy server.


Appendix A. Deprecated Java classes and methods

The classes and methods listed in Table 4 have been deprecated in IBM TivoliAccess Manager Version 4.1. Existing Java applications should be changed to usethe replacement class or method indicated.

Table 4. Deprecated Java Classes and Methods

Deprecated Class or Method Replacement Class or Method

com.tivoli.mts.PDAttrs( ) com.tivoli.mts.PDAttrs(boolean allowDuplicates)

com.tivoli.mts.PDAttrs.add(java.lang.String name,PDAttrValues vals)

com.tivoli.mts.PDAttrs.add( java.lang.String name,java.util.Collection vals)

com.tivoli.mts.PDAttrs.get( java.lang.String key) com.tivoli.mts.PDAttrs.getValues(java.lang.String key)

com.tivoli.mts.SvrSslCfg com.tivoli.pd.jcfg.SvrSslCfg


Appendix B. Notices

This information was developed for products and services offered in the U.S.A.

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

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

IBM Director of LicensingIBM CorporationNorth Castle DriveArmonk, NY 10504-1785U.S.A.

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

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

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

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

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

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


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

IBM Corporation2Z4A/10111400 Burnet RoadAustin, TX 78758U.S.A.

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

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

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

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

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

COPYRIGHT LICENSE:

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

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

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


AIXDB2IBMIBM logoOS/390SecureWayTivoliTivoli logoUniversal DatabaseWebSpherez/OSzSeries

Lotus is a registered trademark of Lotus Development Corporation and/or IBMCorporation.

Domino is a trademark of International Business Machines Corporation and LotusDevelopment Corporation in the United States, other countries, or both.

Microsoft and Windows are trademarks of Microsoft Corporation in the UnitedStates, other countries, or both.

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

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

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

Appendix B. Notices 35

Index

Aadding development systems 2application, deploying 4applications, building 2Authorization API

installing 2authorization server 1, 4azn_entitlements_get_entitlements() function 19

Bbuilding applications 2

Cclasses

PDAttrs 22PDAttrValue 23PDAttrValueList 23PDAttrValues 23PDLoginModule 21PDPermission 22PDPrincipal 21PDStatics 24SvrSslCfg 24

com.tivoli.nts.PDAttrs.get() 31com.tivoli.nts.PDAttrs() 31com.tivoli.nts.SrvSslCfg() 31com.tivoli.pd.jcfg.SvrSslCfg class 24

Ddeploying an application 4deprecated classes and methods 31

com.tivoli.nts.PDAttrs.get() 31com.tivoli.nts.PDAttrs() 31com.tivoli.nts.SrvSslCfgs() 24, 31

development systems, adding 2

Eentitlements 19entitlements service plug-in 19

Ffiles, installation directories 1

IIBM Directory client 3installation 2installation directories 1installation requirements 2

JJava classes 1

PPD.jar file 2pdacld server 4PDAttrs class 22PDAttrValue class 23PDAttrValueList class 23PDAttrValues class 23PDLoginModule class 21pdmgrd server 4PDPermission class 22PDPrincipal class 21PDStatics class 24policy server 4problem determination 4protected objects entitlements service 19

Rregistry, user 3related publications xiirequirements, for installation 2

Ssecure domain 2service plug-ins 19signed JAR files 3software requirements 2SSL 1SvrSslCfg class 24

adding a policy or authorization server 13changing a policy or authorization server 14configuring a server in local mode 13configuring a server in remote mode 12removing a policy or authorization server 14replacing a certificate 14setting the application listening mode 15setting the database directory 15setting the database refresh interval 15setting the port 14unconfiguring an application server 13

Uuser registry 3


��

Printed in U.S.A.

SC32-1141-01

authorization java classes developer’s...

Documents