Administration Java Classes Developer Reference

Transcription

1 Tivoli Access Manager for e-business Version Administration Java Classes Developer Reference SC

2

3 Tivoli Access Manager for e-business Version Administration Java Classes Developer Reference SC

4 Note Before using this information and the product it supports, read the information in Appendix G, Notices, on page 159. Edition notice This edition applies to version 6, release 1, modification 1 of IBM Tivoli Access Manager (product number 5724-C87) and to all subsequent releases and modifications until otherwise indicated in new editions. All rights reserved. Copyright IBM Corporation 2002, US Government Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

5 Contents About this publication v Intended audience v Publications v IBM Tivoli Access Manager for e-business library v Related products and publications vii Accessing terminology online viii Accessing publications online viii Ordering publications ix Accessibility ix Tivoli technical training ix Tivoli user groups ix Support information x Conventions used in this publication x Typeface conventions x Operating system-dependent variables and paths xi Chapter 1. Introduction to the administration API Administration Java classes overview Accessing the Javadoc HTML documentation... 2 Other ways to manipulate administration objects.. 2 Java administration API components Application development kit Building Java applications with the administration API Tivoli Access Manager software requirements.. 4 Configuration of the Java runtime component to a particular Java runtime environment Configuration of the Java administration classes. 5 Security requirements Java administration API example program Deployment of a Java administration API application 6 Gathering of problem determination information.. 6 Enabling tracing on the policy server Enabling tracing on the authorization server... 6 Enabling tracing in the Java runtime component. 7 Gathering of message logs Gathering of trace logs Chapter 2. Using the administration API 9 Administration objects Common classes Initializing the administration API Establishing a security context User ID and password-based authentication.. 13 Certificate-based authentication Manipulating administration objects Creating objects Obtaining a local copy of an object Reading object values Setting object values Listing objects Deleting objects Messages Handling errors Shutting down the administration API Character-based data considerations PDContext application design considerations 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.. 29 Administering protected object spaces Administering protected objects Administering extended attributes for a protected object Chapter 5. Administering access control Administering access control lists Administering access control list entries Administering access control list extended attributes 36 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 sign-on resources Administering Web resources Administering resource groups Administering resource credentials Chapter 9. Administering domains Chapter 10. Configuring application servers Configuring application servers Administering configuration information Certificate maintenance Copyright IBM Corp. 2002, 2010 iii

6 Chapter 11. Administering servers 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 Administering servers and database notification.. 55 Appendix A. Differences between the C and Java administration API Security context management differences Response processing differences Additional differences Appendix B. Deprecated Java classes and methods Appendix C. Administration API equivalents Appendix D. Registry Direct Java API 83 Design Tivoli Access Manager Java API Registry Direct Java API Published API com.tivoli.pd.rgy.rgyregistry com.tivoli.pd.rgy.rgyentity com.tivoli.pd.rgy.rgyuser com.tivoli.pd.rgy.rgygroup com.tivoli.pd.rgy.rgyiterator com.tivoli.pd.rgy.ldap.rgyattributes com.tivoli.pd.rgy.ldap.ldaprgyregistryfactory 92 com.tivoli.pd.rgy.ldap.authzrgyregistryfactory 94 com.tivoli.pd.rgy.util.rgyconfig com.tivoli.pd.jcfg.svrsslcfg Old and new API errors Authenticate and changepassword Administration Attributes Error and trace logging Basic JRE example output Auditing Java logger behavior Authorization Authorization permission checks Residual effects of delegated administration on admin results API Specifications Installation and configuration Upgrade Installation and packaging Configuration Example usage Creating an instance of RgyRegistry Ending use of RgyRegistry Groups Creating a group Showing group details Deleting a group Importing a native group Listing group members Add or remove group members Modify group attribute Users and per-user policy Showing user details Deleting a user Importing a native user Listing users group memberships Modifying user attributes Resetting the user password Changing the users password Authenticating the Users Password Appendix E. User registry differences 145 General concerns LDAP concerns Sun Java System Directory Server concerns Microsoft Active Directory Application Mode (ADAM) concerns URAF concerns Lotus Domino Server concerns Microsoft Active Directory Server concerns Length of names Appendix F. Support information Searching knowledge bases Searching information centers Searching the Internet Obtaining fixes Registering with IBM Software Support Receiving weekly software updates Contacting IBM Software Support Determining the business impact Describing problems and gathering information 156 Submitting problems Appendix G. Notices Trademarks Glossary Index iv Administration Java Classes Developer Reference

