Administration Java Classes Developer Reference

Transcription

1 IBM Tioli Access Manager for e-business Administration Jaa Classes Deeloper Reference Version 5.1 SC

2

3 IBM Tioli Access Manager for e-business Administration Jaa Classes Deeloper Reference Version 5.1 SC

4 Note: Before using this information and the product it supports, read the information in Appendix E, Notices, on page 87. First Edition (Noember 2003) This edition applies to ersion 5, release 1, modification 0 of IBM Tioli Access Manager (product number 5724-C08) and to all subsequent releases and modifications until otherwise indicated in new editions. Copyright International Business Machines Corporation 2002, All rights resered. US Goernment Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

5 Contents Preface ii Who should read this book ii What this book contains ii Publications ix Release information ix Base information ix Web security information x Deeloper references x Technical supplements xi Related publications xi Accessing publications online xi Accessibility x Contacting software support x Conentions used in this book x Typeface conentions x User registry differences x Operating system differences xi Chapter 1. Introducing the administration API Administration Jaa classes oeriew Other ways to manipulate administration objects Jaa administration API components Application deelopment kit Building Jaa applications with the administration API IBM Tioli Access Manager software requirements Configuring the Jaa runtime component to a particular Jaa runtime enironment Configuring to use the Jaa administration classes Security requirements Jaa administration API example program Deploying a Jaa administration API application Gathering problem determination information Enabling tracing on the policy serer Enabling tracing on the authorization serer Enabling tracing in the Jaa runtime component Gathering message logs Gathering trace logs Chapter 2. Using the administration API Administration objects Common classes Initializing the administration API Establishing a security context User ID and password-based authentication Certificate-based authentication Manipulating administration objects Creating objects Obtaining a local copy of an object Reading object alues Setting object alues Listing objects Deleting objects Messages Handling errors Shutting down the administration API Character-based data considerations Copyright IBM Corp. 2002, 2003 iii

6 Chapter 3. Administering users and groups Administering users Administering user information Administering user account policies Administering user password policies Administering groups Administering group information Chapter 4. Administering protected objects and protected object spaces Administering protected object spaces Administering protected objects Administering protected object attributes Chapter 5. Administering access control Administering access control lists Administering access control list entries Administering access control list extended attributes Administering action groups Administering extended actions Chapter 6. Administering protected object policies Administering protected object policy objects PDPop.IPAuthInfo object Administering protected object policy settings Administering protected object policy extended attributes Chapter 7. Administering authorization rules Chapter 8. Administering single signon resources Administering Web resources Administering resource groups Administering resource credentials Chapter 9. Administering domains Chapter 10. Configuring application serers Configuring application serers Administering configuration information Certificate maintenance Chapter 11. Administering serers Getting and performing administration tasks Notifying replica databases when the master authorization database is updated Notifying replica databases automatically Notifying replica databases manually Setting the maximum number of notification threads Setting the notification wait time Administrating serers and database notification Appendix A. Differences between the C and Jaa administration API Security context management differences Response processing differences Additional differences Appendix B. Deprecated Jaa classes and methods Appendix C. User registry differences i IBM Tioli Access Manager for e-business: Administration Jaa Classes Deeloper Reference

7 Appendix D. Administration API equialents Appendix E. Notices Trademarks Glossary Index Contents

8 i IBM Tioli Access Manager for e-business: Administration Jaa Classes Deeloper Reference

9 Preface Who should read this book IBM Tioli Access Manager (Tioli Access Manager) is the base software that is required to run applications in the IBM Tioli Access Manager product suite. It enables the integration of IBM Tioli Access Manager applications that proide a wide range of authorization and management solutions. Sold as an integrated solution, these products proide an access control management solution that centralizes network and application security policy for e-business applications. Note: IBM Tioli Access Manager is the new name of the preiously released software entitled Tioli SecureWay Policy Director. Also, for users familiar with the Tioli SecureWay Policy Director software and documentation, the management serer is now referred to as the policy serer. This reference contains information about how to use Tioli Access Manager administration Jaa classes and methods to enable an application to programmatically perform Tioli Access Manager administration tasks. This document describes the Jaa implementation of the Tioli Access Manager administration API. See the IBM Tioli Access Manager for e-business Administration C API Deeloper Reference for information regarding the C implementation of these APIs. Information on the pdadmin command line interface (CLI) can be found in the IBM Tioli Access Manager for e-business Command Reference. This reference is for application programmers implementing programs in the Jaa programming language to administer the users and objects associated with the IBM Tioli Access Manager product. Readers should be familiar with the following: PC and UNIX operating systems Database architecture and concepts Security management What this book contains Internet protocols, including HTTP, TCP/IP, File Transfer Protocol (FTP), and Telnet The user registry that Tioli Access Manager is configured to use Lightweight Directory Access Protocol (LDAP) and directory serices, if used by your user registry Authentication and authorization If you are enabling Secure Sockets Layer (SSL) communication, you also should be familiar with SSL protocol, key exchange (public and priate), digital signatures, cryptographic algorithms, and certificate authorities. This reference contains the following chapters and appendixes: Chapter 1, Introducing the administration API, on page 1 Copyright IBM Corp. 2002, 2003 ii

