Administration Java Classes Developer’s Reference...Shutting down the administration API...
Transcript of Administration Java Classes Developer’s Reference...Shutting down the administration API...
IBM Tivoli Access Manager
Administration Java ClassesDeveloper’s ReferenceVersion 4.1
SC32-1143-01
���
IBM Tivoli Access Manager
Administration Java ClassesDeveloper’s ReferenceVersion 4.1
SC32-1143-01
���
Note:Before using this information and the product it supports, read the information in Appendix E, “Notices”, on page 71.
Second Edition (August 2003)
This edition replaces SC32-1143-00.
© Copyright International Business Machines Corporation 2002, 2003. All rights reserved.US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contractwith IBM Corp.
Contents
Figures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vii
Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiWho should read this book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiWhat this book contains . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiPublications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii
Release information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiiiBase information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiiiWebSEAL information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiiiWeb security information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xivDeveloper references . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xivTechnical supplements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvRelated publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvAccessing publications online . . . . . . . . . . . . . . . . . . . . . . . . . . . . xviiOrdering publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii
Accessibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xviiContacting software support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xviiConventions used in this book . . . . . . . . . . . . . . . . . . . . . . . . . . . . xviii
Typeface conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xviiiUser registry differences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xviiiOperating system differences . . . . . . . . . . . . . . . . . . . . . . . . . . . . xviii
Chapter 1. Introducing the administration API . . . . . . . . . . . . . . . . . . . 1Administration Java classes overview . . . . . . . . . . . . . . . . . . . . . . . . . . . 1Other ways to manipulate administration objects . . . . . . . . . . . . . . . . . . . . . . . 2Java administration API components . . . . . . . . . . . . . . . . . . . . . . . . . . . 2Application development kit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2Building Java applications with the administration API . . . . . . . . . . . . . . . . . . . . . 3
IBM Tivoli Access Manager software requirements. . . . . . . . . . . . . . . . . . . . . . 3Configuring the Java runtime component to a particular Java runtime environment . . . . . . . . . . 4Configuring to use the Java administration classes . . . . . . . . . . . . . . . . . . . . . . 4Security requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Java administration API example program . . . . . . . . . . . . . . . . . . . . . . . . . 5Deploying a Java administration API application . . . . . . . . . . . . . . . . . . . . . . . 5Gathering problem determination information . . . . . . . . . . . . . . . . . . . . . . . . 6
Chapter 2. Using the administration API . . . . . . . . . . . . . . . . . . . . . . 7Administration objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7Common classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9Initializing the administration API . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10Establishing a security context . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
User ID and password-based authentication . . . . . . . . . . . . . . . . . . . . . . . 10Certificate-based authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Manipulating administration objects . . . . . . . . . . . . . . . . . . . . . . . . . . . 12Creating objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12Obtaining a local copy of an object . . . . . . . . . . . . . . . . . . . . . . . . . . 13Reading object values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14Setting object values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14Listing objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14Deleting objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15Handling errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
© Copyright IBM Corp. 2002, 2003 iii
Shutting down the administration API . . . . . . . . . . . . . . . . . . . . . . . . . . 16Character-based data considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Chapter 3. Administering users and groups . . . . . . . . . . . . . . . . . . . . 19Administering users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19Administering user information . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20Administering user account policies . . . . . . . . . . . . . . . . . . . . . . . . . . . 21Administering user password policies . . . . . . . . . . . . . . . . . . . . . . . . . . 22Administering groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23Administering group information . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Chapter 4. Administering protected objects and protected object spaces . . . . . . . 27Administering protected object spaces . . . . . . . . . . . . . . . . . . . . . . . . . . 27Administering protected objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28Administering protected object attributes . . . . . . . . . . . . . . . . . . . . . . . . . 29
Chapter 5. Administering access control . . . . . . . . . . . . . . . . . . . . . 31Administering access control lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31Administering access control list entries . . . . . . . . . . . . . . . . . . . . . . . . . . 32Administering access control list extended attributes . . . . . . . . . . . . . . . . . . . . . 34Administering action groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34Administering extended actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Chapter 6. Administering protected object policies. . . . . . . . . . . . . . . . . 37Administering protected object policy objects . . . . . . . . . . . . . . . . . . . . . . . . 37
PDPop.IPAuthInfo object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38Administering protected object policy settings . . . . . . . . . . . . . . . . . . . . . . . . 38Administering protected object policy extended attributes . . . . . . . . . . . . . . . . . . . . 39
Chapter 7. Administering single signon resources . . . . . . . . . . . . . . . . . 41Web resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41Resource groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42Resource credentials . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Chapter 8. Configuring application servers . . . . . . . . . . . . . . . . . . . . 45Configuring application servers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45Administering configuration information . . . . . . . . . . . . . . . . . . . . . . . . . 46Certificate maintenance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Chapter 9. Administering servers . . . . . . . . . . . . . . . . . . . . . . . . 47Getting and performing administration tasks . . . . . . . . . . . . . . . . . . . . . . . . 47Notifying replica databases when the master authorization database is updated . . . . . . . . . . . . 47
Notifying replica databases automatically . . . . . . . . . . . . . . . . . . . . . . . . 48Notifying replica databases manually . . . . . . . . . . . . . . . . . . . . . . . . . . 48Setting the maximum number of notification threads . . . . . . . . . . . . . . . . . . . . 48Setting the notification wait time . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Administrating servers and database notification . . . . . . . . . . . . . . . . . . . . . . . 49
Appendix A. Differences between the C and Java administration API . . . . . . . . . 51Security context management differences . . . . . . . . . . . . . . . . . . . . . . . . . 51Response processing differences . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51Additional differences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Appendix B. Deprecated Java classes and methods . . . . . . . . . . . . . . . . 53
Appendix C. User registry differences . . . . . . . . . . . . . . . . . . . . . . 55
Appendix D. Administration C API, Java method, and command line equivalents. . . . 59
iv IBM Tivoli Access Manager: Administration Java Classes Developer’s Reference
Appendix E. Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71Trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Contents v
vi IBM Tivoli Access Manager: Administration Java Classes Developer’s Reference
Figures
1. Granting Java permission to applications . . . . . . . . . . . . . . . . . . . . . . . . 52. Initializing the administration API . . . . . . . . . . . . . . . . . . . . . . . . . . 103. Creating a security context using user ID and password-based authentication . . . . . . . . . . . 114. Creating a security context using certificate-based authentication. . . . . . . . . . . . . . . . 115. Creating a user . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136. Getting a local copy of a PDUser object . . . . . . . . . . . . . . . . . . . . . . . . 137. Deleting a user . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158. Shutting down the administration API . . . . . . . . . . . . . . . . . . . . . . . . 16
© Copyright IBM Corp. 2002, 2003 vii
viii IBM Tivoli Access Manager: Administration Java Classes Developer’s Reference
Tables
1. Administration API application development kit files . . . . . . . . . . . . . . . . . . . . 32. Methods used to list objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153. Administrating users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204. Administrating user information . . . . . . . . . . . . . . . . . . . . . . . . . . 205. Administrating user account policies . . . . . . . . . . . . . . . . . . . . . . . . . 216. Administrating user password policies . . . . . . . . . . . . . . . . . . . . . . . . 227. Administering groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248. Administering group attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . 249. Administering protected object spaces. . . . . . . . . . . . . . . . . . . . . . . . . 28
10. Administering protected objects . . . . . . . . . . . . . . . . . . . . . . . . . . . 2811. Administering protected object attributes . . . . . . . . . . . . . . . . . . . . . . . 2912. Administering access control lists . . . . . . . . . . . . . . . . . . . . . . . . . . 3213. Administering access control list entries . . . . . . . . . . . . . . . . . . . . . . . . 3314. Administering access control list extended attributes . . . . . . . . . . . . . . . . . . . . 3415. Administering action groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3416. Administering extended actions . . . . . . . . . . . . . . . . . . . . . . . . . . . 3517. Administering protected object policy objects . . . . . . . . . . . . . . . . . . . . . . 3718. Administering protected object policy settings . . . . . . . . . . . . . . . . . . . . . . 3919. Administering protected object policy extended attributes . . . . . . . . . . . . . . . . . . 3920. Administering Web resources . . . . . . . . . . . . . . . . . . . . . . . . . . . 4221. Administering resource groups . . . . . . . . . . . . . . . . . . . . . . . . . . . 4222. Administering credentials . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4323. Configuring application servers . . . . . . . . . . . . . . . . . . . . . . . . . . . 4524. Administering configuration information. . . . . . . . . . . . . . . . . . . . . . . . 4625. Certificate maintenance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4626. Administrating servers and database notification . . . . . . . . . . . . . . . . . . . . . 4927. Deprecated Java Classes and Methods . . . . . . . . . . . . . . . . . . . . . . . . 5328. User registry differences when adding a duplicate user to a group . . . . . . . . . . . . . . . 5629. User registry differences when removing a user from a group who is not a member of the group . . . . . 5630. Maximum lengths for names based on user registry . . . . . . . . . . . . . . . . . . . . 5631. Mapping between administration C API, Java methods, and the command line interface . . . . . . . . 60
© Copyright IBM Corp. 2002, 2003 ix
x IBM Tivoli Access Manager: Administration Java Classes Developer’s Reference
Preface
IBM® Tivoli® Access Manager (Tivoli Access Manager) is the base software that isrequired to run applications in the IBM Tivoli Access Manager product suite. Itenables the integration of IBM Tivoli Access Manager applications that provide awide range of authorization and management solutions. Sold as an integratedsolution, these products provide an access control management solution thatcentralizes network and application security policy for e-business applications.
Note: IBM Tivoli Access Manager is the new name of the previously releasedsoftware entitled Tivoli SecureWay® Policy Director. Also, for users familiarwith the Tivoli SecureWay Policy Director software and documentation, themanagement server is now referred to as the policy server.
This reference contains information about how to use Tivoli Access Manageradministration Java™ classes and methods to enable an application toprogrammatically perform Tivoli Access Manager administration tasks. Thisdocument describes the Java implementation of the Tivoli Access Manageradministration API. See the IBM Tivoli Access Manager Administration C APIDeveloper’s Reference for information regarding the C implementation of these APIs.
Information on the pdadmin command line interface (CLI) can be found in theIBM Tivoli Access Manager Command Reference.
Who should read this bookThis reference is for application programmers implementing programs in the Javaprogramming language to administer the users and objects associated with theIBM Tivoli Access Manager product.
Readers should be familiar with the following:v PC and UNIX® operating systemsv Database architecture and conceptsv Security managementv Internet protocols, including HTTP, TCP/IP, File Transfer Protocol (FTP), and
Telnetv The user registry that Tivoli Access Manager is configured to usev Lightweight Directory Access Protocol (LDAP) and directory services, if used by
your user registryv Authentication and authorization
If you are enabling Secure Sockets Layer (SSL) communication, you also should befamiliar with SSL protocol, key exchange (public and private), digital signatures,cryptographic algorithms, and certificate authorities.
What this book containsThis reference contains the following chapters and appendixes:v Chapter 1, “Introducing the administration API”, on page 1
© Copyright IBM Corp. 2002, 2003 xi
Provides an overview of the administration API and its components. It alsocovers building applications with the API and deploying an administration APIprogram.
v Chapter 2, “Using the administration API”, on page 7Each application that uses the administration API must perform certain tasksnecessary for API initialization, shut down, and error handling. This chapterdescribes the supported methods for establishing security contexts, creatingobjects, setting object values, reading object values, listing object information,deleting objects, handling errors, and shutting down.
v Chapter 3, “Administering users and groups”, on page 19The administration API provides a collection of methods for administering TivoliAccess Manager users and groups. This chapter describes the tasks that thosemethods accomplish. It describes the supported methods for administeringusers, user accounts, user passwords, groups, group attributes, and the policiesassociated with users.
v Chapter 4, “Administering protected objects and protected object spaces”, onpage 27This chapter describes the administration API methods that are used toadminister protected object spaces and protected objects. It describes thesupported methods for administering protected object spaces, protected objects,and protected object attributes.
v Chapter 5, “Administering access control”, on page 31This chapter describes the administration API methods that are used toadminister access control. It describes the supported methods for administeringaccess control lists, access control list entries, and access control list extendedattributes.
v Chapter 6, “Administering protected object policies”, on page 37This chapter describes the administration API methods that are used to create,modify, examine, and delete protected object policies. It also discusses attachingor detaching protected objects from protected object policies. It describes thesupported functions for administering protected object policy objects, protectedobject policy settings, and protected object policy extended attributes.
v Chapter 7, “Administering single signon resources”, on page 41This chapter provides instructions for using the administration API to create,modify, or delete web resources, resource groups, and resource credentials.
v Chapter 9, “Administering servers”, on page 47This chapter provides information about getting and performing administrationtasks and notifying the replica database when the master authorization databaseis updated.
v Chapter 8, “Configuring application servers”, on page 45This chapter provides instructions for using the administration API to configureservers, modify server configurations, administer replicas, and performcertificate maintenance.
v Appendix A, “Differences between the C and Java administration API”, onpage 51This appendix outlines the differences between the administration C APIfunctions and the administration Java classes and methods.
v Appendix B, “Deprecated Java classes and methods”, on page 53This appendix provides a list of the Java classes and methods that have beendeprecated in this version of Tivoli Access Manager.
v Appendix C, “User registry differences”, on page 55
xii IBM Tivoli Access Manager: Administration Java Classes Developer’s Reference
This appendix outlines the differences in behavior of the classes and methodsbased on the user registry being used by Tivoli Access Manager.
v Appendix D, “Administration C API, Java method, and command lineequivalents”, on page 59This appendix shows the mapping that exists between the Administration CAPIs, the Administration Java classes and methods, and the command lineinterface (CLI).
v Appendix E, “Notices”, on page 71This appendix provides copyright, legal, and trademark information.
PublicationsThe Tivoli Access Manager library is organized into the following categories:v “Release information”v “Base information”v “WebSEAL information”v “Web security information” on page xivv “Developer references” on page xivv “Technical supplements” on page xv
Release informationv IBM Tivoli Access Manager Read Me First Card
GI11-4198-00 (am41_readme.pdf)Provides information for installing and getting started using Tivoli AccessManager.
v IBM Tivoli Access Manager Release NotesSC32-1130-00 (am41_relnotes.pdf)Provides late-breaking information, such as software limitations, workarounds,and documentation updates.
Base informationv IBM Tivoli Access Manager Base Installation Guide
SC32-1131-01 (am41_install.pdf)Explains how to install, configure, and upgrade Tivoli Access Manager software,including the Web Portal Manager interface.
v IBM Tivoli Access Manager Base Administrator’s GuideSC32-1132-01 (am41_admin.pdf)Describes the concepts and procedures for using Tivoli Access Manager services.Provides instructions for performing tasks from the Web Portal Managerinterface and by using the pdadmin command.
WebSEAL informationv IBM Tivoli Access Manager WebSEAL Installation Guide
SC32-1133-01 (amweb41_install.pdf)Provides installation, configuration, and removal instructions for the WebSEALserver and the WebSEAL application development kit.
v IBM Tivoli Access Manager WebSEAL Administrator’s GuideSC32-1134-01 (amweb41_admin.pdf)
Preface xiii
Provides background material, administrative procedures, and technicalreference information for using WebSEAL to manage the resources of yoursecure Web domain.
Web security informationv IBM Tivoli Access Manager for WebSphere Application Server User’s Guide
SC32-1136-01 (amwas41_user.pdf)Provides installation, removal, and administration instructions for Tivoli AccessManager for IBM WebSphere® Application Server.
v IBM Tivoli Access Manager for WebLogic Server User’s GuideSC32-1137-01 (amwls41_user.pdf)Provides installation, removal, and administration instructions for Tivoli AccessManager for BEA WebLogic Server.
v IBM Tivoli Access Manager Plug-in for Edge Server User’s GuideSC32-1138-01 (amedge41_user.pdf)Describes how to install, configure, and administer the plug-in for IBMWebSphere Edge Server application.
v IBM Tivoli Access Manager Plug-in for Web Servers User’s GuideSC32-1139-01 (amws41_user.pdf)Provides installation instructions, administration procedures, and technicalreference information for securing your Web domain using the plug-in for Webservers.
Developer referencesv IBM Tivoli Access Manager Authorization C API Developer’s Reference
SC32-1140-01 (am41_authC_devref.pdf)Provides reference material that describes how to use the Tivoli Access Managerauthorization C API and the Access Manager service plug-in interface to addTivoli Access Manager security to applications.
v IBM Tivoli Access Manager Authorization Java Classes Developer’s ReferenceSC32-1141-01 (am41_authJ_devref.pdf)Provides reference information for using the Java™ language implementation ofthe authorization API to enable an application to use Tivoli Access Managersecurity.
v IBM Tivoli Access Manager Administration C API Developer’s ReferenceSC32-1142-01 (am41_adminC_devref.pdf)Provides reference information about using the administration API to enable anapplication to perform Tivoli Access Manager administration tasks. Thisdocument describes the C implementation of the administration API.
v IBM Tivoli Access Manager Administration Java Classes Developer’s ReferenceSC32-1143-01 (am41_adminJ_devref.pdf)Provides reference information for using the Java language implementation ofthe administration API to enable an application to perform Tivoli AccessManager administration tasks.
v IBM Tivoli Access Manager WebSEAL Developer’s ReferenceSC32-1135-01 (amweb41_devref.pdf)Provides administration and programming information for the Cross-domainAuthentication Service (CDAS), the Cross-domain Mapping Framework (CDMF),and the Password Strength Module.
xiv IBM Tivoli Access Manager: Administration Java Classes Developer’s Reference
Technical supplementsv IBM Tivoli Access Manager Command Reference
GC32-1107-01 (am41_cmdref.pdf)Provides information about the command line utilities and scripts provided withTivoli Access Manager.
v IBM Tivoli Access Manager Error Message ReferenceSC32-1144-01 (am41_error_ref.pdf)Provides explanations and recommended actions for the messages produced byTivoli Access Manager.
v IBM Tivoli Access Manager Problem Determination GuideGC32-1106-01 (am41_pdg.pdf)Provides problem determination information for Tivoli Access Manager.
v IBM Tivoli Access Manager Performance Tuning GuideSC32-1145-01 (am41_perftune.pdf)Provides performance tuning information for an environment consisting of TivoliAccess Manager with the IBM Directory server defined as the user registry.
Related publicationsThis section lists publications related to the Tivoli Access Manager library.
The Tivoli Software Library provides a variety of Tivoli publications such as whitepapers, datasheets, demonstrations, redbooks, and announcement letters. The TivoliSoftware Library is available on the Web at:http://www.ibm.com/software/tivoli/library/
The Tivoli Software Glossary includes definitions for many of the technical termsrelated to Tivoli software. The Tivoli Software Glossary is available, in English only,from the Glossary link on the left side of the Tivoli Software Library Web pagehttp://www.ibm.com/software/tivoli/library/
IBM Global Security ToolkitTivoli Access Manager provides data encryption through the use of the IBM GlobalSecurity Toolkit (GSKit). GSKit is included on the IBM Tivoli Access Manager BaseCD for your particular platform.
The GSKit package installs the iKeyman key management utility, gsk5ikm, whichenables you to create key databases, public-private key pairs, and certificaterequests. The following document is available on the Tivoli Information CenterWeb site in the same section as the IBM Tivoli Access Manager productdocumentation:v Secure Sockets Layer Introduction and iKeyman User’s Guide
(gskikm5c.pdf)Provides information for network or system security administrators who plan toenable SSL communication in their Tivoli Access Manager environment.
IBM DB2 Universal DatabaseIBM DB2® Universal Database™ is required when installing IBM Directory Server,z/OS™, and OS/390® LDAP servers. DB2 is provided on the product CDs for thefollowing operating system platforms:v IBM AIX®
v Microsoft™ Windows™
v Sun Solaris Operating Environment
Preface xv
DB2 information is available at:
http://www.ibm.com/software/data/db2/
IBM Directory ServerIBM Directory Server, Version 4.1, is included on the IBM Tivoli Access ManagerBase CD for all platforms except Linux for zSeries™. You can obtain the IBMDirectory Server software for Linux for S/390 at:
http://www.ibm.com/software/network/directory/server/download/
If you plan to use IBM Directory Server as your user registry, see the informationprovided at:
http://www.ibm.com/software/network/directory/library/
IBM WebSphere Application ServerIBM WebSphere Application Server, Advanced Single Server Edition 4.0.3, isincluded on the Web Portal Manager CDs and installed with the Web PortalManager interface. For information about IBM WebSphere Application Server, see:
http://www.ibm.com/software/webservers/appserv/infocenter.html
IBM Tivoli Access Manager for Business IntegrationIBM Tivoli Access Manager for Business Integration, available as a separatelyorderable product, provides a security solution for IBM MQSeries®, Version 5.2,and IBM WebSphere® MQ for Version 5.3 messages. IBM Tivoli Access Manager forBusiness Integration allows WebSphere MQSeries applications to send data withprivacy and integrity by using keys associated with sending and receivingapplications. Like WebSEAL and IBM Tivoli Access Manager for OperatingSystems, IBM Tivoli Access Manager for Business Integration, is one of theresource managers that use the authorization services of IBM Tivoli AccessManager for e-business.
The following documents associated with IBM Tivoli Access Manager for BusinessIntegration Version 4.1 are available on the Tivoli Information Center Web site:v IBM Tivoli Access Manager for Business Integration Administrator’s Guide
(SC23-4831-00)v IBM Tivoli Access Manager for Business Integration Release Notes (GI11-0957-00)v IBM Tivoli Access Manager for Business Integration Read Me First (GI11-0958-00)
IBM Tivoli Access Manager for Operating SystemsIBM Tivoli Access Manager for Operating Systems, available as a separatelyorderable product, provides a layer of authorization policy enforcement on UNIXsystems in addition to that provided by the native operating system. IBM TivoliAccess Manager for Operating Systems, like WebSEAL and IBM Tivoli AccessManager for Business Integration, is one of the resource managers that use theauthorization services of IBM Tivoli Access Manager for e-business.
The following documents associated with IBM Tivoli Access Manager forOperating Systems Version 4.1 are available on the Tivoli Information Center Website:v IBM Tivoli Access Manager for Operating Systems Installation Guide (SC23-4829-00)v IBM Tivoli Access Manager for Operating Systems Administration Guide
(SC23-4827-00)
xvi IBM Tivoli Access Manager: Administration Java Classes Developer’s Reference
v IBM Tivoli Access Manager for Operating Systems Problem Determination Guide(SC23-4828-00)
v IBM Tivoli Access Manager for Operating Systems Release Notes (GI11-0951-00)v IBM Tivoli Access Manager for Operating Systems Read Me First (GI11-0949-00)
Accessing publications onlineThe publications for this product are available online in Portable Document Format(PDF) or Hypertext Markup Language (HTML) format, or both in the TivoliSoftware Library: http://www.ibm.com/software/tivoli/library
To locate product publications in the library, click the Product manuals link on theleft side of the Library page. Then, locate and click the name of the product on theTivoli Software Information Center page.
Product publications include release notes, installation guides, user’s guides,administrator’s guides, and developer’s references.
Note: To ensure proper printing of PDF publications, select the Fit to page checkbox in the Adobe Acrobat Print window (which is available when you clickFile →Print).
Ordering publicationsYou can order many IBM Tivoli publications online at:http://www.elink.ibmlink.ibm.com/public/applications/publications/cgibin/pbi.cgi
You can also order by telephone:v In the United States: 800-879-2755v In Canada: 800-426-4968v In other countries, for a list of telephone numbers, see
http://www.ibm.com/software/tivoli/order-lit/
AccessibilityAccessibility features help a user who has a physical disability, such as restrictedmobility or limited vision, to use software products successfully. With this product,you can use assistive technologies to hear and navigate the interface. You also canuse the keyboard instead of the mouse to operate all features of the graphical userinterface.
Contacting software supportBefore contacting IBM Tivoli Software support with a problem, refer to the IBMTivoli Software support Web site at:http://www.ibm.com/software/sysmgmt/products/support/
If you need additional help, contact software support by using the methodsdescribed in the IBM Software Support Guide at the following Web site:http://techsupport.services.ibm.com/guides/handbook.html
The guide provides the following information:v Registration and eligibility requirements for receiving support
Preface xvii
v Telephone numbers and e-mail addresses, depending on the country in whichyou are located
v A list of information you should gather before contacting customer support
Conventions used in this bookThis reference uses several conventions for special terms and actions and foroperating system-dependent commands and paths.
Typeface conventionsThe following typeface conventions are used in this reference:
Bold Lowercase commands or mixed case commands that are difficult todistinguish from surrounding text, keywords, parameters, options, namesof Java classes, and objects are in bold.
Italic Variables, titles of publications, and special words or phrases that areemphasized are in italic.
MonospaceCode examples, command lines, screen output, file and directory namesthat are difficult to distinguish from surrounding text, system messages,text that the user must type, and values for arguments or commandoptions are in monospace.
User registry differencesTivoli Access Manager supports a number of different user registries. In mostcases, the behavior of Tivoli Access Manager is the same regardless of what userregistry is in use. However, there are several cases where the processing of a givenmethod differs based on what user registry is being used. A note similar to thefollowing highlights these differences:
User registry difference: This text would describe the different behavior based onthe user registry in use.
See Appendix C, “User registry differences”, on page 55 for a complete list ofknown differences.
Operating system differencesThis book uses the UNIX convention for specifying environment variables and fordirectory notation. When using the Windows command line, replace $variable with%variable% for environment variables and replace each forward slash (/) with abackslash (\) in directory paths. If you are using the bash shell on a Windowssystem, you can use the UNIX conventions.
xviii IBM Tivoli Access Manager: Administration Java Classes Developer’s Reference
Chapter 1. Introducing the administration API
The IBM Tivoli Access Manager (Tivoli Access Manager) Java runtime componentincludes the Java language version of the Tivoli Access Manager administrationAPI. The Tivoli Access Manager Java runtime component provides a set of Javaclasses and methods for the administration of selected Tivoli Access Manageradministration objects. These classes and methods provide a way for applicationsto administer users, groups, protected objects, and access control lists.
You can use the Tivoli Access Manager application developer kit (ADK) to enableyour application to programmatically administer Tivoli Access Manageradministration objects.
This chapter contains the following topics:v “Administration Java classes overview”v “Java administration API components” on page 2v “Building Java applications with the administration API” on page 3v “Java administration API example program” on page 5v “Deploying a Java administration API application” on page 5v “Gathering problem determination information” on page 6
Note: If you are familiar with the C language interface to the Tivoli AccessManager administration API, see Appendix A, “Differences between the Cand Java administration API”, on page 51 for a general overview ofdifferences. A mapping of C APIs to Java classes and methods can be foundin Appendix D, “Administration C API, Java method, and command lineequivalents”, on page 59.
Administration Java classes overviewThe administration Java classes can be used to administer the following types ofobjects:v Policiesv Usersv Groupsv Access control lists (ACLs)v Extended ACL actionsv Protected object policies (POPs)v Protected objectsv Protected object spacesv Web, or single signon (SSO), resourcesv Web resource groupsv Resource credentials
A set of Java classes are provided for creating, modifying, examining, listing, anddeleting each of the preceding object types. The classes include the methodsnecessary for manipulating each of these administration objects. Theseadministration Java classes are packaged in the PD.jar file that is installed as part
© Copyright IBM Corp. 2002, 2003 1
of the Tivoli Access Manager Java runtime environment component. Applicationsusing the Java runtime environment provided with Tivoli Access Managerautomatically have access to these classes and methods.
The administration API Java classes communicate directly with the Tivoli AccessManager policy server component. The API establishes an authenticated, SecureSockets Layer (SSL) session with the Tivoli Access Manager policy server process.After the SSL session is established, the classes can send administration requests tothe policy server.
The Tivoli Access Manager policy server component services these requests in thesame manner that it would service any other incoming requests.
System administrators also can use the pdadmin command line interface toaccomplish Tivoli Access Manager administration tasks. The Java administrationclasses and methods map closely to these commands. Appendix D,“Administration C API, Java method, and command line equivalents”, on page 59describes the commands that match Java administration API methods. Some Javamethods do not have a pdadmin command line equivalent.
Note: The svrsslcfg command line interface should not be used with Javaapplications. Use the SvrSslCfg Java class to provide this functionality.
Other ways to manipulate administration objectsIn addition to using the Java administration APIs to manipulate these objects, youalso can use the following methods:
pdadmin command line interface (CLI)The pdadmin command line interface is explained in the IBM Tivoli AccessManager Command Reference.
Administration C APIThe administration C API provides support for these administrationobjects. Refer to the IBM Tivoli Access Manager Administration C APIDeveloper’s Reference for details.
Java administration API componentsThe administration API consists of the following components:v The administration Java classesv Javadoc information for the associated Java classes and methodsv A demonstration application
The administration API Java classes are distributed in the Tivoli Access ManagerJava runtime component for each platform. The remainder of the administrationAPI components are distributed in the Tivoli Access Manager ApplicationDeveloper Kit component.
Application development kitThe Javadoc information associated with the administration Java classes andmethods as well as examples are provided as part of the Tivoli Access Managerapplication developer kit (ADK) component package.
2 IBM Tivoli Access Manager: Administration Java Classes Developer’s Reference
Table 1 lists the files that are installed as part of the Tivoli Access Manager ADKcomponent. The PD.jar file, even though it is installed as part of the Tivoli AccessManager 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 HTMLdocumentation for theJava classes andmethods provided withthe Tivoli AccessManager Java runtimecomponent.
AM_BASE/example/pdadminapi_demo/java
README.PDAdminDemoPDAdminDemo.javaPDAdminDemo.classPDAdminDemo$ConsoleEraser.class
A demonstrationprogram is providedwhich illustrates the useof the administrationJava APIs. You can copythe demonstrationprogram to anydirectory. The readmefile explains how to runand recompile thedemonstration program.
JAVA_HOME/lib/ext PD.jar The Java Archive (JAR)file containing theclasses and methodsassociated with theadministration APIs.Note: When you use thepdjrtecfg command lineinterface to configurethe Tivoli AccessManager Java runtimecomponent to aparticular JRE, thisarchive file is copied toJAVA_HOME/lib/ext.Therefore, there is noneed to modify theCLASSPATH in yourenvironment to accessthe classes and methodsdefined in this archivefile.
Building Java applications with the administration APITo develop Java applications that use the Tivoli Access Manager administrationAPI, you must install and configure the required software.
IBM Tivoli Access Manager software requirementsYou must install and configure an Tivoli Access Manager secure domain. If you donot have an Tivoli Access Manager secure domain installed, install one beforebeginning application development. The minimum installation consists of a singlesystem with the following Tivoli Access Manager components installed:
Chapter 1. Introducing the administration API 3
v Tivoli Access Manager runtime environment (see Note 1 on page 4)v Tivoli Access Manager Java runtime componentv Tivoli Access Manager policy serverv Tivoli Access Manager ADK
If you already have an Tivoli Access Manager secure domain installed and want toadd a development system to the domain, the minimum Tivoli Access Managerinstallation consists of the following components:v Tivoli Access Manager runtime environment (see Note 1 on page 4)v Tivoli Access Manager Java runtime componentv Tivoli Access Manager ADK
For Tivoli Access Manager installation instructions, refer to the section of the IBMTivoli Access Manager Base Installation Guide for your operating system platform.
Notes:
1. The Tivoli Access Manager runtime environment component is not needed fordeveloping or deploying an Tivoli Access Manager Java application. Theprerequisite checking for the Tivoli Access Manager ADK component is in errorand erroneously requires that the Tivoli Access Manager runtime component beinstalled, even if you are developing only Java applications and simply needthe Javadoc information and the example files from the ADK component.To save disk space, you can copy the Javadoc HTML information, consisting ofthe entire AM_BASE/nls/javadocs directory tree, along with the sample Javaprogram, in the AM_BASE/example directory tree, to another location on yourdevelopment system and then uninstall the Tivoli Access Manager ADK andruntime components.
2. If you intend to use the Tivoli Access Manager runtime environment for anadministration C API application, you also must install the IBM® SecureWay®
Directory client if an LDAP or Lotus Domino server is being used as the userregistry in the secure domain.
Configuring the Java runtime component to a particular Javaruntime environment
Configure the Tivoli Access Manager Java runtime component to use the properJRE on the system by using the pdjrtecfg command. The Tivoli Access ManagerJava runtime component can be configured to several different JREs on the samesystem, if desired. See the IBM Tivoli Access Manager Base Installation Guide fordetails.
Configuring to use the Java administration classesThe com.tivoli.pd.jcfg.SvrSslCfg Java class must be used to configure theadministration Java APIs. See the IBM Tivoli Access Manager Authorization JavaClasses Developer’s Reference for details on the SvrSslCfg utility.
Notes:
1. Do not use the svrsslcfg command line interface to create configuration filesthat are to be used with Java applications.
2. The com.tivoli.mts.SvrSslCfg class provided in previous versions of IBM TivoliAccess Manager and IBM SecureWay Policy Director has been deprecated. Usethe new com.tivoli.pd.jcfg.SvrSslCfg class instead.
4 IBM Tivoli Access Manager: Administration Java Classes Developer’s Reference
Security requirementsWhen running a Java application in the context of a Java security manager, theapplication must have the proper Java permissions to use the administration JavaAPIs. If the application is not installed as a Java extension in theJAVA_HOME/lib/ext directory, an entry must be added to theJAVA_HOME/lib/security/java.policy file.
For example, to grant Java applications located in the /sb/pdsb/export/classesdirectory, and all its subdirectories, the necessary Java permissions to useauthorization Java classes and methods, add a statement similar to the following tothe java.policy file:
Invoke administration Java classes and methods from a privileged block,doPrivileged(), to alleviate the need for the application’s callers to have this Javapermission as well.
The PD.jar file is signed, but verification of the signing of JAR files is notsupported in this version of Tivoli Access Manager.
Java administration API example programThe Tivoli Access Manager ADK includes the complete Java source code for anexample 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 contextv Display an error messagev Create a new Tivoli Access Manager userv Set a user account to be validv Create a new groupv Add the new user to the groupv Delete a groupv Delete a user
Deploying a Java administration API applicationJava applications that have been developed using the Tivoli Access Manageradministration API must be run on systems that are configured as part of an TivoliAccess Manager secure domain. To run an administration Java application, youmust have installed the Tivoli Access Manager Java runtime component.
Note: Information on installing the Tivoli Access Manager Java runtimecomponent can be found in the IBM Tivoli Access Manager Base InstallationGuide.
// Give applications in /sb/pdsb/export/classes and// its subdirectories access to the Access Manager// Administration APIsgrant codeBase "file:/sb/pdsb/export/classes/-" {
permission javax.security.auth.AuthPermission "PDAdmin";};
Figure 1. Granting Java permission to applications
Chapter 1. Introducing the administration API 5
Gathering problem determination informationWhen developing an administration application, you might encounter a problemwith Tivoli Access Manager. To assist in diagnosing your problem, see the IBMTivoli Access Manager Problem Determination Guide.
6 IBM Tivoli Access Manager: Administration Java Classes Developer’s Reference
Chapter 2. Using the administration API
Each Java application that uses the administration API must perform certain tasksnecessary for API initialization, shut down, and error handling. The administrationAPI 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 10v “Establishing a security context” on page 10v “Manipulating administration objects” on page 12v “Messages” on page 15v “Handling errors” on page 16v “Shutting down the administration API” on page 16v “Character-based data considerations” on page 16
Note: If you are familiar with the administration C API described in the IBM TivoliAccess Manager Administration C API Developer’s Reference, see Appendix A,“Differences between the C and Java administration API”, on page 51.
Administration objectsEach IBM Tivoli Access Manager (Tivoli Access Manager) administration object thatcan be manipulated directly from a Java application is represented by acorresponding Java class. The objects supported in this version of Tivoli AccessManager are as follows:
PDAdminThis class is used to initialize and shut down the operations associatedwith using the Tivoli Access Manager administration classes and methods.The methods in this class are applicable to all administration objects.
PDContextThis class encapsulates the information needed to establish acommunication session between the Java application and the Tivoli AccessManager policy server. Both user ID and password-based andcertificate-based authentication are supported by this class. MultiplePDContext objects can be created and used within the same Java virtualmachine (JVM).
PDUserThis class represents a user in the Tivoli Access Manager policy server.
PDGroupThis class represents a group in the Tivoli Access Manager policy server.
PDPolicyThis class represents the policy information that is associated with aparticular 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 andretrieve account policy information from the user registry on a global orper-user basis.
© Copyright IBM Corp. 2002, 2003 7
PDAcl This class represents an access control list (ACL), which in turn consists ofa list of ACL entries.
PDAclEntryThis class represents an entry in an ACL.
PDAclEntryUserThis class represents a user ACL entry and controls access for a particularuser.
PDAclEntryGroupThis class represents a group ACL entry and controls access for allmembers in a group.
PDAclEntryAnyOtherThis class represents the any-other, or any-other authenticated, entry in anACL. This ACL entry is applied to any user that has been authenticatedinto the Tivoli Access Manager secure domain but is not included in aseparate user or group ACL entry.
PDAclEntryUnAuthThis class represents the unauthenticated user ACL entry. This ACL entryis applied to any user that has not been authenticated by Tivoli AccessManager.
PDProtObjectThis class represents a protected object. A protected object represents aresource that is to be protected, and it has an ACL associated with it. Eachprotected object is uniquely identified by an ID.
PDProtObjectSpaceThis class represents the protected object space object. An object space is alogical grouping of protected objects representing a set of related resourcesto be protected. Each object space is uniquely identified by an ID.
PDPopThis class represents a protected object policy, or POP, which can beattached to a PDProtObject object.
PDActionThis class represents a given permission.
PDActionGroupThis class represents a collection of PDAction objects.
PDRgyGroupNameThis class represents the name of an Tivoli Access Manager group in theunderlying user registry.
PDRgyUserNameThis class represents the name of an Tivoli Access Manager user in theunderlying user registry.
PDRgyNameThis class represents the name of an Tivoli Access Manager object in theunderlying user registry. This object is either an Tivoli Access Manageruser name or group name.
PDAppSvrSpecLocalThis class represents configuration information for a local Java applicationserver.
8 IBM Tivoli Access Manager: Administration Java Classes Developer’s Reference
PDAppSvrSpecRemoteThis class represents configuration information for a remote Javaapplication server.
PDSvrInfoThis class represents a Tivoli Access Manager policy server orauthorization server and is used when creating or changing theconfiguration for a Java application server.
PDAppSvrInfoThis class represents a read-only view of a Java application server’sconfiguration information.
PDServerThis class represents a Tivoli Access Manager policy server, authorizationserver, or other application server.
PDSSOResourceThis class represents a single signon (SSO) resource.
PDSSOResourceGroupThis class represents a single signon (SSO) resource group.
CredIDThis class represents the credential identification information for eachmember of the list returned by the PDSSOCred.listSSOCreds method.
CredInfoThis class represents the credential information for each member of the listreturned by the PDSSOCred.listAndShowSSOCreds method.
PDExceptionThis class creates an exception to reflect that an error or other exceptionalcondition has occurred.
PDMessageThis class represents a single Tivoli Access Manager message and includesthe message code, severity, and the localized message text.
PDMessagesThis class represents a list of one or more Tivoli Access Manager messages.
The methods associated with these classes are thread-safe.
Common classesThe following classes are used for both administration and authorization methods.
PDAttrsThis class represents a list of Tivoli Access Manager attributes.
PDAttrValueThis class represents the value of a Tivoli Access Manager attribute.
PDAttrValuesThis class represents a collection of values for a particular attribute that isunordered and that does not allow duplicates.
PDAttrValueListThis class represents a collection of values for a particular attribute that isordered and allows duplicates.
Chapter 2. Using the administration API 9
Initializing the administration APIBefore using the administration API in a Java application, the PDAdmin objectmust be initialized. This is accomplished by calling the PDAdmin.initialize()method, as shown in Figure 2, passing the name of the application and aPDMessages object. Messages are described in more detail in “Messages” onpage 15.
Establishing a security contextAfter initializing the administration API, you must create an SSL connectionbetween the Java application and the Tivoli Access Manager policy server. Thisconnection is referred to as a security context by the administration API. Thesecurity context provides for the secure transfer of administrative requests anddata between the Java application and the policy server.
A security context can be established using either user ID and password-basedauthentication or certificate-based authentication. In either case, the securitycontext is represented by the PDContext object. Multiple PDContext objects can becreated and used within the same JVM.
Information on Java authentication classes and methods can be found in IBM TivoliAccess Manager Authorization Java Classes Developer’s Reference.
User ID and password-based authenticationTo establish a security context using user ID and password-based authentication,you need the following information:
admin user IDAn Tivoli Access Manager user ID with the appropriate administrativeauthority, such as sec_master.
admin passwordThe password associated with the administrator user ID.
locale The locale that is to be used for returning message data to the application.
configuration file URLThe uniform resource locator (URL) to the configuration file created by theJava SvrSslCfg class. The URL must use the file:/// format.
Note: Do not use the svrsslcfg command line interface to create aconfiguration file that is to be used by a Java application.
To create the security context, create a PDContext object as shown in Figure 3 onpage 11.
PDMessages messages = new PDMessages();
PDAdmin.initialize("myApplicationName", messages);
Figure 2. Initializing the administration API
10 IBM Tivoli Access Manager: Administration Java Classes Developer’s Reference
The contents of the configuration file created by the Java SvrSslCfg class is notexternalized and is subject to change without notice in future releases of TivoliAccess Manager. Users should not use the information in the configuration filedirectly.
Certificate-based authenticationTo establish a security context using certificate-based authentication, you need thefollowing information:
locale The locale that is to be used for returning message data to the application.
configuration file URLThe URL to the configuration file created by the Java SvrSslCfg class. TheURL must use the file:/// format.
Note: Do not use the svrsslcfg command line interface to create aconfiguration file that is to be used by a Java application.
To create the security context, create a PDContext object as shown in Figure 4.
The contents of the configuration file created by the Java SvrSslCfg class is notexternalized and is subject to change without notice in future releases of TivoliAccess Manager. Users should not use the information in the configuration filedirectly.
// Create locale for US English
Locale myLocale = new Locale("ENGLISH", "US");
/*Create a security context using our locale. Need to supply a user ID withadministrative privileges in Access Manager (like sec_master) along withits password and a URL of the form file:/// to the configuration file createdby the SvrSslCfg class.
*/
PDContext myContext = new PDContext(myLocale,adminName,adminPassword,configFileURL);
Figure 3. Creating a security context using user ID and password-based authentication
// Create locale for US English
Locale myLocale = new Locale("ENGLISH", "US");
/*Create a security context using certificate-based authentication.The URL to the configuration file must use the file:/// format. Theconfiguration file is created by the SvrSslCfg class.
*/
PDContext myContext = new PDContext(myLocale,configFileURL);
Figure 4. Creating a security context using certificate-based authentication
Chapter 2. Using the administration API 11
Manipulating administration objectsEach Java class representing an administration object provides static methods tocreate, list, modify, and delete objects stored on the Tivoli Access Manager policyserver. Changes to administration objects on the policy server are immediatelyavailable to other applications.
The constructor of each class can be used to obtain a local copy of a specificadministration object. The instance methods of the class can then be used toretrieve data from the local object and to modify both the local copy of the objectand the object stored on the policy server.
Use of the static methods is recommended for command line and batch-orientedapplications using the administration API. For interactive applications, the instancemethods are recommended.
Creating objectsYou can use the administration API to create Tivoli Access Manager objectsnecessary to complete administrative tasks. Before you create an object, you needto initialize the administration API and establish a security context.
To create an object, use the static creation method associated with theadministration object. For example, to create an Tivoli Access Manager user, youwould use the PDUser.createUser() static method. This is illustrated in Figure 5 onpage 13. This method results in the Tivoli Access Manager user being createdimmediately on the policy server.
12 IBM Tivoli Access Manager: Administration Java Classes Developer’s Reference
Obtaining a local copy of an objectTo obtain a local copy of an administration object, use the constructor for the Javaclass representing the administration object. For example, to get a copy of thePDUser object representing a particular Tivoli Access Manager user, you woulduse the PDUser constructor. This is shown in Figure 6.
/*------------------------------------------------------------------* Create a user, using the PDUser.createUser() static method, and* assign the user to a specific group. This method sends a* request to the policy server to create the user.*------------------------------------------------------------------*/
// Set up all of the user’s attributesString name = "Stephanie Luser";String firstName = "Stephanie";String lastName = "Luser";String password = "herpassword";String description = "Descriptive text for Stephanie Luser";String rgyName = "cn=" + name + "," + rgySuffix;PDRgyUserName pdRgyUserName =
new PDRgyUserName(rgyName, firstName, lastName);boolean ssoUser = false;boolean pwdPolicy = true;ArrayList groupList = new ArrayList();groupList.add(groupAdministrativeAssistants);messages.clear();
PDUser.createUser(mySecurityContext,name,pdRgyUserName,description,password.toCharArray(),groupList,ssoUser,pwdPolicy,messages);
Figure 5. Creating a user
/*------------------------------------------------------------------* Obtain a user using the PDUser constructor.*------------------------------------------------------------------*/
// Set up all of the user’s attributesString name = "Zachary Wommbat";String firstName = "Zachary";String lastName = "Wommbat";String rgyName = "cn=" + name + "," + rgySuffix;PDRgyUserName pdRgyUserName =
new PDRgyUserName(rgyName, firstName, lastName);messages.clear()
PDUser user = new PDUser(mySecurityContext,pdRgyUserName,messages);
Figure 6. Getting a local copy of a PDUser object
Chapter 2. Using the administration API 13
After a local copy of the administration object is obtained, you can use the instancemethods on the object to retrieve or set data associated with the object.
Note: After a local copy of an administration object is obtained, the object could bechanged on the policy server by other users using the command lineinterface, the administration C API, or the Java classes and methods. A fewinstance methods are able to detect inconsistencies between data in the localobject and data in the policy server, but most cannot. It is the responsibilityof the user to ensure that changes made to administration objects are donein a consistent and predictable way when using the instance methods.
Reading object valuesAdministration object data can be obtained by using the instance methodsassociated with the administration object.
To use the instance methods, you must first obtain a local copy of the object, asoutlined in “Obtaining a local copy of an object” on page 13. After obtaining theobject, you can retrieve information about the object by using the instancemethods. For example, to get the description associated with an Tivoli AccessManager user from a local copy of the PDUser object:
userDescription = user.getDescription();
Setting object valuesAdministration object data can be changed by using the instance methodsassociated with the administration object or by using the static methods associatedwith the Java class representing the administration object.
To use the instance methods, you must first obtain a local copy of the object, asoutlined in “Obtaining a local copy of an object” on page 13. After obtaining theobject, you can change information about the object by using the instance methods.For example, to disable the account associated with an Tivoli Access Manager userfrom a local copy of the PDUser object, use the following:user.setAccountValid(mySecurityContext,
false, // Disable the accountmessages);
The instance method changes both the local copy of the administration object aswell as the object stored on the policy server.
To update the PDUser object on the policy server, use the static method:PDUser.setAccountValid(mySecurityContext,
name,false, // Disable the accountmessages);
Listing objectsSome administrative tasks require the Java application to obtain a list of objects.For example, an administrator might need to review the list of existing users inorder to decide if a new user must be created.
Table 2 on page 15 lists the appropriate method to use to list objects based on theJava class that represents an administration object.
14 IBM Tivoli Access Manager: Administration Java Classes Developer’s Reference
Table 2. Methods used to list objects
Object Method to list objects
PDAcl PDAcl.listAcls
PDGroup PDGroup.listGroups
PDProtObject PDProtObject.listProtObjectsPDProtObject.listProtObjectsByAcl
PDProtObjectSpace PDProtObjectSpace.listProtObjectSpaces
PDUser PDUser.listUsers
Deleting objectsTo delete an object, use the static deletion method associated with theadministration object. For example, to delete an Tivoli Access Manager user, youwould use the PDUser.deleteUser() static method. This is illustrated in Figure 7.This method results in the Tivoli Access Manager user being deleted immediatelyfrom the policy server.
MessagesAll constructors, static methods, and instance methods have an output parameterconsisting of a PDMessages object. In addition, exceptions generated by TivoliAccess Manager contain a PDMessages object.
A PDMessages object contains zero or more PDMessage objects. Each PDMessageobject represents a single message and consists of the following:
Message codeA hexadecimal number that uniquely identifies the message.
Message textThe localized text of the message.
SeverityAn indication of the severity of the message:v Informationalv Warningv Error
The message text is localized based on the PDContext object that is used when themethod is invoked except in the case of a read-only instance method on a local
/*------------------------------------------------------------------* Delete a user*------------------------------------------------------------------*/
// Set up all of the user’s attributesString name = "Lee Alan";messages.clear();
PDUser.deleteUser(mySecurityContext,name,true,messages);
Figure 7. Deleting a user
Chapter 2. Using the administration API 15
administration object. When using a read-only instance method, the message text islocalized based on the PDContext object used when the local administration objectwas created.
When a method completes successfully, check the PDMessages object for anyinformational or warning messages associated with the action performed. If anerror is encountered during processing, a PDException exception is thrown, whichmight have messages associated with it.
The same PDMessages object can be used on multiple method invocations. Use theclear() method to clear the contents of the PDMessages object between methodinvocations.
The IBM Tivoli Access Manager Error Message Reference contains a list of themessages issued by Tivoli Access Manager along with an explanation of themessage and the suggested corrective action.
Handling errorsAll constructors, instance methods, and static methods throw a PDExceptionexception when an error or unexpected event occurs. This exception contains aPDMessages object that might contain one or more PDMessage objects. See“Messages” on page 15 for more information about messages and messagehandling.
A PDException object also might contain a wrapped exception that was thrown byanother Java component. Information about this wrapped exception can beobtained by using the methods of the PDException object.
The IBM Tivoli Access Manager Error Message Reference contains a list of themessages issued by Tivoli Access Manager along with an explanation of themessage and the suggested corrective action.
Shutting down the administration APIAfter using the administration API, the PDAdmin object must be shut down. Thisis accomplished by calling the PDAdmin.shutdown() method as shown in Figure 8.
Character-based data considerationsCharacter-based data, such as user IDs and passwords, is stored and manipulatedby the Java classes and methods as strings of Unicode characters. This characterdata is converted from Unicode into UTF-8 (Universal Character SetTransformation Format-8) before being sent to the Tivoli Access Manager policyserver. Similarly, data from the policy server is received in UTF-8 and convertedinto Unicode. Unicode and UTF-8 both allow any character in any locale to beuniquely represented.
However, character data received on the policy server is converted from UTF-8into characters based on the local code page of the server, which cannot uniquelyrepresent all characters in all locales. When character data is returned by the policy
PDAdmin.shutdown(messages);
Figure 8. Shutting down the administration API
16 IBM Tivoli Access Manager: Administration Java Classes Developer’s Reference
server, the data is converted back into UTF-8, which, depending on the charactersoriginally present in the data and the locale used to create the data, could result inone or more of the characters appearing differently.
There are a few ways to reduce the risk of this occurring. One way is to ensurethat the policy server is running with a locale that is compatible with the systemssupplying it data. Another way is to limit the use of characters in character-baseddata, such as user IDs and passwords, to those characters that are representedproperly in the code pages associated with the systems manipulating the data.
Chapter 2. Using the administration API 17
18 IBM Tivoli Access Manager: Administration Java Classes Developer’s Reference
Chapter 3. Administering users and groups
The administration API provides a collection of classes and methods foradministering IBM Tivoli Access Manager (Tivoli Access Manager) users andgroups. This chapter describes the tasks that those classes and methodsaccomplish.
Information about Tivoli Access Manager users and groups is stored in the userregistry. You can use the administration API to both modify and access user andgroup settings in the user registry. In addition, the administration API providesclasses and methods to administer password and account policy settings both on aper user and global basis.
Tivoli Access Manager provides the pdadmin command line interface (CLI) thataccomplishes many of the same user, group, and policy administration tasks.Application developers who have previously used the pdadmin command tomanage an Tivoli Access Manager secure domain will find the administration APIfunctions straightforward to implement.
This chapter contains the following topics:v “Administering users”v “Administering user information” on page 20v “Administering user account policies” on page 21v “Administering user password policies” on page 22v “Administering groups” on page 23v “Administering group information” on page 24
Administering usersThe administration API provides classes and methods for creating, accessing,listing, and deleting Tivoli Access Manager user information within the userregistry.
The name of a user is not case sensitive. Therefore user, USER, User, and UsEr allrefer to the same Tivoli Access Manager user.
The PDUser.createUser method creates a user in the user registry used by theTivoli Access Manager policy server.
Note: When a user definition already exists in the user registry, use thePDUser.importUser method instead.
The PDUser.importUser method imports an existing user definition from the userregistry into Tivoli Access Manager and allows the user definition to be managedby Tivoli Access Manager.
Use the PDUser.deleteUser method to delete a user from Tivoli Access Manager.
Table 3 on page 20 lists the user administration functions.
© Copyright IBM Corp. 2002, 2003 19
User registry difference: Leading and trailing blanks in a user name do not makethe name unique when using an LDAP or ActiveDirectory user registry. However, leading and trailingblanks do make the user name unique when using aDomino server as a user registry. To keep nameprocessing consistent regardless of what user registry isbeing used, do not define user names with leading ortrailing blanks.
Table 3. Administrating users
Function Description
PDUser.createUser Creates the specified user.
PDUser.importUser Creates an Tivoli Access Manager user byimporting an existing user from the userregistry.
PDUser.deleteUser Deletes the specified user.
PDUser.listUsers Lists Tivoli Access Manager users.
Administering user informationThe administration API allows you to administer the information associated withan Tivoli Access Manager user.
When a user account has been created in the user registry, you can set and getdifferent pieces of information about the user. You must create a security contextbetween the calling application and the Tivoli Access Manager policy server beforeyou can access the user registry. You can obtain the user registry information for auser object by specifying either the Tivoli Access Manager user name or the userregistry name.
Table 4 lists the methods available for administering user information.
Table 4. Administrating user information
Function Description
PDUser constructor Instantiates a user object for the specifiedTivoli Access Manager or user registry name.
PDUser object.getDescription Returns the user description.
PDUser object.getRgyName Returns the user registry name for the user.
PDUser object.getId Returns the name of the object.
PDUser object.getFirstName Returns the first-name attribute for the user.
PDUser object.getLastName Returns the last-name attribute for the user.
PDUser object.getPolicy Returns the password and account policysettings associated with the user.
PDUser object.getGroups Lists the groups in which the user is amember.
PDUser object.isAccountValid Returns the account-valid indicator for theuser.
PDUser object.isPDUser Returns a setting that indicates if this is anTivoli Access Manager user.
20 IBM Tivoli Access Manager: Administration Java Classes Developer’s Reference
Table 4. Administrating user information (continued)
Function Description
PDUser object.isSSOUser Returns a setting that indicates if the user hassingle signon capabilities.
PDUser.setDescriptionPDUser object.set Description
Sets a user description.
PDUser.setAccountValidPDUser object.setAccountValid
Enables or disables a user account.
PDUser.setSSOUserPDUser object.setSSOUser
Enables or disables the single signoncapabilities of a user.
PDUser object.isPasswordValid Returns the enabled indicator for the user’spassword.
PDUser.setPasswordPDUser object.setPassword
Sets a user’s password.
PDUser.setPasswordValidPDUser object.setPasswordValid
Enables or disables a user’s password.
Administering user account policiesYou can manage user access by setting account policies. You can specify policiesthat apply only to a single user or specify policies that apply for all users.
When a user’s account policy attribute is set to a value and enforced, that valuealways takes precedence over a value set for the general policy, regardless of whichvalue is more restrictive. If an account policy attribute for a user is not enforced,then the value set for the general policy, if that value is set and enforced, is ineffect for the user.
Table 5 describes the administration API methods that you can use to modify oraccess account policies.
Table 5. Administrating user account policies
Function Description
PDUser.getUserRgy Determines which type of user registry isconfigured for the Tivoli Access Managerpolicy server.
PDPolicy constructor Instantiates a policy object for a user, or forall users in the case of the global policy.
PDPolicy object.acctDisableTimeEnforced Returns an indicator whether the accountdisable time interval policy is enforced.
PDPolicy object.acctDisableTimeUnlimited Returns an indicator whether the accountdisable time interval policy is unlimited.
PDPolicy object.acctExpDateEnforced Returns an indicator whether the accountexpiration date policy is enforced.
PDPolicy object.acctExpDateUnlimited Returns an indicator whether the accountexpiration date policy is unlimited.
PDPolicy object.getAcctExpDate Gets the account expiration date for useraccounts.
PDPolicy object.getAcctDisableTimeInterval Gets the amount of time to disable a useraccount when the maximum number of loginfailures is exceeded.
Chapter 3. Administering users and groups 21
Table 5. Administrating user account policies (continued)
Function Description
PDPolicy object.getMaxFailedLogins Gets the maximum number of failed loginsallowed for user accounts.
PDPolicy object.getAccessibleDaysPDPolicy object.getAccessStartTimePDPolicy object.getAccessEndTimePDPolicy object.getAccessTimezone
Gets the time of day access policy for useraccounts.
PDPolicy object.maxFailedLoginsEnforced Returns an indicator whether the maximumfailed login policy is enforced.
PDPolicy.setAcctExpDatePDPolicy object.setAcctExpDate
Sets the account expiration date for useraccounts.
PDPolicy.setAcctDisableTimePDPolicy object.setAcctDisableTime
Sets the amount of time to disable a useraccount when the maximum number of loginfailures is exceeded.
PDPolicy.setMaxFailedLoginsPDPolicy object.setMaxFailedLogins
Sets the maximum number of failed loginsallowed for user accounts.
PDPolicy.setTodAccessPDPolicy object.setTodAccess
Sets the time of day access for the account foruser accounts.
PDPolicy object.todAccessEnforced Returns an indicator whether the time-of-dayaccess policy is enforced.
Administering user password policiesYou can manage user access by setting password attributes. You can specifypolicies that apply only to a single user or specify policies that apply for all users.
When a user’s password policy attribute is set to a value and enforced, that valuealways takes precedence over a value set for the general policy, regardless of whichvalue is more restrictive. If a password policy attribute for a user is not enforced,then the value set for the general policy, if that value is set and enforced, is ineffect for the user.
Table 6 describes the administration API methods that you can use to modify oraccess password policies.
Table 6. Administrating user password policies
Function Description
PDPolicy constructor Instantiates a policy object for a user, orfor all users in the case of the globalpolicy.
PDPolicy object.getMaxPwdAge Gets the password expiration date.
PDPolicy object.getMaxPwdRepChars Gets the maximum number of repeatedcharacters allowed in the password.
PDPolicy object.getMinPwdAlphas Gets the minimum number of alphabeticcharacters allowed in the password.
PDPolicy object.getMinPwdLen Gets the minimum password length.
PDPolicy object.getMinPwdNonAlphas Gets the minimum number ofnonalphabetic characters allowed in apassword.
22 IBM Tivoli Access Manager: Administration Java Classes Developer’s Reference
Table 6. Administrating user password policies (continued)
Function Description
PDPolicy object.maxPwdAgeEnforced Returns an indicator whether themaximum password age policy isenforced.
PDPolicy object.maxPwdRepCharsEnforced Returns an indicator whether thepassword maximum repeated characterspolicy is enforced.
PDPolicy object.minPwdAlphasEnforced Returns an indicator whether thepassword minimum alphabetic charactersrequired policy is enforced.
PDPolicy object.minPwdLenEnforced Returns an indicator whether theminimum password length policy isenforced.
PDPolicy object.minPwdNonAlphasEnforced Returns an indicator whether thepassword minimum non-alphabeticcharacters policy is enforced.
PDPolicy object.pwdSpacesAllowed Returns an indicator whether spaces areallowed in a password.
PDPolicy.setMaxPwdAgePDPolicy object.setMaxPwdAge
Sets the password expiration date.
PDPolicy.setMaxPwdRepCharsPDPolicy object.setMaxPwdRepChars
Sets the maximum number of repeatedcharacters allowed in a password.
PDPolicy.setMinPwdAlphasPDPolicy object.setMinPwdAlphas
Sets the minimum number of alphabeticcharacters allowed in a password.
PDPolicy.setMinPwdLenPDPolicy object.setMinPwdLen
Sets the minimum password length.
PDPolicy.setMinPwdNonAlphasPDPolicy object.setMinPwdNonAlphas
Sets the minimum number ofnonalphabetic characters allowed in apassword.
PDPolicy.setPwdSpacesAllowedPDPolicy object.setPwdSpacesAllowed
Sets policy for whether spaces are allowedin a password.
Administering groupsThe administration API provides methods for creating, accessing, listing, anddeleting Tivoli Access Manager group information from the user registry.
The name of a group is not case sensitive. Therefore group, GROUP, Group, and GrOuPall refer to the same Tivoli Access Manager group.
The PDGroup.createGroup method creates a group in the user registry used bythe Tivoli Access Manager policy server.
Note: When a group definition already exists in the user registry, use thePDGroup.importGroup method instead.
The PDGroup.importGroup method imports an existing group definition from theuser registry into Tivoli Access Manager and allows the group definition to bemanaged by Tivoli Access Manager.
Table 7 on page 24 lists the group administration functions.
Chapter 3. Administering users and groups 23
User registry difference: Leading and trailing blanks in a group name do notmake the name unique when using an LDAP or ActiveDirectory user registry. However, leading and trailingblanks do make the group name unique when using aDomino server as a user registry. To keep nameprocessing consistent regardless of what user registry isbeing used, do not define group names with leading ortrailing blanks.
Table 7. Administering groups
Function Description
PDGroup.createGroup Creates the specified group.
PDGroup.importGroup Creates an Tivoli Access Manager group byimporting an existing group from the userregistry.
PDGroup.deleteGroup Deletes the specified group.
PDGroup.listGroups Lists Tivoli Access Manager groups.
Administering group informationThe administration API enables you to administer information associated with agroup.
When a group has been created in the user registry, you can set and get differentpieces of information about the group. You must create a security context betweenthe calling application and the Tivoli Access Manager policy server before you canaccess the user registry. You can obtain the user registry information for a groupobject by specifying either the Tivoli Access Manager group name or the userregistry group name.
Table 8 lists the group information administration functions.
Table 8. Administering group attributes
Function Description
PDGroup constructor Instantiates a group object for the specifiedTivoli Access Manager or user registry name.
PDGroup object.getDescription Returns the group description.
PDGroup object.getRgyName Returns the user registry name for the group.
PDGroup object.getId Returns the Tivoli Access Manager name for thegroup.
PDGroup object.isPDGroup Returns an indicator whether the object is anTivoli Access Manager group.
PDGroup.setDescriptionPDGroup object.setDescription
Sets a group description.
PDGroup object.getMembers Lists the members of a group.
PDGroup.addMembersPDGroup object.addMembers
Adds users to a group.User registry difference: Attempting to add aduplicate user to a group is handled differentlydepending on what user registry is being used.See Table 28 on page 56 for details.
24 IBM Tivoli Access Manager: Administration Java Classes Developer’s Reference
Table 8. Administering group attributes (continued)
Function Description
PDGroup.removeMembersPDGroup object.removeMembers
Removes users from a group.User registry difference: Attempting to removea user from a group who is not a member ofthe group is handled differently depending onwhat user registry is being used. See Table 29on page 56 for details.
Chapter 3. Administering users and groups 25
26 IBM Tivoli Access Manager: Administration Java Classes Developer’s Reference
Chapter 4. Administering protected objects and protectedobject spaces
You can use the administration API to create, modify, examine, list, and delete IBMTivoli Access Manager (Tivoli Access Manager) protected objects. These protectedobjects represent resources that must be secured to enforce your security policy.You can specify the security policy by applying access control lists (ACLs) andprotected object policies (POPs) to the protected objects.
Tivoli Access Manager protected objects exist within a virtual hierarchy known as aprotected object space. Tivoli Access Manager provides several protected objectspaces by default. You can use the administration API to define new regions of theprotected object space, to define and secure resources that are specific to athird-party application.
This chapter describes the administration API functions that you can use toadminister protected object spaces and protected objects.
You must be familiar with protected objects before using the administration API.For an introduction to protected objects, see the chapter about managing protectedobjects in the IBM Tivoli Access Manager Base Administrator’s Guide.
For an introduction to the use of ACLs and POPs to secure protected objects, seethe chapter about using access control policies in the IBM Tivoli Access ManagerBase Administrator’s Guide.
This chapter contains the following topics:v “Administering protected object spaces”v “Administering protected objects” on page 28v “Administering protected object attributes” on page 29
Administering protected object spacesYou can use the administration API to create and administer a user-definedprotected object space. You can use this protected object space to define a resourcehierarchy that is specific to a third-party application that uses Tivoli AccessManager authorization services to enforce a security policy.
User-defined object spaces created with the administration API are dynamicbecause they can be updated while Tivoli Access Manager is running.
Table 9 on page 28 lists the methods available for administering protected objectspaces.
Note: For an introduction to the creation of protected object spaces, see theprotected object space information in the IBM Tivoli Access Manager BaseAdministrator’s Guide.
© Copyright IBM Corp. 2002, 2003 27
Table 9. Administering protected object spaces
Function Description
PDProtObjectSpace.createProtObjectSpace Creates an Tivoli Access Manager protectedobject space.
PDProtObjectSpace.deleteProtObjectSpace Deletes the specified Tivoli Access Managerprotected object space.
PDProtObjectSpace.listProtObjectSpaces Lists the Tivoli Access Manager protectedobject spaces.
Administering protected objectsDefine protected objects that reflect the resources that your security policy protects.
The name of a protected object can be of any length and contain any character.However, the forward slash (/) character is interpreted to be part of the objecthierarchy, which allows ACLs to be attached at the various points indicated by theforward slash character.
After you create a protected object, you must specify security policy for it bydefining and attaching ACLs, POPs, or both.
For more information about these Tivoli Access Manager security concepts, see theIBM Tivoli Access Manager Base Administrator’s Guide.
Use caution when implementing protected objects programmatically. In manycases, the protected object hierarchy is manually designed, built, and tested by asecurity expert. Carefully review the hierarchy to ensure that the security policy iscorrectly enforced. If you choose to build protected object hierarchiesprogrammatically, be sure to test and review the settings for each object beforedeploying the security environment.
Table 10 lists the methods available to administer protected objects.
Table 10. Administering protected objects
Function Description
PDProtObject.attachAclPDProtObject object.attachACL
Attaches the specified access control list to thespecified protected object.
PDProtObject.attachPopPDProtObject object.attachPop
Attaches a POP to the specified protectedobject.
PDProtObject.createProtObject Creates an Tivoli Access Manager protectedobject.
PDProtObject.deleteProtObject Deletes the specified Tivoli Access Managerprotected object.
PDProtObject.detachAclPDProtObject object.detachAcl
Detaches the access control list from thespecified protected object.
PDProtObject.detachPopPDProtObject object.detachPop
Detaches a POP from the specified protectedobject.
PDProtObject constructor Instantiates the specified protected object.
PDProtObject object.getAcl Gets the ACL of the specified protected object.
PDProtObject object.getPop Gets the POP of the specified protected object.
28 IBM Tivoli Access Manager: Administration Java Classes Developer’s Reference
Table 10. Administering protected objects (continued)
Function Description
PDProtObject object.getDescription Gets the description of the specified protectedobject.
PDProtObject object.getId Gets the name of the specified protected object.
PDProtObject object.isPolicyAttachable Indicates whether a protected object policy oraccess control list can be attached to thespecified protected object.
PDProtObject.listProtObjectsByPop Returns a list of protected objects that haveprotected object policy (POP) attached.
PDProtObject.listProtObjects Returns the protected objects contained underthe specified directory.
PDProtObject.listProtObjectsByAcl Returns a list of protected objects that have thespecified access control list attached.
PDProtObject.setDescriptionPDProtObject object.setDescription
Sets the description field of the specifiedprotected object.
PDProtObject.setPolicyAttachablePDProtObject object.setPolicyAttachable
Sets whether a protected object policy oraccess control list can be attached to thespecified protected object.
Administering protected object attributesThe attributes for a protected object can be created, set, queried, and deleted.
Table 11 describes the methods for administering protected object attributes.
Table 11. Administering protected object attributes
Function Description
PDProtObject.deleteAttributePDProtObject object.deleteAttribute
Deletes the specified extended attribute (nameand values) from the specified protectedobject.
PDProtObject.deleteAttributeValuePDProtObject object.deleteAttributeValue
Deletes the specified value from the specifiedextended attribute key in the specifiedprotected object.
PDProtObject object.getAttributeValues Returns the values associated with thespecified extended attribute for the specifiedprotected object.
PDProtObject object.getAttributeNames Lists all the extended attributes associatedwith the specified protected object.
PDProtObject.setAttributeValuePDProtObject object.setAttributeValue
Creates an extended attribute with thespecified name and value, if it does notalready exist, and adds the attribute to thespecified protected object. If the attributespecified already exists, the specified value isadded to the existing attribute.
Chapter 4. Administering protected objects and protected object spaces 29
30 IBM Tivoli Access Manager: Administration Java Classes Developer’s Reference
Chapter 5. Administering access control
You can use the administration API to create, modify, examine, list, and delete IBMTivoli Access Manager (Tivoli Access Manager) access control lists (ACLs). You canalso use the administration API to attach ACLs to Tivoli Access Manager protectedobjects and to detach ACLs from protected objects.
Each ACL might contain entries for specific users and groups. You can use theadministration API to set ACL entries for users and groups that already exist in theTivoli Access Manager secure domain. You also can use the administration API toset ACL entries for the default user categories any-other and unauthenticated.
ACL entries consist of one or more permissions. These permissions specify actionsthat the owner of the entry is allowed to perform. Tivoli Access Manager providesa number of default permissions. You can use the adinistration API to defineadditional extended actions. You also can use the administration API to group theextended actions into action groups.
Understand the construction and use of ACLs before using the administration APIACL functions. The proper use of ACLs is key to successfully implementing asecurity policy. For more information, see the chapter about using access controllists in the IBM Tivoli Access Manager Base Administrator’s Guide.
This chapter contains the following topics:v “Administering access control lists”v “Administering access control list entries” on page 32v “Administering access control list extended attributes” on page 34v “Administering extended actions” on page 35v “Administering action groups” on page 34
Administering access control listsACLs enable you to grant or restrict specific users and groups access to protectedresources. The administration API enables you to:v Create and delete ACLsv Retrieve or change information associated with an ACLv List the user, group, any-other, and unauthenticated entries that are included in
the ACLv List all defined ACLs.
The name of an ACL can be of any length. The following characters are allowed inan ACL name:v Alphanumeric characters defined in the localev The underscore (_) characterv The hyphen (-) character
You specify the user entries that belong in each ACL. You also specify thepermissions or actions that each user is allowed to perform.
© Copyright IBM Corp. 2002, 2003 31
You can specify permissions or actions based on group membership, rather thanindividual user identity, to expedite administration tasks.
The administration API defines the PDAcl object to contain a retrieved ACL. Youcan use administration API classes and methods to extract information from thePDAcl object.
Be sure that you understand how to define an ACL policy before using theadministration API ACL methods. For more information, see the section about ACLentry syntax in the IBM Tivoli Access Manager Base Administrator’s Guide.
Table 12 describes the methods for administering ACLs.
Table 12. Administering access control lists
Function Description
PDAcl.createAcl Creates a new ACL.
PDAcl.deleteAcl Deletes the specified ACL.
PDAcl constructor Instantiates the specified ACL.
PDAcl object.getDescription Returns the description of the specified ACL.
PDAcl object.getId Returns the name of the specified ACL.
PDAcl.listAcls Returns the names of all the defined ACLs.
PDAcl.setDescriptionPDAcl object.setDescription
Sets or modifies the description for thespecified ACL.
Administering access control list entriesYou must create an ACL object before you can administer ACL entries for theobject.
The administration API can be used to specify entries for each of the followingACL entry types:v Usersv Groupsv User any-other (also known as any-authenticated)v User unauthenticated
PDAclEntryUserAn ACL entry that applies to a particular user.
PDAclEntryGroupAn ACL entry that applies to all members of a particular group.
PDAclEntryAnyOtherThe ACL entry that applies to any other authenticated users. Any user thathas been authenticated into the Tivoli Access Manager secure domain, butis not covered by a separate user or group entry in the access control list,is allowed the permissions specified by this ACL entry.
PDAclEntryUnAuthThe ACL entry that applies to unauthenticated users. Any user that has notbeen authenticated is allowed the permissions specified by this ACL entry.
32 IBM Tivoli Access Manager: Administration Java Classes Developer’s Reference
Be sure that you understand ACL entry syntax, ACL entry types, and ACLpermission (action) attributes before you use the administration API methods inthis section.
Tivoli Access Manager supports 18 default actions. For a list of the default TivoliAccess Manager actions, see the section about default Tivoli Access Managerpermissions for actions in the IBM Tivoli Access Manager Base Administrator’s Guide.
For more information, see the section about ACL entry syntax in the IBM TivoliAccess Manager Base Administrator’s Guide.
Table 13 lists the methods for administering ACL entries.
Table 13. Administering access control list entries
Function Description
PDAcl object.getPDAclEntryAnyOther Returns the PDAclEntryAnyOther objectassociated with the ACL.
PDAcl object.getPDAclEntryUnAuth Returns the PDAclEntryUnAuth objectassociated with the ACL.
PDAcl object.getPDAclEntriesUser Returns a Java HashMap of thePDAclEntryUser objects associated with theACL.
PDAcl object.getPDAclEntriesGroup Returns a Java HashMap of thePDAclEntryGroup objects associated with theACL.
PDAcl.removePDAclEntryAnyOtherPDAcl object.removePDAclEntryAnyOther
Removes the ACL entry for the any-otheruser from the specified ACL.
PDAcl.removePDAclEntryGroupPDAcl object.removePDAclEntryGroup
Removes the ACL entry for the specifiedgroup from the specified ACL.
PDAcl.removePDAclEntryUnAuthPDAcl object.removePDAclEntryUnAuth
Removes the ACL entry for theunauthenticated user from the specified ACL.
PDAcl.removePDAclEntryUserPDAcl object.removePDAclEntryUser
Removes the ACL entry for the specified userfrom the specified ACL.
PDAcl.setPDAclEntryAnyOtherPDAcl object.setPDAclEntryAnyOther
Sets or modifies the ACL entry for theany-other user in the ACL.
Call this function to specify permissions forall authenticated users that do not have aseparate user or group entry in the specifiedACL.
PDAcl.setPDAclEntryGroupPDAcl object.setPDAclEntryGroup
Sets or modifies the ACL entry for thespecified group in the specified ACL.
PDAcl.setPDAclEntryUnAuthPDAcl object.setPDAclEntryUnAuth
Sets the ACL entry for the unauthenticateduser in the specified ACL.
Call this function to specify permissions forthose users that have not been authenticated.
PDAcl.setPDAclEntryUserPDAcl object.setPDAclEntryUser
Sets the entry for the specified user in thespecified ACL. Use this to specify the actionsthat a user is permitted to perform.
Chapter 5. Administering access control 33
Administering access control list extended attributesExtended attributes for an ACL can be obtained, set, and deleted. Table 14 lists themethods available for administering ACL extended attributes.
Table 14. Administering access control list extended attributes
Function Description
PDAcl.deleteAttributePDAcl object.deleteAttribute
Deletes the specified extended attribute keyfrom the specified ACL.
PDAcl.deleteAttributeValuePDAcl object.deleteAttributeValue
Deletes the specified value from the specifiedextended attribute key in the specified ACL.
PDAcl object.getAttributeValues Gets the extended attribute values for thespecified extended attribute key from thespecified ACL.
PDAcl object.getAttributeNames Lists the extended attribute keys associatedwith the specified ACL.
PDAcl.setAttributeValuePDAcl object.setAttributeValue
Creates an extended attribute with thespecified name and value, if it does notalready exist, and adds the attribute to thespecified ACL. If the attribute specifiedalready exists, the specified value is added tothe existing attribute.
Administering action groupsYou can use the administration API to create, examine, and delete new actiongroups.
Each action group can contain 32 action codes. The default action group, referredto as the primary action group, contains the 18 predefined Tivoli Access Manageraction codes. Thus, you can create up to 14 new action codes to the primary group.
When you need to create more than 32 action codes, you can use theadministration API to define a new action group. Tivoli Access Manager supportsup to 32 action groups.
For more information about action groups, see the section about creating extendedACL actions and action groups in the IBM Tivoli Access Manager BaseAdministrator’s Guide.
Table 15. Administering action groups
Function Description
PDActionGroup.createActionGroup Creates a new action group with the specifiedname.
PDActionGroup.deleteActionGroup Deletes the specified action group and all theactions that belong to the specified group.
PDActionGroup.listActionGroups Lists all the defined action group names.
34 IBM Tivoli Access Manager: Administration Java Classes Developer’s Reference
Administering extended actionsTivoli Access Manager provides a default set of actions (permissions) that belongto the primary action group that can be granted to users or groups. You can usethe administration API to define new, extended actions that supplement the set ofdefault actions. Each of the extended actions can belong to the primary actiongroup or to a custom action group.
Extended actions are typically defined to support actions that are specific to athird-party application. For more information about extended actions, see thesection about creating extended ACL actions and action groups in the IBM TivoliAccess Manager Base Administrator’s Guide.
Table 16. Administering extended actions
Function Description
PDAction.createAction Defines a new action (permission)in thespecified action group.
PDAction.deleteAction Deletes an action (permission) from thespecified action group.
PDAction constructor Gets the specified PDAction object.
PDAction object.getDescription Returns the description for the specifiedaction.
PDAction object.getId Returns the name for the specified action.
PDAction object.getType Returns the type for the specified action.
PDAction.listActions Lists all the defined actions (permissions) forthe specified action group.
Chapter 5. Administering access control 35
36 IBM Tivoli Access Manager: Administration Java Classes Developer’s Reference
Chapter 6. Administering protected object policies
You can use the administration API to create, modify, examine, and delete IBMTivoli Access Manager (Tivoli Access Manager) protected object policies (POPs).You can also use the Administration API to attach or detach POPs from protectedobjects.
You can use POPs to impose additional conditions on operations that are permittedby an access control list (ACL) policy. These additional conditions are enforcedregardless of the user or group identities specified in the ACL entries.
Examples of additional conditions include the following:v Specifying the quality of protectionv Writing a report record to the auditing servicev Requiring an authentication strength levelv Restricting access to a specific time periodv Enabling or disabling warning mode, which allows an administrator to validate
security policy
Be sure that you understand Tivoli Access Manager POPs before using theadministration API to administer POPs. For more information, see the chapterabout using POPs in the IBM Tivoli Access Manager Base Administrator’s Guide.
This chapter contains the following topics:v “Administering protected object policy objects”v “Administering protected object policy settings” on page 38v “Administering protected object policy extended attributes” on page 39
Administering protected object policy objectsPOP objects are administered in a similar way to ACL policies. You can create andconfigure a POP, and then attach the POP to objects in the protected object space.
Table 17. Administering protected object policy objects
Function Description
PDPop.createPop Creates a POP object with the default values.
PDPop.deletePop Deletes the specified POP.
PDPop object.getDescription Gets the description of the specified POP.
PDPop object.getId Gets the name of the specified POP.
PDProtObject.listProtObjectsByPop Finds and lists all protected objects that havethe specified POP attached.
PDPop constructorPDProtObject object.getPop
Gets the specified POP object.
PDPop.listPops Lists all POP objects.
© Copyright IBM Corp. 2002, 2003 37
PDPop.IPAuthInfo objectAn array of PDPop.IPAuthInfo objects is passed as input to thePDPop.setIPAuthInfo and PDPop.removeIPAuthInfo methods. EachPDPop.IPAuthInfo object contains the following information:
IP addressThe IP address, in ″%d.%d.%d.%d″ String format associated with thecredentials that are being checked. A value of ″0.0.0.0″ indicates this settingis for any other network for which this policy is not set explicitly.
NetmaskThe netmask, in ″%d.%d.%d.%d″ String format, associated with thecredentials that are being checked. A value of ″0.0.0.0″ indicates this settingapplies to any other network for which this policy is not set explicitly.
IP authentication levelThe IP authentication level of the credentials for the specified IP addressand netmask when trying to access the protected object to which this POPis attached. Use the constantPDPOP_IPAUTH_LEVEL_FORBIDDEN_ALL_NETWORKS to deny accessfrom all networks.
See the IBM Tivoli Access Manager Base Administrator’s Guide for more informationabout IP authentication POP policy. See the Javadoc for the PDPop.IPAuthInfoobject and its associated methods for additional information.
Administering protected object policy settingsYou can use the administration API to set, modify, or remove attributes in a POP.You must create the POP object before specifying POP settings.
You can use administration API functions to specify the following POP attributes:v Authentication levelsv Quality of Protection (QOP) requirementsv Auditing levelsv Time of day access restrictionsv Warning mode settings
For more information about the use of the authentication level by WebSEAL, seethe section about authentication strength POP policy (step-up) in the IBM TivoliAccess Manager WebSEAL Developer’s Reference.
The quality of protection (QOP) level is not enforced internally by Tivoli AccessManager. Applications that set the quality of protection can enforce it.
Audit levels specify what operations generate an audit record. This value is usedinternally by Tivoli Access Manager and also can be used by applications togenerate their audit records.
The time of day access setting is used to control access to a protected object basedon the time when the access occurs.
The warning mode enables a security administrator to troubleshoot theauthorization policy set on the protected object space.
38 IBM Tivoli Access Manager: Administration Java Classes Developer’s Reference
When you set the warning attribute to yes, any action is possible by any user onthe object where the POP is attached. Any access to an object is permitted even ifthe ACL policy attached to the object is set to deny this access.
Audit records are generated that capture the results of all ACL policies withwarning mode set throughout the object space. The audit log shows the outcomeof an authorization decision as it would have been made if the warning attributehad been set to no.
Table 18. Administering protected object policy settings
Function Description
PDPop object.getIPAuthInfo Gets the IP authentication level informationfrom the specified POP.
PDPop object.getAuditLevel Gets the audit level for the specified POP.
PDPop object.getQOP Gets the quality of protection (QOP) level forthe specified POP.
PDPop object.getTodAccessInfo Gets the time of day range for the specifiedPOP.
PDPop object.getWarningMode Gets the warning mode value from thespecified POP.
PDPop.removeIPAuthInfoPDPop object.removeIPAuthInfo
Removes the specified IP authentication levelinformation from the specified POP.
PDPop.setIPAuthInfoPDPop object.setIPAuthInfo
Sets the IP authentication level information forthe specified POP.
PDPop.setAuditLevelPDPop object.setAuditLevel
Sets the audit level for the specified POP.
PDPop.setDescriptionPDPop object.setDescription
Sets the description of the specified POP.
PDPop.setQOPPDPop object.setQOP
Sets the quality of protection level for thespecified POP.
PDPop.setTodAccessInfoPDPop object.setTodAccessInfo
Sets the time of day range for the specifiedPOP.
PDPop.setWarningModePDPop object.setWarningMode
Sets the warning mode for the specified POP.
Administering protected object policy extended attributesTable 19. Administering protected object policy extended attributes
Function Description
PDPop.deleteAttributePDPop object.deleteAttribute
Deletes the specified extended attribute fromthe specified POP.
PDPop.deleteAttributeValuePDPop object.deleteAttributeValue
Deletes the specified value from the specifiedextended attribute key in the specified POP.
PDPop object.getAttributeValues Gets the values for the specified extendedattribute from the specified POP.
PDPop object.getAttributeNames Lists the extended attributes associated withthe specified POP.
PDPop.setAttributeValuePDPop object.setAttributeValue
Sets the value for the specified extendedattribute in the specified POP.
Chapter 6. Administering protected object policies 39
40 IBM Tivoli Access Manager: Administration Java Classes Developer’s Reference
Chapter 7. Administering single signon resources
You can use the administration API to administer resources that enable an IBMTivoli Access Manager (Tivoli Access Manager) user to obtain single signon (SSO)capability across more than one Web server. This capability requires the use ofTivoli Access Manager WebSEAL junctions.
You can use the administration API to create, modify, examine, and delete thefollowing types of resources:v Web resourcesv Resource groupsv Resource credentials
Be sure that you understand Tivoli Access Manager single signon support beforeyou use the administration API to administer single signon resources. For moreinformation about administering single signon capability across junctioned Webserver resources, see the section about user registry resource managementcommands in the IBM Tivoli Access Manager Base Administrator’s Guide and thesection about using global sign-on (GSO) in the IBM Tivoli Access ManagerWebSEAL Developer’s Reference.
This chapter contains the following topics:v “Web resources”v “Resource groups” on page 42v “Resource credentials” on page 43
Web resourcesA Web resource is a Web server that serves as the backend of an Tivoli AccessManager WebSEAL junction. An application on the joined Web server can requireusers to authenticate specifically to the application. The authentication information,such as user name and password, often differs from the authentication informationused by Tivoli Access Manager.
The junctioned Web server thus requires an authenticated Tivoli Access Manageruser to log in again, using the user name and password specific to the applicationon the joined Web server.
You can use the administration API to configure Tivoli Access Manager so thatTivoli Access Manager users need to authenticate only one time. You must define aWeb resource (server) and then define a user-specific resource credential thatcontains user-specific authentication information for the Web resource.
This section describes how to create, modify, and delete Web resources.Administration of resource credentials is described in “Resource credentials” onpage 43.
Note: The administration API does not perform all WebSEAL junctionconfiguration tasks through the API. Use the pdadmin commands to modifythe junction definitions. For more information, see the IBM Tivoli AccessManager WebSEAL Administrator’s Guide.
© Copyright IBM Corp. 2002, 2003 41
Table 20. Administering Web resources
Function Description
PDSSOResource.createSSOResource Creates a single signon Web resource.
PDSSOResource.deleteSSOResource Deletes the specified single signon Webresource.
PDSSOResource constructor Instantiates the specified single signon Webresource.
PDSSOResource object.getDescription Returns the description of the specified singlesignon Web resource.
PDSSOResource object.getId Returns the name (identifier) of the specifiedsingle signon Web resource.
PDSSOResource.listSSOResources Returns a list of all of the single signon Webresource names.
Resource groupsA resource group is a group of Web servers, all of which have been junctioned to anTivoli Access Manager WebSEAL server and all of which use the same set of userIDs and passwords.
You can use the administration API to create resource groups. You can then createa single resource credential for all the resources in the resource group. This enablesyou to simplify the management of Web resources by grouping similar Webresources into resource groups.
You can also use the administration API to add more Web resources, whennecessary, to an existing resource group.
Table 21. Administering resource groups
Function Description
PDSSOResourceGroup.addSSOResourcePDSSOResourceGroup object.addSSOResource
Adds a single signon resource to asingle signon resource group.
PDSSOResourceGroup.createSSOResourceGroup Creates a single signon groupresource.
PDSSOResourceGroup.deleteSSOResourceGroup Deletes a single signon groupresource.
PDSSOResourceGroup constructor Instantiates the specified singlesignon group resource.
PDSSOResourceGroup object.getDescription Returns the description of thesingle signon group resource.
PDSSOResourceGroup object.getId Returns the name of the singlesignon group resource.
PDSSOResourceGroup object.getSSOResources Returns a list of the member singlesignon resource names for thespecified single signon group.
PDSSOResourceGroup.listSSOResourceGroups Returns a list of all of the singlesignon group resource names.
PDSSOResourceGroup.removeSSOResourcePDSSOResourceGroup object.removeSSOResource
Removes a single signon resourcefrom the specified single signonresource group.
42 IBM Tivoli Access Manager: Administration Java Classes Developer’s Reference
Resource credentialsA resource credential provides a user ID and password for a single signonuser-specific resource, such as a Web server or a group of Web servers. The Webresource or group of Web resources must exist before you can apply resourcecredentials to it.
Resource credential information is stored in the user’s Tivoli Access Manager entryin the user registry.
You can use the administration API to create, modify, examine, and delete resourcecredentials.
Table 22. Administering credentials
Function Description
PDSSOCred.createSSOCred Creates a single signon credential.
PDSSOCred.deleteSSOCred Deletes a single signon credential.
PDSSOCred constructor Instantiates the specified single signoncredential.
PDSSOCred object.getResourceName Returns the name of the single signonresource associated with this credential.
PDSSOCred object.getResourcePassword Returns the password associated with thissingle signon credential.
PDSSOCred object.getResourceUser Returns the name of the resource userassociated with the specified single signoncredential.
PDSSOCred object.getResourceType Returns the type of the single signon resourceassociated with the specified single signoncredential.
PDSSOCred object.getUser Returns the name of the Tivoli AccessManager user associated with this singlesignon credential.
PDSSOCred.listAndShowSSOCreds Returns the list of single signon credentials forthe specified user.
PDSSOCred.listSSOCreds Returns the IDs (user, resource, and type) ofthe single signon credentials for the specifieduser. This information is a subset of thatreturned by the listAndShowSSOCredsmethod.
PDSSOCred.setSSOCredPDSSOCred object.setSSOCred
Modifies a single signon credential.
Chapter 7. Administering single signon resources 43
44 IBM Tivoli Access Manager: Administration Java Classes Developer’s Reference
Chapter 8. Configuring application servers
You can use the administration API to configure and unconfigure authorizationand administration API servers, modify configuration parameters, administerreplicas, and perform certificate maintenance.
The com.tivoli.pd.jcfg.SvrSslCfg class is used to perform the necessaryconfiguration steps that allow an application to use a secure sockets layer (SSL)connection for communicating with the policy server or the authorization server. Itis not intended to do all of the configuration that may be required to ensure acorrectly functioning application. For more information about thecom.tivoli.pd.jcfg.SvrSslCfg class, see the IBM Tivoli Access Manager AuthorizationJava Classes Developer’s Reference
Note: The local host name is used to build a unique name for the application. Insome cases, depending on the TCP/IP configuration, the host name is notalways consistent and may result in look-up failures. For example, theoperating system might return the fully qualified host name while anothermachine might just return the host name. If this happens in your network,you should use the following format to specify the server name to thecommand line interface:server_name/desired_host_name
For the API, these parameters are separate. There, desired_host_name shouldbe specified for the host_name parameter.
This chapter contains the following topics:v “Configuring application servers”v “Administering configuration information” on page 46v “Certificate maintenance” on page 46
Configuring application serversUse the configuration commands to enable an application server (an applicationthat uses the authorization or administration API) to communicate with the policyserver or the authorization server. An administrative user identity (for example,sec_master) and password must be specified for connecting to the policy server.
Table 23. Configuring application servers
Function Description
PDAppSvrConfig.configureAppSvr Configures an application server by updatingthe configuration file and creating the keystorefile.
PDAppSvrConfig.setAppSvrListening Sets or resets the enable-listening parameter inthe configuration file.
PDAppSvrConfig.setAppSvrDbDir Sets the local policy database directory in theconfiguration file.
PDAppSvrConfig.setAppSvrDbRefresh Sets the local policy database database refreshinterval in the configuration file
© Copyright IBM Corp. 2002, 2003 45
Table 23. Configuring application servers (continued)
Function Description
PDAppSvrConfig.setAppSvrPort Changes the listening port number of theapplication in the configuration file.
PDAppSvrConfig.unconfigureAppSvr Unconfigures an application server.
Administering configuration informationTable 24. Administering configuration information
Function Description
PDAppSvrConfig.addPDServer Adds a replica entry to the configuration file.
PDAppSvrConfig.changePDServer Changes parameters of a replica entry in theconfiguration file.
PDAppSvrConfig.removePDServer Removes a replica entry from theconfiguration file.
PDAppSvrConfig.getPDAppSvrInfo Returns a PDAppSvrInfo object containinginformation stored in the configuration file.
PDAppSvrConfig.getKeystoreURL Returns the URL of the keystore file that isassociated with the configuration file.
Certificate maintenanceOnly use the replaceAppSvrCert method when the certificate has beencompromised.
Table 25. Certificate maintenance
Function Description
PDAppSvrConfig.replaceAppSvrCert Replaces the server SSL certificate.
46 IBM Tivoli Access Manager: Administration Java Classes Developer’s Reference
Chapter 9. Administering servers
You can use the administration API to get a list of tasks from the server, send aspecific task to an authorization server, and notify replica databases, eitherautomatically or manually, when the master authorization database is updated.
This chapter contains the following topics:v Getting and performing administration tasksv 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
Getting and performing administration tasksYou can send an administration task to a server. You also can request a list of allsupported administration tasks from a server. The caller must have credentialswith sufficient permission to perform the task. For more information, see the IBMTivoli Access Manager Authorization C API Developer’s Reference.
Notifying replica databases when the master authorization database isupdated
When an administrator makes security policy changes, the policy server makesadjustments to the master authorization database to reflect these changes. Toensure that these changes also are dispersed to any authorization servers withreplica databases, you can do one or more of the following:v Configure an IBM Tivoli Access Manager (Tivoli Access Manager) application,
such as WebSEAL, to poll the master authorization database at regular intervalsfor updates. By default, polling is disabled. For more information about pollingthe master authorization database, see the cache-refresh-interval optiondescribed in the IBM Tivoli Access Manager Authorization C API Developer’sReference.
v Enable the policy server to notify authorization servers each time that the masterauthorization database is updated. This automatic process is recommended forenvironments where database changes are infrequent. For more information, see“Notifying replica databases automatically” on page 48.
v Notify authorization servers, on demand, after you make updates to the masterauthorization database. This manual process is recommended for environmentswhere database changes are frequent and involve substantial changes. Forinstructions, see “Notifying replica databases manually” on page 48.
After you select the method that you want to use to update replica databases(automatic, manual, or both), you can fine-tune settings in the ivmgrd.conf file onthe policy server. For more information, see “Setting the maximum number ofnotification threads” on page 48 and “Setting the notification wait time” on page48.
© Copyright IBM Corp. 2002, 2003 47
Notifying replica databases automaticallyYou can enable the policy server to send notifications to authorization servers eachtime that the master authorization database is updated. In turn, the authorizationservers automatically request a database update from the policy server.
To enable automatic database updates, edit the ivmgrd.conf file on the policyserver and add the following attribute=value pair:[ivmgrd]auto-database-update-notify = yes
You must restart the policy server for changes to take effect. Note that this settingis recommended for environments where the master database is changedinfrequently. To turn off automatic notification, specify no.
Notifying replica databases manuallyWhen the master authorization database is updated, you can use thePDServer.replicateServer method to send notification to application servers thatare configured to receive database update notifications. You can indicate that aspecific server receive update notifications, or specify NULL, which notifies allconfigured authorization servers in the secure domain. If you specify a servername, you are notified whether the server was replicated successfully or if a failureoccurred. If you do not specify a server name, return codes indicate whether or notthe policy server started notifying authorization servers in your secure domain.Note that unless you specify the server-name option, you are not notified when anauthorization server’s database was replicated successfully.
Setting the maximum number of notification threadsWhen the master authorization database is updated, this update is announced toreplica databases through the use of notification threads. Each replica then has theresponsibility of downloading the new data from the master authorizationdatabase.
You can edit the ivmgrd.conf file to set a value for the maximum number ofnotification threads. This number is calculated based on the number of replicadatabases in your secure domain. For example, if you have 10 replica databasesand want to notify them of master database changes simultaneously, specify avalue of 10 for the max-notifier-threads attribute as shown:[ivmgrd]max-notifier-threads = 10
The default value is 10 (threads).
Setting the notification wait timeThere is a time delay between when the policy server updates the masterauthorization database and when notification is sent to database replicas. If youadded auto-database-update-notify = yes to the ivmgrd.conf file as described in“Notifying replica databases automatically” on page 48, you can set this period oftime. To do so, edit the notifier-wait-time value in the ivmgrd.conf file. Forexample, if you are making batch changes to the master authorization database, itis advisable to wait until all changes have been made before policy changes aresent to database replicas. Therefore, you might decide to increase the default valuefrom 15 seconds to 25 seconds as shown:[ivmgrd]notifier-wait-time = 25
48 IBM Tivoli Access Manager: Administration Java Classes Developer’s Reference
By editing the value for this attribute, the policy server is prevented from sendingindividual replica notifications for each of a series of database changes.
Administrating servers and database notificationTable 26. Administrating servers and database notification
Function Description
PDServer.getTaskList Gets the list of tasks from the server.
PDServer.performTask Sends a command to an authorization server.
PDServer.replicateServer Notifies authorization servers to receivedatabase updates.
Chapter 9. Administering servers 49
50 IBM Tivoli Access Manager: Administration Java Classes Developer’s Reference
Appendix A. Differences between the C and Javaadministration API
If you are familiar with the administration C API described in the IBM Tivoli AccessManager Administration C API Developer’s Reference, you should be aware of severalnotable differences between them and the administration Java classes and methodsdescribed in this document. In particular the handling of security contextmanagement and response processing are different between the twoimplementations. In addition, there are other subtle differences outlined in thisappendix.
Security context management differencesThe ivadmin_context_create() function in the C language administration APIcreates a communication connection to the Tivoli Access Manager policy server.The context object returned by this function is tightly coupled to an actual SecureSockets Layer (SSL) session. When the SSL session times out, the user must deletethe context and create a new one in order to re-establish communication with thepolicy server. Unneeded contexts must be deleted on a timely basis withivadmin_context_delete() to free SSL resources. This places the onus on theprogrammer to manage SSL sessions through the use of context objects and theivadmin_context_* APIs.
The Java implementation of the context, using the PDContext object, hides themanagement of the actual SSL sessions from the user. The PDContext object onlycontains the information needed to establish communication with the server: theserver location, the client’s authentication information, and the locale to be usedfor message translation. The PDContext objects are not tied to a particular SSLsession. Instead, an SSL session is obtained when a PDContext object is used in aJava method invocation. Tivoli Access Manager manages the SSL sessions itself —creating them, pooling them, reusing them, and eventually deleting them —without any explicit context management from the programmer.
Response processing differencesMost of the C language administration API functions return a boolean valueindicating the overall success or failure of the requested operation. They alsoreturn an ivadmin_response object as an output parameter. This response objectcontains optional messages that can be subsequently processed using theivadmin_response_* functions.
The Java language administration API methods throw a PDException exception onfailure. Most methods provide a PDMessages output as an output parameter. Thisobject contains optional messages that can be subsequently processed using theaccessor methods provided in the PDMessages object class.
Additional differencesThe following additional differences exist between the C language and Javalanguage implementations of the Tivoli Access Manager administration API.v The method names in the PDUser and PDGroup classes are user registry
neutral. The function names provided in the administration C APIs are
© Copyright IBM Corp. 2002, 2003 51
Lightweight Directory Access Protocol (LDAP) specific. This difference arisesfrom the continuing support of a wider range of user registries in IBM TivoliAccess Manager (Tivoli Access Manager.)
v The user and group names that appear in the methods associated with thePDUser and PDGroup classes are structured to allow for the possible futureaddition of other user registries.
v The type field is not supported in the PDProtObject and PDProtObjectSpaceclasses. Use extended attributes to provide equivalent function. This differencearises from the confusion caused by the type field on the administration C APIsnot being used internally by Tivoli SecureWay Policy Director in the past.
v The caller of the administration Java APIs can specify the locale for theinformation returned by the API. The administration C API always returnsinformation using the default locale.
v The administration Java classes and methods provide both certificate-based anduser ID and password-based authentication. The administration C API onlyprovides user ID and password-based authentication.
v The svrsslcfg command line interface (CLI) only can be used for applicationswritten using the administration C API. For Java applications, use thecom.tivoli.pd.jcfg.SvrSslCfg Java class instead.
v Policy information, such as maximum password age, is encapsulated in aPDPolicy class instead of being defined in the user and context objects as it is inthe administration C API. The function provided is the same whether using theJava classes or the C API.
v When using the administration C APIs, the user must renegotiate the securitycontext when a session time out occurs. The PDContext class handles thisprocessing automatically.
v There is no equivalent Java method for ivadmin_context_delete(). Managingsecurity contexts is handled automatically by the Java transport layer.
52 IBM Tivoli Access Manager: Administration Java Classes Developer’s Reference
Appendix B. Deprecated Java classes and methods
The classes and methods listed in Table 27 have been deprecated in IBM TivoliAccess Manager Version 4.1. Existing Java applications should be changed to usethe replacement class or method indicated.
Table 27. Deprecated Java Classes and Methods
Deprecated Class or Method Replacement Class or Method
com.tivoli.mts.PDAttrs( ) com.tivoli.mts.PDAttrs(boolean allowDuplicates)
com.tivoli.mts.PDAttrs.add(java.lang.String name,PDAttrValues vals)
com.tivoli.mts.PDAttrs.add( java.lang.String name,java.util.Collection vals)
com.tivoli.mts.PDAttrs.get( java.lang.String key) com.tivoli.mts.PDAttrs.getValues(java.lang.String key)
com.tivoli.mts.SvrSslCfg com.tivoli.pd.jcfg.SvrSslCfg
© Copyright IBM Corp. 2002, 2003 53
54 IBM Tivoli Access Manager: Administration Java Classes Developer’s Reference
Appendix C. User registry differences
The following user registry differences are known to exist in this version of IBMTivoli Access Manager (Tivoli Access Manager.)1. Leading and trailing blanks in user names and group names are ignored when
using LDAP or Microsoft Active Directory as the user registry in an TivoliAccess Manager secure domain. However, when using a Lotus Domino serveras a user registry, leading and trailing blanks are significant. To ensure thatprocessing is consistent regardless of what user registry is being used, defineusers and groups in the user registry without leading or trailing blanks intheir names.
2. The forward slash character (/) should be avoided in user and group namesdefined using distinguished name strings. The forward slash character istreated differently in different user registries:
Lotus Domino serverUsers and groups can not be created with names using adistinguished name string containing a forward slash character. Toavoid the problem, either do not use a forward slash character ordefine the user without using the distinguished name designation:pdadmin user create myuser username/locinfo test test testpwd
instead of using this one:pdadmin user create myuser cn=username/o=locinfo test test testpwd
Microsoft Active DirectoryUsers and groups can be created with names using a distinguishedname string containing a forward slash character. However,subsequent operations on the object might fail as some ActiveDirectory functions interpret the forward slash character as a separatorbetween the object name and the host name. To avoid the problem, donot use a forward slash character to define the user.
3. When using a multi-domain Microsoft Active Directory user registry, multipleusers and groups can be defined with the same short name as long as theyreside in different domains. To query information associated with a specificuser or group, use the full name, including the domain, of the user or groupto ensure that you are getting the correct information. If the domaininformation is omitted, information about the user or group defined in thedefault domain is returned, which might not be the expected user or group.The sole use of a short name to identify a user or group should be avoidedfor the same reason.
4. If Microsoft Active Directory is used as the user registry, care must be takenwith user and group names that contain period characters (.) Active Directorydoes not permit a name to end with a period. (See Microsoft Knowledge Basearticle 316595 for details.) The first twenty (20) characters of a user or groupname created by Tivoli Access Manager are mapped to a SAMAccountNamein Active Directory. If the 20th character happens to be a period character,Active Directory considers the name not valid and generates an error. This canhappen if a server in the Tivoli Access Manager happens to have a period inits name in that position, such as centralpolicyserver.company.com.To avoid this problem, rename servers in the Tivoli Access Managerenvironment that have a period character in the 20th position of their name.
© Copyright IBM Corp. 2002, 2003 55
Alternately, if the period occurs in the DNS suffix for a Microsoft Windowsserver, you might be able to avoid the problem by removing the primary DNSsuffix from the Network settings.
5. When using iPlanet Version 5.0 as the user registry, a user that is created,added to a group, and then deleted from the user registry retains its groupmembership. If a user with the same name is created at some later time, thenew user automatically inherits the old group membership and might begiven inappropriate permissions. It is strongly recommended that the user beremoved from all groups before the user is deleted. This problem does notoccur when using the other supported user registries.
6. Attempting to add a duplicate user to a group produces different resultsbased on the user registry being used. Table 28 outlines the differences.
Table 28. User registry differences when adding a duplicate user to a group
Operation LDAP Lotus Domino server Microsoft ActiveDirectory
Add one user andthat user is duplicate
Error No error Error
Add multiple users,first user is duplicate
Error for all users No error Error for all users
Add multiple users, auser other than thefirst is a duplicate
Error for all users No error Partial completionmessage
7. Attempting to remove a user from a group who is not a member of the groupproduces different results based on the user registry being used. Table 29outlines the differences.
Table 29. User registry differences when removing a user from a group who is not amember of the group
Operation LDAP Lotus Domino server Microsoft ActiveDirectory
Remove one user,user is not in thegroup
Error Error Error
Remove multipleusers, first user notin the group
Error for all users Error Error for all users
Remove multipleusers, a user otherthan the first is not inthe group
Error for all users Partial completionmessage
Partial completionmessage
8. The maximum lengths of various names associated with Tivoli AccessManager vary depending on the user registry being used. See Table 30 for acomparison of the maximum lengths allowed and the recommendedmaximum length to use to ensure compatibility with all the user registriessupported by Tivoli Access Manager.
Table 30. Maximum lengths for names based on user registry
Maximumlength of:
LDAP Microsoft ActiveDirectory
Lotus Dominoserver
Recommendedmaximum value
First name(LDAP CN)
256 64 960 64
56 IBM Tivoli Access Manager: Administration Java Classes Developer’s Reference
Table 30. Maximum lengths for names based on user registry (continued)
Maximumlength of:
LDAP Microsoft ActiveDirectory
Lotus Dominoserver
Recommendedmaximum value
Middle name 128 64 65535 64
Last name(surname)
128 64 960 64
Registry UID(LDAP DN)
1024 2048 255 This value isuser
registry-specificand must be
changed whenchanging user
registries.
Tivoli AccessManager useridentity
256 2048 - 1 -length_of_
domain_name
200 - 4 -length_of_
domain_name
This value isuser
registry-specificand must be
changed whenchanging user
registries.
User password unlimited 256 unlimited 256
User description 1024 1024 1024 1024
Group name 256 256
Groupdescription
1024 1024 1024 1024
Single signonresource name
240 256 256 240
Single signonresourcedescription
1024 1024 1024 1024
Single signonuser ID
240 256 256 240
Single signonpassword
unlimited 256 unlimited 256
Single signongroup name
240 256 256 240
Single signongroupdescription
1024 1024 1024 1024
Action name 1 1 1 1
Actiondescription,action type
unlimited unlimited unlimited
Object name,object spacename, ACLname, POPname
unlimited unlimited unlimited
Appendix C. User registry differences 57
Table 30. Maximum lengths for names based on user registry (continued)
Maximumlength of:
LDAP Microsoft ActiveDirectory
Lotus Dominoserver
Recommendedmaximum value
Objectdescription,object spacedescription, ACLdescription, POPdescription
unlimited unlimited unlimited
Even though some names can be of unlimited length, excessive lengths canresult in policy that is difficult to manage and might result in poor systemperformance. Choose maximum values that are logical for your environment.
9. Users created in a Lotus Domino server or Microsoft Active Directory userregistry are automatically given the capability to own single signon credentialsand this capability can not be removed. When using an LDAP user registry,this capability must be explicitly granted to a user and subsequently can beremoved.
10. When the Tivoli Access Manager policy server is using either Microsoft ActiveDirectory or a Lotus Domino server as its user registry, existing TivoliSecureWay Policy Director, Version 3.8 clients are not able to connect to thepolicy server. Either use a different user registry or upgrade the clients toTivoli Access Manager.
58 IBM Tivoli Access Manager: Administration Java Classes Developer’s Reference
Appendix D. Administration C API, Java method, andcommand line equivalents
This appendix shows the mapping that exists between the administration C APIfunctions, the administration Java classes and methods, and the command lineinterface (CLI). In some cases, a given operation can be performed different ways.Note that in some cases two or more method calls might be necessary to achievethe same effect as a single C API function.
Information about the administration C API can be found in the IBM Tivoli AccessManager Administration C API Developer’s Reference.
Information about the pdadmin command line interface can be found in the IBMTivoli Access Manager Command Reference.
© Copyright IBM Corp. 2002, 2003 59
Tabl
e31
.M
appi
ngbe
twee
nad
min
istr
atio
nC
AP
I,Ja
vam
etho
ds,
and
the
com
man
dlin
ein
terf
ace
CA
PI
Java
Cla
ssan
dM
eth
odC
omm
and
Lin
eE
qu
ival
ent
ivad
min
_acl
_att
rdel
key
()P
DA
cl.d
elet
eAtt
rib
ute
PD
Acl
obje
ct.d
elet
eAtt
rib
ute
pdad
min
acl
modi
fyac
l_na
mede
lete
attr
ibut
eat
trib
ute_
name
ivad
min
_acl
_att
rdel
val(
)P
DA
cl.d
elet
eAtt
rib
ute
Val
ue
PD
Acl
obje
ct.d
elet
eAtt
rib
ute
Val
ue
pdad
min
acl
modi
fyac
l_na
mede
lete
attr
ibut
eat
trib
ute_
name
attr
ibut
e_va
lue
ivad
min
_acl
_att
rget
()P
DA
clob
ject
.get
Att
rib
ute
Val
ues
pdad
min
acl
show
acl_
name
attr
ibut
eat
trib
ute_
name
ivad
min
_acl
_att
rlis
t()
PD
Acl
obje
ct.g
etA
ttri
bu
teN
ames
pdad
min
acl
list
acl_
name
attr
ibut
e
ivad
min
_acl
_att
rpu
t()
PD
Acl
.set
Att
rib
ute
Val
ue
PD
Acl
obje
ct.s
etA
ttri
bu
teV
alu
epd
admi
nac
lmo
dify
acl_
name
set
attr
ibut
eat
trib
ute_
name
attr
ibut
e_va
lue
ivad
min
_acl
_cre
ate(
)P
DA
cl.c
reat
eAcl
pdad
min
acl
crea
teac
l_na
me
ivad
min
_acl
_del
ete(
)P
DA
cl.d
elet
eAcl
pdad
min
acl
dele
teac
l_na
me
ivad
min
_acl
_get
()P
DA
clco
nstr
ucto
rpd
admi
nac
lsh
owac
l_na
me
ivad
min
_acl
_get
anyo
ther
()P
DA
clob
ject
.get
PD
Acl
En
tryA
nyO
ther
pdad
min
acl
show
any-
othe
r
ivad
min
_acl
_get
des
crip
tion
()P
DA
clob
ject
.get
Des
crip
tion
pdad
min
acl
show
acl_
name
ivad
min
_acl
_get
grou
p()
PD
Acl
obje
ct.g
etP
DA
clE
ntr
iesG
rou
ppd
admi
nac
lsh
owac
l_na
me
ivad
min
_acl
_get
id()
PD
Acl
obje
ct.g
etId
pdad
min
acl
show
acl_
name
ivad
min
_acl
_get
un
auth
()P
DA
clob
ject
.get
PD
Acl
En
tryU
nA
uth
pdad
min
acl
show
acl_
name
ivad
min
_acl
_get
use
r()
PD
Acl
obje
ct.g
etP
DA
clE
ntr
iesU
ser
pdad
min
acl
show
acl_
name
ivad
min
_acl
_lis
t()
PD
Acl
.list
Acl
spd
admi
nac
lli
st
ivad
min
_acl
_lis
tgro
up
s()
PD
Acl
obje
ct.g
etP
DA
clE
ntr
iesG
rou
ppd
admi
nac
lsh
owac
l_na
me
ivad
min
_acl
_lis
tuse
rs()
PD
Acl
obje
ct.g
etP
DA
clE
ntr
iesU
ser
pdad
min
acl
show
acl_
name
ivad
min
_acl
_rem
ovea
nyo
ther
()P
DA
cl.r
emov
ePD
Acl
En
tryA
nyO
ther
PD
Acl
obje
ct.r
emov
ePD
Acl
En
tryA
nyO
ther
pdad
min
acl
modi
fyac
l_na
mere
move
any-
othe
r
ivad
min
_acl
_rem
oveg
rou
p()
PD
Acl
.rem
oveP
DA
clE
ntr
yGro
up
PD
Acl
obje
ct.r
emov
ePD
Acl
En
tryG
rou
ppd
admi
nac
lmo
dify
acl_
name
remo
vegr
oup
grou
p_na
me
ivad
min
_acl
_rem
oveu
nau
th()
PD
Acl
.rem
oveP
DA
clE
ntr
yUn
Au
thP
DA
clob
ject
.rem
oveP
DA
clE
ntr
yUn
Au
thpd
admi
nac
lmo
dify
acl_
name
remo
veun
auth
enti
cate
d
ivad
min
_acl
_rem
oveu
ser(
)P
DA
cl.r
emov
ePD
Acl
En
tryU
ser
PD
Acl
obje
ct.r
emov
ePD
Acl
En
tryU
ser
pdad
min
acl
modi
fyac
l_na
mere
move
user
user
_nam
e
ivad
min
_acl
_set
anyo
ther
()P
DA
cl.s
etP
DA
clE
ntr
yAn
yOth
erP
DA
clob
ject
.set
PD
Acl
En
tryA
nyO
ther
pdad
min
acl
modi
fyac
l_na
mese
tan
y-ot
her
perm
s
60 IBM Tivoli Access Manager: Administration Java Classes Developer’s Reference
Tabl
e31
.M
appi
ngbe
twee
nad
min
istr
atio
nC
AP
I,Ja
vam
etho
ds,
and
the
com
man
dlin
ein
terf
ace
(con
tinue
d)
CA
PI
Java
Cla
ssan
dM
eth
odC
omm
and
Lin
eE
qu
ival
ent
ivad
min
_acl
_set
des
crip
tion
()P
DA
cl.s
etD
escr
ipti
onP
DA
clob
ject
.set
Des
crip
tion
pdad
min
acl
modi
fyac
l_na
mede
scri
ptio
nde
scri
ptio
n
ivad
min
_acl
_set
grou
p()
PD
Acl
.set
PD
Acl
En
tryG
rou
pP
DA
clob
ject
.set
PD
Acl
En
tryG
rou
ppd
admi
nac
lmo
dify
acl_
name
set
grou
pgr
oup_
name
perm
s
ivad
min
_acl
_set
un
auth
()P
DA
cl.s
etP
DA
clE
ntr
yUn
Au
thP
DA
clob
ject
.set
PD
Acl
En
tryU
nA
uth
pdad
min
acl
modi
fyac
l_na
mese
tun
auth
enti
cate
dpe
rms
ivad
min
_acl
_set
use
r()
PD
Acl
.set
PD
Acl
En
tryU
ser
PD
Acl
obje
ct.s
etP
DA
clE
ntr
yUse
rpd
admi
nac
lmo
dify
acl_
name
set
user
user
_nam
epe
rms
ivad
min
_act
ion
_cre
ate(
)P
DA
ctio
n.c
reat
eAct
ion
pdad
min
acti
oncr
eate
name
desc
ript
ion
acti
on_t
ype
ivad
min
_act
ion
_cre
ate_
in_g
rou
p()
PD
Act
ion
.cre
ateA
ctio
npd
admi
nac
tion
crea
tena
mede
scri
ptio
nac
tion
_typ
eac
tion
_gro
up_n
ame
ivad
min
_act
ion
_del
ete(
)P
DA
ctio
n.d
elet
eAct
ion
pdad
min
acti
onde
lete
name
ivad
min
_act
ion
_del
ete_
from
_gro
up
()P
DA
ctio
n.d
elet
eAct
ion
pdad
min
acti
onde
lete
name
acti
on_g
roup
_nam
e
ivad
min
_act
ion
_get
des
crip
tion
()P
DA
ctio
nob
ject
.get
Des
crip
tion
pdad
min
acti
onli
st
ivad
min
_act
ion
_get
id()
PD
Act
ion
obje
ct.g
etId
pdad
min
acti
onli
st
ivad
min
_act
ion
_get
typ
e()
PD
Act
ion
obje
ct.g
etTy
pe
pdad
min
acti
onli
st
ivad
min
_act
ion
_gro
up
_cre
ate(
)P
DA
ctio
nG
rou
p.c
reat
eAct
ion
Gro
up
pdad
min
acti
ongr
oup
crea
teac
tion
_gro
up_n
ame
ivad
min
_act
ion
_gro
up
_del
ete(
)P
DA
ctio
nG
rou
p.d
elet
eAct
ion
Gro
up
pdad
min
acti
ongr
oup
dele
teac
tion
_gro
up_n
ame
ivad
min
_act
ion
_gro
up
_lis
t()
PD
Act
ion
Gro
up
.list
Act
ion
Gro
up
spd
admi
nac
tion
grou
pli
st
ivad
min
_act
ion
_lis
t()
PD
Act
ion
.list
Act
ion
spd
admi
nac
tion
list
ivad
min
_act
ion
_lis
t_in
_gro
up
()P
DA
ctio
n.li
stA
ctio
ns
pdad
min
acti
onli
stac
tion
_gro
up_n
ame
ivad
min
_cfg
_ad
dre
pli
ca()
PD
Ap
pS
vrC
onfi
g.ad
dP
DS
erve
r.
svrs
slcf
g-a
dd_r
epli
ca-f
cfg_
file
-hho
st_n
ame
[-p
port
][-
kra
nk]
ivad
min
_cfg
_ch
grep
lica
()P
DA
pp
Svr
Con
fig.
chan
geP
DS
erve
rsv
rssl
cfg
-chg
_rep
lica
-fcf
g_fi
le-h
host
_nam
e[-
ppo
rt]
[-k
rank
]
ivad
min
_cfg
_con
figu
rese
rver
2()
PD
Ap
pS
vrC
onfi
g.co
nfi
gure
Ap
pS
vrsv
rssl
cfg
-con
fig
-fcf
g_fi
le-d
kdb_
dir_
name
-nse
rver
_nam
e..
.
ivad
min
_cfg
_ren
ewse
rver
cert
()P
DA
pp
Svr
Con
fig.
rep
lace
Ap
pS
vrC
ert
svrs
slcf
g-c
hgce
rt-f
cfg_
file
-nse
rver
_nam
e[-
Aad
min_
ID]
-Pad
min_
pwd
ivad
min
_cfg
_rm
vrep
lica
()P
DA
pp
Svr
Con
fig.
rem
oveP
DS
erve
rsv
rssl
cfg
-rmv
_rep
lica
-fcf
g_fi
le-h
host
_nam
e[-
ppo
rt]
[-k
rank
]
Appendix D. Administration C API, Java method, and command line equivalents 61
Tabl
e31
.M
appi
ngbe
twee
nad
min
istr
atio
nC
AP
I,Ja
vam
etho
ds,
and
the
com
man
dlin
ein
terf
ace
(con
tinue
d)
CA
PI
Java
Cla
ssan
dM
eth
odC
omm
and
Lin
eE
qu
ival
ent
ivad
min
_cfg
_set
app
lica
tion
cert
()N
otsu
ppor
ted
atth
isti
me.
svrs
slcf
g-m
odif
y-f
cfg_
file
[-t
time
out]
[-C
cert
_fil
e][-
lli
sten
ing_
mode
]
ivad
min
_cfg
_set
key
rin
gpw
d()
Not
appl
icab
le.
svrs
slcf
g-c
hgpw
d-f
cfg_
file
-nse
rver
_nam
e[-
Aad
min_
ID]
[-P
admi
n_pw
d]
ivad
min
_cfg
_set
list
enin
g()
PD
Ap
pS
vrC
onfi
g.se
tAp
pS
vrL
iste
nin
gsv
rssl
cfg
-fcf
g_fi
le-m
odif
y-l
yes
ivad
min
_cfg
_set
por
t()
PD
Ap
pS
vrC
onfi
g.se
tAp
pS
vrP
ort
svrs
slcf
g-c
onfi
g-f
cfg_
file
-dkd
b_di
r_na
me-n
serv
er_n
ame
...
ivad
min
_cfg
_set
sslt
imeo
ut(
)N
otsu
ppor
ted
atth
isti
me.
svrs
slcf
g-m
odif
y-f
cfg_
file
-tti
meou
t[-
Cce
rt_f
ile]
[-l
list
enin
g_mo
de]
ivad
min
_cfg
_un
con
figu
rese
rver
()P
DA
pp
Svr
Con
fig.
un
con
figu
reA
pp
Svr
svrs
slcf
g-u
ncon
fig
-fcf
g_fi
le-n
serv
er_n
ame
[-A
admi
n_ID
]-P
admi
n_pw
d
ivad
min
_con
text
_cle
ard
elcr
ed()
Not
supp
orte
dat
this
tim
e.no
tap
plic
able
ivad
min
_con
text
_cre
ate(
)P
DC
onte
xtco
nstr
ucto
rno
tap
plic
able
ivad
min
_con
text
_cre
ated
efau
lt()
PD
Con
text
cons
truc
tor
not
appl
icab
le
ivad
min
_con
text
_del
ete(
)no
tap
plic
able
not
appl
icab
le
ivad
min
_con
text
_get
acce
xpd
ate(
)P
DP
olic
yob
ject
.get
Acc
tExp
Dat
epd
admi
npo
licy
get
acco
unt-
expi
ry-d
ate
ivad
min
_con
text
_get
dis
able
tim
ein
t()
PD
Pol
icy
obje
ct.g
etA
cctD
isab
leT
imeI
nte
rval
pdad
min
poli
cyge
tdi
sabl
e-ti
me-i
nter
val
ivad
min
_con
text
_get
max
lgn
fail
s()
PD
Pol
icy
obje
ct.g
etM
axFa
iled
Log
ins
pdad
min
poli
cyge
tma
x-lo
gin-
fail
ures
ivad
min
_con
text
_get
max
pw
dag
e()
PD
Pol
icy
obje
ct.g
etM
axP
wd
Age
pdad
min
poli
cyge
tma
x-pa
sswo
rd-a
ge
ivad
min
_con
text
_get
max
pw
dre
pch
ars(
)P
DP
olic
yob
ject
.get
Max
Pw
dR
epC
har
spd
admi
npo
licy
get
max-
pass
word
-rep
eate
d-ch
ars
ivad
min
_con
text
_get
min
pw
dal
ph
as()
PD
Pol
icy
obje
ct.g
etM
inP
wd
Alp
has
pdad
min
poli
cyge
tmi
n-pa
sswo
rd-a
lpha
s
ivad
min
_con
text
_get
min
pw
dle
n()
PD
Pol
icy
obje
ct.g
etM
inP
wd
Len
pdad
min
poli
cyge
tmi
n-pa
sswo
rd-l
engt
h
ivad
min
_con
text
_get
min
pw
dn
onal
ph
as()
PD
Pol
icy
obje
ct.g
etM
inP
wd
Non
Alp
has
pdad
min
poli
cyge
tmi
n-pa
sswo
rd-n
on-a
lpha
s
ivad
min
_con
text
_get
pw
dsp
aces
()P
DP
olic
yob
ject
.pw
dS
pac
esA
llow
edpd
admi
npo
licy
get
pass
word
-spa
ces
ivad
min
_con
text
_get
tod
acce
ss()
PD
Pol
icy
obje
ct.g
etA
cces
sib
leD
ays
PD
Pol
icy
obje
ct.g
etA
cces
sSta
rtT
ime
PD
Pol
icy
obje
ct.g
etA
cces
sEn
dT
ime
PD
Pol
icy
obje
ct.g
etA
cces
sTim
ezon
e
pdad
min
poli
cyge
tto
d-ac
cess
62 IBM Tivoli Access Manager: Administration Java Classes Developer’s Reference
Tabl
e31
.M
appi
ngbe
twee
nad
min
istr
atio
nC
AP
I,Ja
vam
etho
ds,
and
the
com
man
dlin
ein
terf
ace
(con
tinue
d)
CA
PI
Java
Cla
ssan
dM
eth
odC
omm
and
Lin
eE
qu
ival
ent
ivad
min
_con
text
_get
use
rreg
()P
DU
ser.g
etU
serR
gypd
admi
nad
min
show
conf
igur
atio
n
ivad
min
_con
text
_set
acce
xpd
ate(
)P
DP
olic
y.se
tAcc
tExp
Dat
eP
DP
olic
yob
ject
.set
Acc
tExp
Dat
epd
admi
npo
licy
set
acco
unt-
expi
ry-d
ate
[unl
imit
ed|
abso
lute
_tim
e|
unse
t]
ivad
min
_con
text
_set
del
cred
()N
otsu
ppor
ted
atth
isti
me.
not
appl
icab
le
ivad
min
_con
text
_set
dis
able
tim
ein
t()
PD
Pol
icy.
setA
cctD
isab
leT
ime
PD
Pol
icy
obje
ct.s
etA
cctD
isab
leT
ime
pdad
min
poli
cyse
tdi
sabl
e-ti
me-i
nter
val
[num
ber
|un
set
|di
sabl
e]
ivad
min
_con
text
_set
max
lgn
fail
s()
PD
Pol
icy.
setM
axFa
iled
Log
ins
PD
Pol
icy
obje
ct.s
etM
axFa
iled
Log
ins
pdad
min
poli
cyse
tma
x-lo
gin-
fail
ures
[num
ber
|un
set]
ivad
min
_con
text
_set
max
pw
dag
e()
PD
Pol
icy.
setM
axP
wd
Age
PD
Pol
icy
obje
ct.s
etM
axP
wd
Age
pdad
min
poli
cyse
tma
x-pa
sswo
rd-a
ge[r
elat
ive_
time
|un
set]
ivad
min
_con
text
_set
max
pw
dre
pch
ars(
)P
DP
olic
y.se
tMax
Pw
dR
epC
har
sP
DP
olic
yob
ject
.set
Max
Pw
dR
epC
har
spd
admi
npo
licy
set
max-
pass
word
-rep
eate
d-ch
ars
[num
ber
|un
set]
ivad
min
_con
text
_set
min
pw
dal
ph
as()
PD
Pol
icy.
setM
inP
wd
Alp
has
PD
Pol
icy
obje
ct.s
etM
inP
wd
Alp
has
pdad
min
poli
cyse
tmi
n-pa
sswo
rd-a
lpha
s[n
umbe
r|
unse
t]
ivad
min
_con
text
_set
min
pw
dle
n()
PD
Pol
icy.
setM
inP
wd
Len
PD
Pol
icy
obje
ct.s
etM
inP
wd
Len
pdad
min
poli
cyse
tmi
n-pa
sswo
rd-l
engt
h[n
umbe
r|
unse
t]
ivad
min
_con
text
_set
min
pw
dn
onal
ph
as()
PD
Pol
icy.
setM
inP
wd
Non
Alp
has
PD
Pol
icy
obje
ct.s
etM
inP
wd
Non
Alp
has
pdad
min
poli
cyse
tma
x-pa
sswo
rd-n
on-a
lpha
s[n
umbe
r|
unse
t]
ivad
min
_con
text
_set
pw
dsp
aces
()P
DP
olic
y.se
tPw
dS
pac
esA
llow
edP
DP
olic
yob
ject
.set
Pw
dS
pac
esA
llow
edpd
admi
npo
licy
set
pass
word
-spa
ces
[yes
|no
|un
set]
ivad
min
_con
text
_set
tod
acce
ss()
PD
Pol
icy.
setT
odA
cces
sP
DP
olic
yob
ject
.set
Tod
Acc
ess
pdad
min
poli
cyse
tto
d-ac
cess
toda
cces
s_va
lue
ivad
min
_fre
e()
not
appl
icab
leno
tap
plic
able
ivad
min
_gro
up
_ad
dm
emb
ers(
)P
DG
rou
p.a
dd
Mem
ber
sP
DG
roup
obje
ct.a
dd
Mem
ber
spd
admi
ngr
oup
modi
fygr
oup_
name
add
(use
r_na
me1
user
_nam
e2..
.)
ivad
min
_gro
up
_cre
ate2
()P
DG
rou
p.c
reat
eGro
up
pdad
min
grou
pcr
eate
grou
p_na
medn
cn
ivad
min
_gro
up
_del
ete2
()P
DG
rou
p.d
elet
eGro
up
pdad
min
grou
pde
lete
[-re
gist
ry]
grou
p_na
me
ivad
min
_gro
up
_get
()P
DG
rou
pco
nstr
ucto
rpd
admi
ngr
oup
show
grou
p_na
me
ivad
min
_gro
up
_get
byd
n()
PD
Gro
up
cons
truc
tor
pdad
min
grou
psh
ow-d
ndn
ivad
min
_gro
up
_get
cn()
Will
not
besu
ppor
ted
.pd
admi
ngr
oup
show
grou
p_na
me
ivad
min
_gro
up
_get
des
crip
tion
()P
DG
roup
obje
ct.g
etD
escr
ipti
onpd
admi
ngr
oup
show
grou
p_na
me
Appendix D. Administration C API, Java method, and command line equivalents 63
Tabl
e31
.M
appi
ngbe
twee
nad
min
istr
atio
nC
AP
I,Ja
vam
etho
ds,
and
the
com
man
dlin
ein
terf
ace
(con
tinue
d)
CA
PI
Java
Cla
ssan
dM
eth
odC
omm
and
Lin
eE
qu
ival
ent
ivad
min
_gro
up
_get
dn
()P
DG
roup
obje
ct.g
etR
gyN
ame
pdad
min
grou
psh
owgr
oup_
name
ivad
min
_gro
up
_get
id()
PD
Gro
upob
ject
.get
Idpd
admi
ngr
oup
show
grou
p_na
me
ivad
min
_gro
up
_get
mem
ber
s()
PD
Gro
upob
ject
.get
Mem
ber
spd
admi
ngr
oup
show
-mem
bers
grou
p_na
me
ivad
min
_gro
up
_im
por
t2()
PD
Gro
up
.imp
ortG
rou
ppd
admi
ngr
oup
impo
rtgr
oup_
name
dn
ivad
min
_gro
up
_lis
t()
PD
Gro
up
.list
Gro
up
spd
admi
ngr
oup
list
patt
ern
max_
retu
rn
ivad
min
_gro
up
_lis
tbyd
n()
PD
Gro
up
.list
Gro
up
spd
admi
ngr
oup
list
-dn
patt
ern
max_
retu
rn
ivad
min
_gro
up
_rem
ovem
emb
ers(
)P
DG
rou
p.r
emov
eMem
ber
sP
DG
roup
obje
ct.r
emov
eMem
ber
spd
admi
ngr
oup
modi
fygr
oup_
name
remo
ve(u
ser_
name
1us
er_n
ame2
...)
ivad
min
_gro
up
_set
des
crip
tion
()P
DG
rou
p.s
etD
escr
ipti
onP
DG
roup
obje
ct.s
etD
escr
ipti
onpd
admi
ngr
oup
modi
fygr
oup_
name
desc
ript
ion
desc
ript
ion
ivad
min
_ob
ject
spac
e_cr
eate
()P
DP
rotO
bje
ctS
pac
e.cr
eate
Pro
tOb
ject
Sp
ace
pdad
min
obje
ctsp
ace
crea
teob
ject
spac
e_na
me
ivad
min
_ob
ject
spac
e_d
elet
e()
PD
Pro
tOb
ject
Sp
ace.
del
eteP
rotO
bje
ctS
pac
epd
admi
nob
ject
spac
ede
lete
obje
ctsp
ace_
name
ivad
min
_ob
ject
spac
e_li
st()
PD
Pro
tOb
ject
Sp
ace.
list
Pro
tOb
ject
Sp
aces
pdad
min
obje
ctsp
ace
list
ivad
min
_pop
_att
ach
()P
DP
rotO
bje
ct.a
ttac
hP
opP
DP
rotO
bjec
tob
ject
.att
ach
Pop
pdad
min
pop
atta
chob
ject
_nam
epo
p_na
me
ivad
min
_pop
_att
rdel
key
()P
DP
op.d
elet
eAtt
rib
ute
PD
Pop
obje
ct.d
elet
eAtt
rib
ute
pdad
min
pop
modi
fypo
p_na
mede
lete
attr
ibut
eat
trib
ute_
name
ivad
min
_pop
_att
rdel
val(
)P
DP
op.d
elet
eAtt
rib
ute
Val
ue
PD
Pop
obje
ct.d
elet
eAtt
rib
ute
Val
ue
pdad
min
pop
modi
fypo
p_na
mede
lete
attr
ibut
eat
trib
ute_
name
attr
ibut
e_va
lue
ivad
min
_pop
_att
rget
()P
DP
opob
ject
.get
Att
rib
ute
Val
ues
pdad
min
pop
show
pop_
name
attr
ibut
e
ivad
min
_pop
_att
rlis
t()
PD
Pop
obje
ct.g
etA
ttri
bu
teN
ames
pdad
min
pop
list
pop_
name
attr
ibut
e
ivad
min
_pop
_att
rpu
t()
PD
Pop
.set
Att
rib
ute
Val
ue
PD
Pop
obje
ct.s
etA
ttri
bu
teV
alu
epd
admi
npo
pmo
dify
pop_
name
set
attr
ibut
eat
trib
ute_
name
attr
ibut
e_va
lue
ivad
min
_pop
_cre
ate(
)P
DP
op.c
reat
ePop
pdad
min
pop
crea
tepo
p_na
me
ivad
min
_pop
_del
ete(
)P
DP
op.d
elet
ePop
pdad
min
pop
dele
tepo
p_na
me
ivad
min
_pop
_det
ach
()P
DP
rotO
bje
ct.d
etac
hP
opP
DP
rotO
bjec
tob
ject
.att
ach
Pop
pdad
min
pop
deta
chpo
p_na
me
ivad
min
_pop
_fin
d()
PD
Pro
tOb
ject
.list
Pro
tOb
ject
sByP
oppd
admi
npo
pfi
ndpo
p_na
me
ivad
min
_pop
_get
()P
DP
opco
nstr
ucto
rpd
admi
npo
psh
owpo
p_na
me
ivad
min
_pop
_get
aud
itle
vel(
)P
DP
opob
ject
.get
Au
dit
Lev
elpd
admi
npo
psh
owpo
p_na
me
64 IBM Tivoli Access Manager: Administration Java Classes Developer’s Reference
Tabl
e31
.M
appi
ngbe
twee
nad
min
istr
atio
nC
AP
I,Ja
vam
etho
ds,
and
the
com
man
dlin
ein
terf
ace
(con
tinue
d)
CA
PI
Java
Cla
ssan
dM
eth
odC
omm
and
Lin
eE
qu
ival
ent
ivad
min
_pop
_get
des
crip
tion
()P
DP
opob
ject
.get
Des
crip
tion
pdad
min
pop
show
pop_
name
ivad
min
_pop
_get
id()
PD
Pop
obje
ct.g
etId
pdad
min
pop
show
pop_
name
ivad
min
_pop
_get
qop
()P
DP
opob
ject
.get
QO
Ppd
admi
npo
psh
owpo
p_na
me
ivad
min
_pop
_get
tod
()P
DP
opob
ject
.get
Tod
Acc
essI
nfo
pdad
min
pop
show
pop_
name
ivad
min
_pop
_get
war
nm
ode(
)P
DP
opob
ject
.get
War
nin
gMod
epd
admi
npo
psh
owpo
p_na
me
ivad
min
_pop
_lis
t()
PD
Pop
.list
Pop
spd
admi
npo
pli
st
ivad
min
_pop
_rem
ovei
pau
th()
PD
Pop
.rem
oveI
PAu
thIn
foP
DP
opob
ject
.rem
oveI
PAu
thIn
fopd
admi
npo
pmo
dify
pop_
name
set
ipau
thre
move
netw
ork
netm
ask
ivad
min
_pop
_set
anyo
ther
nw
()P
DP
op.s
etu
thIn
fopd
admi
npo
pmo
dify
pop_
name
set
ipau
than
yoth
ernw
auth
enti
cati
on_l
evel
ivad
min
_pop
_set
anyo
ther
nw
_for
bid
den
()P
DP
op.s
etIP
Au
thIn
fopd
admi
npo
pmo
dify
pop_
name
set
ipau
than
yoth
ernw
forb
idde
n
ivad
min
_pop
_set
aud
itle
vel(
)P
DP
op.s
etA
ud
itL
evel
PD
Pop
obje
ct.s
etA
ud
itL
evel
pdad
min
pop
modi
fypo
p_na
mese
tau
dit-
leve
l[a
ll|
none
|au
dit_
leve
l_li
st]
ivad
min
_pop
_set
des
crip
tion
()P
DP
op.s
etD
escr
ipti
onP
DP
opob
ject
.set
Des
crip
tion
pdad
min
pop
modi
fypo
p_na
mese
tde
scri
ptio
nde
scri
ptio
n
ivad
min
_pop
_set
ipau
th()
PD
Pop
.set
IPA
uth
Info
PD
Pop
obje
ct.s
etIP
Au
thIn
fopd
admi
npo
pmo
dify
pop_
name
set
ipau
thad
dne
twor
kne
tmas
kau
then
tica
tion
_lev
el
ivad
min
_pop
_set
ipau
th_f
orb
idd
en()
PD
Pop
.set
IPA
uth
Info
PD
Pop
obje
ct.s
etIP
Au
thIn
fopd
admi
npo
pmo
dify
pop_
name
set
ipau
thad
dne
twor
kne
tmas
kfo
rbid
den
ivad
min
_pop
_set
qop
()P
DP
op.s
etQ
OP
PD
Pop
obje
ct.s
etQ
OP
pdad
min
pop
modi
fypo
p_na
mese
tqo
p[n
one
|in
tegr
ity
|pr
ivac
y]
ivad
min
_pop
_set
tod
()P
DP
op.s
etTo
dA
cces
sIn
foP
DP
opob
ject
.set
Tod
Acc
essI
nfo
.
pdad
min
pop
modi
fypo
p_na
mese
tto
d-ac
cess
tod_
valu
e
ivad
min
_pop
_set
war
nm
ode(
)P
DP
op.s
etW
arn
ingM
ode
PD
Pop
obje
ct.s
etW
arn
ingM
ode
pdad
min
pop
modi
fypo
p_na
mese
twa
rnin
g[
on|
off
]
ivad
min
_pro
tob
j_at
tach
acl(
)P
DP
rotO
bje
ct.a
ttac
hA
clP
DP
rotO
bjec
tob
ject
.att
ach
Acl
pdad
min
acl
atta
chob
ject
_nam
eac
l_na
me
ivad
min
_pro
tob
j_at
trd
elk
ey()
PD
Pro
tOb
ject
.del
eteA
ttri
bu
teP
DP
rotO
bjec
tob
ject
.del
eteA
ttri
bu
tepd
admi
nob
ject
modi
fyob
ject
_nam
ede
lete
attr
ibut
e_na
me
Appendix D. Administration C API, Java method, and command line equivalents 65
Tabl
e31
.M
appi
ngbe
twee
nad
min
istr
atio
nC
AP
I,Ja
vam
etho
ds,
and
the
com
man
dlin
ein
terf
ace
(con
tinue
d)
CA
PI
Java
Cla
ssan
dM
eth
odC
omm
and
Lin
eE
qu
ival
ent
ivad
min
_pro
tob
j_at
trd
elva
l()
PD
Pro
tOb
ject
.del
eteA
ttri
bu
teV
alu
eP
DP
rotO
bjec
tob
ject
.del
eteA
ttri
bu
teV
alu
epd
admi
nob
ject
modi
fyob
ject
_nam
ede
lete
attr
ibut
e_na
meat
trib
ute_
valu
e
ivad
min
_pro
tob
j_at
trge
t()
PD
Pro
tObj
ect
obje
ct.g
etA
ttri
bu
teV
alu
espd
admi
nob
ject
show
obje
ct_n
ame
attr
ibut
eat
trib
ute_
name
ivad
min
_pro
tob
j_at
trli
st()
PD
Pro
tObj
ect
obje
ct.g
etA
ttri
bu
teN
ames
pdad
min
obje
ctli
stob
ject
_nam
eat
trib
ute
ivad
min
_pro
tob
j_at
trp
ut(
)P
DP
rotO
bje
ct.s
etA
ttri
bu
teV
alu
eP
DP
rotO
bjec
tob
ject
.set
Att
rib
ute
Val
ue
pdad
min
obje
ctmo
dify
obje
ct_n
ame
set
attr
ibut
eat
trib
ute_
name
attr
ibut
e_va
lue
ivad
min
_pro
tob
j_cr
eate
()P
DP
rotO
bje
ct.c
reat
ePro
tOb
ject
pdad
min
obje
ctcr
eate
obje
ct_n
ame
ivad
min
_pro
tob
j_d
elet
e()
PD
Pro
tOb
ject
.del
eteP
rotO
bje
ctpd
admi
nob
ject
dele
teob
ject
_nam
e
ivad
min
_pro
tob
j_d
etac
hac
l()
PD
Pro
tOb
ject
.det
ach
Acl
PD
Pro
tObj
ect
obje
ct.d
etac
hA
clpd
admi
nac
lde
tach
obje
ct_n
ame
ivad
min
_pro
tob
j_ge
t2()
PD
Pro
tOb
ject
cons
truc
tor
pdad
min
obje
ctsh
owob
ject
_nam
e
ivad
min
_pro
tob
j_ge
tacl
()P
DP
rotO
bjec
tob
ject
.get
Acl
pdad
min
obje
ctsh
owob
ject
_nam
e
ivad
min
_pro
tob
j_ge
tdes
c()
PD
Pro
tObj
ect
obje
ct.g
etD
escr
ipti
onpd
admi
nob
ject
show
obje
ct_n
ame
ivad
min
_pro
tob
j_ge
tid
()P
DP
rotO
bjec
tob
ject
.get
Idpd
admi
nob
ject
show
obje
ct_n
ame
ivad
min
_pro
tob
j_ge
tpol
icya
ttac
hab
le()
PD
Pro
tObj
ect
obje
ct.is
Pol
icyA
ttac
hab
lepd
admi
nob
ject
show
obje
ct_n
ame
ivad
min
_pro
tob
j_ge
tpop
()N
otsu
ppor
ted
atth
isti
me.
not
appl
icab
le
ivad
min
_pro
tob
j_ge
ttyp
e()
Will
not
besu
ppor
ted
.pd
admi
nob
ject
show
obje
ct_n
ame
ivad
min
_pro
tob
j_li
st3(
)P
DP
rotO
bje
ct.li
stP
rotO
bje
cts
pdad
min
obje
ctli
stdi
rect
ory_
name
ivad
min
_pro
tob
j_li
stb
yacl
()P
DP
rotO
bje
ct.li
stP
rotO
bje
ctsB
yAcl
pdad
min
acl
find
acl_
name
ivad
min
_pro
tob
j_se
tdes
c()
PD
Pro
tOb
ject
.set
Des
crip
tion
PD
Pro
tObj
ect
obje
ct.s
etD
escr
ipti
onpd
admi
nob
ject
modi
fyob
ject
_nam
ede
scri
ptio
nde
scri
ptio
n
ivad
min
_pro
tob
j_se
tnam
e()
Will
not
besu
ppor
ted
.pd
admi
nob
ject
modi
fyob
ject
_nam
ena
mena
meco
nfli
ct_r
esol
utio
nre
solu
tion
_mod
ifie
r
ivad
min
_pro
tob
j_se
tpol
icya
ttac
hab
le()
PD
Pro
tOb
ject
.set
Pol
icyA
ttac
hab
leP
DP
rotO
bjec
tob
ject
.set
Pol
icyA
ttac
hab
lepd
admi
nob
ject
modi
fyob
ject
_nam
eis
Poli
cyAt
tach
able
[yes
|no
]
ivad
min
_pro
tob
j_se
ttyp
e()
Will
not
besu
ppor
ted
.pd
admi
nob
ject
modi
fyob
ject
_nam
ety
pety
pe
ivad
min
_res
pon
se_g
etco
de(
)no
tap
plic
able
not
appl
icab
le
ivad
min
_res
pon
se_g
etco
un
t()
not
appl
icab
leno
tap
plic
able
ivad
min
_res
pon
se_g
etm
essa
ge()
not
appl
icab
leno
tap
plic
able
66 IBM Tivoli Access Manager: Administration Java Classes Developer’s Reference
Tabl
e31
.M
appi
ngbe
twee
nad
min
istr
atio
nC
AP
I,Ja
vam
etho
ds,
and
the
com
man
dlin
ein
terf
ace
(con
tinue
d)
CA
PI
Java
Cla
ssan
dM
eth
odC
omm
and
Lin
eE
qu
ival
ent
ivad
min
_res
pon
se_g
etm
odif
ier(
)no
tap
plic
able
not
appl
icab
le
ivad
min
_res
pon
se_g
etok
()no
tap
plic
able
not
appl
icab
le
ivad
min
_ser
ver_
gett
ask
list
()P
DS
erve
r.get
Task
Lis
tpd
admi
nse
rver
list
task
sse
rver
_nam
e
ivad
min
_ser
ver_
per
form
task
()P
DS
erve
r.per
form
Task
pdad
min
serv
erta
skse
rver
_nam
eta
sk_t
o_pe
rfor
m
ivad
min
_ser
ver_
rep
lica
te()
PD
Ser
ver.s
erve
rRep
lica
tepd
admi
nse
rver
repl
icat
ese
rver
_nam
e
ivad
min
_sso
cred
_cre
ate(
)P
DS
SO
Cre
d.c
reat
eSS
OC
red
pdad
min
rsrc
cred
crea
tere
sour
ce_n
ame
rsrc
user
reso
urce
_use
rid
rsrc
pwd
reso
urce
_pwd
rsrc
type
[web
|gr
oup]
user
user
_nam
e
ivad
min
_sso
cred
_del
ete(
)P
DS
SO
Cre
d.d
elet
eSS
OC
red
pdad
min
rsrc
cred
dele
tere
sour
ce_n
ame
rsrc
type
[web
|gr
oup]
user
user
_nam
e
ivad
min
_sso
cred
_get
()P
DS
SO
Cre
dco
nstr
ucto
rpd
admi
nrs
rccr
edsh
owre
sour
ce_n
ame
rsrc
type
[web
|gr
oup]
user
user
_nam
e
ivad
min
_sso
cred
_get
id()
PD
SSO
Cre
dob
ject
.get
Res
ourc
eNam
epd
admi
nrs
rccr
edsh
owre
sour
ce_n
ame
rsrc
type
[web
|gr
oup]
user
user
_nam
e
ivad
min
_sso
cred
_get
ssop
assw
ord
()P
DSS
OC
red
obje
ct.g
etR
esou
rceP
assw
ord
not
appl
icab
le
ivad
min
_sso
cred
_get
ssou
ser(
)P
DSS
OC
red
obje
ct.g
etR
esou
rceU
ser
not
appl
icab
le
ivad
min
_sso
cred
_get
typ
e()
PD
SSO
Cre
dob
ject
.get
Res
ourc
eTyp
epd
admi
nrs
rccr
edsh
owre
sour
ce_n
ame
rsrc
type
[web
|gr
oup]
user
user
_nam
e
ivad
min
_sso
cred
_get
use
r()
PD
SSO
Cre
dob
ject
.get
Use
rpd
admi
nrs
rccr
edsh
owre
sour
ce_n
ame
rsrc
type
[web
|gr
oup]
user
user
_nam
e
ivad
min
_sso
cred
_lis
t()
PD
SSO
Cre
dob
ject
.list
An
dS
how
SS
OC
red
sP
DSS
OC
red
obje
ct.li
stS
SO
Cre
ds
pdad
min
rsrc
cred
list
user
user
_nam
e
ivad
min
_sso
cred
_set
()P
DS
SO
Cre
d.s
etS
SO
Cre
dP
DSS
OC
red
obje
ct.s
etS
SO
Cre
d.
pdad
min
rsrc
cred
modi
fyre
sour
ce_n
ame
rsrc
type
[web
|gr
oup]
[-rs
rcus
erre
sour
ce_u
seri
d][-
rsrc
pwd
reso
urce
_pwd
]us
erus
er_n
ame
ivad
min
_sso
grou
p_a
dd
res(
)P
DS
SO
Res
ourc
eGro
up
.ad
dS
SO
Res
ourc
eP
DSS
OR
esou
rceG
roup
.ad
dS
SO
Res
ourc
epd
admi
nrs
rcgr
oup
modi
fyre
sour
ce_g
roup
_nam
ead
drs
rcna
mere
sour
ce_n
ame
ivad
min
_sso
grou
p_c
reat
e()
PD
SS
OR
esou
rceG
rou
p.c
reat
eSS
OR
esou
rceG
rou
ppd
admi
nrs
rcgr
oup
crea
tere
sour
ce_g
roup
_nam
e[-
desc
desc
ript
ion]
ivad
min
_sso
grou
p_d
elet
e()
PD
SS
OR
esou
rceG
rou
p.d
elet
eSS
OR
esou
rceG
rou
ppd
admi
nrs
rcgr
oup
dele
tere
sour
ce_g
roup
_nam
e
ivad
min
_sso
grou
p_g
et()
PD
SS
OR
esou
rceG
rou
pco
nstr
ucto
rpd
admi
nrs
rcgr
oup
show
reso
urce
_gro
up_n
ame
Appendix D. Administration C API, Java method, and command line equivalents 67
Tabl
e31
.M
appi
ngbe
twee
nad
min
istr
atio
nC
AP
I,Ja
vam
etho
ds,
and
the
com
man
dlin
ein
terf
ace
(con
tinue
d)
CA
PI
Java
Cla
ssan
dM
eth
odC
omm
and
Lin
eE
qu
ival
ent
ivad
min
_sso
grou
p_g
etd
escr
ipti
on()
PD
SSO
Cre
dob
ject
.get
Des
crip
tion
pdad
min
rsrc
grou
psh
owre
sour
ce_g
roup
_nam
e
ivad
min
_sso
grou
p_g
etid
()P
DSS
OC
red
obje
ct.g
etId
pdad
min
rsrc
grou
psh
owre
sour
ce_g
roup
_nam
e
ivad
min
_sso
grou
p_g
etre
sou
rces
()P
DSS
OC
red
obje
ct.g
etS
SO
Res
ourc
espd
admi
nrs
rcgr
oup
show
reso
urce
_gro
up_n
ame
ivad
min
_sso
grou
p_l
ist(
)P
DS
SO
Cre
d.li
stS
SO
Res
ourc
eGro
up
spd
admi
nrs
rcgr
oup
list
ivad
min
_sso
grou
p_r
emov
eres
()P
DS
SO
Cre
d.r
emov
eSS
OR
esou
rce
PD
SSO
Cre
dob
ject
.rem
oveS
SO
Res
ourc
e.pd
admi
nrs
rcgr
oup
modi
fyre
sour
ce_g
roup
_nam
ere
move
rsrc
name
reso
urce
_nam
e
ivad
min
_sso
web
_cre
ate(
)P
DS
SO
Res
ourc
e.cr
eate
SS
OR
esou
rce
pdad
min
rsrc
crea
tere
sour
ce_n
ame
[-de
scde
scri
ptio
n]
ivad
min
_sso
web
_del
ete(
)P
DS
SO
Res
ourc
e.d
elet
eSS
OR
esou
rce
pdad
min
rsrc
dele
tere
sour
ce_n
ame
ivad
min
_sso
web
_get
()P
DS
SO
Res
ourc
eon
stru
ctor
pdad
min
rsrc
show
reso
urce
_nam
e
ivad
min
_sso
web
_get
des
crip
tion
()P
DSS
OR
esou
rce
obje
ct.g
etD
escr
ipti
onpd
admi
nrs
rcsh
owre
sour
ce_n
ame
ivad
min
_sso
web
_get
id()
PD
SSO
Res
ourc
eob
ject
.get
Idpd
admi
nrs
rcsh
owre
sour
ce_n
ame
ivad
min
_sso
web
_lis
t()
PD
SS
OR
esou
rce.
list
SS
OR
esou
rces
pdad
min
rsrc
list
ivad
min
_use
r_cr
eate
3()
PD
Use
r.cre
ateU
ser
pdad
min
user
crea
te[-
gsou
ser]
[-no
-pas
swor
d-po
licy
]us
er_n
ame
dncn
snpw
d(
grou
p1gr
oup2
....
)
ivad
min
_use
r_d
elet
e2()
PD
Use
r.del
eteU
ser
pdad
min
user
dele
te[-
regi
stry
]us
er_n
ame
ivad
min
_use
r_ge
t()
PD
Use
rco
nstr
ucto
rpd
admi
nus
ersh
owus
er_n
ame
ivad
min
_use
r_ge
tacc
exp
dat
e()
PD
Pol
icy
obje
ct.g
etA
cctE
xpD
ate
pdad
min
user
get
acco
unt-
expi
ry-d
ate
[-us
erus
er_n
ame
]
ivad
min
_use
r_ge
tacc
oun
tval
id()
PD
Use
rob
ject
.isA
ccou
ntV
alid
pdad
min
user
show
user
_nam
e
ivad
min
_use
r_ge
tbyd
n()
PD
Use
rco
nstr
ucto
rpd
admi
nus
ersh
ow-d
ndn
ivad
min
_use
r_ge
tcn
()P
DU
ser
obje
ct.g
etFi
rstN
ame
pdad
min
user
show
user
_nam
e
ivad
min
_use
r_ge
tdes
crip
tion
()P
DU
ser
obje
ct.g
etD
escr
ipti
onpd
admi
nus
ersh
owus
er_n
ame
ivad
min
_use
r_ge
tdis
able
tim
ein
t()
PD
Pol
icy
obje
ct.g
etA
cctD
isab
leT
imeI
nte
rval
pdad
min
poli
cyge
tdi
sabl
e-ti
me-i
nter
val
[-us
erus
er_n
ame]
ivad
min
_use
r_ge
tdn
()P
DU
ser
obje
ct.g
etR
gyN
ame
pdad
min
user
show
user
_nam
e
ivad
min
_use
r_ge
tid
()P
DU
ser
obje
ct.g
etId
pdad
min
user
show
user
_nam
e
ivad
min
_use
r_ge
tmax
lgn
fail
s()
PD
Pol
icy
obje
ct.g
etM
axFa
iled
Log
ins
pdad
min
poli
cyge
tma
x-lo
gin-
fail
ures
[-us
erus
er_n
ame]
68 IBM Tivoli Access Manager: Administration Java Classes Developer’s Reference
Tabl
e31
.M
appi
ngbe
twee
nad
min
istr
atio
nC
AP
I,Ja
vam
etho
ds,
and
the
com
man
dlin
ein
terf
ace
(con
tinue
d)
CA
PI
Java
Cla
ssan
dM
eth
odC
omm
and
Lin
eE
qu
ival
ent
ivad
min
_use
r_ge
tmax
pw
dag
e()
PD
Pol
icy
obje
ct.g
etM
axP
wd
Age
pdad
min
poli
cyge
tma
x-pa
sswo
rd-a
ge[-
user
user
_nam
e]
ivad
min
_use
r_ge
tmax
pw
dre
pch
ars(
)P
DP
olic
yob
ject
.get
Max
Pw
dR
epC
har
spd
admi
npo
licy
get
max-
pass
word
-rep
eate
d-ch
ars
[-us
erus
er_n
ame]
ivad
min
_use
r_ge
tmem
ber
ship
s()
PD
Use
rob
ject
.get
Gro
up
spd
admi
nus
ersh
ow-g
roup
sus
er_n
ame
ivad
min
_use
r_ge
tmin
pw
dal
ph
as()
PD
Pol
icy
obje
ct.g
etM
inP
wd
Alp
has
pdad
min
poli
cyge
tmi
n-pa
sswo
rd-a
lpha
s[-
user
user
_nam
e]
ivad
min
_use
r_ge
tmin
pw
dle
n()
PD
Pol
icy
obje
ct.g
etM
inP
wd
Len
pdad
min
poli
cyge
tmi
n-pa
sswo
rd-l
engt
h[-
user
user
_nam
e]
ivad
min
_use
r_ge
tmin
pw
dn
onal
ph
as()
PD
Pol
icy
obje
ct.g
etM
inP
wd
Non
Alp
has
pdad
min
poli
cyge
tmi
n-pa
sswo
rd-n
on-a
lpha
s[-
user
user
_nam
e]
ivad
min
_use
r_ge
tpas
swor
dva
lid
()P
DU
ser
obje
ct.is
Pas
swor
dV
alid
pdad
min
user
show
user
_nam
e
ivad
min
_use
r_ge
tpw
dsp
aces
()P
DP
olic
yob
ject
.pw
dS
pac
esA
llow
edpd
admi
npo
licy
get
pass
word
-spa
ces
[-us
erus
er_n
ame]
ivad
min
_use
r_ge
tsn
()P
DU
ser
obje
ct.g
etL
astN
ame
pdad
min
user
show
user
_nam
e
not
appl
icab
leP
DU
ser
obje
ct.is
PD
Use
rpd
admi
nus
ersh
owus
er_n
ame
ivad
min
_use
r_ge
tsso
use
r()
PD
Use
rob
ject
.isS
SO
Use
rpd
admi
nus
ersh
owus
er_n
ame
ivad
min
_use
r_ge
ttod
acce
ss()
PD
Pol
icy
obje
ct.g
etA
cces
sib
leD
ays
PD
Pol
icy
obje
ct.g
etA
cces
sSta
rtT
ime
PD
Pol
icy
obje
ct.g
etA
cces
sEn
dT
ime
pdad
min
poli
cyge
tto
d-ac
cess
-use
rus
er_n
ame
ivad
min
_use
r_im
por
t2()
PD
Use
r.im
por
tUse
rpd
admi
nus
erim
port
[-gs
ouse
r]us
er_n
ame
dn
ivad
min
_use
r_li
st()
PD
Use
r.lis
tUse
rspd
admi
nus
erli
stpa
tter
nma
x_re
turn
ivad
min
_use
r_li
stb
ydn
()P
DU
ser.l
istU
sers
pdad
min
user
list
-dn
patt
ern
max_
retu
rn
ivad
min
_use
r_se
tacc
exp
dat
e()
PD
Pol
icy.
setA
cctE
xpD
ate
PD
Pol
icy
obje
ct.s
etA
cctE
xpD
ate
pdad
min
poli
cyse
tac
coun
t-ex
piry
-dat
e[u
nlim
ited
|ab
solu
te_t
ime
|un
set]
[-us
erus
er_n
ame]
ivad
min
_use
r_se
tacc
oun
tval
id()
PD
Use
r.set
Acc
oun
tVal
idP
DU
ser
obje
ct.s
etA
ccou
ntV
alid
pdad
min
user
modi
fyus
er_n
ame
acco
unt-
vali
d[y
es|
no]
ivad
min
_use
r_se
tdes
crip
tion
()P
DU
ser.s
etD
escr
ipti
onP
DU
ser
obje
ct.s
etD
escr
ipti
onpd
admi
nus
ermo
dify
user
_nam
ede
scri
ptio
nde
scri
ptio
n
ivad
min
_use
r_se
tdis
able
tim
ein
t()
PD
Pol
icy.
setA
cctD
isab
leT
ime
PD
Pol
icy
obje
ct.s
etA
cctD
isab
leT
ime
pdad
min
poli
cyse
tdi
sabl
e-ti
me-i
nter
val
[num
ber
|un
set
|di
sabl
e][-
user
user
_nam
e]
Appendix D. Administration C API, Java method, and command line equivalents 69
Tabl
e31
.M
appi
ngbe
twee
nad
min
istr
atio
nC
AP
I,Ja
vam
etho
ds,
and
the
com
man
dlin
ein
terf
ace
(con
tinue
d)
CA
PI
Java
Cla
ssan
dM
eth
odC
omm
and
Lin
eE
qu
ival
ent
ivad
min
_use
r_se
tmax
lgn
fail
s()
PD
Pol
icy.
setM
axFa
iled
Log
ins
PD
Pol
icy
obje
ct.s
etM
axFa
iled
Log
ins
pdad
min
poli
cyse
tma
x-lo
gin-
fail
ures
[num
ber
|un
set]
[-us
erus
er_n
ame]
ivad
min
_use
r_se
tmax
pw
dag
e()
PD
Pol
icy.
setM
axP
wd
Age
PD
Pol
icy
obje
ct.s
etM
axP
wd
Age
pdad
min
poli
cyse
tma
x-pa
sswo
rd-a
ge[u
nset
|re
lati
ve_t
ime]
[-us
erus
er_n
ame]
ivad
min
_use
r_se
tmax
pw
dre
pch
ars(
)P
DP
olic
y.se
tMax
Pw
dR
epC
har
sP
DP
olic
yob
ject
.set
Max
Pw
dR
epC
har
spd
admi
npo
licy
set
max-
pass
word
-rep
eate
d-ch
ars
[num
ber
|un
set]
[-us
erus
er_n
ame]
ivad
min
_use
r_se
tmin
pw
dal
ph
as()
PD
Pol
icy.
setM
inP
wd
Alp
has
PD
Pol
icy
obje
ct.s
etM
inP
wd
Alp
has
pdad
min
poli
cyse
tmi
n-pa
sswo
rd-a
lpha
s[n
umbe
r|
unse
t][-
user
user
_nam
e]
ivad
min
_use
r_se
tmin
pw
dle
n()
PD
Pol
icy.
setM
inP
wd
Len
PD
Pol
icy
obje
ct.s
etM
inP
wd
Len
pdad
min
poli
cyse
tmi
n-pa
sswo
rd-l
engt
h[n
umbe
r|
unse
t][-
user
user
_nam
e]
ivad
min
_use
r_se
tmin
pw
dn
onal
ph
as()
PD
Pol
icy.
setM
inP
wd
Non
Alp
has
PD
Pol
icy
obje
ct.s
etM
inP
wd
Non
Alp
has
pdad
min
poli
cyse
tmi
n-pa
sswo
rd-n
on-a
lpha
s[n
umbe
r|
unse
t][-
user
user
_nam
e]
ivad
min
_use
r_se
tpas
swor
d()
PD
Use
r.set
Pas
swor
dP
DU
ser
obje
ct.s
etP
assw
ord
pdad
min
user
modi
fyus
er_n
ame
pass
word
pass
word
ivad
min
_use
r_se
tpas
swor
dva
lid
()P
DU
ser.s
etP
assw
ord
Val
idP
DU
ser
obje
ct.s
etP
assw
ord
Val
idpd
admi
nus
ermo
dify
user
_nam
epa
sswo
rd-v
alid
[yes
|no
]
ivad
min
_use
r_se
tpw
dsp
aces
()P
DP
olic
y.se
tPw
dS
pac
esA
llow
edP
DP
olic
yob
ject
.set
Pw
dS
pac
esA
llow
edpd
admi
npo
licy
set
pass
word
-spa
ces
[yes
|no
|un
set]
[-us
erus
er_n
ame]
ivad
min
_use
r_se
tsso
use
r()
PD
Use
r.set
SS
OU
ser
PD
Use
rob
ject
.set
SS
OU
ser
pdad
min
user
modi
fyus
er_n
ame
gsou
ser
[yes
|no
]
ivad
min
_use
r_se
ttod
acce
ss()
PD
Pol
icy.
setT
odA
cces
sP
DP
olic
yob
ject
.set
Tod
Acc
ess
pdad
min
poli
cyse
tto
d-ac
cess
tod_
valu
e-u
ser
user
_nam
e
70 IBM Tivoli Access Manager: Administration Java Classes Developer’s Reference
Appendix E. Notices
This information was developed for products and services offered in the U.S.A.
IBM may not offer the products, services, or features discussed in this document inother countries. Consult your local IBM representative for information on theproducts and services currently available in your area. Any reference to an IBMproduct, program, or service is not intended to state or imply that only that IBMproduct, program, or service may be used. Any functionally equivalent product,program, or service that does not infringe any IBM intellectual property right maybe used instead. However, it is the user’s responsibility to evaluate and verify theoperation of any non-IBM product, program, or service.
IBM may have patents or pending patent applications covering subject matterdescribed in this document. The furnishing of this document does not give youany license to these patents. You can send license inquiries, in writing, to:
IBM Director of LicensingIBM CorporationNorth Castle DriveArmonk, NY 10504-1785U.S.A.
For license inquiries regarding double-byte (DBCS) information, contact the IBMIntellectual Property Department in your country or send inquiries, in writing, to:
IBM World Trade Asia CorporationLicensing2-31 Roppongi 3-chome, Minato-kuTokyo 106-0032, Japan
The following paragraph does not apply to the United Kingdom or any othercountry where such provisions are inconsistent with local law:INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THISPUBLICATION “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHEREXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIEDWARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESSFOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express orimplied warranties in certain transactions, therefore, this statement may not applyto you.
This information could include technical inaccuracies or typographical errors.Changes are periodically made to the information herein; these changes will beincorporated in new editions of the publication. IBM may make improvementsand/or changes in the product(s) and/or the program(s) described in thispublication at any time without notice.
Any references in this information to non-IBM Web sites are provided forconvenience only and do not in any manner serve as an endorsement of those Websites. The materials at those Web sites are not part of the materials for this IBMproduct and use of those Web sites is at your own risk.
IBM may use or distribute any of the information you supply in any way itbelieves appropriate without incurring any obligation to you.
© Copyright IBM Corp. 2002, 2003 71
Licensees of this program who wish to have information about it for the purposeof enabling: (i) the exchange of information between independently createdprograms and other programs (including this one) and (ii) the mutual use of theinformation which has been exchanged, should contact:
IBM Corporation2Z4A/10111400 Burnet RoadAustin, TX 78758U.S.A.
Such information may be available, subject to appropriate terms and conditions,including in some cases, payment of a fee.
The licensed program described in this information and all licensed materialavailable for it are provided by IBM under terms of the IBM Customer Agreement,IBM International Program License Agreement, or any equivalent agreementbetween us.
Information concerning non-IBM products was obtained from the suppliers ofthose products, their published announcements or other publicly available sources.IBM has not tested those products and cannot confirm the accuracy ofperformance, compatibility or any other claims related to non-IBM products.Questions on the capabilities of non-IBM products should be addressed to thesuppliers of those products.
All statements regarding IBM’s future direction or intent are subject to change orwithdrawal without notice, and represent goals and objectives only.
This information contains examples of data and reports used in daily businessoperations. To illustrate them as completely as possible, the examples include thenames of individuals, companies, brands, and products. All of these names arefictitious and any similarity to the names and addresses used by an actual businessenterprise is entirely coincidental.
COPYRIGHT LICENSE:
This information contains sample application programs in source language, whichillustrate programming techniques on various operating platforms. You may copy,modify, and distribute these sample programs in any form without payment toIBM, for the purposes of developing, using, marketing or distributing applicationprograms conforming to the application programming interface for the operatingplatform for which the sample programs are written. These examples have notbeen thoroughly tested under all conditions. IBM, therefore, cannot guarantee orimply reliability, serviceability, or function of these programs. You may copy,modify, and distribute these sample programs in any form without payment toIBM for the purposes of developing, using, marketing, or distributing applicationprograms conforming to IBM’s application programming interfaces.
If you are viewing this information softcopy, the photographs and colorillustrations may not appear.
TrademarksThe following terms are trademarks or registered trademarks of InternationalBusiness Machines Corporation in the United States, other countries, or both:
72 IBM Tivoli Access Manager: Administration Java Classes Developer’s Reference
AIXDB2IBMIBM logoOS/390SecureWayTivoliTivoli logoUniversal DatabaseWebSpherez/OSzSeries
Lotus is a registered trademark of Lotus Development Corporation and/or IBMCorporation.
Domino is a trademark of International Business Machines Corporation and LotusDevelopment Corporation in the United States, other countries, or both.
Microsoft and Windows are trademarks of Microsoft Corporation in the UnitedStates, other countries, or both.
Java and all Java-based trademarks and logos are trademarks or registeredtrademarks of Sun Microsystems, Inc. in the United States and other countries.
UNIX is a registered trademark of The Open Group in the United States and othercountries.
Other company, product, and service names may be trademarks or service marksof others.
Appendix E. Notices 73
74 IBM Tivoli Access Manager: Administration Java Classes Developer’s Reference
Glossary
Aaccess control. In computer security, the process ofensuring that the resources of a computer system canbe accessed only by authorized users in authorizedways.
access control list (ACL). In computer security, a listthat is associated with an object that identifies all thesubjects that can access the object and their accessrights. For example, an access control list is a list that isassociated with a file that identifies the users who canaccess the file and identifies the users’ access rights tothat file.
access permission. The access privilege that applies tothe entire object.
action. An access control list (ACL) permissionattribute. See also access control list.
ACL. See access control list.
administration service. An authorization API runtimeplug-in that can be used to perform administrationrequests on a Tivoli Access Manager resource managerapplication. The administration service will respond toremote requests from the pdadmin command toperform tasks, such as listing the objects under aparticular node in the protected object tree. Customersmay develop these services using the authorizationADK.
attribute list. A linked list that contains extendedinformation that is used to make authorizationdecisions. Attribute lists consist of a set of name = valuepairs.
authentication. (1) In computer security, verification ofthe identity of a user or the user’s eligibility to accessan object. (2) In computer security, verification that amessage has not been altered or corrupted. (3) Incomputer security, a process that is used to verify theuser of an information system or of protected resources.See also multi-factor authentication, network-basedauthentication, and step-up authentication.
authorization. (1) In computer security, the rightgranted to a user to communicate with or make use ofa computer system. (2) The process of granting a usereither complete or restricted access to an object,resource, or function.
authorization rule. See rule.
authorization service plug-in. A dynamically loadablelibrary (DLL or shared library) that can be loaded by
the Tivoli Access Manager authorization API runtimeclient at initialization time in order to performoperations that extend a service interface within theAuthorization API. The service interfaces that arecurrently available include Administration, ExternalAuthorization, Credentials modification, Entitlementsand PAC manipulation interfaces. Customers maydevelop these services using the authorization ADK.
BBA. See basic authentication.
basic authentication. A method of authentication thatrequires the user to enter a valid user name andpassword before access to a secure online resource isgranted.
bind. To relate an identifier to another object in aprogram; for example, to relate an identifier to a value,an address or another identifier, or to associate formalparameters and actual parameters.
blade. A component that provides application-specificservices and components.
business entitlement. The supplemental attribute of auser credential that describes the fine-grainedconditions that can be used in the authorization ofrequests for resources.
CCA. See certificate authority.
CDAS. See Cross Domain Authentication Service.
CDMF. See Cross Domain Mapping Framework.
certificate. In computer security, a digital documentthat binds a public key to the identity of the certificateowner, thereby enabling the certificate owner to beauthenticated. A certificate is issued by a certificateauthority.
certificate authority (CA). An organization that issuescertificates. The certificate authority authenticates thecertificate owner’s identity and the services that theowner is authorized to use, issues new certificates,renews existing certificates, and revokes certificatesbelonging to users who are no longer authorized to usethem.
CGI. See common gateway interface.
© Copyright IBM Corp. 2002, 2003 75
cipher. Encrypted data that is unreadable until it hasbeen converted into plain data (decrypted) with a key.
common gateway interface (CGI). An Internetstandard for defining scripts that pass information froma Web server to an application program, through anHTTP request, and vice versa. A CGI script is a CGIprogram that is written in a scripting language, such asPerl.
configuration. (1) The manner in which the hardwareand software of an information processing system areorganized and interconnected. (2) The machines,devices, and programs that make up a system,subsystem, or network.
connection. (1) In data communication, an associationestablished between functional units for conveyinginformation. (2) In TCP/IP, the path between twoprotocol applications that provides reliable data streamdelivery service. In the Internet, a connection extendsfrom a TCP application on one system to a TCPapplication on another system. (3) In systemcommunications, a line over which data can be passedbetween two systems or between a system and adevice.
container object. A structural designation thatorganizes the object space into distinct functionalregions.
cookie. Information that a server stores on a clientmachine and accesses during subsequent sessions.Cookies allow servers to remember specific informationabout clients.
credentials. Detailed information, acquired duringauthentication, that describes the user, any groupassociations, and other security-related identityattributes. Credentials can be used to perform amultitude of services, such as authorization, auditing,and delegation.
credentials modification service. An authorizationAPI runtime plug-in which can be used to modify aTivoli Access Manager credential. Credentialsmodification services developed externally bycustomers are limited to performing operation to addand remove from the credentials attribute list and onlyto those attributes that are considered modifiable.
cross domain authentication service (CDAS). AWebSEAL service that provides a shared librarymechanism that allows you to substitute the defaultWebSEAL authentication mechanisms with a customprocess that returns a Tivoli Access Manager identity toWebSEAL. See also WebSEAL.
cross domain mapping framework (CDMF). Aprogramming interface that allows a developer tocustomize the mapping of user identities and thehandling of user attributes when WebSEALe-Community SSO function are used.
Ddaemon. A program that runs unattended to performcontinuous or periodic systemwide functions, such asnetwork control. Some daemons are triggeredautomatically to perform their task; others operateperiodically.
directory schema. The valid attribute types and objectclasses that can appear in a directory. The attributetypes and object classes define the syntax of theattribute values, which attributes must be present, andwhich attributes may be present for the directory.
distinguished name (DN). The name that uniquelyidentifies an entry in a directory. A distinguished nameis made up of attribute:value pairs, separated bycommas.
digital signature. In e-commerce, data that isappended to, or is a cryptographic transformation of, adata unit and that enables the recipient of the data unitto verify the source and integrity of the unit and torecognize potential forgery.
DN. See distinguished name.
domain. (1) A logical grouping of users, systems, andresources that share common services and usuallyfunction with a common purpose. (2) That part of acomputer network in which the data processingresources are under common control. See also domainname.
domain name. In the Internet suite of protocols, aname of a host system. A domain name consists of asequence of subnames that are separated by a delimitercharacter. For example, if the fully qualified domainname (FQDN) of a host system isas400.rchland.vnet.ibm.com, each of the following is adomain name: as400.rchland.vnet.ibm.com,vnet.ibm.com, ibm.com.
EEAS. See External Authorization Service.
encryption. In computer security, the process oftransforming data into an unintelligible form in such away that the original data either cannot be obtained orcan be obtained only by using a decryption process.
entitlement. A data structure that containsexternalized security policy information. Entitlementscontain policy data or capabilities that are formatted ina way that is understandable to a specific application.
entitlement service. An authorization API runtimeplug-in which can be used to return entitlements froman external source for a principal or set of conditions.Entitlements are normally application specific data thatwill be consumed by the resource manager application
76 IBM Tivoli Access Manager: Administration Java Classes Developer’s Reference
in some way or added to the principal’s credentials foruse further on in the authorization process. Customersmay develop these services using the authorizationADK.
external authorization service. An authorization APIruntime plug-in that can be used to make applicationor environment specific authorization decisions as partof the Tivoli Access Manager authorization decisionchain. Customers may develop these services using theauthorization ADK.
Ffile transfer protocol (FTP). In the Internet suite ofprotocols, an application layer protocol that usesTransmission Control Protocol (TCP) and Telnetservices to transfer bulk-data files between machines orhosts.
Gglobal signon (GSO). A flexible single sign-onsolution that enables the user to provide alternativeuser names and passwords to the back-end Webapplication server. Global signon grants users access tothe computing resources they are authorized to use —through a single login. Designed for large enterprisesconsisting of multiple systems and applications withinheterogeneous, distributed computing environments,GSO eliminates the need for users to manage multipleuser names and passwords. See also single signon.
GSO. See global signon.
Hhost. A computer that is connected to a network (suchas the Internet or an SNA network) and provides anaccess point to that network. Also, depending on theenvironment, the host may provide centralized controlof the network. The host can be a client, a server, orboth a client and a server simultaneously.
HTTP. See Hypertext Transfer Protocol.
hypertext transfer protocol (HTTP). In the Internetsuite of protocols, the protocol that is used to transferand display hypertext documents.
IInternet protocol (IP). In the Internet suite ofprotocols, a connectionless protocol that routes datathrough a network or interconnected networks and actsas an intermediary between the higher protocol layersand the physical network.
Internet suite of protocols. A set of protocolsdeveloped for use on the Internet and published as
Requests for Comments (RFCs) through the InternetEngineering Task Force (IETF).
interprocess communication (IPC). (1) The process bywhich programs communicate data to each other andsynchronize their activities. Semaphores, signals, andinternal message queues are common methods ofinterprocess communication. (2) A mechanism of anoperating system that allows processes to communicatewith each other within the same computer or over anetwork.
IP. See Internet Protocol.
IPC. See Interprocess Communication.
Jjunction. An HTTP or HTTPS connection between afront-end WebSEAL server and a back-end Webapplication server. WebSEAL uses a junction to provideprotective services on behalf of the back-end server.
Kkey. In computer security, a sequence of symbols thatis used with a cryptographic algorithm for encryptingor decrypting data. See private key and public key.
key database file. See key ring.
key file. See key ring.
key pair. In computer security, a public key and aprivate key. When the key pair is used for encryption,the sender uses the public key to encrypt the message,and the recipient uses the private key to decrypt themessage. When the key pair is used for signing, thesigner uses the private key to encrypt a representationof the message, and the recipient uses the public key todecrypt the representation of the message for signatureverification.
key ring. In computer security, a file that containspublic keys, private keys, trusted roots, and certificates.
LLDAP. See Lightweight Directory Access Protocol.
lightweight directory access protocol (LDAP). Anopen protocol that (a) uses TCP/IP to provide access todirectories that support an X.500 model and (b) doesnot incur the resource requirements of the morecomplex X.500 Directory Access Protocol (DAP).Applications that use LDAP (known asdirectory-enabled applications) can use the directory asa common data store and for retrieving informationabout people or services, such as e-mail addresses,public keys, or service-specific configurationparameters. LDAP was originally specified in RFC
Glossary 77
1777. LDAP version 3 is specified in RFC 2251, and theIETF continues work on additional standard functions.Some of the IETF-defined standard schemas for LDAPare found in RFC 2256.
lightweight third party authentication (LTPA). Anauthentication framework that allows single sign-onacross a set of Web servers that fall within an Internetdomain.
LTPA. See lightweight third party authentication.
Mmanagement domain. The default domain in whichTivoli Access Manager enforces security policies forauthentication, authorization, and access control. Thisdomain is created when the policy server is configured.See also domain.
management server. Obsolete. See policy server.
metadata. Data that describes the characteristics ofstored data.
migration. The installation of a new version or releaseof a program to replace an earlier version or release.
multi-factor authentication. A protected object policy(POP) that forces a user to authenticate using two ormore levels of authentication. For example, the accesscontrol on a protected resource can require that theusers authenticate with both user name/password anduser name/token passcode. See also protected objectpolicy.
multiplexing proxy agent (MPA). A gateway thataccommodates multiple client access. These gatewaysare sometimes known as Wireless Access Protocol(WAP) gateways when clients access a secure domainusing a WAP. Gateways establish a single authenticatedchannel to the originating server and tunnel all clientrequests and responses through this channel.
Nnetwork-based authentication. A protected objectpolicy (POP) that controls access to objects based on theinternet protocol (IP) address of the user. See alsoprotected object policy.
PPAC. See privilege attribute certificate.
permission. The ability to access a protected object,such as a file or directory. The number and meaning ofpermissions for an object are defined by the accesscontrol list (ACL). See also access control list.
policy. A set of rules that are applied to managedresources.
policy server. The Tivoli Access Manager server thatmaintains the location information about other serversin the secure domain.
polling. The process by which databases areinterrogated at regular intervals to determine if dataneeds to be transmitted.
POP. See protected object policy.
portal. An integrated Web site that dynamicallyproduces a customized list of Web resources, such aslinks, content, or services, available to a specific user,based on the access permissions for the particular user.
privilege attribute certificate. A digital document thatcontains a principal’s authentication and authorizationattributes and a principal’s capabilities.
privilege attribute certificate service. Anauthorization API runtime client plug-in whichtranslates a PAC of a predetermined format in to aTivoli Access Manager credential, and vice-versa. Theseservices could also be used to package or marshall aTivoli Access Manager credential for transmission toother members of the secure domain. Customers maydevelop these services using the authorization ADK.See also privilege attribute certificate.
protected object. The logical representation of anactual system resource that is used for applying ACLsand POPs and for authorizing user access. See alsoprotected object policy and protected object space.
protected object policy (POP). A type of securitypolicy that imposes additional conditions on theoperation permitted by the ACL policy to access aprotected object. It is the responsibility of the resourcemanager to enforce the POP conditions. See also accesscontrol list, protected object, and protected object space.
protected object space. The virtual objectrepresentation of actual system resources that is usedfor applying ACLs and POPs and for authorizing useraccess. See also protected object and protected object policy.
private key. In computer security, a key that is knownonly to its owner. Contrast with public key.
public key. In computer security, a key that is madeavailable to everyone. Contrast with private key.
Qquality of protection. The level of data security,determined by a combination of authentication,integrity, and privacy conditions.
78 IBM Tivoli Access Manager: Administration Java Classes Developer’s Reference
Rregistry. The datastore that contains access andconfiguration information for users, systems, andsoftware.
replica. A server that contains a copy of the directoryor directories of another server. Replicas back upservers in order to enhance performance or responsetimes and to ensure data integrity.
resource object. The representation of an actualnetwork resource, such as a service, file, and program.
response file. A file that contains a set of predefinedanswers to questions asked by a program and that isused instead of entering those values one at a time.
role activation. The process of applying the accesspermissions to a role.
role assignment. The process of assigning a role to auser, such that the user has the appropriate accesspermissions for the object defined for that role.
routing file. An ASCII file that contains commandsthat control the configuration of messages.
RSA encryption. A system for public-keycryptography used for encryption and authentication. Itwas invented in 1977 by Ron Rivest, Adi Shamir, andLeonard Adleman. The system’s security depends onthe difficulty of factoring the product of two largeprime numbers.
rule. One or more logical statements that enable theevent server to recognize relationships among events(event correlation) and to execute automated responsesaccordingly.
run time. The time period during which a computerprogram is executing. A runtime environment is anexecution environment.
Sscalability. The ability of a network system to respondto increasing numbers of users who access resources.
schema. The set of statements, expressed in a datadefinition language, that completely describe thestructure of a database. In a relational database, theschema defines the tables, the fields in each table, andthe relationships between fields and tables.
secure sockets layer (SSL). A security protocol thatprovides communication privacy. SSL enablesclient/server applications to communicate in a way thatis designed to prevent eavesdropping, tampering, andmessage forgery. SSL was developed by NetscapeCommunications Corp. and RSA Data Security, Inc.
security management. The management disciplinethat addresses an organization’s ability to control accessto applications and data that are critical to its success.
self-registration. The process by which a user canenter required data and become a registered TivoliAccess Manager user, without the involvement of anadministrator.
service. Work performed by a server. A service can bea simple request for data to be sent or stored (as withfile servers, HTTP servers, e-mail servers, and fingerservers), or it can be more complex work such as thatof print servers or process servers.
silent installation. An installation that does not sendmessages to the console but instead stores messagesand errors in log files. Also, a silent installation can useresponse files for data input. See also response file.
single signon (SSO). The ability of a user to logononce and access multiple applications without havingto logon to each application separately. See also globalsignon.
SSL. See Secure Sockets Layer.
SSO. See Single Signon.
step-up authentication. A protected object policy(POP) that relies on a preconfigured hierarchy ofauthentication levels and enforces a specific level ofauthentication according to the policy set on a resource.The step-up authentication POP does not force the userto authenticate using multiple levels of authenticationto access any given resource but requires the user toauthenticate at a level at least as high as that requiredby the policy protecting a resource.
suffix. A distinguished name that identifies the topentry in a locally held directory hierarchy. Because ofthe relative naming scheme used in LightweightDirectory Access Protocol (LDAP), this suffix applies toevery other entry within that directory hierarchy. Adirectory server can have multiple suffixes, eachidentifying a locally held directory hierarchy.
Ttoken. (1) In a local area network, the symbol ofauthority passed successively from one data station toanother to indicate the station temporarily in control ofthe transmission medium. Each data station has anopportunity to acquire and use the token to control themedium. A token is a particular message or bit patternthat signifies permission to transmit. (2) In local areanetworks (LANs), a sequence of bits passed from onedevice to another along the transmission medium.When the token has data appended to it, it becomes aframe.
Glossary 79
trusted root. In the Secure Sockets Layer (SSL), thepublic key and associated distinguished name of acertificate authority (CA).
Uuniform resource identifier (URI). The characterstring used to identify content on the Internet,including the name of the resource (a directory and filename), the location of the resource (the computerwhere the directory and file name exist), and how theresource can be accessed (the protocol, such as HTTP).An example of a URI is a uniform resource locator, orURL.
uniform resource locator (URL). A sequence ofcharacters that represent information resources on acomputer or in a network such as the Internet. Thissequence of characters includes (a) the abbreviatedname of the protocol used to access the informationresource and (b) the information used by the protocolto locate the information resource. For example, in thecontext of the Internet, these are abbreviated names ofsome protocols used to access various informationresources: http, ftp, gopher, telnet, and news; and thisis the URL for the IBM home page:http://www.ibm.com.
URI. See uniform resource identifier.
URL. See uniform resource locator.
user. Any person, organization, process, device,program, protocol, or system that uses a serviceprovided by others.
user registry. See registry.
Vvirtual hosting. The capability of a Web server thatallows it to appear as more than one host to theInternet.
WWeb Portal Manager (WPM). A Web-based graphicalapplication used to manage Tivoli Access Manager Baseand WebSEAL security policy in a secure domain. Analternative to the pdadmin command line interface, thisGUI enables remote administrator access and enablesadministrators to create delegated user domains andassign delegate administrators to these domains.
WebSEAL. A Tivoli Access Manager blade. WebSEALis a high performance, multi-threaded Web server thatapplies a security policy to a protected object space.WebSEAL can provide single sign-on solutions andincorporate back-end Web application server resourcesinto its security policy.
WPM. See Web Portal Manager.
80 IBM Tivoli Access Manager: Administration Java Classes Developer’s Reference
Index
Aaccess control list entries, table 33access control list entry types 32access control lists, table 32account functions, table 21, 22accounts 20action group functions, table 34action groups
overview 34adding development systems 4ADK component 2administration tasks 47any-authenticated 32any-other 32API differences 59application developer kit (ADK) 2application development kit (ADK) 2application, deploying 5applications, building 3audit log 39audit records 39authentication
certificate-based 11user ID and password-based 10
Bbuilding applications 3
Ccom.tivoli.nts.PDAttrs.get() 53com.tivoli.nts.PDAttrs() 53com.tivoli.nts.SrvSslCfg() 53commands, pdadmin 2commands, svrsslcfg 2components 2createGroup method 23createUser method 19
Ddemonstration program 5deploying an application 5deprecated classes and methods 53
com.tivoli.nts.PDAttrs.get() 53com.tivoli.nts.PDAttrs() 53com.tivoli.nts.SrvSslCfgs() 53
development systems, adding 4
Eexample program 5extended action functions, table 35extended actions, overview 35
Ffiles, installation directories 3
Ggetting administration tasks 47group attributes, table 24group functions, table 24groups
access control list entry type 32overview 19
IIBM SecureWay Directory client 4initializing API 10installation 3installation directories 3installation requirements 3
JJava classes 1Javadoc information 2
Mmethods
PDAcl.listAcls 15PDAdmin.initialize 10PDAdmin.shutdown 16PDGroup.createGroup 23PDGroup.importGroup 23PDGroup.listGroups 15PDPolicy.acctDisableTimeEnforced 21PDPolicy.acctDisableTimeUnlimited 21PDPolicy.acctExpDateEnforced 21PDPolicy.acctExpDateUnlimited 21PDPolicy.getAccessEndTime 22PDPolicy.getAccessibleDays 22PDPolicy.getAccessStartTime 22PDPolicy.getAccessTimezone 22PDPolicy.getAcctDisableTimeInterval 21PDPolicy.getAcctExpDate 21PDPolicy.getMaxFailedLogins 22PDPolicy.maxFailedLoginsEnforced 22PDPolicy.setAcctDisableTime 22PDPolicy.setAcctExpDate 22PDPolicy.setMaxFailedLogins 22PDPolicy.setTodAccess 22PDPolicy.todAccessEnforced 22PDProtObject.listProtObjects 15PDProtObject.listProtObjectsByAcl 15PDProtObjectSpace.listProtObjectSpaces 15PDUser.createUser 12, 19, 20PDUser.deleteUser 15, 19, 20PDUser.getDescription 14, 20PDUser.getFirstName 20PDUser.getGroups 20
© Copyright IBM Corp. 2002, 2003 81
methods (continued)PDUser.getId 20PDUser.getLastName 20PDUser.getPolicy 20PDUser.getRgyName 20PDUser.getUserRgy 21PDUser.importUser 19, 20PDUser.isAccountValid 20PDUser.isPDUser 20PDUser.isSSOUser 21PDUser.listUsers 15, 20PDUser.setAccountValid 14, 21PDUser.setDescription 21PDUser.setPassword 21PDUser.setPasswordValid 21PDUser.setSSOUser 21
Nnotification wait time 48
Oobjects
CredID 9CredInfo 9PDAcl 8, 32PDAclEntry 8, 32PDAclEntryAnyOther 8, 32PDAclEntryGroup 8, 32PDAclEntryUnAuth 8, 32PDAclEntryUser 8, 32PDAction 8PDActionGroup 8PDAdmin 7PDAppSvrInfo 9PDAppSvrSpecLocal 8PDAppSvrSpecRemote 9PDAttrs 9PDAttrValue 9PDAttrValueList 9PDAttrValues 9PDContext 7, 51PDException 9, 51PDGroup 7, 23PDMessage 9, 15PDMessages 9, 15, 51PDPolicy 7, 21PDPop 8PDProtObject 8PDProtObjectSpace 8, 27PDRgyGroupName 8PDRgyName 8PDRgyUserName 8PDServer 9PDSSOResource 9PDSSOResourceGroup 9PDSvrInfo 9PDUser 7, 19
Ppassword functions, table 22, 23passwords 21, 22PD.jar file 1pdadmin command line utility 2
PDContext object 51PDException object 51PDGroup 23PDMessages object 51PDUser 19PDUser.deleteUser method 19performing administration tasks 47protected object attributes 29protected object functions, table 28, 29protected object policies 37
administering 37defined 27
protected object policy (POP) 27protected object policy extended attributes, table 39protected object policy objects 37protected object policy objects, table 37protected object policy settings 38protected object policy settings, table 39protected object space functions, table 28protected object spaces 27protected objects 27, 28
Rregistry, user 4related publications xvreplica databases, notification threads 48replica databases, notifying of updates 47, 48requirements, for installation 3response processing 51
Ssecure domain 3Secure Sockets Layer (SSL) 2security context 10, 51servers and databases, table 49software requirements 3svrsslcfg command line utility 2
Uunauthenticated 32Unicode 16user account functions, table 21, 22user accounts 20user functions, table 20user password functions, table 22, 23user passwords 21, 22user registry 4
differences xviii, 55maximum values 56, 57, 58
users 19, 32using the administration API 7UTF-8 16
Wwait time 48warning attribute 39
82 IBM Tivoli Access Manager: Administration Java Classes Developer’s Reference
����
Printed in U.S.A.
SC32-1143-01