Administration Java Classes Developer’s Referencepublib.boulder.ibm.com/tividd/td/ITAME/SC32-0842-00/en_US/PDF/a… · GC32-0844

IBM Tivoli Access Manager

Administration Java ClassesDeveloper’s ReferenceVersion 3.9

SC32-0842-00

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

First Edition (April 2002)

This edition applies to version 3.9 of IBM Tivoli Access Manager (product number 5724-C08) and to all subsequentreleases and modifications until otherwise indicated in new editions.

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

Contents

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

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

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

IBM Tivoli Access Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiRelated publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiiiAccessing publications online . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvOrdering publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvProviding feedback about publications . . . . . . . . . . . . . . . . . . . . . . . . . xv

Accessibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvContacting customer support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xviConventions used in this reference . . . . . . . . . . . . . . . . . . . . . . . . . . . xvi

Typeface conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xviUser registry differences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvi

Chapter 1. Introducing the administration API . . . . . . . . . . . . . . . . . . . 1Administration Java classes overview . . . . . . . . . . . . . . . . . . . . . . . . . . . 1Objects not supported by administration Java classes . . . . . . . . . . . . . . . . . . . . . . 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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

Java administration API example program . . . . . . . . . . . . . . . . . . . . . . . . . 5Deploying a Java administration API application . . . . . . . . . . . . . . . . . . . . . . . 5Gathering problem determination information . . . . . . . . . . . . . . . . . . . . . . . . 5

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

Chapter 2. Using the administration API . . . . . . . . . . . . . . . . . . . . . . 7Administration objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7Initializing the administration API . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9Establishing a security context . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

User ID and password-based authentication . . . . . . . . . . . . . . . . . . . . . . . . 9Certificate-based authentication. . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

Manipulating administration objects . . . . . . . . . . . . . . . . . . . . . . . . . . . 11Creating objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11Obtaining a local copy of an object . . . . . . . . . . . . . . . . . . . . . . . . . . 12Reading object values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13Setting object values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13Listing objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13Deleting objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14Handling errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15Shutting down the administration API . . . . . . . . . . . . . . . . . . . . . . . . . . 15Character-based data considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

© Copyright IBM Corp. 2002 iii

Chapter 3. Administering users and groups . . . . . . . . . . . . . . . . . . . . 17Administering users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17Administering user information . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18Administering user account policies . . . . . . . . . . . . . . . . . . . . . . . . . . . 19Administering user password policies . . . . . . . . . . . . . . . . . . . . . . . . . . 20Administering groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21Administering group information . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

Chapter 4. Administering protected objects and protected object spaces . . . . . . . 25Administering protected object spaces . . . . . . . . . . . . . . . . . . . . . . . . . . 25Administering protected objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26Administering protected object attributes . . . . . . . . . . . . . . . . . . . . . . . . . 27

Chapter 5. Administering access control . . . . . . . . . . . . . . . . . . . . . 29Administering access control lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29Administering access control list entries . . . . . . . . . . . . . . . . . . . . . . . . . . 30Administering access control list extended attributes . . . . . . . . . . . . . . . . . . . . . 31

Appendix A. Differences between the C and Java administration API . . . . . . . . . 33

Appendix B. Deprecated classes and methods . . . . . . . . . . . . . . . . . . 35

Appendix C. User registry differences . . . . . . . . . . . . . . . . . . . . . . 37

Appendix D. Administration C API, Java method, and command line equivalents. . . . 41

Appendix E. Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53Trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

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

Figures

1. Granting Java permission to applications . . . . . . . . . . . . . . . . . . . . . . . . 52. Initializing the administration API . . . . . . . . . . . . . . . . . . . . . . . . . . 93. Creating a security context using user ID and password-based authentication . . . . . . . . . . . 104. Creating a security context using certificate-based authentication. . . . . . . . . . . . . . . . 105. Creating a user . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126. Getting a local copy of a PDUser object . . . . . . . . . . . . . . . . . . . . . . . . 127. Deleting a user . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148. Shutting down the administration API . . . . . . . . . . . . . . . . . . . . . . . . 15