10 Proides an oeriew of the administration API and its components. It also coers building applications with the API and deploying an administration API program. Chapter 2, Using the administration API, on page 9 Each application that uses the administration API must perform certain tasks necessary for API initialization, shut down, and error handling. This chapter describes the supported methods for establishing security contexts, creating objects, setting object alues, reading object alues, listing object information, deleting objects, handling errors, and shutting down. Chapter 3, Administering users and groups, on page 19 The administration API proides a collection of methods for administering Tioli Access Manager users and groups. This chapter describes the tasks that those methods accomplish. It describes the supported methods for administering users, user accounts, user passwords, groups, group attributes, and the policies associated with users. Chapter 4, Administering protected objects and protected object spaces, on page 25 This chapter describes the administration API methods that are used to administer protected object spaces and protected objects. It describes the supported methods for administering protected object spaces, protected objects, and protected object attributes. Chapter 5, Administering access control, on page 29 This chapter describes the administration API methods that are used to administer access control. It describes the supported methods for administering access control lists, access control list entries, and access control list extended attributes. Chapter 6, Administering protected object policies, on page 35 This chapter describes the administration API methods that are used to create, modify, examine, and delete protected object policies. It also discusses attaching or detaching protected objects from protected object policies. It describes the supported functions for administering protected object policy objects, protected object policy settings, and protected object policy extended attributes. Chapter 7, Administering authorization rules, on page 39 This chapter proides instructions for using the administration API to create, delete, list, and modify authorization rules. Chapter 8, Administering single signon resources, on page 41 This chapter proides instructions for using the administration API to create, modify, or delete web resources, resource groups, and resource credentials. Chapter 9, Administering domains, on page 45 This chapter proides instructions for using the administration API to create, delete, list, and modify Tioli Access Manager policy serer domains. Chapter 11, Administering serers, on page 49 This chapter proides information about getting and performing administration tasks and notifying the replica database when the master authorization database is updated. Chapter 10, Configuring application serers, on page 47 This chapter proides instructions for using the administration API to configure serers, modify serer configurations, administer replicas, and perform certificate maintenance. Appendix A, Differences between the C and Jaa administration API, on page 53 iii IBM Tioli Access Manager for e-business: Administration Jaa Classes Deeloper Reference

11 This appendix outlines the differences between the administration C API functions and the administration Jaa classes and methods. Appendix B, Deprecated Jaa classes and methods, on page 55 This appendix proides a list of the Jaa classes and methods that hae been deprecated in this ersion of Tioli Access Manager. Appendix C, User registry differences, on page 57 This appendix outlines the differences in behaior of the classes and methods based on the user registry being used by Tioli Access Manager. Appendix D, Administration API equialents, on page 61 This appendix shows the mapping that exists between the Administration C APIs, the Administration Jaa classes and methods, and the command line interface (CLI). Appendix E, Notices, on page 87 This appendix proides copyright, legal, and trademark information. Publications Reiew the descriptions of the Tioli Access Manager library, the prerequisite publications, and the related publications to determine which publications you might find helpful. After you determine the publications you need, refer to the instructions for accessing publications online. Additional information about the IBM Tioli Access Manager for e-business product itself can be found at: The Tioli Access Manager library is organized into the following categories: Release information Base information Web security information on page x Deeloper references on page x Technical supplements on page xi Release information IBM Tioli Access Manager for e-business Read This First (GI ) Proides information for installing and getting started using Tioli Access Manager. IBM Tioli Access Manager for e-business Release Notes (GI ) Proides late-breaking information, such as software limitations, workarounds, and documentation updates. Base information IBM Tioli Access Manager Base Installation Guide (SC ) Explains how to install and configure the Tioli Access Manager base software, including the Web Portal Manager interface. This book is a subset of IBM Tioli Access Manager for e-business Web Security Installation Guide and is intended for use with other Tioli Access Manager products, such as IBM Tioli Access Manager for Business Integration and IBM Tioli Access Manager for Operating Systems. Preface ix