7 About this publication Intended audience Publications IBM Tivoli Access Manager for e-business provides an access control management solution to centralize network and application security policy for e-business applications. This reference contains information about how to use Tivoli Access Manager administration Java classes and methods to enable an application to programmatically perform Tivoli Access Manager administration tasks. This document describes the Java implementation of the Tivoli Access Manager administration API. See the IBM Tivoli Access Manager for e-business: Administration C API Developer Reference for information regarding the C implementation of these APIs. Information about the pdadmin command-line interface (CLI) can be found in the IBM Tivoli Access Manager for e-business: Command Reference. This reference is for application programmers writing programs in and Java programming language to administer the users and objects associated with the Tivoli Access Manager for e-business product. Readers must be familiar with: v Microsoft Windows and UNIX operating systems v Database architecture and concepts v Security management v Internet protocols, including HTTP, TCP/IP, File Transfer Protocol (FTP), and Telnet v The user registry that Tivoli Access Manager is configured to use v Lightweight Directory Access Protocol (LDAP) and directory services, if used by your user registry v Authentication and authorization To enable Secure Sockets Layer (SSL) communication, you must be familiar with SSL protocol, key exchange (public and private), digital signatures, cryptographic algorithms, and certificate authorities. This section lists publications in the IBM Tivoli Access Manager for e-business library and related documents. The section also describes how to access Tivoli publications online and how to order Tivoli publications. IBM Tivoli Access Manager for e-business library The following documents are in the Tivoli Access Manager for e-business library: v v IBM Tivoli Access Manager for e-business: Quick Start Guide, GI Provides steps that summarize major installation and configuration tasks. IBM Tivoli Access Manager for e-business: Release Notes, GC Copyright IBM Corp. 2002, 2010 v

8 v v v v v v v v v v v v Provides information about installing and getting started, system requirements, and known installation and configuration problems. IBM Tivoli Access Manager for e-business: Installation Guide, GC Explains how to install and configure Tivoli Access Manager for e-business. IBM Tivoli Access Manager for e-business: Upgrade Guide, SC Upgrade from version 5.0, 6.0, or 6.1 to version IBM Tivoli Access Manager for e-business: Administration Guide, SC Describes the concepts and procedures for using Tivoli Access Manager. Provides instructions for performing tasks from the Web Portal Manager interface and by using the pdadmin utility. IBM Tivoli Access Manager for e-business: WebSEAL Administration Guide, SC Provides background material, administrative procedures, and reference information for using WebSEAL to manage the resources of your secure Web domain. IBM Tivoli Access Manager for e-business: Plug-in for Edge Server Administration Guide, SC Provides instructions for integrating Tivoli Access Manager with the IBM WebSphere Edge Server application. IBM Tivoli Access Manager for e-business: Plug-in for Web Servers Administration Guide, SC Provides procedures and reference information for securing your Web domain using a Web server plug-in. IBM Tivoli Access Manager for e-business: Shared Session Management Administration Guide, SC Provides deployment considerations and operational instructions for the session management server. IBM Global Security Kit: Secure Sockets Layer Introduction and ikeyman User's Guide, SC Provides information for enabling SSL communication in the Tivoli Access Manager environment. IBM Tivoli Access Manager for e-business: Auditing Guide, SC Provides information about configuring and managing audit events using the native Tivoli Access Manager approach and the Common Auditing and Reporting Service. You can also find information about installing and configuring the Common Auditing and Reporting Service. Use this service for generating and viewing operational reports. IBM Tivoli Access Manager for e-business: Command Reference, SC Provides reference information about the commands, utilities, and scripts that are provided with Tivoli Access Manager. IBM Tivoli Access Manager for e-business: Administration C API Developer Reference, SC Provides reference information about using the C language implementation of the administration API to enable an application to perform Tivoli Access Manager administration tasks. IBM Tivoli Access Manager for e-business: Administration Java Classes Developer Reference, SC Provides reference information about using the Java language implementation of the administration API to enable an application to perform Tivoli Access Manager administration tasks. vi Administration Java Classes Developer Reference