© Copyright IBM Corp. 2002 v

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

Tables

1. Administration API application development kit files . . . . . . . . . . . . . . . . . . . . 32. Methods used to list objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143. Administrating users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184. Administrating user information . . . . . . . . . . . . . . . . . . . . . . . . . . 185. Administrating user account policies . . . . . . . . . . . . . . . . . . . . . . . . . 196. Administrating user password policies . . . . . . . . . . . . . . . . . . . . . . . . 207. Administering groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228. Administering group attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . 229. Administering protected object spaces. . . . . . . . . . . . . . . . . . . . . . . . . 26

10. Administering protected objects . . . . . . . . . . . . . . . . . . . . . . . . . . . 2611. Administering protected object attributes . . . . . . . . . . . . . . . . . . . . . . . 2712. Administering access control lists . . . . . . . . . . . . . . . . . . . . . . . . . . 3013. Administering access control list entries . . . . . . . . . . . . . . . . . . . . . . . . 3114. Administering access control list extended attributes . . . . . . . . . . . . . . . . . . . . 3115. User registry differences when adding a duplicate user to a group . . . . . . . . . . . . . . . 3816. User registry differences when removing a user from a group who is not a member of the group . . . . . 3817. Maximum lengths for names based on user registry . . . . . . . . . . . . . . . . . . . . 3818. Mapping between administration C API, Java methods, and the command line interface . . . . . . . . 42

© Copyright IBM Corp. 2002 vii

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

Preface