12 IBM Tioli Access Manager Base Administration Guide (SC ) Describes the concepts and procedures for using Tioli Access Manager serices. Proides instructions for performing tasks from the Web Portal Manager interface and by using the pdadmin command. Web security information IBM Tioli Access Manager for e-business Web Security Installation Guide (SC ) Proides installation, configuration, and remoal instructions for the Tioli Access Manager base software as well as the Web Security components. This book is a superset of IBM Tioli Access Manager Base Installation Guide. IBM Tioli Access Manager Upgrade Guide (SC ) Explains how to upgrade from Tioli SecureWay Policy Director Version 3.8 or preious ersions of Tioli Access Manager to Tioli Access Manager Version 5.1. IBM Tioli Access Manager for e-business WebSEAL Administration Guide (SC ) Proides background material, administratie procedures, and technical reference information for using WebSEAL to manage the resources of your secure Web domain. IBM Tioli Access Manager for e-business IBM WebSphere Application Serer Integration Guide (SC ) Proides installation, remoal, and administration instructions for integrating Tioli Access Manager with IBM WebSphere Application Serer. IBM Tioli Access Manager for e-business IBM WebSphere Edge Serer Integration Guide (SC ) Proides installation, remoal, and administration instructions for integrating Tioli Access Manager with the IBM WebSphere Edge Serer application. IBM Tioli Access Manager for e-business Plug-in for Web Serers Integration Guide (SC ) Proides installation instructions, administration procedures, and technical reference information for securing your Web domain using the plug-in for Web serers. IBM Tioli Access Manager for e-business BEA WebLogic Serer Integration Guide (SC ) Proides installation, remoal, and administration instructions for integrating Tioli Access Manager with BEA WebLogic Serer. IBM Tioli Access Manager for e-business IBM Tioli Identity Manager Proisioning Fast Start Guide (SC ) Proides an oeriew of the tasks related to integrating Tioli Access Manager and Tioli Identity Manager and explains how to use and install the Proisioning Fast Start collection. Deeloper references IBM Tioli Access Manager for e-business Authorization C API Deeloper Reference (SC ) Proides reference material that describes how to use the Tioli Access Manager authorization C API and the Tioli Access Manager serice plug-in interface to add Tioli Access Manager security to applications. x IBM Tioli Access Manager for e-business: Administration Jaa Classes Deeloper Reference

13 IBM Tioli Access Manager for e-business Authorization Jaa Classes Deeloper Reference (SC ) Proides reference information for using the Jaa language implementation of the authorization API to enable an application to use Tioli Access Manager security. IBM Tioli Access Manager for e-business Administration C API Deeloper Reference (SC ) Proides reference information about using the administration API to enable an application to perform Tioli Access Manager administration tasks. This document describes the C implementation of the administration API. IBM Tioli Access Manager for e-business Administration Jaa Classes Deeloper Reference (SC ) Proides reference information for using the Jaa language implementation of the administration API to enable an application to perform Tioli Access Manager administration tasks. IBM Tioli Access Manager for e-business Web Security Deeloper Reference (SC ) Proides administration and programming information for the cross-domain authentication serice (CDAS), the cross-domain mapping framework (CDMF), and the password strength module. Technical supplements IBM Tioli Access Manager for e-business Command Reference (SC ) Proides information about the command line utilities and scripts proided with Tioli Access Manager. IBM Tioli Access Manager Error Message Reference (SC ) Proides explanations and recommended actions for the messages produced by Tioli Access Manager. IBM Tioli Access Manager for e-business Problem Determination Guide (SC ) Proides problem determination information for Tioli Access Manager. IBM Tioli Access Manager for e-business Performance Tuning Guide (SC ) Proides performance tuning information for an enironment consisting of Tioli Access Manager with the IBM Tioli Directory serer as the user registry. Related publications This section lists publications related to the Tioli Access Manager library. The Tioli Software Library proides a ariety of Tioli publications such as white papers, datasheets, demonstrations, redbooks, and announcement letters. The Tioli Software Library is aailable on the Web at: The Tioli Software Glossary includes definitions for many of the technical terms related to Tioli software. The Tioli Software Glossary is aailable, in English only, from the Glossary link on the left side of the Tioli Software Library Web page IBM Global Security Kit Tioli Access Manager proides data encryption through the use of the IBM Global Security Kit (GSKit) Version 7.0. GSKit is included on the IBM Tioli Access Manager Base CD for your particular platform, as well as on the IBM Tioli Access Manager Preface xi