9 v IBM Tivoli Access Manager for e-business: Authorization C API Developer Reference, SC Provides reference information about using the C language implementation of the authorization API to enable an application to use Tivoli Access Manager security. v IBM Tivoli Access Manager for e-business: Authorization Java Classes Developer Reference, SC Provides reference information about using the Java language implementation of the authorization API to enable an application to use Tivoli Access Manager security. v IBM Tivoli Access Manager for e-business: Web Security Developer Reference, SC Provides programming and reference information for developing authentication modules. v IBM Tivoli Access Manager for e-business: Troubleshooting Guide, GC Provides problem determination information. v IBM Tivoli Access Manager for e-business: Error Message Reference, GI Provides explanations and recommended actions for the messages and return code. v IBM Tivoli Access Manager for e-business: Performance Tuning Guide, SC Provides performance tuning information for an environment consisting of Tivoli Access Manager with the IBM Tivoli Directory Server as the user registry. Related products and publications This section lists the IBM products that are related to and included with a Tivoli Access Manager solution. IBM Global Security Kit Tivoli Access Manager provides data encryption through the use of the Global Security Kit (GSKit), version 7.0. GSKit is included on the IBM Tivoli Access Manager Base CD for your particular platform, as well as on the IBM Tivoli Access Manager Web Security CDs, the IBM Tivoli Access Manager Shared Session Management CDs, and the IBM Tivoli Access Manager Directory Server CDs. The GSKit package provides the ikeyman key management utility, gsk7ikm, which creates key databases, public-private key pairs, and certificate requests. The IBM Global Security Kit: Secure Sockets Layer Introduction and ikeyman User's Guide is available on the Tivoli Information Center Web site in the same section as the Tivoli Access Manager product documentation. IBM Tivoli Directory Server IBM Tivoli Directory Server, version 6.1, is included on the IBM Tivoli Access Manager Directory Server set of CDs for the required operating system. You can find additional information about Tivoli Directory Server at: IBM Tivoli Directory Integrator IBM Tivoli Directory Integrator, version 6.1.1, is included on the IBM Tivoli Directory Integrator CD for the required operating system. You can find additional information about IBM Tivoli Directory Integrator at: About this publication vii

10 IBM DB2 Universal Database IBM DB2 Universal Database Enterprise Server Edition, version 9.1, is provided on the IBM Tivoli Access Manager Directory Server set of CDs and is installed with the Tivoli Directory Server software. DB2 is required when using Tivoli Directory Server or z/os LDAP servers as the user registry for Tivoli Access Manager. For z/os LDAP servers, you must separately purchase DB2. You can find additional information about DB2 at: IBM WebSphere Application Server WebSphere Application Server, version 6.1, is included on the IBM Tivoli Access Manager WebSphere Application Server set of CDs for the required operating system. WebSphere Application Server enables the support of the following applications: v Web Portal Manager interface, which administers Tivoli Access Manager. v Web Administration Tool, which administers Tivoli Directory Server. v v v Common Auditing and Reporting Service, which processes and reports on audit events. Session management server, which manages shared session in a Web security server environment. Attribute Retrieval Service. You can find additional information about WebSphere Application Server at: Accessing terminology online The Tivoli Software Glossary includes definitions for many of the technical terms related to Tivoli software. The Tivoli Software Glossary is available at the following Tivoli software library Web site: The IBM Terminology Web site consolidates the terminology from IBM product libraries in one convenient location. You can access the Terminology Web site at Accessing publications online The documentation CD contains the publications that are in the product library. The format of the publications is PDF, HTML, or both. Refer to the readme file on the CD for instructions on how to access the documentation. The product CD contains the publications that are in the product library. The format of the publications is PDF, HTML, or both. To access the publications using a Web browser, open the infocenter.html file. The file is in the appropriate publications directory on the product CD. IBM posts publications for this and all other Tivoli products, as they become available and whenever they are updated, to the Tivoli Documentation Central Web site at viii Administration Java Classes Developer Reference

11 Accessibility Note: If you print PDF documents on other than letter-sized paper, set the option in the File Print window that allows Adobe Reader to print letter-sized pages on your local paper. Ordering publications You can order many Tivoli publications online at Tivoli technical training Tivoli user groups You can also order by telephone by calling one of these numbers: v In the United States: v In Canada: In other countries, contact your software account representative to order Tivoli publications. To locate the telephone number of your local representative, perform the following steps: 1. Go to 2. Select your country from the list and click Go. 3. Click About this site in the main panel to see an information page that includes the telephone number of your local representative. Accessibility features help users with a physical disability, such as restricted mobility or limited vision, to use software products successfully. With this product, you can use assistive technologies to hear and navigate the interface. You can also use the keyboard instead of the mouse to operate all features of the graphical user interface. Visit the IBM Accessibility Center at accessibility/ for more information about IBM's commitment to accessibility. For additional information, see the Accessibility Appendix in IBM Tivoli Access Manager for e-business Installation Guide. For Tivoli technical training information, refer to the following IBM Tivoli Education Web site at Tivoli user groups are independent, user-run membership organizations that provide Tivoli users with information to assist them in the implementation of Tivoli Software solutions. Through these groups, members can share information and learn from the knowledge and experience of other Tivoli users. Tivoli user groups include the following members and groups: v 23,000+ members v 144+ groups Access the link for the Tivoli Users Group at About this publication ix