IBM® Tivoli® Access Manager (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 Access Manageradministration Java™ classes and methods to enable an application toprogrammatically perform Access Manager administration tasks. This documentdescribes the Java implementation of the Access Manager administration API. Seethe IBM Tivoli Access Manager Administration C API Developer’s Reference forinformation regarding the C implementation of these APIs.

Information on the pdadmin command line interface (CLI) can be found in theIBM Tivoli Access Manager Base Administrator’s Guide.

Who should read this referenceThis 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 Access Manager is configured to usev Lightweight Directory Access Protocol (LDAP) and directory services, if used by

your user registryv Authentication and authorizationIf 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 reference containsThis reference contains the following chapters and appendixes:v Chapter 1, “Introducing the administration API” on page 1

© Copyright IBM Corp. 2002 ix

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 17The administration API provides a collection of methods for administeringAccess 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 25This 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 29This 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 Appendix A, “Differences between the C and Java administration API” onpage 33This appendix outlines the differences between the administration C APIfunctions and the administration Java classes and methods.

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

v Appendix C, “User registry differences” on page 37This appendix outlines the differences in behavior of the classes and methodsbased on the user registry being used by Access Manager.

v Appendix D, “Administration C API, Java method, and command lineequivalents” on page 41This 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 53This appendix provides copyright, legal, and trademark information.

PublicationsThis section lists publications in the Access Manager library and any other relateddocuments. It also describes how to access Tivoli publications online, how to orderTivoli publications, and how to make comments on Tivoli publications.

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

IBM Tivoli Access ManagerThe Access Manager library is organized into the following categories:v “Release information”v “Base information”v “WebSEAL information”v “Web security information” on page xiiv “Developer references” on page xiiv “Technical supplements” on page xiii

Publications in the product library are included in Portable Document Format(PDF) on the product CD. To access these publications using a Web browser, openthe infocenter.html file located in the /doc directory on the product CD.

For additional sources of information about Access Manager and related topics, seethe following Web sites:

http://www.ibm.com/redbookshttps://www.tivoli.com/secure/support/documents/fieldguides

Release informationv IBM Tivoli Access Manager for e-business Read Me First

GI11-0918 (am39_readme.pdf)Provides information for installing and getting started using Access Manager.

v IBM Tivoli Access Manager for e-business Release NotesGI11-0919 (am39_relnotes.pdf)Provides late-breaking information, such as software limitations, workarounds,and documentation updates.

Base informationv IBM Tivoli Access Manager Base Installation Guide

GC32-0844

Provides background material, administrative procedures, and technicalreference information for using WebSEAL to manage the resources of yoursecure Web domain.

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

v IBM Tivoli Access Manager WebSEAL for Linux on zSeries Installation GuideGC23-4797 (amweb39_zinstall.pdf)Provides installation, configuration, and removal instructions for WebSEALserver and the WebSEAL application development kit for Linux on the zSeriesplatform

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

GC32-0850 (amwas39_user.pdf)Provides installation, removal, and administration instructions for AccessManager for IBM WebSphere® Application Server.

v IBM Tivoli Access Manager for WebLogic Server User’s GuideGC32-0851 (amwls39_user.pdf)Provides installation, removal, and administration instructions for AccessManager for BEA WebLogic Server.

v IBM Tivoli Access Manager Plug-in for Edge Server User’s GuideGC23-4685 (amedge39_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 GuideGC23-4686 (amws39_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

GC32-0849 (am39_authC_devref.pdf)Provides reference material that describes how to use the Access Managerauthorization C API and the Access Manager service plug-in interface to addAccess Manager security to applications.

v IBM Tivoli Access Manager Authorization Java Classes Developer’s ReferenceGC23-4688 (am39_authJ_devref.pdf)Provides reference information for using the Java™ language implementation ofthe authorization API to enable an application to use Access Manager security.

v IBM Tivoli Access Manager Administration C API Developer’s ReferenceGC32-0843 (am39_adminC_devref.pdf)Provides reference information about using the administration API to enable anapplication to perform Access Manager administration tasks. This documentdescribes the C implementation of the administration API.

v IBM Tivoli Access Manager Administration Java Classes Developer’s ReferenceSC32-0842 (am39_adminJ_devref.pdf)

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

Provides reference information for using the Java language implementation ofthe administration API to enable an application to perform Access Manageradministration tasks.

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

Technical supplementsv IBM Tivoli Access Manager Performance Tuning Guide

GC43-0846 (am39_perftune.pdf)Provides performance tuning information for an environment consisting ofAccess Manager with IBM SecureWay Directory defined as the user registry.

v IBM Tivoli Access Manager Capacity Planning GuideGC32-0847 (am39_capplan.pdf)Assists planners in determining the number of WebSEAL, user registry, andbackend Web servers needed to achieve a required workload.

v IBM Tivoli Access Manager Error Message ReferenceSC32-0845 (am39_error_ref.pdf)Provides explanations and recommended actions for the messages produced byAccess Manager.

The Tivoli Glossary includes definitions for many of the technical terms related toTivoli software. The Tivoli Glossary is available, in English only, at the followingWeb site:

http://www.tivoli.com/support/documents/glossary/termsm03.htm

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

IBM DB2® Universal Database™IBM DB2 Universal Database is required when installing IBM SecureWay Directory,z/OS™, and OS/390® SecureWay LDAP servers. DB2 information is available atthe following Web site:

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

IBM Global Security ToolkitAccess Manager provides data encryption through the use of the IBM GlobalSecurity Toolkit (GSKit). GSKit is shipped 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 paris, and certificaterequests. The following document is available in the /doc/GSkit directory on theIBM Tivoli Access Manager Base CD for your particular platform: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 Access Manager secure domain.

Preface xiii

http://www.tivoli.com/support/documents/glossary/termsm03.htmhttp://www.ibm.com/software/data/db2/

IBM SecureWay DirectoryIBM SecureWay Directory, Version 3.2.2, is shipped on the IBM Tivoli AccessManager Base CD for your particular platform. If you plan to install the IBMSecureWay Directory server as your user registry, the following documents areavailable in the /doc/Directory path on the IBM Tivoli Access Manager Base CDfor your particular platform:v IBM SecureWay Directory Installation and Configuration Guide, SC32-0845

(aparent.pdf, lparent.pdf, sparent.pdf, wparent.pdf)Provides installation, configuration, and migration information for IBMSecureWay Directory components on AIX®, Linux, Solaris OperatingEnvironment, and Microsoft® Windows® operating systems.

v IBM SecureWay Directory Release Notes(relnote.pdf)Supplements IBM SecureWay Directory, Version 3.2.2, product documentationand describes features and functions made available to you in this release.

v IBM SecureWay Directory Readme Addendum(addendum322.pdf)Provides information about changes and fixes that occurred after the IBMSecureWay Directory documentation had been translated. This book is providedin English only.

v IBM SecureWay Directory Server Readme(server.pdf)Provides a description of the IBM SecureWay Directory Server, Version 3.2.2.

v IBM SecureWay Directory Client Readme(client.pdf)Provides a description of the IBM SecureWay Directory Client SDK, Version3.2.2. This software development kit (SDK) provides LDAP applicationdevelopment support.

v IBM SecureWay Directory Configuration Schema(scparent.pdf)Describes the directory information tree (DIT) and the attributes that are used toconfigure the slapd32.conf file. In IBM SecureWay Directory Version 3.2, thedirectory settings are stored using the LDAP Directory Interchange Format(LDIF) format in the slapd32.conf file.

v IBM SecureWay Directory Tuning Guide(tuning.pdf)Provides performance tuning information for IBM SecureWay Directory. Tuningconsiderations for directory sizes ranging from a few thousand entries tomillions of entries are given where applicable.

For more information about IBM SecureWay Directory, see the following Web site:

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

IBM WebSphere Application ServerIBM WebSphere Application Server, Advanced Single Server Edition 4.0.2, isinstalled with the Web portal manager interface. For information about IBMWebSphere Application Server, see the following Web site:

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

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

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

Accessing publications onlinePublications in the product libraries are included in Portable Document Format(PDF) on the product CD. To access these publications using a Web browser, openthe infocenter.html file, which is located in the /doc directory on the product CD.

When IBM publishes an updated version of one or more online or hardcopypublications, they are posted to the Tivoli Information Center. The TivoliInformation Center contains the most recent version of the publications in theproduct library in PDF or HTML format, or both. Translated documents are alsoavailable for some products.

You can access the Tivoli Information Center and other sources of technicalinformation from the following Web site:

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

Information is organized by product, including release notes, installation guides,user’s guides, administrator’s guides, and developer’s references.

Note: If you print PDF documents on other than letter-sized paper, select the Fit topage check box in the Adobe Acrobat Print dialog (which is available whenyou click File → Print) to ensure that the full dimensions of a letter-sizedpage are printed on the paper that you are using.

Ordering publicationsYou can order many Tivoli publications online at the following Web site:

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

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

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

Providing feedback about publicationsWe are very interested in hearing about your experience with Tivoli products anddocumentation, and we welcome your suggestions for improvements. If you havecomments or suggestions about our products and documentation, contact us in oneof the following ways:v Send an e-mail to [email protected] Complete our customer feedback survey at the following Web site:

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

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 can alsouse the keyboard instead of the mouse to operate all features of the graphical userinterface.

Preface xv

http://www.tivoli.com/support/documents/http://www.elink.ibmlink.ibm.com/public/applications/publications/cgibin/pbi.cgihttp://www.elink.ibmlink.ibm.com/public/applications/publications/cgibin/pbi.cgihttp://www.tivoli.com/inside/store/lit_order.htmlhttp://www.tivoli.com/support/survey/

Contacting customer supportIf you have a problem with any Tivoli product, you can contact Tivoli CustomerSupport. See the Tivoli Customer Support Handbook at the following Web site:

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

The handbook provides information about how to contact Tivoli CustomerSupport, depending on the severity of your problem, and the followinginformation:v Registration and eligibilityv Telephone numbers and e-mail addresses, depending on the country in which

you are locatedv What information to gather before contacting support

Conventions used in this referenceThis reference uses several conventions for special terms and actions and operatingsystem-dependent commands and paths.

Typeface conventionsThe following typeface conventions are used in this reference:

Bold Command names and options, keywords, names of Java classesand objects, and other information that you must use literallyappear in bold.

Italic Variables, command options, and values you must provide appearin italics. Titles of publications and special words or phrases thatare emphasized also appear in italics.

Monospace Code examples, command lines, screen output, file and directorynames, and system messages appear in monospace font.

Brackets ([ ]) Information enclosed in brackets ([ ]) is optional. Anything notenclosed in brackets must be specified.

Braces ({ }) Braces ({ }) identify a set of mutually exclusive options, withexactly one option required.

Vertical Bar (|)Mutually exclusive options are separated by a vertical bar (|).

... Additional parameters of the same type can be specified here.

User registry differencesAccess Manager supports a number of different user registries. In most cases, thebehavior of Access Manager is the same regardless of what user registry is in use.However, there are several cases where the processing of a given method differsbased on what user registry is being used. A note similar to the followinghighlights 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 37 for a complete list ofknown differences.

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

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

Chapter 1. Introducing the administration API

The IBM Tivoli Access Manager (Access Manager) Java runtime componentincludes the Java language version of the Access Manager administration API. TheAccess Manager Java runtime component provides a set of Java classes andmethods for the administration of selected Access Manager administration objects.These classes and methods provide a way for applications to administer users,groups, protected objects, and access control lists.

You can use the Access Manager application developer kit (ADK) to enable yourapplication to programmatically administer Access Manager administration 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 5

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 Protected objectsv Protected object spaces

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 partof the Access Manager Java runtime environment component. Applications usingthe Java runtime environment provided with Access Manager automatically haveaccess to these classes and methods.

The administration API Java classes communicate directly with the AccessManager policy server component. The API establishes an authenticated, SecureSockets Layer (SSL) session with the Access Manager policy server process. Afterthe SSL session is established, the classes can send administration requests to thepolicy server.

The Access Manager policy server component services these requests in the samemanner that it would service any other incoming requests.

System administrators also can use the pdadmin command line interface toaccomplish Access Manager administration tasks. The Java administration classes

© Copyright IBM Corp. 2002 1

and methods map closely to these commands. Appendix D, “Administration CAPI, Java method, and command line equivalents” on page 41 describes thecommands that match Java administration API methods. Some Java methods donot 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.

Objects not supported by administration Java classesThe administration API Java classes do not support the manipulation of thefollowing administration objects in this version:v Extended ACL actionsv Configurationv Protected object policies (POP)v Web resourcesv Web resource groupsv Resource credentialsv Servers

To manipulate these objects in this version of Access Manager, use one of thefollowing methods:

pdadmin command line interface (CLI)The pdadmin command line interface is explained in the IBM Tivoli AccessManager Base Administrator’s Guide.

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 Access Manager Javaruntime component for each platform. The remainder of the administration APIcomponents are distributed in the Access Manager Application Developer Kitcomponent.

Application development kitThe Javadoc information associated with the administration Java classes andmethods as well as examples are provided as part of the Access Managerapplication developer kit (ADK) component package.

Table 1 on page 3 lists the files that are installed as part of the Access ManagerADK component. The PD.jar file, even though it is installed as part of the AccessManager Java runtime component, is listed in the table for completeness.

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

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 Access Manager Javaruntime component.

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 Access Manager Javaruntime component 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 Access Manager administration API, youmust install and configure the required software.

IBM Tivoli Access Manager software requirementsYou must install and configure an Access Manager secure domain. If you do nothave an Access Manager secure domain installed, install one before beginningapplication development. The minimum installation consists of a single systemwith the following Access Manager components installed:v Access Manager runtime environment (see Note 1 on page 4)v Access Manager Java runtime componentv Access Manager policy serverv Access Manager ADK

Chapter 1. Introducing the administration API 3

If you already have an Access Manager secure domain installed and want to add adevelopment system to the domain, the minimum Access Manager installationconsists of the following components:v Access Manager runtime environment (see Note 1 on page 4)v Access Manager Java runtime componentv Access Manager ADK

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

Notes:

1. The Access Manager runtime environment component is not needed fordeveloping or deploying an Access Manager Java application. The prerequisitechecking for the Access Manager ADK component is in error and erroneouslyrequires that the Access Manager runtime component be installed, even if youare developing only Java applications and simply need the Javadoc informationand 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 Access Manager ADK and runtimecomponents.

2. If you intend to use the 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 Access Manager Java runtime component to use the proper JRE onthe system by using the pdjrtecfg command. The Access Manager Java runtimecomponent can be configured to several different JREs on the same system, ifdesired. See the IBM Tivoli Access Manager Base Installation Guide for details.

Configuring to use the Java administration classesThe SvrSslCfg Java class must be used to configure the administration Java APIs.See the IBM Tivoli Access Manager Authorization Java Classes Developer’s Reference fordetails on the SvrSslCfg utility.

Note: Do not use the svrsslcfg command line interface to create configuration filesthat are to be used with Java applications.

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 use


authorization 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 Access Manager.

Java administration API example programThe Access Manager ADK includes the complete Java source code for an exampleprogram 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 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 Access Manageradministration API must be run on systems that are configured as part of anAccess Manager secure domain. To run an administration Java application, youmust have installed the Access Manager Java runtime component.

Note: Information on installing the Access Manager Java runtime component canbe found in the IBM Tivoli Access Manager Base Installation Guide.

Gathering problem determination informationWhen developing an administration application, you might encounter a problemwith Access Manager. To assist Tivoli support personnel in diagnosing yourproblem, gather problem determination information relating to your error.

Access Manager components can be configured to log information to one or morefiles. You can enable tracing for the policy server and the Access Manager Javaruntime component.

// 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

Enabling tracing on the policy serverTo enable tracing on the policy server, edit the /etc/routing file, located in theinstallation directory for the Access Manager policy server, and uncomment the lastline.

Shut down and restart the policy server daemon, pdmgrd.

Enabling tracing in the Java runtime componentTracing for the Access Manager Java runtime component is controlled by settingsin the JAVA_HOME/PolicyDirector/PDJLog.properties file. To enable tracing, editthe properties file and update the following line to set isLogging to true:baseGroup.PDJTraceLogger.isLogging=true

Gathering trace and message logsTrace and message log files for the Access Manager policy server are written to the/log directory in the Access Manager installation directory. To determine thenames of the files, you need to determine the process identifier, or PID, of theAccess Manager policy server process.

Determine the PID for the policy server by checking the ivmgrd.pid file:cat ivmgrd.pid

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

Trace and message log files associated with the Access Manager Java runtimecomponent are written to files in the /log directory with the following names:PDJTrace.log.*PDJFatal.log.*PDJWarning.log.*PDJError.log.*


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 9v “Establishing a security context” on page 9v “Manipulating administration objects” on page 11v “Messages” on page 14v “Handling errors” on page 15v “Shutting down the administration API” on page 15v “Character-based data considerations” on page 15

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

Administration objectsEach IBM Tivoli Access Manager (Access Manager) administration object that canbe manipulated directly from a Java application is represented by a correspondingJava class. The objects supported in this version of Access Manager are as follows:

PDAdminThis class is used to initialize and shut down the operations associatedwith using the Access Manager administration classes and methods. Themethods in this class are applicable to all administration objects.

PDContextThis class encapsulates the communication session between the Javaapplication and the Access Manager policy server. Both user ID andpassword-based and certificate-based authentication are supported by thisclass. Multiple PDContext objects can be created and used within the sameJava virtual machine (JVM).

PDUserThis class represents a user in the Access Manager policy server.

PDGroupThis class represents a group in the Access Manager policy server.

PDPolicyThis class represents the policy information that is associated with aparticular Access Manager user or, in the case of the global policy, that isassociated with all users. The PDPolicy class is used to set and retrieveaccount policy information from the user registry on a global or per-userbasis.

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 Access Manager secure domain but is not included in a separateuser 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 Access Manager.

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.

PDRgyGroupNameThis class represents the name of an Access Manager group in theunderlying user registry.

PDRgyUserNameThis class represents the name of an Access Manager user in theunderlying user registry.

PDRgyNameThis class represents the name of an Access Manager object in theunderlying user registry. This object is either an Access Manager user nameor group name.

PDExceptionThis class creates an exception to reflect that an error or other exceptionalcondition has occurred.

PDMessageThis class represents a single Access Manager message and includes themessage code, severity, and the localized message text.

PDMessagesThis class represents a list of one or more Access Manager messages.

The methods associated with these classes are thread-safe.


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

Establishing a security contextAfter initializing the administration API, you must create an SSL connectionbetween the Java application and the 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 Access Manager user ID with the appropriate administrative authority,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 10.

PDMessages messages = new PDMessages();

PDAdmin.initialize("myApplicationName", messages);

Figure 2. Initializing the administration API

Chapter 2. Using the administration API 9

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 AccessManager. Users should not use the information in the configuration file directly.

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 AccessManager. Users should not use the information in the configuration file directly.

// 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


Manipulating administration objectsEach Java class representing an administration object provides static methods tocreate, list, modify, and delete objects stored on the Access Manager policy server.Changes to administration objects on the policy server are immediately available toother 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 Access Manager objects necessary tocomplete administrative tasks. Before you create an object, you need to initializethe 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 Access Manager user, you woulduse the PDUser.createUser() static method. This is illustrated in Figure 5 onpage 12. This method results in the Access Manager user being createdimmediately on the policy server.


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 Access Manager user, you would use thePDUser 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


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 12. After obtaining theobject, you can retrieve information about the object by using the instancemethods. For example, to get the description associated with an Access Manageruser 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 12. After obtaining theobject, you can change information about the object by using the instance methods.For example, to disable the account associated with an Access Manager user from alocal 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 14 lists the appropriate method to use to list objects based on theJava class that represents an administration object.


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 Access Manager user, you woulduse the PDUser.deleteUser() static method. This is illustrated in Figure 7. Thismethod results in the Access Manager user being deleted immediately from thepolicy server.

MessagesAll constructors, static methods, and instance methods have an output parameterconsisting of a PDMessages object. In addition, exceptions generated by AccessManager 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


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 Access Manager along with an explanation of the message andthe 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 14 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 Access Manager along with an explanation of the message andthe 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 Access Manager policy server.Similarly, data from the policy server is received in UTF-8 and converted intoUnicode. Unicode and UTF-8 both allow any character in any locale to be uniquelyrepresented.

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


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 3. Administering users and groups

The administration API provides a collection of classes and methods foradministering IBM Tivoli Access Manager (Access Manager) users and groups. Thischapter describes the tasks that those classes and methods accomplish.

Information about Access Manager users and groups is stored in the user registry.You can use the administration API to both modify and access user and groupsettings in the user registry. In addition, the administration API provides classesand methods to administer password and account policy settings both on a peruser and global basis.

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 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 18v “Administering user account policies” on page 19v “Administering user password policies” on page 20v “Administering groups” on page 21v “Administering group information” on page 22

Administering usersThe administration API provides classes and methods for creating, accessing,listing, and deleting Access Manager user information within the user registry.

The name of a user is not case sensitive. Therefore user, USER, User, and UsEr allrefer to the same Access Manager user.

The PDUser.createUser method creates a user in the user registry used by theAccess 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 Access Manager and allows the user definition to be managed byAccess Manager.

Use the PDUser.deleteUser method to delete a user from Access Manager.

Table 3 on page 18 lists the user administration functions.

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 trailing


blanks 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 Access Manager user by importingan existing user from the user registry.

PDUser.deleteUser Deletes the specified user.

PDUser.listUsers Lists Access Manager users.

Administering user informationThe administration API allows you to administer the information associated withan 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 Access Manager policy server before youcan access the user registry. You can obtain the user registry information for a userobject by specifying either the Access Manager user name or the user registryname.

Table 4 lists the methods available for administering user information.

Table 4. Administrating user information


PDUser constructor Instantiates a user object for the specifiedAccess 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 anAccess Manager user.

PDUser object.isSSOUser Returns a setting that indicates if the user hassingle signon capabilities.

PDUser.setDescriptionPDUser object.set Description

Sets a user description.


Table 4. Administrating user information (continued)


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


PDUser.getUserRgy Determines which type of user registry isconfigured for the Access Manager policyserver.

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

PDPolicy object.getMaxFailedLogins Gets the maximum number of failed loginsallowed for user accounts.

Chapter 3. Administering users and groups 19

Table 5. Administrating user account policies (continued)


PDPolicy object.getAccessibleDaysPDPolicy object.getAccessStartTimePDPolicy object.getAccessStopTime

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


PDPolicy constructor Instantiates a policy object for a user, orfor all users in the case of the globalpolicy.

PDPolicy object.getPwdExpDate 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.

PDPolicy object.maxPwdAgeEnforced Returns an indicator whether themaximum password age policy isenforced.


Table 6. Administrating user password policies (continued)


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.setPwdExpDatePDPolicy object.setPwdExpDate

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 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 Access Manager group.

The PDGroup.createGroup method creates a group in the user registry used bythe 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 Access Manager and allows the group definition to be managedby Access Manager.

Table 7 on page 22 lists the group administration functions.

User registry difference: Leading and trailing blanks in a group name do notmake the name unique when using an LDAP or Active


Directory 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


PDGroup.createGroup Creates the specified group.

PDGroup.importGroup Creates an Access Manager group byimporting an existing group from the userregistry.

PDGroup.deleteGroup Deletes the specified group.

PDGroup.listGroups Lists 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 Access Manager policy server before you can accessthe user registry. You can obtain the user registry information for a group object byspecifying either the Access Manager group name or the user registry group name.

Table 8 lists the group information administration functions.

Table 8. Administering group attributes


PDGroup constructor Instantiates a group object for the specifiedAccess 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 Access Manager name for thegroup.

PDGroup object.isPDGroup Returns an indicator whether the object is anAccess 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 15 on page 38 for details.


Table 8. Administering group attributes (continued)


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 16on page 38 for details.


Chapter 4. Administering protected objects and protectedobject spaces

You can use the administration API to create, modify, examine, list, and delete IBMTivoli Access Manager (Access Manager) protected objects. These protected objectsrepresent resources that must be secured to enforce your security policy. You canspecify the security policy by applying access control lists (ACLs) to the protectedobjects.

Access Manager protected objects exist within a virtual hierarchy known as aprotected object space. Access Manager provides several protected object spaces bydefault. You can use the administration API to define new regions of the protectedobject space, to define and secure resources that are specific to a third-partyapplication.

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 to secure protected objects, see the chapterabout using access control policies in the IBM Tivoli Access Manager BaseAdministrator’s Guide.

This chapter contains the following topics:v “Administering protected object spaces”v “Administering protected objects” on page 26v “Administering protected object attributes” on page 27

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 Access Managerauthorization services to enforce a security policy.

User-defined object spaces created with the administration API are dynamicbecause they can be updated while Access Manager is running.

Table 9 on page 26 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.


Table 9. Administering protected object spaces


PDProtObjectSpace.createProtObjectSpace Creates an Access Manager protected objectspace.

PDProtObjectSpace.deleteProtObjectSpace Deletes the specified Access Managerprotected object space.

PDProtObjectSpace.listProtObjectSpaces Lists the Access Manager protected objectspaces.

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.

For more information about these Access Manager security concepts, see the IBMTivoli 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


PDProtObject.attachAclPDProtObject object.attachACL

Attaches the specified access control list to thespecified protected object.

PDProtObject.createProtObject Creates an Access Manager protected object.

PDProtObject.deleteProtObject Deletes the specified Access Manager protectedobject.

PDProtObject.detachAclPDProtObject object.detachAcl

Detaches the access control list from thespecified protected object.

PDProtObject constructor Instantiates the specified protected object.

PDProtObject object.getAcl Gets the ACL of the specified protected object.

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.


Table 10. Administering protected objects (continued)


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


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 27

Chapter 5. Administering access control

You can use the administration API to create, modify, examine, list, and delete IBMTivoli Access Manager (Access Manager) access control lists (ACLs). You can alsouse the administration API to attach ACLs to Access Manager protected objectsand 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 theAccess Manager secure domain. You also can use the administration API to setACL 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. Access Manager provides anumber of default permissions.

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 30v “Administering access control list extended attributes” on page 31

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 or group entries that are included in the ACL

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.

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


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:

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 Access Manager secure domain, but is notcovered by a separate user or group entry in the access control list, isallowed the permissions specified by this ACL entry.

PDAclEntryUnAuthThe ACL entry that applies to una

Documents

Administration Java Classes Developer’s Referencepublib.boulder.ibm.com/tividd/td/ITAME/SC32-0842-00/en_US/PDF/a… · GC32-0844