14 Web Security CDs, the IBM Tioli Access Manager Web Administration Interfaces CDs, and the IBM Tioli Access Manager Directory Serer CDs. The GSKit package proides the ikeyman key management utility, gsk7ikm, which is used to create key databases, public-priate key pairs, and certificate requests. The following document is aailable on the Tioli Information Center Web site in the same section as the IBM Tioli Access Manager product documentation: IBM Global Security Kit Secure Sockets Layer and ikeyman User s Guide (SC ) Proides information for network or system security administrators who plan to enable SSL communication in their Tioli Access Manager enironment. IBM Tioli Directory Serer IBM Tioli Directory Serer, Version 5.2, is included on the IBM Tioli Access Manager Directory Serer CD for the desired operating system. Note: IBM Tioli Directory Serer is the new name for the preiously released software known as: IBM Directory Serer (Version 4.1 and Version 5.1) IBM SecureWay Directory Serer (Version 3.2.2) IBM Directory Serer Version 4.1, IBM Directory Serer Version 5.1, and IBM Tioli Directory Serer Version 5.2 are all supported by IBM Tioli Access Manager Version 5.1. Additional information about IBM Tioli Directory Serer can be found at: IBM DB2 Uniersal Database IBM DB2 Uniersal Database Enterprise Serer Edition, Version 8.1 is proided on the IBM Tioli Access Manager Directory Serer CD and is installed with the IBM Tioli Directory Serer software. DB2 is required when using IBM Tioli Directory Serer, z/os, or OS/390 LDAP serers as the user registry for Tioli Access Manager. Additional information about DB2 can be found at: IBM WebSphere Application Serer IBM WebSphere Application Serer, Adanced Single Serer Edition 5.0, is included on the IBM Tioli Access Manager Web Administration Interfaces CD for the desired operating system. WebSphere Application Serer enables the support of both the Web Portal Manager interface, which is used to administer Tioli Access Manager, and the Web Administration Tool, which is used to administer IBM Tioli Directory Serer. IBM WebSphere Application Serer Fix Pack 2 is also required by Tioli Access Manager and is proided on the IBM Tioli Access Manager WebSphere Fix Pack CD. Additional information about IBM WebSphere Application Serer can be found at: xii IBM Tioli Access Manager for e-business: Administration Jaa Classes Deeloper Reference

15 IBM Tioli Access Manager for Business Integration IBM Tioli Access Manager for Business Integration, aailable as a separately orderable product, proides a security solution for IBM MQSeries, Version 5.2, and IBM WebSphere MQ for Version 5.3 messages. IBM Tioli Access Manager for Business Integration allows WebSphere MQSeries applications to send data with priacy and integrity by using keys associated with sending and receiing applications. Like WebSEAL and IBM Tioli Access Manager for Operating Systems, IBM Tioli Access Manager for Business Integration, is one of the resource managers that use the serices of IBM Tioli Access Manager. Additional information about IBM Tioli Access Manager for Business Integration can be found at: The following documents associated with IBM Tioli Access Manager for Business Integration Version 5.1 are aailable on the Tioli Information Center Web site: IBM Tioli Access Manager for Business Integration Administration Guide (SC ) IBM Tioli Access Manager for Business Integration Problem Determination Guide (GC ) IBM Tioli Access Manager for Business Integration Release Notes (GI ) IBM Tioli Access Manager for Business Integration Read This First (GI ) IBM Tioli Access Manager for WebSphere Business Integration Brokers IBM Tioli Access Manager for WebSphere Business Integration Brokers, aailable as part of IBM Tioli Access Manager for Business Integration, proides a security solution for WebSphere Business Integration Message Broker, Version 5.0 and WebSphere Business Integration Eent Broker, Version 5.0. IBM Tioli Access Manager for WebSphere Business Integration Brokers operates in conjunction with Tioli Access Manager to secure JMS publish/subscribe applications by proiding password and credentials-based authentication, centrally-defined authorization, and auditing serices. Additional information about IBM Tioli Access Manager for WebSphere Integration Brokers can be found at: The following documents associated with IBM Tioli Access Manager for WebSphere Integration Brokers, Version 5.1 are aailable on the Tioli Information Center Web site: IBM Tioli Access Manager for WebSphere Business Integration Brokers Administration Guide (SC ) IBM Tioli Access Manager for WebSphere Business Integration Brokers Release Notes (GI ) IBM Tioli Access Manager for Business Integration Read This First (GI ) IBM Tioli Access Manager for Operating Systems IBM Tioli Access Manager for Operating Systems, aailable as a separately orderable product, proides a layer of authorization policy enforcement on UNIX systems in addition to that proided by the natie operating system. IBM Tioli Preface xiii

16 Access Manager for Operating Systems, like WebSEAL and IBM Tioli Access Manager for Business Integration, is one of the resource managers that use the serices of IBM Tioli Access Manager. Additional information about IBM Tioli Access Manager for Operating Systems can be found at: The following documents associated with IBM Tioli Access Manager for Operating Systems Version 5.1 are aailable on the Tioli Information Center Web site: IBM Tioli Access Manager for Operating Systems Installation Guide (SC ) IBM Tioli Access Manager for Operating Systems Administration Guide (SC ) IBM Tioli Access Manager for Operating Systems Problem Determination Guide (SC ) IBM Tioli Access Manager for Operating Systems Release Notes (GI ) IBM Tioli Access Manager for Operating Systems Read Me First (GI ) IBM Tioli Identity Manager IBM Tioli Identity Manager Version 4.5, aailable as a separately orderable product, enables you to centrally manage users (such as user IDs and passwords) and proisioning (that is proiding or reoking access to applications, resources, or operating systems.) Tioli Identity Manager can be integrated with Tioli Access Manager through the use of the Tioli Access Manager Agent. Contact your IBM account representatie for more information about purchasing the Agent. Additional information about IBM Tioli Identity Manager can be found at: Accessing publications online The publications for this product are aailable online in Portable Document Format (PDF) or Hypertext Markup Language (HTML) format, or both in the Tioli software library: To locate product publications in the library, click the Product manuals link on the left side of the library page. Then, locate and click the name of the product on the Tioli software information center page. Product publications include release notes, installation guides, user s guides, administrator s guides, and deeloper s references. Note: To ensure proper printing of PDF publications, select the Fit to page check box in the Adobe Acrobat Print window (which is aailable when you click File Print). xi IBM Tioli Access Manager for e-business: Administration Jaa Classes Deeloper Reference