12 Support information If you have a problem with your IBM software, you want to resolve it quickly. IBM provides the following ways for you to obtain the support you need: Online Access the Tivoli Software Support site at sysmgmt/products/support/index.html?ibmprd=tivman. Access the IBM Software Support site at probsub.html. IBM Support Assistant The IBM Support Assistant is a free local software serviceability workbench that helps you resolve questions and problems with IBM software products. The Support Assistant provides quick access to support-related information and serviceability tools for problem determination. To install the Support Assistant software, go to support/isa. Troubleshooting Guide For more information about resolving problems, see the IBM Tivoli Access Manager for e-business Installation Guide. Conventions used in this publication This publication uses several conventions for special terms and actions, operating system-dependent commands, and paths. Typeface conventions This publication uses the following typeface conventions: Bold Italic v v v v v Lowercase commands and mixed case commands that are otherwise difficult to distinguish from surrounding text Interface controls (check boxes, push buttons, radio buttons, spin buttons, fields, folders, icons, list boxes, items inside list boxes, multicolumn lists, containers, menu choices, menu names, tabs, property sheets), labels (such as Tip:, and Operating system considerations:) Keywords and parameters in text Citations (examples: titles of publications, diskettes, and CDs Words defined in text (example: a nonswitched line is called a point-to-point line) v Emphasis of words and letters (words as words example: "Use the word that to introduce a restrictive clause."; letters as letters example: "The LUN address must start with the letter L.") v New terms in text (except in a definition list): a view is a frame in a workspace that contains data. v Variables and values you must provide:... where myname represents... Monospace v Examples and code examples v File names, programming keywords, and other elements that are difficult to distinguish from surrounding text v Message text and prompts addressed to the user x Administration Java Classes Developer Reference

13 v v Text that the user must type Values for arguments or command options Operating system-dependent variables and paths This publication uses the UNIX convention for specifying environment variables and for directory notation. When using the Windows command line, replace $variable with % variable% for environment variables and replace each forward slash (/) with a backslash (\) in directory paths. The names of environment variables are not always the same in the Windows and UNIX environments. For example, %TEMP% in Windows environments is equivalent to $TMPDIR in UNIX environments. Note: If you are using the bash shell on a Windows system, you can use the UNIX conventions. About this publication xi

14 xii Administration Java Classes Developer Reference

15 Chapter 1. Introduction to the administration API The Tivoli Access Manager Java runtime component includes the Java language version of the Tivoli Access Manager administration API. The Tivoli Access Manager Java runtime component provides a set of Java classes and methods for the administration of selected Tivoli Access Manager administration objects. These classes and methods provide a way for applications to administer users, groups, protected objects, and access control lists. You can use the Tivoli Access Manager application developer kit (ADK) to enable your application to programmatically administer Tivoli Access Manager administration objects. This chapter contains the following topics: v Administration Java classes overview v Accessing the Javadoc HTML documentation on page 2 v Java administration API components on page 3 v Building Java applications with the administration API on page 4 v Java administration API example program on page 6 v Deployment of a Java administration API application on page 6 v Gathering of problem determination information on page 6 Note: If you are familiar with the C language interface to the Tivoli Access Manager administration API, see Appendix A, Differences between the C and Java administration API, on page 57 for a general overview of differences. A mapping of C APIs to Java classes and methods can be found in Appendix C, Administration API equivalents, on page 61. Administration Java classes overview The administration Java classes can be used to administer the following types of objects: v Policies v Users v Groups v Access control lists (ACLs) v Extended ACL actions v Protected object policies (POPs) v Protected objects v Protected object spaces v Authorization rules v Domains v Web, or single signon (SSO), resources v Web resource groups v Resource credentials A set of Java classes are provided 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 administration Java classes are packaged in the PD.jar file that is installed as part of the Tivoli Access Manager Java runtime environment component. Applications Copyright IBM Corp. 2002,

16 using the Java runtime environment provided with Tivoli Access Manager automatically have access to these classes and methods. The administration API Java classes communicate directly with the Tivoli Access Manager policy server component. The API establishes an authenticated, Secure Sockets Layer (SSL) session with the Tivoli Access Manager policy server process. After the SSL session is established, the classes can send administration requests to the policy server. The Tivoli Access Manager policy server component services these requests in the same manner that it would service any other incoming requests. System administrators also can use the pdadmin command-line interface to accomplish Tivoli Access Manager administration tasks. The Java administration classes and methods map closely to these commands. Appendix C, Administration API equivalents, on page 61 describes the commands that match Java administration API methods. Some Java methods do not have a pdadmin command-line equivalent. Note: Do not use the svrsslcfg command-line interface with the Java applications. Use the SvrSslCfg Java class to provide this functionality. Accessing the Javadoc HTML documentation To add Tivoli Access Manager authorization and security services to new or existing Java applications, use the Javadoc information provided with the Tivoli Access Manager application developer kit (ADK) along with this book. Consult the Javadoc HTML documentation for deprecated Java APIs before you update existing Tivoli Access Manager application. Copy the Javadoc HTML information stored in the entire AM_BASE/nls/javadocs directory tree, to another location on your development system. Then, uninstall the Tivoli Access Manager ADK and runtime components. Only the Tivoli Access Manager Runtime for Java component is necessary for running Java applications. See Table 1 on page 3 for the Javadoc installation location. Other ways to manipulate administration objects In addition to using the Java 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 Tivoli Access Manager for e-business: Command Reference. Administration C API The administration C API provides support for these administration objects. Refer to the IBM Tivoli Access Manager for e-business: Administration C API Developer Reference for details. 2 Administration Java Classes Developer Reference

17 Java administration API components Application development kit The administration API consists of the following components: v The administration Java classes v Javadoc information for the associated Java classes and methods v A demonstration application The administration API Java classes are distributed in the Tivoli Access Manager Java runtime component for each platform. The remaining administration API components are distributed in the Tivoli Access Manager Application Developer Kit component. The Javadoc information associated with the administration Java classes and methods as well as examples are provided as part of the Tivoli Access Manager application developer kit (ADK) component package. Table 1 lists the files that are installed as part of the Tivoli Access Manager ADK component. The PD.jar file, even though it is installed as part of the Tivoli Access Manager Java runtime component, is listed in the table for completeness. Table 1. Administration API application development kit files Directory Files File description AM_BASE/nls/javadocs /pdjrte/index.html index.html (and many others) Javadoc HTML documentation for the Java classes and methods provided with the Tivoli Access Manager Java runtime component. JAVA_HOME/lib/ext PD.jar The Java Archive (JAR) file containing the classes and methods associated with the administration APIs. Note: When you use the pdjrtecfg command-line interface to configure the Tivoli Access Manager Java runtime component to a particular JRE, this archive file is copied to JAVA_HOME/lib/ext. Therefore, you do not have to modify the CLASSPATH in your environment to access the classes and methods defined in this archive file. AM_BASE/example/ pdadminapi_demo/java AM_BASE/example/ authz_demo/java README.PDAdminDemo PDAdminDemo.java PDAdminDemo.class PDAdminDemo$ConsoleEraser.class PDCallbackHandler.class PDDemoSetup.class PDDemoSetup.java PDJaasDemo$1.class PDJaasDemo.class PDJaasDemo.java PDListObjectsDemo.class PDListObjectsDemo.java PDPermissionDemo.class PDPermissionDemo.java README.JaznDemo A demonstration program is provided to illustrate the use of the administration Java APIs. Copy the demonstration program to any other directory. The readme file explains how to run and recompile the demonstration program. These files consist of various demos illustrating the use of Tivoli Access Manager's Java authorization APIs. Please read README.JaznDemo for a description on how to run the various demonstrations. Chapter 1. Introduction to the administration API 3

18 Table 1. Administration API application development kit files (continued) Directory Files File description AM_BASEexample/ local_remote_demo/java PDLRAuthzDemo1.class PDLRAuthzDemo1.java PDLRAuthzDemo2$1.class PDLRAuthzDemo2$2.class PDLRAuthzDemo2.class PDLRAuthzDemo2.java PDLRExerciseDialog$1.class PDLRExerciseDialog$2.class PDLRExerciseDialog$3.class PDLRExerciseDialog$4.class PDLRExerciseDialog.class PDLRExerciseDialog.java PDLRTestDemo.class PDLRTestDemo.java PDtamdemoException.class PDtamdemoException.java PDTimer.class PDTimer.java README.PDLocalRemoteDemo These files consist of a demonstration that illustrates the use of both the local and remote modes of administration and authorization APIs. The demonstration provides a graphical user interface for defining the various setup parameters. Please see the README.PDlocalRemoteDemo for a description on how to generate the documentation for the demonstration classes. Building Java applications with the administration API To develop Java applications that use the Tivoli Access Manager administration API, you must install and configure the required software. Tivoli Access Manager software requirements You must install and configure secure domain. If you do not have secure domain installed, install one before beginning application development. The minimum installation consists of a single system with the following Tivoli Access Manager components installed: v Tivoli Access Manager runtime environment (see Note 1 on page 4) v Tivoli Access Manager Java runtime component v Tivoli Access Manager policy server v Tivoli Access Manager ADK If you already have an Tivoli Access Manager secure domain installed and want to add a development system to the domain, the minimum Tivoli Access Manager installation consists of the following components: v Tivoli Access Manager runtime environment (see Note 1) v Tivoli Access Manager Java runtime component v Tivoli Access Manager ADK For Tivoli Access Manager installation instructions, refer to the section of the IBM Tivoli Access Manager for e-business: Installation Guide for your operating system platform. Notes: 1. The installation of Tivoli Access Manager requires the installation of the Tivoli Access Manager runtime component. This runtime component is not required for developing or deploying Java applications. In this specific situation, you can reclaim the disk space that is used by the Tivoli Access Manager ADK and runtime components while saving the Javadoc HTML information and the example files from the ADK component. 4 Administration Java Classes Developer Reference

19 To reclaim this disk space, copy the Javadoc information, consisting of the entire AM_BASE/nls/javadocs directory tree, and copy the sample Java program, in the AM_BASE/example directory tree, to another location on your development system and then uninstall the Tivoli Access Manager ADK and runtime components. 2. If you intend to use the Tivoli Access Manager runtime environment for an administration C API application, you also must install the IBM Directory client if an LDAP or Lotus Domino server is being used as the user registry in the secure domain. Configuration of the Java runtime component to a particular Java runtime environment Configure the Access Manager Runtime for Java component to use the proper JRE on the system by using the pdjrtecfg command. The Tivoli Access Manager Java runtime component can be configured to several different JREs on the same system, if required. See the IBM Tivoli Access Manager for e-business: Installation Guide for details. Configuration of the Java administration classes The com.tivoli.pd.jcfg.svrsslcfg Java class must be used to configure the administration Java APIs. See the IBM Tivoli Access Manager for e-business: Authorization Java Classes Developer Reference for details on the SvrSslCfg utility. Notes: 1. Do not use the svrsslcfg command-line interface to create configuration files that are to be used with Java applications. 2. The com.tivoli.mts.svrsslcfg class provided in previous versions of Tivoli Access Manager and IBM SecureWay Policy Director has been deprecated. Use the new com.tivoli.pd.jcfg.svrsslcfg class instead. Security requirements To run a Java application in the context of a Java security manager, the application must have proper Java permissions to use the administration Java APIs. If the application is not installed as a Java extension in the JAVA_HOME/lib/ext directory, an entry must be added to the JAVA_HOME/lib/security/java.policy file. To grant the necessary permission to the Java applications located in the /sb/pdsb/export/classes directory, and all its subdirectories, the necessary Java permissions to use authorization Java classes and methods, add a statement like the following to the java.policy file: // Give applications in /sb/pdsb/export/classes and // its subdirectories access to the Access Manager // Administration APIs grant codebase "file:/sb/pdsb/export/classes/-" { permission javax.security.auth.authpermission "PDAdmin"; }; Figure 1. Granting Java permission to applications Invoke administration Java classes and methods from a privileged block, doprivileged(), to alleviate the need for the application callers to have this Java permission as well. Chapter 1. Introduction to the administration API 5

20 The PD.jar file is signed, but verification of the signing of JAR files is not supported in this version of Tivoli Access Manager. Java administration API example program The Tivoli Access Manager ADK includes the complete Java source code for an example program that demonstrates the use of the administration Java classes. The example program demonstrates how to perform the following tasks: v Initialize an administration API security context v Display an error message v Create a new Tivoli Access Manager user v Set a user account to be valid v Create a new group v Add the new user to the group v Delete a group v Delete a user Deployment of a Java administration API application Java applications that have been developed using the Tivoli Access Manager administration API must be run on systems that are configured as part of an Tivoli Access Manager secure domain. To run an administration Java application, you must have installed the Tivoli Access Manager Java runtime component. Note: Information about installing the Tivoli Access Manager Java runtime component can be found in the IBM Tivoli Access Manager for e-business: Installation Guide. Gathering of problem determination information Tivoli Access Manager components can be configured to log information to one or more trace files. You can enable tracing for the policy server, the authorization server, the Java runtime component, or any system using the Tivoli Access Manager runtime environment. Enabling tracing on the policy server To enable tracing on the policy server: 1. Edit the /etc/pdmgrd_routing file, located in the installation directory for the Tivoli Access Manager policy server. 2. Uncomment the last line. 3. Shut down and restart the policy server daemon pdmgrd. Enabling tracing on the authorization server To enable tracing on the authorization server: 1. Edit the /etc/pdacld_routing file, located in the installation directory for the Tivoli Access Manager authorization server. 2. Uncomment the last line. 3. Shut down and restart the authorization server daemon, pdacld. 6 Administration Java Classes Developer Reference

21 Enabling tracing in the Java runtime component Tracing for the Tivoli Access Manager Java runtime component is controlled by settings in the properties file created by the com.tivoli.pd.jcfg.svrsslcfg command. To enable tracing: 1. Edit the properties file created. 2. Update the line associated with the required application-server-name to set islogging to true: basegroup.pdjapplication-server-nametracelogger.islogging=true Each Java application can be configured to use a different properties file, and the properties file can have 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 Tivoli Access Manager Java runtime environment component. This properties file is associated with, and can be used to enable tracing in, the pdjrtecfg command as well as the com.tivoli.pd.jcfg.svrsslcfg command. Gathering of message logs Message logs associated with applications that are configured using the com.tivoli.pd.jcfg.svrsslcfg command are, by default, written to a set of three files: msg application_name1.log, msg application_name2.log, and msg application_name3.log, where application_name is the name specified with the appsvr parameter of SvrSslCfg. 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 themselves, 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 Java programs not configured with the com.tivoli.pd.jcfg.svrsslcfg command. This properties file specifies different file names for each class of Tivoli Access Manager messages: FATAL, ERROR, WARNING, NOTICE, or NOTICEVERBOSE. Each class of message is written to a set of three 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_noticeverbosen.log For more information about message logging, see the IBM Tivoli Access Manager for e-business: Troubleshooting Guide. Gathering of trace logs Trace logs associated with applications that are configured using the com.tivoli.pd.jcfg.svrsslcfg command are, by default, written to a set of three files: trace application_name1.log, trace application_name2.log, and trace application_name3.log, where application_name is the name specified with the appsvr parameter of SvrSslCfg. Each file is 512 KB in size, and the trace application_name1.log file always contains the latest trace entries. The Chapter 1. Introduction to the administration API 7

22 number and size of these files, as well as the base name of the files themselves, 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 Java programs not configured with the com.tivoli.pd.jcfg.svrsslcfg command. By default, this trace output is directed to a set of three 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 themselves, can be configured using the options in the PDJLog.properties file. For more information, see the IBM Tivoli Access Manager for e-business: Troubleshooting Guide. 8 Administration Java Classes Developer Reference

23 Chapter 2. Using the administration API Administration objects Each Java application that uses the administration API must perform certain tasks necessary for API initialization, shut down, and error handling. The administration API provides methods for each of these tasks. The following sections in this chapter describe the supported functions: v Administration objects v Initializing the administration API on page 12 v Establishing a security context on page 12 v Manipulating administration objects on page 14 v Messages on page 17 v PDContext application design considerations on page 19 v Handling errors on page 18 v Shutting down the administration API on page 18 v Character-based data considerations on page 18 Note: If you are familiar with the administration C API described in the IBM Tivoli Access Manager for e-business: Administration C API Developer Reference, see Appendix A, Differences between the C and Java administration API, on page 57. Each Tivoli Access Manager administration object that can be manipulated directly from a Java application is represented by a corresponding Java class. The objects supported in this version of Tivoli Access Manager are as follows: PDAdmin This class is used to initialize and shut down the operations associated with using the Tivoli Access Manager administration classes and methods. The methods in this class are applicable to all administration objects. PDAuthzRule This class represents a Tivoli Access Manager authorization rule. PDContext This class encapsulates the information needed to establish a communication session between the Java application and the Tivoli Access Manager policy server. 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 Java virtual machine (JVM). PDContext creation is a resource exhaustive operation. Although there is no upper limit to creating multiple PDContext objects, system resource limitation eventually determines how many can be successfully created and used. It is recommended that only few PDContext objects be created and pooled in the application environment. Reuse the small number of created PDContext objects whenever possible within the same application. Because each user application needs are different, pooling PDContext objects is not mandatory. Pooling PDContext objects is recommended if you Copyright IBM Corp. 2002,

24 have a server application that makes numerous calls. If you have an application that makes only an occasional call, or if you have various stand-alone applications making calls, pooling is not necessary. The close() method provided in the PDContext class is only to clean up the logger data that is associated with the context, the close() method does not destroy the context. PDDomain This class represents a Tivoli Access Manager policy server domain. PDUser This class represents a user in the Tivoli Access Manager policy server. PDGroup This class represents a group in the Tivoli Access Manager policy server. PDPolicy This class represents the policy information that is associated with a particular Tivoli 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 retrieve 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, orany-other authenticated, entry in an ACL. This ACL entry is applied to any user that has been authenticated into the Tivoli 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 Tivoli 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. 10 Administration Java Classes Developer Reference

25 PDAdmSvcPobj This class represents the value of a Tivoli Access Manager administration service protected object. PDAction This class represents a given permission. PDActionGroup This class represents a collection of PDAction objects. PDRgyGroupName This class represents the name of an Tivoli Access Manager group in the underlying user registry. PDRgyUserName This class represents the name of an Tivoli Access Manager user in the underlying user registry. PDRgyName This class represents the name of an Tivoli Access Manager object in the underlying user registry. This object is either an Tivoli Access Manager user name or group name. PDAppSvrSpecLocal This class represents configuration information for a local Java application server. PDAppSvrSpecRemote This class represents configuration information for a remote Java application server. PDSvrInfo This class represents a Tivoli Access Manager policy server or authorization server and is used when creating or changing the configuration for a Java application server. PDAppSvrInfo This class represents a read-only view of a Java application server's configuration information. PDServer This class represents a Tivoli Access Manager policy server, authorization server, or other application server. PDSSOResource This class represents a single sign-on (SSO) resource. PDSSOResourceGroup This class represents a single signon (SSO) resource group. PDSSOCred.CredID This class represents the credential identification information for each member of the list returned by the PDSSOCred.listSSOCreds method. PDSSOCred.CredInfo This class represents the credential information for each member of the list returned by the PDSSOCred.listAndShowSSOCreds method. PDException This class creates an exception to reflect that an error or other exceptional condition has occurred. Chapter 2. Using the administration API 11

26 Common classes PDMessage This class represents a single Tivoli Access Manager message and includes the message code, severity, and the localized message text. PDMessages This class represents a list of one or more Tivoli Access Manager messages. The methods associated with these classes are threadsafe. The following classes are used for both administration and authorization methods. PDAttrs This class represents a list of Tivoli Access Manager attributes. PDAttrValue This class represents the value of a Tivoli Access Manager attribute. PDAttrValues This class represents a collection of values for a particular attribute that is unordered and that does not allow duplicates. PDAttrValueList This class represents a collection of values for a particular attribute that is ordered and allows duplicates. Initializing the administration API Before using the administration API in a Java application, the PDAdmin object must be initialized. This initialization is accomplished by calling the PDAdmin.initialize() method, as shown in Figure 2, by passing the name of the application and a PDMessages object. Messages are described in more detail in Messages on page 17. PDMessages messages = new PDMessages(); PDAdmin.initialize("myApplicationName", messages); Figure 2. Initializing the administration API Establishing a security context After initializing the administration API, you must create an SSL connection between the Java application and the Tivoli Access Manager policy server. This connection is referred to as a security context by the administration API. The security context provides for the secure transfer of administrative requests and data between the Java application and the policy server. A security context can be established using either user ID and password-based authentication or certificate-based authentication. In either case, the security context is represented by the PDContext object. Multiple PDContext objects can be created and used within the same JVM. PDContext creation is a resource exhaustive operation. Although there is no upper limit to creating multiple PDContext objects, system resource limitation eventually determines how many can be successfully created and used. It is recommended that only a few PDContext objects must be created and pooled in the application 12 Administration Java Classes Developer Reference