17 Accessibility Contacting software support Accessibility features help a user who has a physical disability, such as restricted mobility or limited ision, to use software products successfully. With this product, you can use assistie technologies to hear and naigate the interface. You also can use the keyboard instead of the mouse to operate all features of the graphical user interface. Before contacting IBM Tioli Software Support with a problem, refer to the IBM Tioli Software Support site by clicking the Tioli support link at the following Web site: If you need additional help, contact software support by using the methods described in the IBM Software Support Guide at the following Web site: The guide proides the following information: Conentions used in this book Registration and eligibility requirements for receiing support Telephone numbers, depending on the country in which you are located A list of information you should gather before contacting customer support This reference uses seeral conentions for special terms and actions and for operating system-dependent commands and paths. Typeface conentions The following typeface conentions are used in this reference: Bold Italic Lowercase commands or mixed case commands that are difficult to distinguish from surrounding text, keywords, parameters, options, names of Jaa classes, and objects are in bold. Variables, titles of publications, and special words or phrases that are emphasized are in italic. Monospace Code examples, command lines, screen output, file and directory names that are difficult to distinguish from surrounding text, system messages, text that the user must type, and alues for arguments or command options are in monospace. User registry differences Tioli Access Manager supports a number of different user registries. In most cases, the behaior of Tioli Access Manager is the same regardless of what user registry is in use. Howeer, there are seeral cases where the processing of a gien method differs based on what user registry is being used. A note similar to the following highlights these differences: User registry difference: This text would describe the different behaior based on the user registry in use. Preface x

18 See Appendix C, User registry differences, on page 57 for a complete list of known differences. Operating system differences This book uses the UNIX conention for specifying enironment ariables and for directory notation. When using the Windows command line, replace $ariable with %ariable% for enironment ariables and replace each forward slash (/) with a backslash (\) in directory paths. If you are using the bash shell on a Windows system, you can use the UNIX conentions. xi IBM Tioli Access Manager for e-business: Administration Jaa Classes Deeloper Reference

19 Chapter 1. Introducing the administration API The IBM Tioli Access Manager (Tioli Access Manager) Jaa runtime component includes the Jaa language ersion of the Tioli Access Manager administration API. The Tioli Access Manager Jaa runtime component proides a set of Jaa classes and methods for the administration of selected Tioli Access Manager administration objects. These classes and methods proide a way for applications to administer users, groups, protected objects, and access control lists. You can use the Tioli Access Manager application deeloper kit (ADK) to enable your application to programmatically administer Tioli Access Manager administration objects. This chapter contains the following topics: Administration Jaa classes oeriew Jaa administration API components on page 2 Building Jaa applications with the administration API on page 3 Jaa administration API example program on page 5 Deploying a Jaa administration API application on page 5 Gathering problem determination information on page 5 Note: If you are familiar with the C language interface to the Tioli Access Manager administration API, see Appendix A, Differences between the C and Jaa administration API, on page 53 for a general oeriew of differences. A mapping of C APIs to Jaa classes and methods can be found in Appendix D, Administration API equialents, on page 61. Administration Jaa classes oeriew The administration Jaa classes can be used to administer the following types of objects: Policies Users Groups Access control lists (ACLs) Extended ACL actions Protected object policies (POPs) Protected objects Protected object spaces Authorization rules Domains Web, or single signon (SSO), resources Web resource groups Resource credentials A set of Jaa classes are proided for creating, modifying, examining, listing, and deleting each of the preceding object types. The classes include the methods necessary for manipulating each of these administration objects. These Copyright IBM Corp. 2002,

20 administration Jaa classes are packaged in the PD.jar file that is installed as part of the Tioli Access Manager Jaa runtime enironment component. Applications using the Jaa runtime enironment proided with Tioli Access Manager automatically hae access to these classes and methods. The administration API Jaa classes communicate directly with the Tioli Access Manager policy serer component. The API establishes an authenticated, Secure Sockets Layer (SSL) session with the Tioli Access Manager policy serer process. After the SSL session is established, the classes can send administration requests to the policy serer. The Tioli Access Manager policy serer component serices these requests in the same manner that it would serice any other incoming requests. System administrators also can use the pdadmin command line interface to accomplish Tioli Access Manager administration tasks. The Jaa administration classes and methods map closely to these commands. Appendix D, Administration API equialents, on page 61 describes the commands that match Jaa administration API methods. Some Jaa methods do not hae a pdadmin command line equialent. Note: The srsslcfg command line interface should not be used with Jaa applications. Use the SrSslCfg Jaa class to proide this functionality. Other ways to manipulate administration objects In addition to using the Jaa administration APIs to manipulate these objects, you also can use the following methods: pdadmin command line interface (CLI) The pdadmin command line interface is explained in the IBM Tioli Access Manager for e-business Command Reference. Administration C API The administration C API proides support for these administration objects. Refer to the IBM Tioli Access Manager for e-business Administration C API Deeloper Reference for details. Jaa administration API components The administration API consists of the following components: The administration Jaa classes Jaadoc information for the associated Jaa classes and methods A demonstration application Application deelopment kit The administration API Jaa classes are distributed in the Tioli Access Manager Jaa runtime component for each platform. The remainder of the administration API components are distributed in the Tioli Access Manager Application Deeloper Kit component. The Jaadoc information associated with the administration Jaa classes and methods as well as examples are proided as part of the Tioli Access Manager application deeloper kit (ADK) component package. 2 IBM Tioli Access Manager for e-business: Administration Jaa Classes Deeloper Reference

21 Table 1 lists the files that are installed as part of the Tioli Access Manager ADK component. The PD.jar file, een though it is installed as part of the Tioli Access Manager Jaa runtime component, is listed in the table for completeness. Table 1. Administration API application deelopment kit files Directory Files File Description AM_BASE/nls/jaadocs /pdjrte/index.html AM_BASE/example/ pdadminapi_demo/jaa index.html (and many others) README.PDAdminDemo PDAdminDemo.jaa PDAdminDemo.class PDAdminDemo$ConsoleEraser.class Jaadoc HTML documentation for the Jaa classes and methods proided with the Tioli Access Manager Jaa runtime component. A demonstration program is proided which illustrates the use of the administration Jaa APIs. You can copy the demonstration program to any directory. The readme file explains how to run and recompile the demonstration program. JAVA_HOME/lib/ext PD.jar The Jaa Archie (JAR) file containing the classes and methods associated with the administration APIs. Note: When you use the pdjrtecfg command line interface to configure the Tioli Access Manager Jaa runtime component to a particular JRE, this archie file is copied to JAVA_HOME/lib/ext. Therefore, there is no need to modify the CLASSPATH in your enironment to access the classes and methods defined in this archie file. Building Jaa applications with the administration API To deelop Jaa applications that use the Tioli Access Manager administration API, you must install and configure the required software. IBM Tioli Access Manager software requirements You must install and configure an Tioli Access Manager secure domain. If you do not hae an Tioli Access Manager secure domain installed, install one before beginning application deelopment. The minimum installation consists of a single system with the following Tioli Access Manager components installed: Tioli Access Manager runtime enironment (see Note 1 on page 4) Tioli Access Manager Jaa runtime component Tioli Access Manager policy serer Tioli Access Manager ADK If you already hae an Tioli Access Manager secure domain installed and want to add a deelopment system to the domain, the minimum Tioli Access Manager installation consists of the following components: Tioli Access Manager runtime enironment (see Note 1 on page 4) Tioli Access Manager Jaa runtime component Tioli Access Manager ADK For Tioli Access Manager installation instructions, refer to the section of the IBM Tioli Access Manager Base Installation Guide for your operating system platform. Chapter 1. Introducing the administration API 3

22 Notes: 1. The Tioli Access Manager runtime enironment component is not needed for deeloping or deploying an Tioli Access Manager Jaa application. The prerequisite checking for the Tioli Access Manager ADK component is in error and erroneously requires that the Tioli Access Manager runtime component be installed, een if you are deeloping only Jaa applications and simply need the Jaadoc information and the example files from the ADK component. To sae disk space, you can copy the Jaadoc HTML information, consisting of the entire AM_BASE/nls/jaadocs directory tree, along with the sample Jaa program, in the AM_BASE/example directory tree, to another location on your deelopment system and then uninstall the Tioli Access Manager ADK and runtime components. 2. If you intend to use the Tioli Access Manager runtime enironment for an administration C API application, you also must install the IBM Directory client if an LDAP or Lotus Domino serer is being used as the user registry in the secure domain. Configuring the Jaa runtime component to a particular Jaa runtime enironment Configure the Tioli Access Manager Jaa runtime component to use the proper JRE on the system by using the pdjrtecfg command. The Tioli Access Manager Jaa runtime component can be configured to seeral different JREs on the same system, if desired. See the IBM Tioli Access Manager Base Installation Guide for details. Configuring to use the Jaa administration classes The com.tioli.pd.jcfg.srsslcfg Jaa class must be used to configure the administration Jaa APIs. See the IBM Tioli Access Manager for e-business Authorization Jaa Classes Deeloper Reference for details on the SrSslCfg utility. Notes: 1. Do not use the srsslcfg command line interface to create configuration files that are to be used with Jaa applications. 2. The com.tioli.mts.srsslcfg class proided in preious ersions of IBM Tioli Access Manager and IBM SecureWay Policy Director has been deprecated. Use the new com.tioli.pd.jcfg.srsslcfg class instead. Security requirements When running a Jaa application in the context of a Jaa security manager, the application must hae the proper Jaa permissions to use the administration Jaa APIs. If the application is not installed as a Jaa extension in the JAVA_HOME/lib/ext directory, an entry must be added to the JAVA_HOME/lib/security/jaa.policy file. For example, to grant Jaa applications located in the /sb/pdsb/export/classes directory, and all its subdirectories, the necessary Jaa permissions to use authorization Jaa classes and methods, add a statement similar to the following to the jaa.policy file: 4 IBM Tioli Access Manager for e-business: Administration Jaa Classes Deeloper Reference

23 // Gie applications in /sb/pdsb/export/classes and // its subdirectories access to the Access Manager // Administration APIs grant codebase "file:/sb/pdsb/export/classes/-" { permission jaax.security.auth.authpermission "PDAdmin"; }; Figure 1. Granting Jaa permission to applications Inoke administration Jaa classes and methods from a priileged block, dopriileged(), to alleiate the need for the application s callers to hae this Jaa permission as well. The PD.jar file is signed, but erification of the signing of JAR files is not supported in this ersion of Tioli Access Manager. Jaa administration API example program The Tioli Access Manager ADK includes the complete Jaa source code for an example program that demonstrates the use of the administration Jaa classes. The example program demonstrates how to perform the following tasks: Initialize an administration API security context Display an error message Create a new Tioli Access Manager user Set a user account to be alid Create a new group Add the new user to the group Delete a group Delete a user Deploying a Jaa administration API application Jaa applications that hae been deeloped using the Tioli Access Manager administration API must be run on systems that are configured as part of an Tioli Access Manager secure domain. To run an administration Jaa application, you must hae installed the Tioli Access Manager Jaa runtime component. Note: Information on installing the Tioli Access Manager Jaa runtime component can be found in the IBM Tioli Access Manager Base Installation Guide. Gathering problem determination information When deeloping a Jaa application, you might encounter a problem with Tioli Access Manager. To assist Tioli support personnel in diagnosing your problem, gather problem determination information relating to your error. Tioli Access Manager components can be configured to log information to one or more trace files. You can enable tracing for the policy serer, the authorization serer, the Jaa runtime component, or any system using the Tioli Access Manager runtime enironment. Chapter 1. Introducing the administration API 5

24 Enabling tracing on the policy serer To enable tracing on the policy serer, edit the /etc/pdmgrd_routing file, located in the installation directory for the Tioli Access Manager policy serer, and uncomment the last line. Shut down and restart the policy serer daemon, pdmgrd. Enabling tracing on the authorization serer To enable tracing on the authorization serer, edit the /etc/pdacld_routing file, located in the installation directory for the Tioli Access Manager authorization serer, and uncomment the last line. Shut down and restart the authorization serer daemon, pdacld. Enabling tracing in the Jaa runtime component Tracing for the Tioli Access Manager Jaa runtime component is controlled by settings in the properties file created by the com.tioli.pd.jcfg.srsslcfg command. To enable tracing, edit the properties file created and update the line associated with the desired application-serer-name to set islogging to true: basegroup.pdj<application-serer-name>tracelogger.islogging=true Each Jaa application can be configured to use a different properties file, and the properties file can hae any name and be located in any directory. The PDJLog.properties file, located in the PolicyDirector subdirectory of the associated JRE, is installed by the Tioli Access Manager Jaa runtime enironment component. This properties file is associated with, and can be used to enable tracing in, the pdjrtecfg command as well as the com.tioli.pd.jcfg.srsslcfg command. Gathering message logs Message logs associated with applications that are configured using the com.tioli.pd.jcfg.srsslcfg command are, by default, written to a set of 3 files: msg application_name1.log, msg application_name2.log, and msg application_name3.log, where application_name is the name specified with the appsr parameter of SrSslCfg. Each file is 512 KB in size, and the msg application_name1.log file always contains the latest messages. The number and size of these files, as well as the base name of the files themseles, can be configured using the options in the configuration file. Note: There are two underscore characters (_) following the characters msg in the default file names. The PDJLog.properties file controls the message logging for Jaa programs not configured with the com.tioli.pd.jcfg.srsslcfg command. This properties file specifies different file names for each class of Tioli Access Manager message: FATAL, ERROR, WARNING, NOTICE, or NOTICEVERBOSE. Each class of message is written to a set of 3 files, with names of the following form: msg amj_fataln.log msg amj_errorn.log msg amj_warningn.log msg amj_noticen.log msg amj_noticeerbosen.log 6 IBM Tioli Access Manager for e-business: Administration Jaa Classes Deeloper Reference

25 For more information on message logging, see the IBM Tioli Access Manager for e-business Problem Determination Guide. Gathering trace logs Trace logs associated with applications that are configured using the com.tioli.pd.jcfg.srsslcfg command are, by default, written to a set of 3 files: trace application_name1.log, trace application_name2.log, and trace application_name3.log, where application_name is the name specified with the appsr parameter of SrSslCfg. Each file is 512 KB in size, and the trace application_name1.log file always contains the latest trace entries. The number and size of these files, as well as the base name of the files themseles, can be configured using the options in the configuration file. Note: There are two underscore characters (_) following the characters trace in the default file names. The PDJLog.properties file controls the trace logging for Jaa programs not configured with the com.tioli.pd.jcfg.srsslcfg command. By default, this trace output is directed to a set of 3 files called trace amj1.log, trace amj2.log, and trace amj3.log. The number and size of these files, as well as the base name of the files themseles, can be configured using the options in the PDJLog.properties file. For more information, see the IBM Tioli Access Manager for e-business Problem Determination Guide. Chapter 1. Introducing the administration API 7

26 8 IBM Tioli Access Manager for e-business: Administration Jaa Classes Deeloper Reference

27 Chapter 2. Using the administration API Administration objects Each Jaa application that uses the administration API must perform certain tasks necessary for API initialization, shut down, and error handling. The administration API proides methods for each of these tasks. The following sections in this chapter describe the supported functions: Administration objects Initializing the administration API on page 12 Establishing a security context on page 12 Manipulating administration objects on page 14 Messages on page 17 Handling errors on page 18 Shutting down the administration API on page 18 Character-based data considerations on page 18 Note: If you are familiar with the administration C API described in the IBM Tioli Access Manager for e-business Administration C API Deeloper Reference, see Appendix A, Differences between the C and Jaa administration API, on page 53. Each IBM Tioli Access Manager (Tioli Access Manager) administration object that can be manipulated directly from a Jaa application is represented by a corresponding Jaa class. The objects supported in this ersion of Tioli Access Manager are as follows: PDAdmin This class is used to initialize and shut down the operations associated with using the Tioli Access Manager administration classes and methods. The methods in this class are applicable to all administration objects. PDAuthzRule This class represents a Tioli Access Manager authorization rule. PDContext This class encapsulates the information needed to establish a communication session between the Jaa application and the Tioli Access Manager policy serer. Both user ID and password-based and certificate-based authentication are supported by this class. Multiple PDContext objects can be created and used within the same Jaa irtual machine (JVM). PDDomain This class represents a Tioli Access Manager policy serer domain. PDUser This class represents a user in the Tioli Access Manager policy serer. PDGroup This class represents a group in the Tioli Access Manager policy serer. Copyright IBM Corp. 2002,

28 PDPolicy This class represents the policy information that is associated with a particular Tioli Access Manager user or, in the case of the global policy, that is associated with all users. The PDPolicy class is used to set and retriee account policy information from the user registry on a global or per-user basis. PDAcl This class represents an access control list (ACL), which in turn consists of a list of ACL entries. PDAclEntry This class represents an entry in an ACL. PDAclEntryUser This class represents a user ACL entry and controls access for a particular user. PDAclEntryGroup This class represents a group ACL entry and controls access for all members in a group. PDAclEntryAnyOther This class represents the any-other, or any-other authenticated, entry in an ACL. This ACL entry is applied to any user that has been authenticated into the Tioli Access Manager secure domain but is not included in a separate user or group ACL entry. PDAclEntryUnAuth This class represents the unauthenticated user ACL entry. This ACL entry is applied to any user that has not been authenticated by Tioli Access Manager. PDProtObject This class represents a protected object. A protected object represents a resource that is to be protected, and it has an ACL associated with it. Each protected object is uniquely identified by an ID. PDProtObjectSpace This class represents the protected object space object. An object space is a logical grouping of protected objects representing a set of related resources to be protected. Each object space is uniquely identified by an ID. PDPop This class represents a protected object policy, or POP, which can be attached to a PDProtObject object. PDAdmScPobj This class represents the alue of a Tioli Access Manager administration serice protected object. PDAction This class represents a gien permission. PDActionGroup This class represents a collection of PDAction objects. PDRgyGroupName This class represents the name of an Tioli Access Manager group in the underlying user registry. PDRgyUserName This class represents the name of an Tioli Access Manager user in the underlying user registry. 10 IBM Tioli Access Manager for e-business: Administration Jaa Classes Deeloper Reference