Administration Java Classes Developer Reference

IBM Security Access Manager for WebVersion 8.012 December 2014

Administration Java Classes DeveloperReference

��

NoteBefore using this information and the product it supports, read the information in “Notices” on page 127.

Edition notice

Note: This edition applies to version 8.0.1.0 of IBM Security Access Manager for Web (product number5725-L52) and to all subsequent releases and modifications until otherwise indicated in new editions.

© Copyright IBM Corporation 2002, 2014.US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contractwith IBM Corp.

Contents

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

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

About this publication . . . . . . . . ixAccess to documentation and terminology . . . . ixAccessibility . . . . . . . . . . . . . . ixTechnical training. . . . . . . . . . . . . xSupport information . . . . . . . . . . . . xStatement of Good Security Practices . . . . . . x

Chapter 1. Introduction to theadministration API . . . . . . . . . . 1Administration Java classes overview . . . . . . 1Accessing the Javadoc HTML documentation . . . 2Other ways to manipulate administration objects . . 2Java administration API components . . . . . . 2Building Java applications with the administrationAPI . . . . . . . . . . . . . . . . . 2

Configuration of the Java runtime component to aparticular Java runtime environment . . . . . 2Configuration of the Java administration classes . 3Security requirements . . . . . . . . . . 3

Java administration API example program . . . . 3Deployment of a Java administration API application 3Gathering of problem determination information . . 4

Enabling tracing in the Java runtime component . 4Gathering of message logs . . . . . . . . . 4Gathering of trace logs . . . . . . . . . . 5

Chapter 2. Using the administration API 7Administration objects . . . . . . . . . . . 7Common classes . . . . . . . . . . . . . 9Establishing 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 . . . . . . . . . . . . . 16Character-based data considerations . . . . . . 16PDContext application design considerations . . . 16

Chapter 3. Administering users andgroups. . . . . . . . . . . . . . . 19Administering users . . . . . . . . . . . 19Administering user information . . . . . . . 20Administering user account policies . . . . . . 21Administering user password policies . . . . . 23

Administering groups . . . . . . . . . . . 25Administering group information . . . . . . . 25

Chapter 4. Administering protectedobjects and protected object spaces . . 27Administering protected object spaces . . . . . 27Administering protected objects . . . . . . . 28Administering extended attributes for a protectedobject . . . . . . . . . . . . . . . . 30

Chapter 5. Administering accesscontrol . . . . . . . . . . . . . . . 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 protectedobject policies . . . . . . . . . . . 37Administering protected object policy objects . . . 37

PDPop.IPAuthInfo object . . . . . . . . . 38Administering protected object policy settings . . . 39Administering protected object policy extendedattributes . . . . . . . . . . . . . . . 40

Chapter 7. Administering authorizationrules. . . . . . . . . . . . . . . . 43

Chapter 8. Administering singlesign-on resources . . . . . . . . . . 45Administering Web resources . . . . . . . . 45Administering resource groups . . . . . . . . 46Administering resource credentials . . . . . . 47

Chapter 9. Administering domains . . . 49

Chapter 10. Configuring applicationservers . . . . . . . . . . . . . . 51Configuring application servers. . . . . . . . 51Administering configuration information . . . . 52Certificate maintenance . . . . . . . . . . 52

Chapter 11. Administering servers . . . 53Getting and performing administration tasks . . . 53Notifying replica databases when the masterauthorization database is updated . . . . . . . 53

Notifying replica databases automatically . . . 54Notifying replica databases manually . . . . . 54Setting the maximum number of notificationthreads . . . . . . . . . . . . . . . 54Setting the notification wait time . . . . . . 54

© Copyright IBM Corp. 2002, 2014 iii

Administering servers and database notification . . 55

Appendix A. Deprecated Java classesand methods . . . . . . . . . . . . 57

Appendix B. Registry Direct Java API 59Design . . . . . . . . . . . . . . . . 59Security Access Manager Java API . . . . . . . 59Registry Direct Java API . . . . . . . . . . 59Published API . . . . . . . . . . . . . 60

com.tivoli.pd.rgy.RgyRegistry . . . . . . . 60com.tivoli.pd.rgy.RgyEntity . . . . . . . . 63com.tivoli.pd.rgy.RgyUser . . . . . . . . 64com.tivoli.pd.rgy.RgyGroup . . . . . . . . 66com.tivoli.pd.rgy.RgyIterator. . . . . . . . 67com.tivoli.pd.rgy.ldap.RgyAttributes . . . . . 67com.tivoli.pd.rgy.ldap.LdapRgyRegistryFactory 68com.tivoli.pd.rgy.ldap.AuthzRgyRegistryFactory 70com.tivoli.pd.rgy.util.RgyConfig . . . . . . 71com.tivoli.pd.jcfg.SvrSslCfg . . . . . . . . 71

Old and new API errors . . . . . . . . . . 71Authenticate and changePassword. . . . . . 71Administration . . . . . . . . . . . . 74

Attributes . . . . . . . . . . . . . . . 78Error and trace logging . . . . . . . . . . 89

Basic JRE example output . . . . . . . . 89Auditing . . . . . . . . . . . . . . . 89

Java logger behavior . . . . . . . . . . 89Authorization . . . . . . . . . . . . . 93

Authorization permission checks . . . . . . 93Residual effects of delegated administration onadmin results . . . . . . . . . . . . . 96

API Specifications . . . . . . . . . . . . 98Installation and configuration . . . . . . . . 98

Federated LDAP servers . . . . . . . . . 98Upgrade . . . . . . . . . . . . . . 98Installation and packaging . . . . . . . . 98Configuration . . . . . . . . . . . . 98

Configuration options . . . . . . . . . 100Example usage . . . . . . . . . . . . . 109

Creating an instance of RgyRegistry . . . . . 109Ending use of RgyRegistry . . . . . . . . 109

Groups . . . . . . . . . . . . . . . 109Creating a group . . . . . . . . . . . 109Showing group details . . . . . . . . . 110Deleting a group . . . . . . . . . . . 110Importing a native group . . . . . . . . 111Listing group members . . . . . . . . . 111Add or remove group members . . . . . . 112Modifying group attribute . . . . . . . . 112Users and per-user policy . . . . . . . . 113Showing user details . . . . . . . . . . 114Deleting a user . . . . . . . . . . . . 115Importing a native user . . . . . . . . . 115Listing a user's group memberships . . . . . 116Modifying user attributes . . . . . . . . 116Resetting the user password . . . . . . . 117Changing the user password . . . . . . . 117Authenticating the user Password . . . . . 118

Appendix C. User registry differences 119General concerns . . . . . . . . . . . . 119LDAP concerns . . . . . . . . . . . . . 119

Sun Java System Directory Server concerns . . 120Microsoft Active Directory LightweightDirectory Service (AD LDS) concerns . . . . 120Microsoft Active Directory Server concerns . . 120

Length of names . . . . . . . . . . . . 122

Appendix D. Accessibility features forIBM Security Access Manager . . . . 125

Notices . . . . . . . . . . . . . . 127

Index . . . . . . . . . . . . . . . 131

iv IBM Security Access Manager for Web Version 8.0 12 December 2014: Administration Java Classes Developer Reference

Figures

1. Creating a security context using user ID andpassword-based authentication . . . . . . 11

2. Creating a security context usingcertificate-based authentication . . . . . . 12

3. Getting a local copy of a PDUser object . . . 134. Registry Direct Java API . . . . . . . . 60

© Copyright IBM Corp. 2002, 2014 v

vi IBM Security Access Manager for Web Version 8.0 12 December 2014: Administration Java Classes Developer Reference

Tables

1. Methods used to list objects . . . . . . . 142. Administering users . . . . . . . . . 203. Administering user information . . . . . . 204. Administering user account policies . . . . 225. Administering user password policies. . . . 236. Administering groups . . . . . . . . . 257. Administering group attributes . . . . . . 268. Administering protected object spaces. . . . 289. Administering protected objects . . . . . . 28

10. Administering protected object attributes 3011. Administering access control lists . . . . . 3212. Administering access control list entries 3313. Administering access control list extended

attributes . . . . . . . . . . . . . 3414. Administering action groups . . . . . . . 3515. Administering extended actions . . . . . . 3516. Administering protected object policy objects 3717. Administering protected object policy settings 3918. Administering protected object policy

extended attributes . . . . . . . . . . 40

19. Administering authorization rules . . . . . 4320. Administering Web resources . . . . . . 4521. Administering resource groups . . . . . . 4622. Administering credentials . . . . . . . . 4723. Administering domains . . . . . . . . 4924. Configuring application servers . . . . . . 5125. Administering configuration information 5226. Certificate maintenance . . . . . . . . 5227. Administering servers and database

notification. . . . . . . . . . . . . 5528. Authentication API error information . . . . 7229. Exceptions and the error codes. . . . . . . 7530. API attribute details. . . . . . . . . . 7931. Java logger namespace . . . . . . . . . 9232. Authorization permissions for groups . . . . 9433. List of operations and permissions to be

checked . . . . . . . . . . . . . . 9734. Configuration options. . . . . . . . . 10135. Maximum lengths for names by user registry

and the optimal length across user registries . 123

© Copyright IBM Corp. 2002, 2014 vii

viii IBM Security Access Manager for Web Version 8.0 12 December 2014: Administration Java Classes Developer Reference

About this publication

IBM Security Access Manager for Web, formerly called IBM Tivoli Access Managerfor e-business, is a user authentication, authorization, and web single sign-onsolution for enforcing security policies over a wide range of web and applicationresources.

This reference contains information about how to use Security Access Manageradministration Java™ classes and methods to enable an application toprogrammatically perform Security Access Manager administration tasks. Thisdocument describes the Java implementation of the Security Access Manageradministration API.

Access to documentation and terminologyThis section provides:v Links to “Online publications.”v A link to the “IBM Terminology website.”

Online publications

IBM posts product documentation when the product is released and when thedocumentation is updated at the following locations:

IBM Security Access Manager for Web libraryThe product documentation site (http://www.ibm.com/support/knowledgecenter/SSELE6_8.0.1/com.ibm.ammob.doc_8.0.1/welcome.html)displays the welcome page and navigation for the library.

IBM Security Systems Documentation CentralIBM Security Systems Documentation Central provides an alphabetical listof all IBM Security Systems product libraries and links to the onlinedocumentation for specific versions of each product.

IBM Publications CenterThe IBM Publications Center site (http://www.ibm.com/e-business/linkweb/publications/servlet/pbi.wss) offers customized search functionsto help you find all the IBM publications you need.

IBM Terminology website

The IBM Terminology website consolidates terminology for product libraries in onelocation. You can access the Terminology website at http://www.ibm.com/software/globalization/terminology.

AccessibilityAccessibility features help users with a physical disability, such as restrictedmobility or limited vision, to use software products successfully. You can use thekeyboard instead of the mouse to operate all features of the graphical userinterface.

For additional information, see the Accessibility Appendix.

© Copyright IBM Corp. 2002, 2014 ix

http://www.ibm.com/support/knowledgecenter/SSELE6_8.0.1/com.ibm.ammob.doc_8.0.1/welcome.html

http://www.ibm.com/support/knowledgecenter/SSELE6_8.0.1/com.ibm.ammob.doc_8.0.1/welcome.html

https://www.ibm.com/developerworks/mydeveloperworks/wikis/home?lang=en#/wiki/IBM%20Security%20Systems%20Documentation%20Central/page/Welcome

http://www.ibm.com/e-business/linkweb/publications/servlet/pbi.wss

http://www.ibm.com/e-business/linkweb/publications/servlet/pbi.wss

http://www.ibm.com/software/globalization/terminology

http://www.ibm.com/software/globalization/terminology

Technical trainingFor technical training information, see the following IBM Education website athttp://www.ibm.com/services/learning.

Support informationIBM Support provides assistance with code-related problems and routine, shortduration installation or usage questions. You can directly access the IBM SoftwareSupport site at http://www.ibm.com/support .

IBM Security Access Manager for Web Troubleshooting topics provides detailsabout:v What information to collect before contacting IBM Support.v The various methods for contacting IBM Support.v How to use IBM Support Assistant.v Instructions and problem-determination resources to isolate and fix the problem

yourself.

Statement of Good Security PracticesIT system security involves protecting systems and information throughprevention, detection and response to improper access from within and outsideyour enterprise. Improper access can result in information being altered, destroyed,misappropriated or misused or can result in damage to or misuse of your systems,including for use in attacks on others. No IT system or product should beconsidered completely secure and no single product, service or security measurecan be completely effective in preventing improper use or access. IBM systems,products and services are designed to be part of a comprehensive securityapproach, which will necessarily involve additional operational procedures, andmay require other systems, products or services to be most effective. IBM DOESNOT WARRANT THAT ANY SYSTEMS, PRODUCTS OR SERVICES AREIMMUNE FROM, OR WILL MAKE YOUR ENTERPRISE IMMUNE FROM, THEMALICIOUS OR ILLEGAL CONDUCT OF ANY PARTY.

x IBM Security Access Manager for Web Version 8.0 12 December 2014: Administration Java Classes Developer Reference

http://www.ibm.com/services/learning

http://www.ibm.com/support

http://www.ibm.com/support/knowledgecenter/SSELE6_8.0.1/com.ibm.isam.doc_8.0.1/landing/trouble_landing.html

Chapter 1. Introduction to the administration API

The Security Access Manager Java runtime component includes the Java languageversion of the Security Access Manager administration API. The Security AccessManager Java runtime component provides a set of Java classes and methods forthe administration of selected Security Access Manager administration objects.These classes and methods provide a way for applications to administer users,groups, protected objects, and access control lists.

This chapter contains the following topics:v “Administration Java classes overview”v “Accessing the Javadoc HTML documentation” on page 2v “Java administration API components” on page 2v “Building Java applications with the administration API” on page 2v “Java administration API example program” on page 3v “Deployment of a Java administration API application” on page 3v “Gathering of problem determination information” on page 4

Administration Java classes overviewA set of Java classes is 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 Security Access Manager Java runtime environment component.Applications which use the Java runtime environment that is provided withSecurity Access Manager automatically have access to these classes and methods.

The 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 Authorization rulesv Domainsv Web, or single signon (SSO), resourcesv Web resource groupsv Resource credentials

The administration API Java classes communicate directly with the Security AccessManager policy server component. The API establishes an authenticated, SecureSocket Layer (SSL) session with the Security Access Manager policy server process.After the SSL session is established, the classes can send administration requests tothe policy server.

© Copyright IBM Corp. 2002, 2014 1

The Security Access Manager policy server component services these requests inthe same manner that it would service any other incoming requests.

Accessing the Javadoc HTML documentationThis section explains where to access the Javadoc HTML documentation so you canadd authorization and security services to Java application.

To add IBM Security Access Manager for Web authorization and security servicesto new or existing Java applications, use the Javadoc information provided withthe Security Access Manager Runtime for Java installation package along with thisbook.

Consult the Javadoc HTML documentation for deprecated Java APIs before youupdate existing IBM Security Access Manager for Web application.

Other ways to manipulate administration objectsYou can use the Java administration APIs to manipulate administration objects.Other than that, you also can use the Registry Direct Java API to manipulateadministration objects.

Registry Direct Java APIThe Registry Direct API directly accesses the underlying Security AccessManager registry rather than through Authorization servers or PolicyServer. The API also provides access to most of the underlying registryuser attributes and the attributes available through the traditional SecurityAccess Manager Java API. See the “Registry Direct Java API” on page 59section for details.

Java administration API components

The 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 Security Access ManagerRuntime for Java component, which can be downloaded from the appliance.

Building Java applications with the administration API

To develop Java applications that use the Security Access Manager administrationAPI, you must install and configure the required software.

Configuration of the Java runtime component to a particularJava runtime environment

Configure the IBM Security Access Manager Runtime for Java component to usethe proper JRE on the system by using the pdjrtecfg command on UNIX or thepdjrtecfg.bat command on Windows. The Security Access Manager Java runtimecomponent can be configured to several different JREs on the same system, ifrequired.

2 IBM Security Access Manager for Web Version 8.0 12 December 2014: Administration Java Classes Developer Reference

Configuration of the Java administration classes

The com.tivoli.pd.jcfg.SvrSslCfg Java class must be used to configure theadministration Java APIs. See the IBM Security Access Manager for Web:Authorization Java Classes Developer Reference for details on the SvrSslCfg utility.

Note:

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 SecurityAccess Manager and IBM® SecureWay Policy Director has been deprecated. Usethe new com.tivoli.pd.jcfg.SvrSslCfg class instead.

Security requirements

To run a Java application in the context of a Java security manager, the applicationmust have proper Java permissions to use the administration Java APIs. If theapplication is not installed as a Java extension in the JAVA_HOME/lib/ext directory,an entry must be added to the JAVA_HOME/lib/security/java.policy file.

Invoke administration Java classes and methods from a privileged block,doPrivileged(), to alleviate the need for the application 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 Security Access Manager.

Java administration API example program

The Security Access Manager Runtime for Java installation package includes thecomplete Java source code for an example program that demonstrates the use ofthe 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 Security 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

Deployment of a Java administration API applicationJava applications that have been developed using the Security Access Manageradministration API must be run on systems that are configured as part of aSecurity Access Manager secure domain.

To run an administration Java application, you must have installed the SecurityAccess Manager Java runtime component.

Chapter 1. Introduction to the administration API 3

Gathering of problem determination information

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

Enabling tracing in the Java runtime componentEnable tracing in the Java runtime component by editing the properties file settingsthat the com.tivoli.pd.jcfg.SvrSslCfg command creates.

Tracing for the Security Access Manager Java runtime component is controlled bythe properties file settings the com.tivoli.pd.jcfg.SvrSslCfg command create.1. Edit the properties file created.2. Update the line associated with the required application-server-name to set

isLogging to true:baseGroup.PDJapplication-server-nameTraceLogger.isLogging=true

Each Java application can be configured to use a different properties file, andthe properties file can have any name and be located in any directory.The PDJLog.properties file, located in the PolicyDirector subdirectory of theassociated JRE, is installed by the Security Access Manager Java runtimeenvironment component. This properties file is associated with, and can beused to enable tracing in, the pdjrtecfg command as well as thecom.tivoli.pd.jcfg.SvrSslCfg command.

Gathering of message logsMessage logs associated with applications that are configured bu using thecom.tivoli.pd.jcfg.SvrSslCfg command are, by default, which is written to a setof three files: msg__application_name1.log, msg__application_name2.log, andmsg__application_name3.log, where application_name is the name that is specifiedwith the appSvr parameter of SvrSslCfg.

Each file is 512 KB in size, and the msg__application_name1.log file alwayscontains the latest messages.

The number, size, and base name of these files can be configured by using theoptions in the configuration file.

Note: There are two underscore characters (_) following the characters msg in thedefault file names.

The PDJLog.properties file controls the message logging for Java programs thatare not configured with the com.tivoli.pd.jcfg.SvrSslCfg command. Thisproperties file specifies different file names for each class of Security AccessManager messages: FATAL, ERROR, WARNING, NOTICE, or NOTICEVERBOSE.Each class of message is written to a set of three files, with names of the followingform:msg__amj_fatalN.logmsg__amj_errorN.logmsg__amj_warningN.logmsg__amj_noticeN.logmsg__amj_noticeverboseN.log


Gathering of trace logsTrace logs associated with applications that are configured by using thecom.tivoli.pd.jcfg.SvrSslCfg command are, by default, which is written to a setof three files: trace__application_name1.log, trace__application_name2.log, andtrace__application_name3.log, where application_name is the name that is specifiedwith the appSvr parameter of SvrSslCfg.

Each file is 512 KB in size, and the trace__application_name1.log file alwayscontains the latest trace entries.

The number, size, and base name of these files can be configured by using theoptions in the configuration file.

Note: There are two underscore characters (_) following the characters trace in thedefault file names.

The PDJLog.properties file controls the trace logging for Java programs that arenot configured with the com.tivoli.pd.jcfg.SvrSslCfg command. By default, thistrace output is directed to a set of three files that are called trace__amj1.log,trace__amj2.log, and trace__amj3.log. The number, size, and base name of thesefiles can be configured by using the options in the PDJLog.properties file.

Chapter 1. Introduction to the administration API 5

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 “Establishing a security context” on page 10v “Manipulating administration objects” on page 12v “Messages” on page 15v “PDContext application design considerations” on page 16v “Handling errors” on page 16v “Character-based data considerations” on page 16

Administration objectsEach Security Access Manager administration object that can be manipulateddirectly from a Java application is represented by a corresponding Java class. Thissection describes the administration objects.

The following objects are supported in this version of Security Access Manager:

PDAuthzRuleThis class represents a Security Access Manager authorization rule.

PDContextThis class encapsulates the information needed to establish acommunication session between the Java application and the SecurityAccess Manager 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).

PDContext creation is a resource exhaustive operation. Although there is noupper limit to creating multiple PDContext objects, system resourcelimitation eventually determines how many can be successfully createdand used. Create and pool only few PDContext objects in the applicationenvironment. Reuse the small number of created PDContext objectswhenever possible within the same application.

Because each user application needs are different, pooling PDContextobjects is not mandatory. Pool PDContext objects if you have a serverapplication that makes numerous calls. If you have an application thatmakes only an occasional call, or if you have various stand-aloneapplications which make calls, pooling is not necessary.

PDDomainThis class represents a Security Access Manager policy server domain.

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

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


PDPolicyThis class represents the policy information that is associated with aparticular Security 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.

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 applies to any user who is authenticated into theSecurity 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 who was not authenticated by Security 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 which represents a set of relatedresources to 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.

PDAdmSvcPobjThis class represents the value of a Security Access Manager administrationservice protected object.

PDActionThis class represents a permission.

PDActionGroupThis class represents a collection of PDAction objects.

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

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


PDRgyNameThis class represents the name of a Security Access Manager object in theunderlying user registry. This object is either a Security Access Manageruser name or group name.

PDAppSvrSpecLocalThis class represents configuration information for a local Java applicationserver.

PDAppSvrSpecRemoteThis class represents configuration information for a remote Javaapplication server.

PDSvrInfoThis class represents a Security 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 serverconfiguration information.

PDServerThis class represents a Security Access Manager policy server, authorizationserver, or other application server.

PDSSOResourceThis class represents a single sign-on (SSO) resource.

PDSSOResourceGroupThis class represents a single sign-on (SSO) resource group.

PDSSOCred.CredIDThis class represents the credential identification information for eachmember of the list returned by the PDSSOCred.listSSOCreds method.

PDSSOCred.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 occurred.

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

PDMessagesThis class represents a list of one or more Security Access Managermessages.

The methods associated with these classes are threadsafe.

Common classesThis section describes class used for both administration and authorizationmethods.

PDAttrsThis class represents a list of Security Access Manager attributes.

Chapter 2. Using the administration API 9

PDAttrValueThis class represents the value of a Security 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.

Establishing a security contextAfter initializing the administration API, you must create an SSL connectionbetween the Java application and the Security Access Manager policy server.

This connection 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.

PDContext creation is a resource exhaustive operation. Although there is no upperlimit to creating multiple PDContext objects, system resource limitation eventuallydetermines how many can be successfully created and used. Create and pool onlya few PDContext objects in the application environment.

For more Information about Java authentication classes and methods, see the IBMSecurity Access Manager for Web: Authorization Java Classes Developer Reference.

User ID and password-based authenticationThis section describes the information you need to establish a security context withuser ID and password authentication.

To establish a security context using user ID and password-based authentication,you need the following information:

admin user IDA Security 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.When this value is not supplied as a key parameter, the PDContextconstructor uses the default locale.

domainThe Security Access Manager policy server domain to which the user isauthenticated. When this value is not supplied, the domain is obtainedfrom the configuration file URL. When the configuration file URL does notcontain domain information, the local domain associated with the JavaRuntime Environment is used.


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

The contents of the configuration file created by the Java SvrSslCfg class is notexternalized and is subject to change without notice. Users must not use theinformation in the configuration file directly.

Certificate-based authenticationThis section describes the information you need to establish a security context withcertificate-based authentication.

To 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 2 onpage 12.

// 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,domain,configFileURL);

Figure 1. Creating a security context using user ID and password-based authentication


The contents of the configuration file created by the Java SvrSslCfg class is notexternalized and is subject to change without notice. Users must not use theinformation in the configuration file directly.

Manipulating administration objectsEach Java class, which represents an administration object, provides static methodsto create, list, modify, and delete objects stored on the Security Access Managerpolicy 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. You can use the class instance methods for the followingpurposes:v To retrieve data from the local object.v To modify both the local copy of the object and the object stored on the policy

server.

Use static methods for command-line and batch-oriented applications by using theadministration API. For interactive applications, use instance methods.

Creating objectsYou can use the administration API to create Security Access Manager objectsnecessary to complete administrative tasks.

Before you create an object, you must initialize the administration API andestablish a security context.

To create an object, use the static creation method associated with theadministration object. For example, to create a Security Access Manager user, youwould use the PDUser.createUser() static method. This method results in theSecurity Access Manager user being created immediately on the policy server. Seethe following static method sample, Creating a user.

// 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 2. Creating a security context using certificate-based authentication


Creating a user

/*------------------------------------------------------------------* 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);

Obtaining a local copy of an objectTo obtain a local copy of an administration object, use the constructor for the Javaclass that represents the administration object.

For example, to get a copy of the PDUser object representing a particular SecurityAccess Manager user, you would use the PDUser constructor as shown in Figure 3.

After obtaining a local copy of the administration object, use the instance methodson the object to retrieve or set data associated with the object.

/*------------------------------------------------------------------* 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 3. Getting a local copy of a PDUser object


Reading object valuesYou can view administration object data by using the instance methods associatedwith the administration object.

To use the instance methods, first obtain a local copy of the object, as outlined in“Obtaining a local copy of an object” on page 13. After obtaining the object,retrieve information about the object by using the instance methods. For example,to get the description associated with a Security Access Manager user from a localcopy of the PDUser object:userDescription = user.getDescription();

Setting object valuesYou can change administration object data with the instance methods associatedwith the administration object. You can also change administration object data withthe static methods associated with the Java class representing the administrationobject.

Before using the instance methods, you must 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 using the instance methods.For example, to disable the account associated with a Security Access Manageruser from a local copy of the PDUser object, use:user.setAccountValid(mySecurityContext,

false, // Disable the accountmessages);

The instance method changes both local copy of the administration object as wellas 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.This section describes the method for listing objects based on their Java class.

For example, an administrator must review the list of existing users to decidewhether a new user must be created.

Table 1 lists the appropriate method to use to list objects based on the Java classthat represents an administration object.

Table 1. Methods used to list objects

Object Method to list objects

PDAcl PDAcl.listAcls

PDGroup PDGroup.listGroups

PDProtObjectPDProtObject.listProtObjectsPDProtObject.listProtObjectsByAcl

PDProtObjectSpace PDProtObjectSpace.listProtObjectSpaces


Table 1. Methods used to list objects (continued)

Object Method to list objects

PDUser PDUser.listUsers

PDDomain PDDomain.listDomains

PDAuthzRule PDAuthzRule.listAuthzRules

Deleting objectsTo delete an object, use the static deletion method associated with theadministration object.

For example, to delete a Security Access Manager user, use thePDUser.deleteUser() static method. This method deletes the Security AccessManager user from the policy server immediately. See the following sample staticmethod, Deleting a user.

Deleting a user

/*------------------------------------------------------------------* Delete a user*------------------------------------------------------------------*/

// Set up all of the user’s attributesString name = "Leah Allen";messages.clear();

PDUser.deleteUser(mySecurityContext,name,true,messages);

MessagesAll constructors, static methods, and instance methods have an output parameterconsisting of a PDMessages object. This section describes the attributes of aPDMessages object.

In addition, exceptions generated by Security Access Manager contain a PDMessagesobject.

A PDMessages object can be empty or contain one or more PDMessages objects. EachPDMessages object represents a single message and consists of the followingattributes:

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 used when the methodis invoked except in the case of read-only instance method on a localadministration object.

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 Security Access Manager for Web: Error Message Reference contains a list ofthe messages issued by Security Access Manager along with an explanation of themessage and the suggested corrective action. Messages are indexed by hexadecimaland decimal message number, as well as by message identifier.

Handling errorsAll constructors, instance methods, and static methods generate a PDExceptionexception when an error or unexpected event occurs. This exception contains aPDMessages object that contains one or more PDMessages objects.

For more information about messages and message handling, see “Messages” onpage 15.

A PDException object also might contain a wrapped exception thrown by anotherJava component. Information about this wrapped exception can be obtained usingthe methods of the PDException object.

The IBM Security Access Manager for Web: Error Message Reference contains a list ofthe messages issued by Security Access Manager along with an explanation of themessage and the suggested corrective action.

Character-based data considerationsCharacter-based data, such as user IDs and passwords, are stored and manipulatedas strings of Unicode characters by the Java classes and methods.

This character data is converted from Unicode into UTF-8 (Universal Character SetTransformation Format-8) before being sent to the Security Access Manager policyserver and stored in the user registry. Similarly, data from the user registry and thepolicy server is received in UTF-8 and converted into Unicode. Unicode and UTF-8both allow any character in any locale to be uniquely represented.

PDContext application design considerationsThis section explains some aspects of PDContext application design to consider.

Note:

For detailed information about PDContext pooling class, see the Javadoc HTMLdocumentation.


There are a few points to consider before you use the PDContext class to designapplications, such as:v How many applications use PDContext concurrently?v How many users per application use PDContext?v Will the application initiate administrative requests to the Policy Server? If yes,

is it handled by a single user or many users?

The most important concept to remember when you design an application thatuses the PDContext class is that PDContext objects must be reused wheneverpossible. Do not create a PDContext object for every operation. Doing so quicklyexhaust the sessions available on the server.

For every PDContext object created by your application, a session is created andmaintained on the Policy Server. The validity of the session is controlled by thessl-v3-timeout parameter in the pd.conf file. The default value forssl-v3-timeout in thepd.conf file is 7200 seconds (2 hours).

Each PDContext object can manage several connections. However, only oneconnection is active per context at a time. Other connections are queued up andblocked until the current connection is completed, allowing the next connection tocomplete. By default each PDContext object supports 10 connections. Theconnection support is advantageous in multithreaded applications which allowmultiple threads to easily share a PDContext. This approach is best for applicationwith few threads and only occasional requests to the policy server.

The number of PDContext objects that are created represents the number ofconcurrent requests that are handled by your application. For applications thatrequire many threads and frequent requests to the policy server, the PDContextobjects must be maintained in a pool where PDContext objects are checked out asneeded and returned when the operation completes. Depending on the number ofthreads and the number PDContext objects in the pool, the approach yields goodperformance results.

Application requirements vary considerably depending on the goal. As a result, wecan provide only general guidelines on a PDContext Pool design. Basicrequirements include:v Maintain the pool as a private class variable.v All methods that access the pool must be synchronized.v Start with a pool size of 10 PDContext objects and adjust as needed to improve

performance.v Creating PDContext objects can take a lot of time. Avoid the use of large pool

sizes.v To improve overall performance, do not create PDContext objects immediately.

Initialize the pool when the application starts, instead.


Chapter 3. Administering users and groups

The administration API provides a collection of classes and methods foradministering Security Access Manager users and groups. This section describesthe tasks that those classes and methods accomplish.

Information about Security 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.

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 23v “Administering groups” on page 25v “Administering group information” on page 25

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

The name of a user is not case-sensitive. The following user names all refer to thesame Security Access Manager user:v user

v USER

v User

v UsEr

The PDUser.createUser method creates a user in the user registry that is used bythe Security Access Manager policy server.

Note: When a user definition exists in the user registry, use thePDUser.importUser method instead.

The PDUser.importUser method imports an existing user definition from your userregistry into Security Access Manager and allows the user definition to bemanaged by Security Access Manager.

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

Table 2 on page 20 lists the user administration functions.

User registry difference: Leading and trailing blank spaces in a user name do notmake the name unique when using an LDAP or Active Directory user registry.However, leading and trailing blanks do make the user name unique when using a


Domino server as a user registry. To keep name processing consistent regardless ofwhat user registry is being used, do not define user names with leading or trailingblanks.

Table 2. Administering users

Method Description

PDUser.createUser Creates the specified user.

PDUser.importUser Creates a Security AccessManager user by importing anexisting user from your userregistry.

PDUser.deleteUser Deletes the specified user.

PDUser.listUsers Lists Security Access Managerusers.

For detailed reference information about these methods, see the Javadoc HTMLdocumentation.

Administering user informationThe administration API allows you to administer the information associated with aSecurity Access Manager user.

When a user account has been created in the user registry, you can set and getvarious information about the user. You must create a security context between thecalling application and the Security Access Manager policy server before you canaccess the user registry. You can obtain the user registry information for a userobject by specifying either the Security Access Manager user name or the userregistry name.

Table 3 lists the methods available for administering user information.

Table 3. Administering user information

Methods Description

PDUser constructor Instantiates a user object forthe specified Security AccessManager or user registryname.

PDUser object.getDescription Returns the user description.

PDUser object.getRgyName Returns the user registryname for the user.

PDUser object.getId Returns the name of theobject.

PDUser object.getFirstName Returns the first-nameattribute for the user.

PDUser object.getLastName Returns the last-nameattribute for the user.

PDUSer object.getLastLogin Returns the last login time.

PDUser object.getPolicy Returns the password andaccount policy settingsassociated with the user.


Table 3. Administering user information (continued)

Methods Description

PDUser object.getGroups Lists the groups in whichthe user is a member.

PDUser object.isAccountValid Returns the account-validindicator for the user.

PDUser object.isPDUser Returns an indicatorwhether the user is aSecurity Access Manageruser.

PDUser object.isSSOUser Returns an indicatorwhether the user has singlesign-on capabilities.

PDUser.setDescriptionPDUser object.set Description

Sets a user description.

PDUser.setAccountValidPDUser object.setAccountValid

Enables or disables a useraccount.

PDUser.setSSOUserPDUser object.setSSOUser

Enables or disables thesingle signon capabilities ofa user.

PDUser object.isPasswordValid Returns the enabledindicator for the userpassword.

PDUser.setPasswordPDUser object.setPassword

Sets a user password.

PDUser.setPasswordValidPDUser object.setPasswordValid

Enables or disables a userpassword.


Administering user account policiesYou can manage user access by setting account policies. You can specify policiesthat apply either only to a single user or for all users.

When a user account policy attribute is set to a value and enforced, the valuealways takes precedence over a value that is set for the general policy. This is trueeven if the value that is set for the general policy is more restrictive.

If an account policy attribute for a user is not enforced, then the value is set for thegeneral policy. If that value is set and enforced, then the value is applied for theuser.

Table 4 on page 22 describes the administration API methods that are used tomodify or access account policies.

Chapter 3. Administering users and groups 21

Table 4. Administering user account policies

Method Description

PDUser.getUserRgy Determines which type of userregistry is configured for theSecurity Access Manager policyserver.

PDPolicy constructor Instantiates a policy object for auser, or for all users in the case ofthe global policy.

PDPolicy object.acctDisableTimeEnforced Returns an indicator whether theaccount disable time intervalpolicy is enforced.

PDPolicy object.acctDisableTimeUnlimited Returns an indicator whether theaccount disable time intervalpolicy is unlimited.

PDPolicy object.acctExpDateEnforced Returns an indicator whether theaccount expiration date policy isenforced.

PDPolicy object.acctExpDateUnlimited Returns an indicator whether theaccount expiration date policy isunlimited.

PDPolicy object.getAcctExpDate Returns the account expirationdate for user accounts.

PDPolicy object.getAcctDisableTimeInterval Returns the amount of time todisable a user account when themaximum number of loginfailures is exceeded.

PDPolicy object.PDPolicy.getMaxConcurrentWebSessions Returns the maximum concurrentweb sessions that are allowed.

PDPolicy object.getMaxFailedLogins Returns the maximum number offailed logins that are allowed foruser accounts.

PDPolicy object.getAccessibleDaysPDPolicy object.getAccessStartTimePDPolicy object.getAccessEndTimePDPolicy object.getAccessTimezone

Returns the time of day accesspolicy for user accounts.

PDPolicy.maxConcurrentWebSessionsDisplaced Returns an indicator whether themaximum concurrent websessions policy is displaced.

PDPolicy.maxConcurrentWebSessionsEnforced Returns an indicator whether themaximum concurrent websessions policy is enforced.

PDPolicy.maxConcurrentWebSessionsUnlimited Returns an indicator whether themaximum concurrent websessions policy is unlimited.

PDPolicy object.maxFailedLoginsEnforced Returns an indicator whether themaximum failed login policy isenforced.

PDPolicy.setAcctExpDatePDPolicy object.setAcctExpDate

Sets the account expiration datefor user accounts.


Table 4. Administering user account policies (continued)

Method Description

PDPolicy.setAcctDisableTimePDPolicy object.setAcctDisableTime

Sets the amount of time todisable a user account when themaximum number of loginfailure is exceeded.

PDPolicy.setMaxConcurrentWebSessionsPDPolicy object.PDPolicy.setMaxConcurrentWebSessions

Sets the maximum concurrentWeb sessions that are allowed.

PDPolicy.setMaxFailedLoginsPDPolicy object.setMaxFailedLogins

Sets the maximum number offailed logins allowed for useraccounts.

PDPolicy.setTodAccessPDPolicy object.setTodAccess

Sets the time of day access for theaccount for user accounts.Note: When setting a passwordpolicy, you provide a list of days,start time, and end time. Thestart time and end time apply toeach day on the list. If thespecified start time is later thanthe specified end time, then theaccess is allowed until thespecified end time is reached thenext day.

PDPolicy object.todAccessEnforced Returns an indicator whether thetime-of-day access policy isenforced.


Administering user password policiesYou can manage user access by setting password attributes. You can specifypolicies that apply either only to a single user or for all users.

When a user password policy attribute is set to a value and enforced, the valuealways takes precedence over the value that is set for the general policy. This istrue regardless of which value is more restrictive. If a password policy attribute fora user is not enforced, then the value is set for the general policy, if that value isset and enforced, is in effect for the user.

Table 5 describes the administration API methods that you can use to modify oraccess password policies.

Table 5. Administering user password policies

Method Description

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

PDPolicy object.getMaxPwdAge Returns the password expiration date.


Table 5. Administering user password policies (continued)

Method Description

PDPolicy object.getMaxPwdRepChars Returns the maximum number ofrepeated characters that are allowed inthe password.

PDPolicy object.getMinPwdAlphas Returns the minimum number ofalphabetic characters that are allowed inthe password.

PDPolicy object.getMinPwdLen Returns the minimum password length.

PDPolicy object.getMinPwdNonAlphas Returns the minimum number ofnonalphabetic characters that areallowed in a password.

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 alphabeticcharacters required 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 that are allowed in apassword.

PDPolicy.setMinPwdAlphasPDPolicy object.setMinPwdAlphas

Sets the minimum number of alphabeticcharacters that are allowed in apassword.

PDPolicy.setMinPwdLenPDPolicy object.setMinPwdLen

Sets the minimum password length.

PDPolicy.setMinPwdNonAlphasPDPolicy object.setMinPwdNonAlphas

Sets the minimum number ofnon-alphabetic characters that areallowed in a password.

PDPolicy.setPwdSpacesAllowedPDPolicy object.setPwdSpacesAllowed

Sets policy for whether spaces areallowed in a password.



Administering groupsThe administration API provides methods for creating, accessing, listing, anddeleting Security Access Manager group information from the user registry.

The name of a group is not case-sensitive. The following group names all pertainto the same Security Access Manager group:v group

v GROUP

v Group

v GrOuP

The PDGroup.createGroup method creates a group in the user registry that is usedby the Security Access Manager policy server.

Note: When a group definition exists in the user registry, use thePDGroup.importGroup method instead.

The PDGroup.importGroup method imports an existing group definition from theuser registry into Security Access Manager and allows the group definition to bemanaged by Security Access Manager.

Table 6 lists the group administration functions.

Table 6. Administering groups

Method Description

PDGroup.createGroup Creates the specified group.

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

PDGroup.deleteGroup Deletes the specified group.

PDGroup.listGroups Lists Security Access Manager groups.


Administering group informationYou can manage information that is associated with a group by using theadministration API.

When a group is created in the user registry, you can set and get different pieces ofinformation about the group. You must create a security context between thecalling application and the Security Access Manager policy server before you canaccess the user registry. You can obtain the user registry information for a groupobject by specifying either the Security Access Manager group name or the userregistry group name.

Table 7 on page 26 lists the group information administration functions.


Table 7. Administering group attributes

Method Description

PDGroup constructor Instantiates a group object for the specifiedSecurity Access Manager or user registryname.

PDGroup object.getDescription Returns the group description.

PDGroup object.getRgyName Returns the user registry name for the group.

PDGroup object.getId Returns the Security Access Manager namefor the group.

PDGroup object.isPDGroup Returns an indicator whether the object is aSecurity 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.

PDGroup.removeMembersPDGroup object.removeMembers

Removes users from a group.



Chapter 4. Administering protected objects and protectedobject spaces

You can use the administration API to create, modify, examine, list, and deleteSecurity Access Manager protected objects.

These protected objects represent resources that must be secured to enforce yoursecurity policy. You can specify the security policy by applying access control lists(ACLs), protected object policies (POPs), and authorization rules to the protectedobjects.

Security Access Manager protected objects exist within a virtual hierarchy knownas a protected object space. Security Access Manager provides several protected objectspaces by default. You can use the administration API to define new regions of theprotected object space and 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 Security Access Manager for Web: Administration Guide.

For an introduction to the use of ACLs, POPs, and authorization rules to secureprotected objects, see the chapters about using access control policies, protectedobject policies, and authorization rules in the IBM Security Access Manager for Web:Administration Guide.

This chapter contains the following topics:v “Administering protected object spaces”v “Administering protected objects” on page 28v “Administering extended attributes for a protected object” on page 30

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 resource hierarchy that isspecific to a third-party application that uses Security Access Managerauthorization services to enforce a security policy.

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

Table 8 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 Security Access Manager for Web:Administration Guide.


Table 8. Administering protected object spaces

Methods Description

PDProtObjectSpace.createProtObjectSpace Creates a Security Access Manager protected object space.

PDProtObjectSpace.deleteProtObjectSpace Deletes the specified Security Access Manager protectedobject space.

PDProtObjectSpace.listProtObjectSpaces Lists the Security Access Manager protected object 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. Theforward slash (/) character is interpreted to be part of the object hierarchy, whichallows ACLs to be attached at the various points that are indicated by the forwardslash character.

After you create a protected object, you can specify a security policy for it bydefining and attaching ACLs, POPs, authorization rules, or any combination ofthese entities.

For more information about the Security Access Manager security concepts, see theIBM Security Access Manager for Web: Administration Guide.

When you implement protected objects programmatically, use caution. 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 before youdeploy the security environment.

Table 9 lists the methods available to administer protected objects.

Table 9. Administering protected objects

Methods Description

PDProtObject.attachAclPDProtObject object.attachACL

Attaches the specified access control list to the specifiedprotected object.

PDProtObject.attachPopPDProtObject object.attachPop

Attaches a POP to the specified protected object.

PDProtObject.attachAuthzRulePDProtObj object.attachAuthzRule

Attaches an authorization rule to the specified protectedobject.

PDProtObject.createProtObject Creates a Security Access Manager protected object.

PDProtObject.deleteProtObject Deletes the specified Security Access Manager protectedobject.

PDProtObject.detachAclPDProtObject object.detachAcl

Detaches the access control list from the specified protectedobject.


Table 9. Administering protected objects (continued)

Methods Description

PDProtObject.detachPopPDProtObject object.detachPop

Detaches a POP from the specified protected object.

PDProtObject.detachAuthzRulePDProtObj object.detachAuthzRule

Detaches an authorization rule from the specified protectedobject.

PDProtObject constructor Instantiates the specified protected object. If the protectedobject name specified does not exist, default values areshown. To determine that a protected object exists, usePDProtObject.exists.

PDProtObject object.getAclId Gets the name of the ACL attached to the specifiedprotected object.

PDProtObject object.getEffectiveAclId Gets the name of the ACL in effect for the specifiedprotected object.

PDProtObject object.getPopIdGets the name of the POP attached to the specifiedprotected object.

PDProtObject object.getEffectivePopIdGets the name of the POP in effect for the specifiedprotected object.

PDProtObj object.getAuthzRuleIdGets the name of the authorization rule object that isattached to the specified protected object.

PDProtObj object.getEffectiveAuthzRuleIdGets the name of the authorization rule object that is ineffect for the specified protected object.

PDProtObject object.getDescription Gets the description of the specified protected object.

PDProtObject object.getId Gets the name of the specified protected object.

PDProtObject object.isPolicyAttachable Indicates whether a protected object policy or access controllist can be attached to the specified protected object.

PDProtObject object.exists Indicates whether a protected object exists.

PDProtObject object.access Indicates whether a specific action to a specific object ispermitted.

PDProtObject object.multiAccess Indicates whether the specified actions to the specifiedobjects are permitted.

PDProtObject.listProtObjectsByPop Returns a list of protected objects that have the specifiedprotected object policy (POP) attached.

PDProtObject.listProtObjects Returns the protected objects contained under the specifieddirectory.

PDProtObject.listProtObjectsByAcl Returns a list of protected objects that have the specifiedaccess control list attached.

PDProtObject.setDescriptionPDProtObject object.setDescription

Sets the description field of the specified protected object.

PDProtObject.setPolicyAttachablePDProtObject object.setPolicyAttachable

Sets whether a protected object policy or access control listcan be attached to the specified protected object.

PDProtObj.listProtObjectsByAuthzRuleLists the protected objects that have the specifiedauthorization rule attached.

Chapter 4. Administering protected objects and protected object spaces 29


Administering extended attributes for a protected objectThe extended attributes for a protected object can be created, set, queried, anddeleted.

Protected objects without explicitly defined extended attributes inherit the firstfound set of extended attributes, which are defined at the parent object within theinheritance chain. The found set of extended attributes replaces the empty set ofdefined attributes. These inherited attributes are called effective extended attributes.

Table 10 describes the methods for administering extended attributes and effectiveextended attributes for a protected object.

Table 10. Administering protected object attributes

Methods 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.getEffectiveAttributeValuesDisplays a list of the values for the effectiveextended attribute that is associated with thespecified protected object.

PDProtObject.getEffectiveAttributeNamesDisplays a list of all the effective extendedattributes that are associated with the specifiedprotected object.

PDProtObject.getEffectiveAttributeObjectId Displays the name of the protected object thathas the extended attributes defined. When noextended attributes are defined, NULL isreturned.

PDProtObject object.getAttributeValues Returns the values that are associated with thespecified extended attribute for the specifiedprotected object.

PDProtObject object.getAttributeNames Lists all the extended attributes that areassociated with the specified protected object.

PDProtObject.setAttributeValuePDProtObject object.setAttributeValue

Creates an extended attribute with thespecified name and value, if it does not exist,and adds the attribute to the specifiedprotected object. If the attribute specifiedexists, the specified value is added to theexisting attribute.



Chapter 5. Administering access control

You can use the administration API to create, modify, examine, list, and deleteSecurity Access Manager access control lists (ACLs).

Use the administration API to attach ACLs to Security 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 exist in theSecurity Access Manager secure domain. You can also use the administration APIto set 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. Security Access Managerprovides a number of default permissions. You can use the administration API todefine additional extended actions. You also can use the administration API togroup the extended 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 Security Access Manager for Web: Administration 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 listsYou can allow or restrict specific users and groups from accessing protectedresources by using access control lists (ACLs).

You can do the following tasks with the administration API:v Create and delete ACLsv Retrieve or change information that is 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 that are defined in the localev The underscore (_) characterv The hyphen (-) character

You can specify the following items:


v User entries that belong in each ACLv Permissions or actions that each user is allowed to performv Permissions or actions that are based on group membership, rather than

individual 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 theivadmin_aclPDAcl object.

Be sure that you understand how to define an ACL policy before you use theadministration API ACL methods . For more information, see the section aboutACL entry syntax in the IBM Security Access Manager for Web: Administration Guide.

Table 11 describes the methods for administering ACLs.

Table 11. Administering access control lists

Methods Description

PDAcl.createAcl Creates 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 thatis already authenticated into the Security Access Manager secure domain,but is not covered by a separate user or group entry in the access controllist, is allowed the permissions that are specified by this ACL entry.


PDAclEntryUnAuthThe ACL entry that applies to unauthenticated users. Any user that is notalready authenticated is allowed the permissions that are specified by thisACL entry.

Be sure that you understand ACL entry syntax, ACL entry types, and ACLpermission (action) attributes before you use the administration API methods inthis section.

Security Access Manager supports 18 default actions. For a list of the defaultSecurity Access Manager actions, see the section about default Security AccessManager permissions for actions in the IBM Security Access Manager for Web:Administration Guide.

For more information, see the section about ACL entry syntax in the IBM SecurityAccess Manager for Web: Administration Guide.

Table 12 lists the methods for administering ACL entries.

Table 12. Administering access control list entries

Methods Description

PDAcl object.getPDAclEntryAnyOther Returns the PDAclEntryAnyOther object that is associatedwith the ACL.

PDAcl object.getPDAclEntryUnAuth Returns the PDAclEntryUnAuth object that is associated withthe ACL.

PDAcl object.getPDAclEntriesUser Returns a Java HashMap of the PDAclEntryUser objects thatare associated with the ACL.

PDAcl object.getPDAclEntriesGroup Returns a Java HashMap of the PDAclEntryGroup objects thatare associated with the ACL.

PDAcl.removePDAclEntryAnyOtherPDAcl object.removePDAclEntryAnyOther

Removes the ACL entry for the any-other user from thespecified ACL.

PDAcl.removePDAclEntryGroupPDAcl object.removePDAclEntryGroup

Removes the ACL entry for the specified group from thespecified ACL.

PDAcl.removePDAclEntryUnAuthPDAcl object.removePDAclEntryUnAuth

Removes the ACL entry for the unauthenticated user fromthe specified ACL.

PDAcl.removePDAclEntryUserPDAcl object.removePDAclEntryUser

Removes the ACL entry for the specified user from thespecified ACL.

PDAcl.setPDAclEntryAnyOtherPDAcl object.setPDAclEntryAnyOther

Sets or modifies the ACL entry for the any-other user inthe ACL.

Call this function to specify permissions for allauthenticated users who do not have a separate user orgroup entry in the specified ACL.

PDAcl.setPDAclEntryGroupPDAcl object.setPDAclEntryGroup

Sets or modifies the ACL entry for the specified group inthe specified ACL.

Chapter 5. Administering access control 33

Table 12. Administering access control list entries (continued)

Methods Description

PDAcl.setPDAclEntryUnAuthPDAcl object.setPDAclEntryUnAuth

Sets the ACL entry for the unauthenticated user in thespecified ACL.

Call this function to specify permissions for those usersthat are not already authenticated.

PDAcl.setPDAclEntryUserPDAcl object.setPDAclEntryUser

Sets the entry for the specified user in the specified ACL.Use this function to specify the actions that a user ispermitted to perform.


Administering access control list extended attributesExtended attributes for an ACL can be obtained, set, and deleted.

Table 13 lists the methods available for administering ACL extended attributes.

Table 13. Administering access control list extended attributes

Methods 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 not exist,and adds the attribute to the specified ACL. Ifthe attribute specified exists, the specifiedvalue is added to the existing values for theattribute.


Administering action groupsYou can use the administration API to create, examine, and delete new actiongroups.

Each action group can contain up to 32 actions. The default action group, referredto as the primary action group, contains the 18 predefined Security AccessManager actions, which means you can create up to 14 new actions to the primarygroup.


When you need to create more than 32 actions, you can use the administration APIto define a new action group. Security Access Manager supports up to 32 actiongroups.

For more information about action groups, see the section about creating extendedACL actions and action groups in the IBM Security Access Manager for Web:Administration Guide. Table 14 lists the methods for administering action groups.

Table 14. Administering action groups

Methods Description

PDActionGroup.createActionGroupCreates new action group with the specifiedname.

PDActionGroup.deleteActionGroupDeletes the specified action group and all theactions that belong to the specified group.

PDActionGroup.listActionGroupsLists all the defined action group names.


Administering extended actions

Security 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 SecurityAccess Manager for Web: Administration Guide.

Table 15 lists the methods for administering extended actions.

Table 15. Administering extended actions

Methods 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

Chapter 6. Administering protected object policies

Use the administration API to create, modify, examine, and delete Security AccessManager protected object policies (POPs).

You can also use the Administration API to attach or detach POPs from protectedobjects.

You can use POPs to impose more conditions on operations that are included inthe access control list (ACL) policy. These additional conditions are enforcedregardless of the user or group identities that are specified in the ACL entries.

See the following examples of the conditions: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 the warning mode, which allows an administrator to

validate security policy

You must understand the Security Access Manager POP concepts before you usethe administration API to administer POPs.

See the details in the following topics:v “Administering protected object policy objects”v “Administering protected object policy settings” on page 39v “Administering protected object policy extended attributes” on page 40

Administering protected object policy objects

POP 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 16 lists the methods for administering protected object policy objects.

Table 16. Administering protected object policy objects

Method Description

PDPop.createPop Creates a POP object with the default values.

PDPop.deletePop Deletes the specified POP.

PDPop object.getDescription Returns the description of the specified POP.

PDPop object.getId Returns the name of the specified POP.

PDProtObject.listProtObjectsByPop Finds and lists all protected objects that havethe specified POP attached.

PDPop constructorPDProtObject object.getPop

Returns the specified POP object.

PDPop.listPops Lists all POP objects.



PDPop.IPAuthInfo objectAn array of PDPop.IPAuthInfo objects is passed as input to thePDPop.setIPAuthInfo and PDPop.removeIPAuthInfo methods.

Each PDPop.IPAuthInfo object contains the following information:v The IP address that is associated with the credentials that are being checked.v The netmask that is associated with the credentials that are being checked.v The IP authentication level of the credentials for the specified IP address and

netmask that are used when accessing the protected object to which this POP isattached. All integer values except 1000 are supported for specifying a levelindex. Use the constant IPAUTH_LEVEL_FORBIDDEN_ALL_NETWORKS to deny accessfrom all networks.

The IP address and netmask can be specified in either of the following formats:

IPv4 The primary format of an IPv4 IP address is x.x.x.x, which is a 32-bitnumeric address that is written as four numbers that are separated byperiods. A value of 0.0.0.0 indicates that this setting is for any othernetwork for which this policy is not set explicitly.

IPv6

One of the primary formats of an IPv6 IP address is x:x:x:x:x:x:x:x,which is a 128-bit numeric address that is written as eight numbers thatare separated by colons. The contiguous fields that contain only the digitszero can be collapsed (for example:0009:0000:0000:0000:0000:0008:0007:0006 can be represented as9::8:7:6).

A zero network and netmask value indicates that this setting is for anyother network for which this policy is not set explicitly. See the standardRFC 2373 to determine what constitutes a valid representation of an IPv6address. Security Access Manager does not support prefix notation.

Note: When you specify the IP address or netmask, be aware of the followingrestrictions:v IPv4 clients must provide addresses in IPv4 format to IPv4 servers.v IPv4 clients can provide addresses in IPv4 or IPv6 format to IPv6 servers.

For an IPv6 address to be accepted, the server must be IPv6. You cannot providean IPv6 address to an IPv4 server.

See the IBM Security Access Manager for Web: Administration Guide for moreinformation about the IP authentication POP policy. See the Javadoc informationfor the PDPop.IPAuthInfo object and its associated methods for more 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 you specify 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

Authentication levels specify whether more or alternative authentication isrequired to access a protected object. The additional authentication is also calledstep-up authentication. This means that an additional authentication step isrequired to access resources that require more restrictive access policies. When youuse step-up authentication, you can filter users according to their IP addresses, oryou can specify step-up authentication for all users, regardless of IP address.

The quality of protection (QOP) level is not enforced internally by Security 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 Security 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.

Note: When you modify a protected object policy, you must provide a list of days,start time, and end time. The start time and end time apply to each day on the list.If the specified start time is greater than the specified end time, then the access isallowed until the specified end time of the next day.

The warning mode enables a security administrator to troubleshoot theauthorization policy set on the protected object space.

When you set the warning attribute to yes, any action is possible by any user onthe object where the POP is attached. Any object can be accessed even if the ACLpolicy 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 is made if the warning attribute is set to no.

Table 17 lists the methods for administering protected object policy settings.

Table 17. Administering protected object policy settings

Methods Description

PDPop object.getIPAuthInfoReturns the IP authentication level information from thespecified POP.

PDPop object.getAuditLevelReturns the audit level for the specified POP.

Chapter 6. Administering protected object policies 39

Table 17. Administering protected object policy settings (continued)

Methods Description

PDPop object.getQOPReturns the quality of protection (QOP) level for thespecified POP.

PDPop object.getTodAccessInfoReturns the time of day range for the specified POP.

PDPop object.getWarningModeReturns the warning mode value from the specified POP.

PDPop.removeIPAuthInfoPDPop object.removeIPAuthInfo

Removes the specified IP authentication level informationfrom the specified POP.

PDPop.setIPAuthInfoPDPop object.setIPAuthInfo

Sets the IP authentication level information for the specifiedPOP.

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 the specified POP.

PDPop.setTodAccessInfoPDPop object.setTodAccessInfo

Sets the time of day range for the specified POP.

PDPop.setWarningModePDPop object.setWarningMode

Sets the warning mode for the specified POP.


Administering protected object policy extended attributes

Table 18 lists the methods for administering protected object policy extendedattributes.

Table 18. Administering protected object policy extended attributes

Methods 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 41

Chapter 7. Administering authorization rules

Authorization rules are conditions or standards that are contained in anauthorization policy that are used to make access decisions that are based onattributes such as user, application, and environment context. Authorization rulesare defined to specify conditions that must be met before access to a protectedobject is permitted. A rule is created by using Boolean conditions that are based ondata that is supplied to the authorization engine within the user credential, fromthe resource manager application or from the encompassing business environment.

A Security Access Manager authorization rule is a policy type like an access controllist (ACL) or a protected object policy (POP). The rule is stored as a text rulewithin a rule policy object and is attached to a protected object in the same wayand with the same constraints as ACLs and POPs.

The Security Access Manager administration Java classes provide methods tocreate, delete, modify, list, and get authorization rules.

For more information about authorization rules, see the IBM Security AccessManager for Web: Administration Guide.

Use the methods shown in Table 19 to administer authorization rule objects.

Table 19. Administering authorization rules

Method Description

PDAuthzRule.createAuthzRule Creates the specified authorization rule object.

PDAuthzRule.deleteAuthzRule Deletes the specified authorization rule object.

PDAuthzRule constructorInstantiates the specified authorization rule object.

PDAuthzRule object.getId Returns the ID for the specified authorization rule.

PDAuthzRule object.getDescription Returns the description for the specified authorization rule.

PDAuthzRule object.getFailReason Returns the fail reason, if any, for the specifiedauthorization rule.

PDAuthzRule object.getRuleText Returns the rule text for the specified authorization rule.

PDAuthzRule.listAuthzRules Lists all the registered authorization rules.

PDAuthzRule.setDescriptionPDAuthzRule object.setDescription

Sets the description for the specified authorization rule.

PDAuthzRule.setRuleTextPDAuthzRule object.setRuleText

Sets the authorization rule text.

PDAuthzRule.setFailReasonPDAuthzRule object.setFailReason

Sets the authorization rule fail reason.



Chapter 8. Administering single sign-on resources

You can use the administration API to administer resources that enable a SecurityAccess Manager user to obtain single sign-on (SSO) capability across more thanone web server.

This capability requires the use of Security Access Manager WebSEAL junctions.

You can use the administration API to create, modify, examine, and delete thefollowing types of resources:v Administering web resourcesv Administering resource groupsv Administering resource credentials

Be sure that you understand Security Access Manager single sign-on supportbefore you use the administration API to administer single sign-on resources.

This chapter contains the following topics:v “Administering Web resources”v “Administering resource groups” on page 46v “Administering resource credentials” on page 47

Administering Web resources

A Web resource is a Web server that serves as the backend of a Security 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 differsfrom the authentication information used by Security Access Manager. Because ofthis difference, the junctioned Web server requires an authenticated Security AccessManager user to log in again, using the user name and password specific to theapplication on the joined Web server.

You can use the administration API to configure Security Access Manager so thatSecurity Access Manager users must 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 “Administering resourcecredentials” on page 47.

Table 20 lists the methods for administering Web resources.

Table 20. Administering Web resources

Methods Description

PDSSOResource.createSSOResource Creates a single sign-on Web resource.

PDSSOResource.deleteSSOResource Deletes the specified single sign-on Webresource.


Table 20. Administering Web resources (continued)

Methods Description

PDSSOResource constructor Instantiates the specified single sign-on Webresource.

PDSSOResource object.getDescription Returns the description of the specified singlesign-on Web resource.

PDSSOResource object.getId Returns the name (identifier) of the specifiedsingle sign-on Web resource.

PDSSOResource.listSSOResources Returns a list of all the single sign-on Webresource names.


Administering resource groupsA resource group is a group of web servers that are connected to a Security AccessManager WebSEAL server and that use the same set of user IDs 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. A singleresource credential lets you simplify the management of web resources bygrouping similar web resources into resource groups.

You can also use the administration API to add more web resources, whennecessary, to an existing resource group.

Table 21 lists the methods for administering resource groups.

Table 21. Administering resource groups

Methods Description

PDSSOResourceGroup.addSSOResourcePDSSOResourceGroup object.addSSOResource

Adds a single sign-on resource to asingle sign-on resource group.

PDSSOResourceGroup.createSSOResourceGroup Creates a single sign-on groupresource.

PDSSOResourceGroup.deleteSSOResourceGroup Deletes a single sign-on groupresource.

PDSSOResourceGroup constructor the specified single sign-on groupresource.

PDSSOResourceGroup object.getDescription Returns the description of the singlesign-on group resource.

PDSSOResourceGroup object.getId Returns the name of the singlesign-on group resource.

PDSSOResourceGroup object.getSSOResources Returns a list of the member singlesign-on resource names for thespecified single sign-on group.

PDSSOResourceGroup.listSSOResourceGroups Returns a list of all single sign-ongroup resource names.

PDSSOResourceGroup.removeSSOResourcePDSSOResourceGroup object.removeSSOResource

Removes a single sign-on resourcefrom the specified single sign-onresource group.


Depending on the LDAP server in your environment, any attempt to remove anon-existing resource from a group, might generate an error.


Administering resource credentials

A resource credential provides a user ID and password for a single sign-onuser-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 Security Access Manager entry inthe user registry.

You can use the administration API to create, modify, examine, and delete resourcecredentials.

Table 22 lists the methods for administering credentials.

Table 22. Administering credentials

Methods Description

PDSSOCred.createSSOCred Creates a single sign-on credential.

PDSSOCred.deleteSSOCred Deletes a single sign-on credential.

PDSSOCred constructor the specified single sign-on credential.

PDSSOCred object.getResourceName Returns the name of the single sign-onresource associated with this credential.

PDSSOCred object.getResourcePassword Returns the password associated with thissingle sign-on credential.

PDSSOCred object.getResourceUser Returns the name of the resource userassociated with the specified single sign-oncredential.

PDSSOCred object.getResourceType Returns the type of the single sign-on resourceassociated with the specified single sign-oncredential.

PDSSOCred object.getUser Returns the name of the Security AccessManager user associated with this singlesign-on credential.

PDSSOCred.listAndShowSSOCreds Returns the list of single sign-on credentialsfor the specified user.

PDSSOCred.listSSOCreds Returns the IDs (user, resource, and type) ofthe single sign-on credentials for the specifieduser. This information is a subset of thatreturned by the listAndShowSSOCreds method.

PDSSOCred.setSSOCredPDSSOCred object.setSSOCred

Modifies a single sign-on credential.


Chapter 8. Administering single sign-on resources 47

Chapter 9. Administering domains

A Security Access Manager domain consists of all the physical resources thatrequire protection along with the associated security policy used to protect thoseresources.

The initial domain is the management domain and is created when the PolicyServer is configured. Multiple domains can exist simultaneously within a SecurityAccess Manager environment.

Data is securely partitioned between domains. A user or process must authenticateto a specific domain to access data contained within it.

Each Security Access Manager environment contains a single management domain.A user must be authenticated to the management domain to create, delete, list, ormodify additional domains.

To specify the management domain in methods that take a domain argument, usethe PDDomain.getMgmtDomainName method.

Each Java Runtime Environment (JRE) can optionally be configured to use aspecific domain. This domain is called the local domain. To specify the localdomain in methods that take a domain argument, use thePDDomain.getLocalDomainName method. If a JRE is not configured to use a specificdomain, the local domain defaults to the management domain.

The Java classes provide methods that can be used to manage domains.

For more information about the management of domains, see the IBM SecurityAccess Manager for Web: Administration Guide. Table 23 lists the methods foradministering domains.

Table 23. Administering domains

Methods Description

PDDomain.createDomain Creates new Security Access Manager domain.

PDDomain.deleteDomain Deletes the specified Security Access Manager domain.

PDDomain constructor Instantiates the specified domain object.

PDDomain object.getDescription Gets the description for the specified Security AccessManager domain.

PDDomain object.getId Gets the name of the specified Security Access Managerdomain.

PDDomain.listDomains Lists the names of all the Security Access Manager domains,except for the management domain.

PDDomain.getLocalDomainName Gets the name of the local domain.

PDDomain.getMgmtDomainName Gets the name of the management domain.

PDDomain.setDescriptionPDDomain object.setDescription

Changes the description for the specified Security AccessManager domain.



Chapter 10. Configuring application servers

You can use the administration API to configure and unconfigure authorizationand administration servers, modify configuration parameters, administer replicas,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.

It is not intended to do all the configuration that might be required to ensure acorrectly functioning application.

This chapter contains the following topics:v “Configuring application servers”v “Administering configuration information” on page 52v “Certificate maintenance” on page 52

Configuring application servers

Use 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 24. Configuring application servers

Methods Description

PDAppSvrConfig.configureAppSvr Configures an application server by updatingthe configuration file and creating thekeystore file.

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 refresh intervalin the configuration file

PDAppSvrConfig.setAppSvrPort Changes the listening port number of theapplication in the configuration file.

PDAppSvrConfig.unconfigureAppSvr Unconfigures an application server.



Administering configuration information

Use the configuration commands to add, change, or delete replica entries in theconfiguration file as well as return other configuration information.

Table 25. Administering configuration information

Methods Description

PDAppSvrConfig.addPDServerAdds a replica entry to the configuration file.

PDAppSvrConfig.changePDServerChanges parameters of a replica entry in theconfiguration file.

PDAppSvrConfig.removePDServerRemoves 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 maintenance

Only use ivadmin_cfg_renewservercert() the replaceAppSvrCert method when thecertificate has been compromised.

Table 26. Certificate maintenance

Methods Description

PDAppSvrConfig.replaceAppSvrCertand replaces the server SSL certificate.



Chapter 11. 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 tasks”v “Notifying replica databases when the master authorization database is

updated”– “Notifying replica databases automatically” on page 54– “Notifying replica databases manually” on page 54– “Setting the maximum number of notification threads” on page 54– “Setting the notification wait time” on page 54

Getting and performing administration tasks

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

Notifying replica databases when the master authorization database isupdated

When an administrator makes security policy changes, the policy server adjusts tothe master authorization database to reflect these changes.

To ensure that these changes also are dispersed to any authorization servers withreplica databases, you can do one or more of the following:v Configure a Security Access Manager application server, such as WebSEAL, to

poll the master authorization database at regular intervals for updates. Bydefault, polling is disabled.

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

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

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 54 and “Setting the notification wait time” on page54.


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 stanza entry pair:[ivmgrd]auto-database-update-notify = yes

Restart the policy server for changes to take effect. Use the setting forenvironments where the master database is not changed frequently. To turn offautomatic notification, specify no.

Notifying replica databases manuallyWhen the master authorization database is updated, you can use thePDServer.replicateServer method to send notifications to application servers thatare configured to receive database update notifications.

You can indicate that a specific server receive update notifications, or specifyNULL, which notifies all configured authorization servers in the secure domain.

If you specify a server name, you are notified whether the server was replicatedsuccessfully or if a failure occurred. If you do not specify a server name, returncodes indicate whether the policy server started notifying authorization servers inyour secure domain.

Unless you specify the server-name option, you are not notified when anauthorization server database was replicated successfully.

Setting the maximum number of notification threads

When 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 stanza entry 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 you added the auto-database-update-notify = yes stanza entry to theivmgrd.conf file as described in “Notifying replica databases automatically,” youcan set this period.


To do so, edit the notifier-wait-time stanza entry value in the ivmgrd.conf file.For example, if you are making batch changes to the master authorizationdatabase, wait until all changes are finished before policy changes are sent todatabase replicas. As a result, you might decide to increase the default value from15 seconds to 25 seconds as shown:[ivmgrd]notifier-wait-time = 25

By editing the value for this attribute, the policy server is prevented from sendingindividual replica notifications for each of a series of database changes.

Administering servers and database notificationTable 27. Administering servers and database notification

Methods Description

PDServer constructor Instantiates a server object.

PDServer object.getAdminServices Returns the list of Administration Servicesregistered by this server.

PDServer object.getDescription Returns the description of this server.

PDServer object.getHostName Returns the host name of this server.

PDServer object.getId Returns the identifier of this server.

PDServer object.getPort Returns the port of this server.

PDServer object.getTaskList Returns a list of tasks from the server.

PDServer object.getUserId Returns the user identifier of this server.

PDServer.listServers Lists all the registered servers.

PDServer.performTask Sends a command to an authorization server.

PDServer.replicateServer Notifies authorization servers to receivedatabase updates.


Chapter 11. Administering servers 55

Appendix A. Deprecated Java classes and methods

For information about the deprecated Java classes and methods, see the JavadocHTML documentation.

Existing Java applications must be changed to use the indicated replacement classor method.


Appendix B. Registry Direct Java API

The Registry Direct API directly accesses the underlying Security Access Managerregistry rather than through Authorization servers or Policy Server.

This API also provides access to most of the underlying registry user attributes andthe attributes available through the traditional Security Access Manager Java API.

The advantages of this API are as follows:v Removes the dependency on the Policy Server, a single point of failure.v Provides more attribute access for developers.v Improves performance and scalability.

This API provides attribute read-only Global Sign On (Single Sign On resourcecredential) support. It does not create, enable, disable, or delete the users that areenabled for Global Sign On.

DesignThe Registry Direct API is a set of Java interfaces that provide the requiredadministration and authentication methods. This design supports only IBMDirectory Server and Oracle Database registry types.

The factory class generates an instance that implements the primary interface forspecific registry.

Use the provided utility class to configure the API configuration in the stand-alonemode. The Security Access Manager Java API configuration class is for both theSecurity Access Manager Java API and Registry Direct Java API. If authorization isenabled in the Registry Direct Java API, the Registry Direct API uses the existingJava API to authorize access to API methods.

Security Access Manager Java APIThis section illustrates how the API works.

The Security Access Manager Java API uses the Policy Server for user, group, andpolicy administration. The API uses the Authorization Server for authentication.

Registry Direct Java APIIf authorization is enabled, the Security Access Manager Java API requires theAuthorization Server. To reduce this dependency, run the Security Access ManagerJava API in local mode.

In local mode, the Registry Direct API authorizes decisions internally instead ofusing the Authorization server. The Authorization Server generates a credential forthe administrator user who was authorized when this API starts.

The following diagram illustrates the Registry Direct Java API.


Published APIThe API published to users consists of Java Interfaces and Factory classes togenerate instances of the primary interface.

See detailed information about each class in the Javadoc included with theproduct. The following sections describe the Java interfaces and methods of theAPI.

com.tivoli.pd.rgy.RgyRegistry

The primary interface RgyRegistry consists of the following methods:v getUser(), getNativeUser(), getGroup(), and getNativeGroup()v createUser() and createGroup()v newRgyAttributes()v deleteUser() and deleteGroup()v listUsers(), listNativeUsers(), listGroups, and listNativeGroups()v setRgyThreadLocale() and getRgyThreadLocale()v toRegistryDate() and fromRegistryDate()v condenseResourceCredential() and expandResourceCredential()v close()

getUser(), getNativeUser(), getGroup(), and getNativeGroup()

Fetch Security Access Manager and native user or group attributes. Theycreate corresponding RgyUser or RgyGroup instances to hold these attributesand allow operations on the entity.

For getNativeUser() or getNativeGroup(), the native user or group usesthe native ID (a DN for LDAP native registries), and the attributes of theuser or group are fetched.

Auditing

Java Runtime

ISAM Registry Direct Java API

New ISAM Client App

ISAM Authzn API Classes

ISAM Authzn Client

Old Java API

Authorization

ISAM AuthorizationServer

LDAPServer

LDAP Authn

LDAP Admin

Figure 4. Registry Direct Java API


If the native user or group is also a Security Access Manager entity, thecorresponding Security Access Manager attributes are also fetched.

When you import the native entity, the API uses the Security AccessManager domain that is passed through the getNativeUser() orgetNativeGroup()

An RgyUser or RgyGroup instance does not need to be a Security AccessManager entity and might contain only the native entity attributes. You canexamine the virtual attribute isSecEntity to determine whether the entityexists. If the value of isSecEntity is true, the Security Access Managerentity exists.

Prototype:RgyUser getUser(String domain, String userId) throws RgyException;RgyUser getNativeUser(String domain, String userNativeId) throwsRgyException;RgyGroup getGroup(String domain, String groupId) throws RgyException;RgyGroup getNativeGroup(String domain, String groupNativeId) throwsRgyException;

createUser() and createGroup()

Create a Security Access Manager user or group along with the underlyingnative entity. If the underlying native entity exists, use getNativeUser() orgetNativeGroup() with the RgyUser or RgyGroup import() method.

Supply the required attributes like cn and sn.

Optionally, specify the following attributes during method creation:v Native entity attributes such as description.v Security Access Manager user attributes like secAcctValid.v Security Access Manager user policy attributes such as

passwordMinLength.

Prototype:RgyUser createUser(String domain, String userId,String userNativeId, char[] password,boolean bypassPasswordPolicy,RgyAttributes rgyAttributes,Set <string> groupIds)throws RgyException;RgyGroup createGroup(String domain, String groupId,String groupNativeId,RgyAttributes rgyAttributes)throws RgyException;

newRgyAttributes()

Creates an empty instance of RgyAttributes. This method populates andsupplies the empty instance to createUser(), createGroup(),RgyUser.import(), and RgyGroup.import() methods.

Prototype:RgyAttributes newRgyAttributes();

deleteUser() and deleteGroup()

Deletes Security Access Manager user and group, and optionally deletesthe native entity.

This API does not update the GSO data of the user. You cannot delete GSOenabled users. You can use the virtual attribute isGSOUser to confirm if anRgyUser is GSO enabled.

Appendix B. Registry Direct Java API 61

The WarningNativeEntityInUseRgyException error is generated if otherapplications create entries under the native entry. Despite this error, theAPI deletes this Security Access Managerentity. You can ignore the error ifthe method permits.

Prototype:

void deleteUser(String domain, String userId, booleandeleteNativeUser) throws RgyException;

void deleteGroup(String domain, String groupId, booleandeleteNativeGroup) throws RgyException;

listUsers(), listNativeUsers(), listGroups, and listNativeGroups()

listUsers() lists Security Access Manager users

listNativeUsers() lists the native users

listgroups() lists the Security Access Manager groups

listNativegroup() lists the native groups.

The native lists return native IDs. For LDAP, the native id is a DN. Eachnative entity, the ID refers contains an attribute that matches the suppliedattribute pattern. The non-native list methods returns Security AccessManager IDs that match the supplied pattern. All methods return anRgyIterator instance to iterate the result set.

The PageSize parameter is optional and it can be ignored by the API.

Prototype:RgyIterator listUsers(String domain, String userIdPattern,int maxResults,int pageSize)throws RgyException;RgyIterator listNativeUsers(StringsearchAttributeName, String searchAttributePattern, int maxResults,int pageSize) throws RgyException;RgyIterator listGroups(String domain, String groupIdPattern,int maxResults,int pageSize)throws RgyException;RgyIterator listNativeGroups(String searchAttributeName, StringsearchAttributePattern,int maxResults, int pageSize)throws RgyException;

setRgyThreadLocale() and getRgyThreadLocale()

Set and fetch the locale that is used when generating messages forRgyExceptions. You can set locale independently for each thread. If the setmethod is not invoked for a thread, the default locale for that thread isJava Runtime default locale. The log messages use the Java Runtimedefault locale and are not affected by setRgyThreadLocale() method.

Prototype:void setRgyThreadLocale(Locale locale);Locale getRgyThreadLocale();

toRegistryDate() and fromRegistryDate()

toRegistryDate() converts a Java date instance into a string format. Youcan supply this string format to the API for Security Access Managerattributes that require an absolute date, such as secAcctExpires.

fromRegistryDate() to interpret the date that is provided in SecurityAccess Manager attributes such as secPwdLastChanged and secPwdLastUsed.

Prototype:


String toRegistryDate(Date javaDate) throws RgyException;Date fromRegistryDate(String registryDate) throws RgyException;

condenseResourceCredential() and expandResourceCredential()

The expandResourceCredential method extracts the four component valuesfrom condensed form into an array of strings. The components are indexedas follows:public final int RESOURCE_CRED_NAME_INDEX = 0;public final int RESOURCE_CRED_TYPE_INDEX = 1;public final int RESOURCE_CRED_USER_INDEX = 2;public final int RESOURCE_CRED_PASSWORD_INDEX = 3;public final int RESOURCE_CRED_LENGTH = 4;

CondenseResourceCredential() reverses the processes.

Each value of the attribute resourceCredentials is returned from theregistry for users in condensed form.

The component value that is indexed by RESOURCE_CRED_TYPE_INDEX is oneof the following:public static final String RESOURCE_TYPE_WEB_VALUE = "Web Resource";public static final String RESOURCE_TYPE_GROUP_VALUE = "Resource Group";

close()

Releases any used resources, such as open connections to LDAP. TheRgyRegistry methods and any instances of RgyUser, RgyGroup, orRgyIterator generated by the RgyRegistry instance must not be used afterthe instance is closed.

Prototype:

void close();

com.tivoli.pd.rgy.RgyEntityRgyEntity provides methods common to RgyUser and RgyGroup interfaces.

This section explains the following methods:v getId() and getNativeId()v attributeNameIterator(), getOneAttributeValue(), and getAttributeValues()v attributeDelete(), attributeReplace(), and attributeAdd()v getDomain() and getRgyRegistry()

getId() and getNativeId()

Provide the Security Access Manager ID for the user or group withgetId() and the native registry ID with getNativeId(). This productsupports only LDAP registries. The registry native ID is an LDAPDistinguished Name. The value of Security Access Manager ID is null ifthe LDAP account does not have any associated Security Access Manageridentity.

Example :

v getId() returns a string similar to sec_master.v getNativeId() returns a string similar to

cn=SecurityMaster,secAuthority=Default.

Prototype:String getId();String getNativeId();


attributeNameIterator(), getOneAttributeValue(), and getAttributeValues()

You can obtain available attribute names using theattributeNameIterator() method.

getOneAttributeValue() is a convenience method you can use when youare sure that the attribute has only one value.

The getAttributeValues() Security Access Manager returns the attributevalues as an array of objects.

All the value objects in the array are in the same class as a string or bytearray. The cached values in the RgyEntity for the attributes are never readagain from the registry. You must fetch a new instance of the entity usingthe RgyRegistry to ensure that the attribute values are the latest.

Prototype:Iterator <String> attributeNameIterator();Object getOneAttributeValue(String name);Object[] getAttributeValues(String name);

attributeDelete(), attributeReplace(), and attributeAdd()

Modify the attributes of entities with these methods. Attribute values areeither a string or byte. If an attribute has multiple values, you can supplyall the values as objects. All objects in the array can represent the sameclass. The API updates the values of both RgyEntity and the attributesfrom the cache to the registry.

Prototype: void attributeDelete(String name) throws RgyException; voidattributeDelete(String name, Object value) throws RgyException; voidattributeDelete(String name, Object[] values) throws RgyException; voidattributeReplace(String name, Object value) throws RgyException; voidattributeReplace(String name, Object[] values) throws RgyException; voidattributeAdd(String name, Object value) throws RgyException; voidattributeAdd(String name, Object[] values) throws RgyException;

Note: The Delete, Replace, or Add method of the RgyEntity updates thecached values only for the instance on which the method is invoked.

getDomain() and getRgyRegistry()

getDomain() returns a specific domain when RgyRegistry fetches the entity.

getRgyRegistry() returns the RgyRegistry instance that instantiated theRgyEntity instance.

com.tivoli.pd.rgy.RgyUserRgyUser extends RgyEntity to provide user-specific methods.

The following section explains the methods in the RgyUser interface:v authenticate()v changePassword()v setPassword()v listGroups() and listNativeGroups()v importNativeUser()

authenticate()


Fetch the policy and account state attribute values from RgyUser to ensurethat the values used during authentication are the latest cached values inthe RgyUser instance. This method does not generate a Security AccessManager credential.

If the authentication is successful, no error is generated. Otherwise, anerror which indicates the reason for the failure is generated. Failure mightbe caused by a wrong password or any other factors, such as anunavailable account.

The Security Access Manager password validation policy is based onpolicies and account states. The Registry Direct Java API passwordvalidation process is compatible with the Security Access Managerpassword validation process.

Prototype:void authenticate(char[] password) throws RgyException;

Note: Authentication takes the time of day access restriction into account.When setting a password policy, the user might provide a list of days, starttime, and end time. The start time and end time apply to each day on thelist. If the specified start time is greater than the specified end time, thenthe access is allowed until the specified end time of the next day.

changePassword()

Authenticates the current password and, if successful, sets the password tothe new value.

If the authentication of the current password succeeds, the API sets thenew password value. If the configuration property ldap.enhanced-pwd-policy is enabled, the password is updated by using the users credential.This method supports the native LDAP policy, which requires users tochange the password after the administrator resets the password. Use thesetPassword() method to reset the administrative password.

Prototype:

void changePassword(char[] currentPassword, char[] newPassword)throws RgyException;

setPassword()

Sets the account password to the new value.

This method updates the user password by using the administrativeaccount credentials of the Registry Direct API. If a specific native LDAPpolicy is enabled for the account, this method resets the native registryaccount state.

Note: Use this method when the administrator resets the user password,or the user password is reset by using the user-self-care password recoveryprocess.

Prototype:

void setPassword(char[] newPassword) throws RgyException;

listGroups() and listNativeGroups()

listGroups() lists the groups to which the user belongs.

listNativeGroups() method returns a list of the native IDs of the groups.The list might include groups that are not Security Access Manager


enabled. The group list is not cached in the RgyUser instance, and eachinvocation of the methods searches the registry to determine themembership.

Prototype:Set <string> listGroups() throws RgyException;Set <string> listNativeGroups() throws RgyException;

importNativeUser()

Converts the LDAP native user account into a Security Access Managerentity.

Prototype:void importNativeUser(String userId, RgyAttributes rgyAttributes,String groupId) throws RgyException;

com.tivoli.pd.rgy.RgyGroupRgyGroup extends RgyEntity to provide group-specific methods.

This section describes the following methods in the RgyGroup interface:v listMemberIds() and listMemberNativeIds()v addMembers() and removeMembers()v importNativeGroup()

listMemberIds() and listMemberNativeIds()

Returns a list of members who belong to the group.

When you call these methods, they fetch the member list directly from theregistry such as LDAP. The member list is not cached in the RgyGroupinstance.

ListMemberNativeIds() returns a list of native IDs (DNs for LDAP). Thereturned membership list can include native IDs of users who are notSecurity Access Manager enabled.

Prototype:Set <string> listMemberIds() throws RgyException;Set <string> listMemberNativeIds() throws RgyException;

addMembers() and removeMembers()

Adds and removes Security Access Manager users from the groupmembership list.

This method does not provide any option to manage the membership ofdynamic or nested groups. These methods fail if the membership list isdetermined by dynamic methods or from nested group membership.

Prototype:void addMembers(List <String> memberIds) throws RgyException;void removeMembers(List <String> memberIds) throws RgyException;

importNativeGroup()

Converts the LDAP native group into a Security Access Manager entity.

Prototype:void importNativeGroup(String groupId, RgyAttributes rgyAttributes)throws RgyException;


com.tivoli.pd.rgy.RgyIteratorThis interface provides an iterator for lists of user and group IDs.

Depending on the RgyRegistry method that returns the RgyIterator instance, thegroup IDs are either Security Access Manager IDs or native IDs.

This section explains the following methods in the RgyIterator interface:v hasNext()v next()v close()

hasNext()

Returns the Boolean value true if another ID is available.

This method generates SizeLimitExceededRgyException if more results areavailable than those specified in maxResults when the RgyIterator wasconstructed, or the Registry Server is configured to allow. This exceptionoccurs on the call after returning the last available ID.

Prototype:boolean hasNext() throws RgyException;

next()

Returns the next available ID.

Prototype:String next() throws RgyException;

close()

Stops the iteration.

If RgyIterator does not throw an exception or hasNext() does not returnfalse and the caller has finished using the RgyIterator instance, callclose() immediately to release any used resource. Each open RgyIteratorinstance opens a connection to the native registry.

The Registry Direct Java API limits the number of open RgyIterator torestrict the number of simultaneous connections. When the maximum limitis reached, instantiating new RgyIterator is not possible until at least oneof the existing connections is closed.

Prototype:void close();

com.tivoli.pd.rgy.ldap.RgyAttributesRgyAttributes creates a collection of attributes for creating or importing a user orgroup.

This section explains the following methods available in the RgyAttributesinterface:v putAttribute()v addAttribute()v removeAttribute()v putAttributesInto()v getOneAttributeValue() and getAttributeValues()


v nameIterator()

putAttribute()Replaces any existing attribute value with the specified values. If thespecified attribute does not exist in the RgyAttribute instance, it is createdby using the values that are passed through this method.

addAttribute()Adds one or more values to the existing values for the specified attribute.If the specified attribute does not exist, it is created by using the valuesthat are passed through this method.

removeAttribute()Removes the specified values from the attribute that is passed through theRgyAttributes instance.

If the specified attribute is not present in the RgyAttributes instance, it isignored.

If the attribute does not have any associated values, the attribute isremoved after the attributes values are removed.

If only the attribute name is specified, this method removes the attributecompletely.

putAttributesInto()All attributes available in theRgyAttribute are added to the specifiedRgyAttribute instance. This method replaces the attributes that contain thesame name.

getOneAttributeValue() and getAttributeValues()Fetches the values of the named attribute. If the attribute named bygetOneAttributeValue() contains more than one value, any one attributevalue is returned. There is no specific pattern that is based on which themethod selects the value.

nameIterator()Returns an Iterator<String> that provides the names of all the attributescurrently stored in the RgyAttributes instance.

com.tivoli.pd.rgy.ldap.LdapRgyRegistryFactoryThis factory creates instances of the API interfaces that manipulate Security AccessManager entities in LDAP registries.

When configured correctly, the factory authorizes and audits the API methods. Thissection explains the following methods available in the LdapRgyRegistryFactoryinterface:v getRgyRegistryInstance()v getLdapRgyRegistryInstance()

getRgyRegistryInstance()

The primary method obtains RgyRegistry instance for LDAP registries.

Consider the other methods only if it requires authorization and the callerprovides PDAuthorizationContext instance this API uses for authorizationchecks. This instance is required if PDAuthorizationContext is shared forother purposes because only one PDAuthorizationContext must beinstantiated per configuration file that is created by thecom.tivoli.pd.jcfg.SvrSslCfg tool.


Prototype:public class LdapRgyRegistryFactory {public static RgyRegistry getLdapRgyRegistryInstance(Properties properties, Map enhancements) throws RgyException;}

If you use getRgyRegistryInstance() method that requires authorization,then propertiesUrl is referred in the configuration properties file. ThispropertiesUrl must include both PDAuthorizationContext andRgyRegistry configurations.

Typically, the API uses the com.tivoli.pd.jcfg.SvrSslCfg tool to createand manage this combined configuration file. The PD.jar file must beaccessible by this API and be using the class path.

If API method authorization is not required, specify the RgyRegistryconfiguration properties in the file. The PD.jar file is not required whencom.tivoli.pd.rgy.util.RgyConfig uses this method to create and managethis registry instance.

This method uses authz.enable-authorization configuration property todetermine whether PDAuthorizationContext must be used to create andauthorize the API methods.

getLdapRgyRegistryInstance()

Creates an instance of RgyRegistry that manipulates LDAP registries. Itdoes not automatically enable authorization or auditing.

If you pass the registry instance to the appropriate registry, you canperform authorization and auditing operations.

These methods are used when the caller wants to provide their ownPDAuthorizationContext instance for the RgyRegistry API to authorize itsmethods.

LdapRgyRegistryFactory.getLdapRgyRegistryInstance(URL propertiesUrl,Map enhancements) closely emulates theLdapRgyRegistry.getRgyRegistryInstance() when combined withv AuthzRgyRegistryFactory.getRgyRegistryInstance(URL propertiesUrl

v Map enhancements

v RgyRegistry wrappedRgyRegistry

v PDAuthorizationContext pdAuthzContext

v String adminUserId)

Instead of authz.enable-authorization configuration property enablingauthorization of the API, supplying a non-null PDAuthorizationContextenables it.

The Administrator user in the authorization of this API is provided as anargument rather than specifying it in the configuration properties file.

Prototype:public class LdapRgyRegistryFactory {public static RgyRegistry getLdapRgyRegistryInstance(URL propertiesUrl, Map enhancements) throws RgyException;public static RgyRegistry getRgyRegistryInstance(URL propertiesUrl, Map enhancements)throws RgyException;}


com.tivoli.pd.rgy.ldap.AuthzRgyRegistryFactoryThis factory creates instances of the RgyRegistry API interface that authorizes andaudits other RgyRegistry API instances.

This section explains the following methods in the RgyIterator interface:v getRgyRegistryInstance()v getRgyRegistryInstance()v updateAdminId()v getPdAuthzContext()


If authz.enable-authorization is enabled, this version ofgetRgyRegistryInstance() creates the required PDAuthorizationContext.

The getRgyRegistryInstance() uses authz.pdauthorizatoncontext-user asthe administrative user for authorization decisions when it grants access tomethods.

Thecom.tivoli.pd.rgy.ldap.RgyRegistryFactory.getRgyRegistryInstance()instance uses this method for authorization and auditing. ThewrappedRgyRegistry is owned by this method, and the instance isautomatically closed when appropriate. The caller or calling method mustnot use or close the instance.

Prototype:public static RgyRegistry getRgyRegistryInstance(URL propertiesUrl,Map enhancements, RgyRegistry wrappedRgyRegistry) throws RgyException;


Supplies PDAuthorizationContext context, rather than creating it. Thesemethods ignore authz.enable-authorization andauthz.pdauthorizatoncontext-user configuration settings and usePDAuthorizationContext and adminUserId. If the PDAuthorizationContextis null, it enables auditing and disables authorization.

Prototype:public static RgyRegistry getRgyRegistryInstance(Properties properties, Map enhancements, RgyRegistry wrappedRgyRegistry,PDAuthorizationContext pdAuthzContext, String adminUserId)throws RgyException;public static RgyRegistry getRgyRegistryInstance(URL propertiesUrl, Map enhancements, RgyRegistry wrappedRgyRegistry,PDAuthorizationContext pdAuthzContext, String adminUserId)throws RgyException;

updateAdminId()

Updates the administrative user ID used in authorization decisions.

If the specified rgyRegistry instance is not an instance ofAuthzRgyRegistry, the method does not perform any action. Ifauthorization is not enabled for AuthzRgyRegistry instance, this methoddoes not perform any action.

Prototype:public static void updateAdminId(RgyRegistry rgyRegistry,String adminUserId) throws ConfigurationErrorRgyException;

getPdAuthzContext()


Returns the PDAuthorizationContext used by the AuthzRgyRegistryinstance.

This method returns a null value if:v The specified rgyRegistry instance is not an instance of

AuthzRgyRegistry.v Authorization is not enabled for the AuthzRgyRegistry instance.

Prototype:public static PDAuthorizationContext getPdAuthzContext(RgyRegistry rgyRegistry);

com.tivoli.pd.rgy.util.RgyConfig

Use com.tivoli.pd.rgy.util.RgyConfig to create and maintain the configurationproperties file. You can ignore the PD.jar file or the Security Access ManagerRuntime and use this configuration properties file for Registry Direct Java API.

Do not use com.tivoli.pd.rgy.util.RgyConfig to authorize new API methods.Instructions for using this tool are available in the configuration section.

com.tivoli.pd.jcfg.SvrSslCfgThe com.tivoli.pd.jcfg.SvrSslCfg tool supports the combined configurationproperties file for PDAuthorizationContext and RgyRegistry.

This tool allows combined use of the Security Access Manager Java API andRegistry Direct Java API.

Instructions for using the enhancements to this tool are available in theconfiguration section.

Old and new API errors

The Registry Direct Java API user, group, and policy administration methodsgenerate errors that closely match the existing user and group administration APIerrors. This section lists the error codes and explains the errors generated by theAPI.

Authenticate and changePasswordFor the RgyUser.authenticate() and RgyUser.changePassword(), the RegistryDirect Java API generates errors that closely match the existingazn_util_password_authenticate and azn_util_password_change AZN API errors.

The following table maps the error codes and the API errors:


Tabl

e28

.Aut

hent

icat

ion

AP

Ier

ror

info

rmat

ion

Rgy

Exc

epti

onA

ZN

AP

IE

rror

AZ

Nst

atu

sco

de

AZ

NA

PI

Mes

sage

ServerDownRgyException

AZN_S_FAILURE,

ivacl_s_registry_server_down

ivac

l_s_

regi

stry

_ser

ver_

dow

nH

PD

AC

0779

ET

heL

DA

Pre

gist

ryse

rver

isd

own.

N/

AAZN_S_FAILURE,

ivacl_s_registry_

client_memory_error

ivac

l_s_

regi

stry

_clie

nt_m

emor

y_er

ror

HP

DA

C07

77E

LD

AP

Reg

istr

ycl

ient

retu

rned

am

emor

yer

ror.

MultipleDnFoundRgyException

InvalidParametersRgyException

AZN_S_FAILURE,

ivacl_s_registry_client_

bad_ldap_dn

ivac

l_s_

regi

stry

_clie

nt_b

ad_l

dap_

dnH

PD

AC

0772

ET

heL

DA

Pus

erre

gist

rycl

ient

retu

rned

aner

ror

stat

usfo

rth

esp

ecif

ied

DN

.

N/

AAZN_S_FAILURE,

ivacl_s_registry_client_

unavailable

ivac

l_s_

regi

stry

_clie

nt_u

nava

ilabl

eH

PD

AC

0771

ET

heus

erre

gist

rycl

ient

isun

avai

labl

e.

(nul

lre

turn

ed)

AZN_S_FAILURE,

ivauthn_invalid_username

vaut

hn_i

nval

id_u

sern

ame

HP

DIA

0202

WA

nun

know

nus

erna

me

was

prov

ided

toA

cces

sM

anag

er.

PasswordSetInvalidRgyException

AZN_S_U_PASSWORD_EXPIRED,0

ivac

l_s_

azn_

s_u_

pass

wor

d_ex

pire

dH

PD

AC

1354

Eaz

nAPI

Use

rpa

ssw

ord

expi

red

.

AccountSetInvalidRgy

Exception

AZN_S_U_ACCOUNT_DISABLED,0

ivac

l_s_

azn_

s_u_

acco

unt_

disa

bled

HP

DA

C13

64E

aznA

PIA

ccou

ntL

ogin

isd

isab

led

.

ErrPolicyTodAccessDenied

RgyException

AZN_S_U_TOD_ACCESS_DENIED,

ivauthn_tod_denied

ivau

thn_

tod_

deni

edH

PD

IA02

18W

Aut

hent

icat

ion

byus

erd

enie

dat

this

tim

eof

the

day

.

ErrPolicyAcctLockedOutRgy

Exception

AZN_S_U_ACCOUNT_LOCKEDOUT,

0iv

acl_

s_az

n_s_

u_ac

coun

t_lo

cked

out

HP

DA

C13

66E

aznA

PIT

heus

erac

coun

tis

lock

edou

t.

ErrPolicyPwdTooShortRgyException

AZN_S_U_PASSWORD_TOO_SHORT,0

ivac

l_s_

azn_

s_u_

pass

wor

d_to

o_sh

ort

HP

DA

C13

67E

aznA

PIN

ewpa

ssw

ord

isto

osh

ort.

ErrPolicyPwdHasSpaces

RgyException

AZN_S_U_PASSWORD_HAS_SPACES,

0iv

acl_

s_az

n_s_

u_pa

ssw

ord_

has_

spac

esH

PD

AC

1368

Eaz

nAPI

New

pass

wor

dha

sill

egal

spac

es.

ErrPolicyPwdTooManyRepeated

RgyException

AZN_S_U_PASSWORD_TOO

_MANY_REPEATED,0

ivac

l_s_

azn_

s_u_

pass

wor

d_to

o_m

any_

repe

ated

HP

DA

C13

69E

aznA

PIN

ewpa

ssw

ord

has

too

man

yre

peat

edch

arac

ters

.

ErrPolicyPwdTooFewAlphaRgy

Exception


_FEW_ALPHA,0

ivac

l_s_

azn_

s_u_

pass

wor

d_to

o_fe

w_a

lpha

HP

DA

C13

70E

aznA

PIN

ewpa

ssw

ord

has

too

few

alph

abet

icch

arac

ters

.

ErrPolicyPwdTooFewNonalpha

RgyException


_FEW_NONALPHA,

0iv

acl_

s_az

n_s_

u_pa

ssw

ord_

too_

few

_no

n_al

pha

HP

DA

C13

71E

aznA

PIN

ewpa

ssw

ord

has

too

few

non-

alph

abet

icch

arac

ters

.

InsufficientAccessRgyException

AZN_S_U_INSUFFICIENT

_ACCESS,

0iv

acl_

s_az

n_s_

u_in

suffi

cien

t_ac

cess

HP

DA

C13

72E

aznA

PIC

alle

rd

oes

not

have

the

perm

issi

onto

perf

orm

requ

este

dop

erat

ion.

ErrPolicyAcctDisabledRgy

Exception

AZN_S_U_PASSWORD_ACCT_DISABLED,

0iv

acl_

s_az

n_s_

u_pa

ssw

ord_

tacc

t_di

sabl

edH

PD

AC

1374

Waz

nAPI

Thi

sac

coun

tis

dis

able

dd

ueto

too

man

yfa

iled

logi

nat

tem

pts.

ErrPolicyAcctLockedOutRgyException

AZN_S_U_AUTHEN_FAILED_ACCT_LOCKEDOUT,

0iv

acl_

s_az

n_s_

u_au

then

_fai

led_

acct

_loc

kedo

utH

PD

AC

1376

Eaz

nAPI

Use

rre

gist

ryau

then

tica

tion

faile

d;t

heus

erac

coun

tha

sbe

enlo

cked

due

toto

om

any

faile

dlo

gin

atte

mpt

s.

ErrPolicyInvalidAcctDisabled

RgyException

AZN_S_U_AUTHEN_FAILED_ACCT_DISABLED,0

ivac

l_s_

azn_

s_u_

auth

en_f

aile

d_ac

ct_d

isab

led

HP

DA

C13

77E

aznA

PIU

ser

regi

stry

auth

enti

cati

onfa

iled

;the

user

acco

unt

has

been

dis

able

dd

ueto

too

man

yfa

iled

logi

nat

tem

pts.

N/

AAZN_S_FAILURE,

rgy_s_ira_server_in_config_only_

mode

rgy_

s_ir

a_se

rver

_in_

conf

ig_

only

_mod

eH

PD

RG

0207

WT

heL

DA

Pse

rver

isan

IBM

Tivo

li®

Dir

ecto

rySe

rver

inco

nfig

urat

ion

only

mod

e.A

cces

sM

anag

erca

nnot

oper

ate

norm

ally

wit

hth

eL

DA

Pse

rver

inth

ism

ode.

NativePasswordExpiredRgy

Exception

(whe

nld

ap.e

nhan

ced-

pwd-

polic

y=tr

ue)

AZN_S_FAILURE,

ivauthn_ldap_password_expired

(whe

n[ldap]

enhanced-pwd-policy=yes)

ivau

thn_

ldap

_pas

swor

d_ex

pire

dH

PD

IA02

37W

Aut

hent

icat

ion

faile

d.T

heac

coun

tca

nnot

belo

gged

inbe

caus

eth

epa

ssw

ord

expi

red

.


Tabl

e28

.Aut

hent

icat

ion

AP

Ier

ror

info

rmat

ion

(con

tinue

d)R

gyE

xcep

tion

AZ

NA

PI

Err

orA

ZN

stat

us

cod

eA

ZN

AP

IM

essa

ge

NativePasswordNoModRgyException

(whe

nld

ap.e

nhan

ced-

pwd-

polic

y=tr

ue)

AZN_S_FAILURE,

ivauthn_ldap_password_no_mod

(whe

n[ldap]


ivau

thn_

ldap

_pas

swor

d_no

_mod

HP

DIA

0318

WT

heus

erd

oes

not

have

perm

issi

onto

mod

ify

thei

rpa

ssw

ord

.

NativePassword

TooYoungRgyException

(whe

nld

ap.e

nhan

ced-

pwd-

polic

y=tr

ue)

AZN_S_FAILURE,

ivauthn_ldap_password_

too_young

(whe

n[ldap]

enhanced-pwd-policy=

yes)

ivau

thn_

ldap

_pas

swor

d_to

o_yo

ung

HP

DIA

0320

WT

heus

erca

nnot

chan

geth

eir

pass

wor

dun

tiltime

period

elap

ses

afte

rth

epr

evio

usch

ange

.

NativePassword

InHistoryRgyException

(whe

nldap.enhanced-pwd-policy=true)

AZN_S_FAILURE,

ivauthn_ldap_password_

in_history

(whe

n[ldap]

enhanced-pwd-policy=

yes)

ivau

thn_

ldap

_pas

swor

d_in

_his

tory

HP

DIA

0322

WT

heus

eris

not

perm

itte

dto

use

the

new

pass

wor

das

itw

asus

edre

cent

ly.

NativeAccountLockedRgyException

(whe

nldap.enhanced-pwd-policy=true)

AZN_S_FAILURE,

ivauthn_ldap_account_locked

ivau

thn_

ldap

_acc

ount

_loc

ked

HP

DIA

0239

WA

uthe

ntic

atio

nfa

iled

.The

acco

unt

islo

cked

.

NativeAccountInactivated

RgyException

(whe

nld

ap.e

nhan

ced-

pwd-

polic

y=tr

ue)

AZN_S_FAILURE,

ivauthn_ldap_account_inactivated

(whe

n[ldap]


ivau

thn_

ldap

_acc

ount

_ina

ctiv

ated

HP

DIA

0241

WA

uthe

ntic

atio

nfa

iled

.The

acco

unt

isd

eact

ivat

ed.

UnhandledRgyException

and

othe

rRgyExceptions

AZN_S_AZN_S_FAILURE,

ivacl_s_registry_client_error

ivac

l_s_

regi

stry

_clie

nt_e

rror

HP

DA

C07

73E

The

LD

AP

user

regi

stry

clie

ntre

turn

edan

unex

pect

edfa

ilure

stat

us.

WarningPasswordExpiresSoonRgy

Exception

(whe

nld

ap.e

nhan

ced-

pwd-

polic

y=tr

ue)

N/

AN

/A

N/

A


AdministrationThe Registry Direct Java API user, group, and policy administration methodsgenerate errors that closely match the existing user and group administration APIerrors.

The following table maps this relationship:


Tabl

e29

.E

xcep

tions

and

the

erro

rco

des.

Rgy

Exc

epti

onE

rror

cod

eE

rror

text

Tim

eLim

itE

xcee

ded

Rgy

Exc

epti

oniv

mgr

d_s_

ira2

_tim

elim

it_e

xcee

ded

HP

DM

G07

65W

The

requ

est

mad

eto

the

LD

AP

serv

erex

ceed

edth

eti

me

limit

conf

igur

edin

the

serv

er.

Size

Lim

itE

xcee

ded

Rgy

Exc

epti

onU

nhan

dle

dR

gyE

xcep

tion

ivm

grd_

s_ir

a2_s

izel

imit

_exc

eede

dH

PD

MG

0766

WT

hese

arch

requ

est

exce

eded

the

max

imum

num

ber

ofen

trie

sth

eL

DA

Pse

rver

can

retu

rn.

Inva

lidD

nSyn

taxR

gyE

xcep

tion

ivm

grd_

s_ir

a2_i

nval

id_d

n_sy

ntax

HP

DM

G07

67E

The

Dis

ting

uish

edN

ame

(DN

)ha

san

inva

lidsy

ntax

.

Inva

lidC

red

enti

alsR

gyE

xcep

tion

ivm

grd_

s_ir

a2_i

nval

id_c

rede

ntia

lsH

PD

MG

0768

EU

nabl

eto

log

in.

Insu

ffic

ient

Acc

essR

gyE

xcep

tion

ivm

grd_

s_ir

a2_i

nsuf

ficie

nt_a

cces

sH

PD

MG

0769

ET

here

wer

ein

suff

icie

ntL

DA

Pac

cess

priv

ilege

sfo

rSe

curi

tyA

cces

sM

anag

erto

crea

tean

dd

elet

een

trie

sin

the

regi

stry

.

Obj

ectC

lass

Vio

lati

onR

gyE

xcep

tion

ivm

grd_

s_ir

a2_o

bjec

t_cl

ass_

viol

atio

nH

PD

MG

0770

ET

hese

ttin

gsd

efin

edfo

rth

een

try

are

inva

lid(o

bjec

tcl

ass

viol

atio

n).

Con

text

Not

Em

ptyR

gyE

xcep

tion

ivm

grd_

s_ir

a2_n

ot_a

llow

ed_o

n_no

nlea

fH

PD

MG

0771

ET

hese

ttin

gsca

nnot

del

ete

the

entr

yco

mpl

etel

ybe

caus

eit

has

unex

pect

edsu

bent

ries

inth

eL

DA

Pre

gist

ry.T

ypic

ally

this

happ

ens

whe

nth

ed

elet

edus

eror

grou

pis

am

embe

rof

anot

her

dom

ain.

Alr

ead

yExi

stsR

gyE

xcep

tion

ivm

grd_

s_ir

a2_a

lrea

dy_e

xist

sH

PD

MG

0772

WT

heen

try

exis

ts.

Serv

erD

ownR

gyE

xcep

tion

ivm

grd_

s_ir

a2_s

erve

r_do

wn

HP

DM

G07

73E

The

requ

est

faile

dbe

caus

eth

eL

DA

Pse

rver

isd

own.

N/

Aiv

mgr

d_s_

ira2

_filt

er_e

rror

HP

DM

G10

52E

Are

gist

rym

emor

yal

loca

tion

faile

d.

N/

Aiv

mgr

d_s_

ira2

_con

nect

_err

orH

PD

MG

0776

EA

ner

ror

conn

ecti

ngto

the

LD

AP

serv

eroc

curr

ed.

N/

Aiv

mgr

d_s_

ira2

_ref

erra

l_lim

it_e

xcee

ded

HP

DM

G07

77W

The

LD

AP

refe

rral

limit

was

exce

eded

.

N/

Aiv

mgr

d_s_

ira2

_ssl

_ini

tial

ize_

faile

dH

PD

MG

0778

ET

heSS

Lin

itia

lizat

ion

faile

dfo

rco

nnec

tion

toth

eL

DA

Pse

rver

.

N/

Aiv

mgr

d_s_

ira2

_ssl

_par

am_e

rror

HP

DM

G07

79E

SSL

para

met

erer

ror

occu

rred

whe

nco

nnec

ting

toth

eL

DA

Pse

rver

.

N/

Aiv

mgr

d_s_

ira2

_ssl

_han

dsha

ke_f

aile

dH

PD

MG

0780

ET

heSS

Lha

ndsh

ake

faile

dw

hen

conn

ecti

ngto

the

LD

AP

serv

er.

N/

Aiv

mgr

d_s_

ira2

_ssl

_get

_cip

her_

faile

dH

PD

MG

0781

ESS

Lfa

iled

toes

tabl

ish

the

requ

este

den

cryp

tion

ciph

erle

vel

whe

nco

nnec

ting

toth

eL

DA

Pse

rver

.

N/

Aiv

mgr

d_s_

ira2

_ssl

_not

_ava

ilabl

eH

PD

MG

0782

ESS

Lw

asno

tav

aila

ble

for

conn

ecti

onto

the

LD

AP

serv

er

N/

Aiv

mgr

d_s_

ira2

_ssl

_key

ring

_not

_fou

ndH

PD

MG

0783

ET

heSS

LK

eyD

atab

ase

file

was

not

foun

dfo

rco

nnec

tion

toth

eL

DA

Pse

rver

.


Tabl

e29

.E

xcep

tions

and

the

erro

rco

des.

(con

tinue

d)

Rgy

Exc

epti

onE

rror

cod

eE

rror

text

N/

Aiv

mgr

d_s_

ira2

_ssl

_pas

swor

d_no

t_sp

ecifi

edH

PD

MG

0784

ET

heSS

Lpa

ssw

ord

was

not

spec

ifie

dfo

rco

nnec

tion

toth

eL

DA

Pse

rver

.

Mul

tipl

eDnF

ound

Rgy

Exc

epti

oniv

mgr

d_s_

ira2

_mul

tipl

e_dn

_fou

ndH

PD

MG

0752

EM

ore

than

one

mat

chin

gD

isti

ngui

shed

Nam

e(D

N)

was

foun

d.

N/

Aiv

mgr

d_s_

ira2

_bad

_sec

_log

in_f

orm

atH

PD

MG

0753

EA

nin

valid

form

atof

the

auth

oriz

atio

nm

echa

nism

attr

ibut

ew

asfo

und

inth

eus

eren

try.

NoS

uchA

ttri

bute

Rgy

Exc

epti

onN

oSuc

hObj

ectR

gyE

xcep

tion

(nul

lre

turn

ed)

ivm

grd_

s_ir

a2_n

o_en

try_

foun

dH

PD

MG

0754

WT

heen

try

was

not

foun

d.I

fcr

eati

nga

user

ora

grou

p,en

sure

that

the

Dis

ting

uish

edN

ame

(DN

)sp

ecif

ied

has

the

corr

ect

synt

axan

dis

valid

.

Inva

lidO

ldPa

ssw

ord

Rgy

Exc

epti

oniv

mgr

d_s_

ira2

_inv

alid

_old

_pas

swor

dH

PD

MG

0759

WT

heus

erna

me

exis

tsin

the

regi

stry

.

IdA

lrea

dyE

xist

sRgy

Exc

epti

oniv

mgr

d_s_

ira2

_uid

_alr

eady

_exi

sts

HP

DM

G07

56W

Inco

rrec

tcu

rren

tpa

ssw

ord

.

IdA

lrea

dyE

xist

sRgy

Exc

epti

oniv

mgr

d_s_

ira2

_gid

_alr

eady

_exi

sts

HP

DM

G07

60W

The

grou

pna

me

exis

tsin

the

regi

stry

.

N/

Aiv

mgr

d_s_

ira2

_not

_a_u

ser_

dnH

PD

MG

0761

WT

heen

try

refe

rred

toby

the

Dis

ting

uish

edN

ame

(DN

)m

ust

bea

pers

onen

try.

N/

Aiv

mgr

d_s_

ira2

_not

_a_g

roup

_dn

HP

DM

G07

62W

The

entr

yre

ferr

edto

byth

eD

isti

ngui

shed

Nam

e(D

N)

mus

tbe

agr

oup

entr

y.

N/

Aiv

mgr

d_s_

ira2

_lda

p_no

t_su

ppor

ted

HP

DM

G07

63E

LD

AP

isno

tco

nfig

ured

asa

regi

stry

ofus

ers

and

grou

ps.

Alr

ead

yIm

port

edR

gyE

xcep

tion

ivm

grd_

s_ir

a2_e

ntry

_alr

eady

_sec

user

HP

DM

G07

57W

The

Dis

ting

uish

edN

ame

(DN

)is

alre

ady

conf

igur

edas

aus

er.

Alr

ead

yIm

port

edR

gyE

xcep

tion

ivm

grd_

s_ir

a2_e

ntry

_alr

eady

_sec

grou

pH

PD

MG

0758

WT

heD

isti

ngui

shed

Nam

e(D

N)

isal

read

yco

nfig

ured

asa

grou

p.

Nat

iveI

dA

lrea

dyE

xist

sRgy

Exc

epti

oniv

mgr

d_s_

ira2

_use

r_al

read

y_ex

ists

HP

DM

G07

89W

The

user

Dis

ting

uish

edN

ame

(DN

)ca

nnot

becr

eate

dbe

caus

eit

exis

ts.

Nat

iveI

dA

lrea

dyE

xist

sRgy

Exc

epti

oniv

mgr

d_s_

ira2

_gro

up_a

lrea

dy_e

xist

sH

PD

MG

0790

WT

hegr

oup

Dis

ting

uish

edN

ame

(DN

)ca

nnot

becr

eate

dbe

caus

eit

exis

ts.

Err

Inva

lidPa

ssw

ord

Cha

rsR

gyE

xcep

tion

ivau

thn_

pass

wd_

polic

y_vi

olat

ion

HP

DIA

0300

WPa

ssw

ord

reje

cted

due

topo

licy

viol

atio

n.

Err

Polic

yPw

dTo

oSho

rtR

gyE

xcep

tion

ivau

thn_

pass

wd_

too_

shor

tH

PD

IA03

01W

Pass

wor

dre

ject

edd

ueto

min

imum

leng

thpo

licy.

Err

Polic

yPw

dTo

oFew

Alp

haR

gyE

xcep

tion

ivau

thn_

pass

wd_

too_

few

_alp

has

HP

DIA

0304

WPa

ssw

ord

reje

cted

due

toth

em

inim

umal

phab

etic

char

acte

rspo

licy.

Err

Polic

yPw

dTo

oFew

Non

alph

aRgy

Exc

epti

oniv

auth

n_pa

ssw

d_to

o_fe

w_n

onal

phas

HP

DIA

0305

WPa

ssw

ord

reje

cted

due

toth

em

inim

umno

n-al

phab

etic

char

acte

rspo

licy.

Err

Polic

yPw

dTo

oMan

yRep

eate

dR

gyE

xcep

tion

ivau

thn_

pass

wd_

too_

man

y_re

peat

edH

PD

IA03

03W

Pass

wor

dre

ject

edd

ueto

the

max

imum

repe

ated

char

acte

rspo

licy.

Err

Polic

yPw

dH

asSp

aces

Rgy

Exc

epti

oniv

auth

n_pa

ssw

d_ha

s_sp

aces

HP

DIA

0302

WPa

ssw

ord

reje

cted

due

toth

esp

aces

polic

y.


Tabl

e29

.E

xcep

tions

and

the

erro

rco

des.

(con

tinue

d)

Rgy

Exc

epti

onE

rror

cod

eE

rror

text

Nam

ingV

iola

tion

Rgy

Exc

epti

oniv

mgr

d_s_

ira2

_inv

alid

_dn_

synt

axH

PD

MG

0767

ET

heD

isti

ngui

shed

Nam

e(D

N)

has

anin

valid

synt

ax.

Pass

wor

dSe

tInv

alid

Rgy

Exc

epti

oniv

auth

n_ac

coun

t_ex

pire

diva

uthn

_pas

swor

d_ex

pire

dH

PD

IA02

04W

The

user

pass

wor

dha

sex

pire

d.

Err

Polic

yAcc

tDis

able

dR

gyE

xcep

tion

ivau

thn_

pass

wd_

acct

_dis

able

dH

PD

IA03

09W

Thi

sac

coun

tis

dis

able

d.

Can

tCha

ngeD

ynam

icG

roup

Rgy

Exc

epti

onrg

y_s_

ira_

cant

_cha

nge_

dyna

mic

_gro

upH

PD

RG

0200

ET

hesp

ecif

ied

grou

pis

ad

ynam

icgr

oup

and

cann

otbe

mod

ifie

d.

N/

Arg

y_s_

ira_

serv

er_i

n_co

nfig

_onl

y_m

ode

HP

DR

G02

07W

The

LD

AP

serv

eris

anIB

MTi

voli

Dir

ecto

rySe

rver

runn

ing

inco

nfig

urat

ion

only

mod

e.Se

curi

tyA

cces

sM

anag

erd

oes

not

oper

ate

wit

hth

eL

DA

Pse

rver

inth

ism

ode.

Unh

and

led

Rgy

Exc

epti

onan

dot

her

Rgy

Exc

epti

ons

ivm

grd_

s_ir

a2_i

nter

nal_

erro

rH

PD

MG

0764

EA

nin

tern

aler

ror

occu

rred

.


AttributesThe API provides access to the Security Access Manager user attributes and groupattributes.

The new API provides access to:v Security Access Manager user attributes, and the native user attributes.v Security Access Manager group attributes, the description, and cn attributes of

the native group.

The following table describes the API attribute details:


Tabl

e30

.AP

Iat

trib

ute

deta

ils

AP

IC

onst

ant

Nam

eE

ntr

yO

per

atio

nD

escr

ipti

on

MIN_

PASS

WORD

_LEN

GTH

_NAM

Epa

ssw

ordM

inLe

ngth

Secu

rity

Acc

ess

Man

ager

Use

rPo

licy

vR

ead

vA

dd

vD

elet

e

vR

epla

ce

vC

reat

e

vIm

port

Min

imum

leng

thof

apa

ssw

ord

.Mul

tiby

tech

arac

ters

are

trea

ted

asa

sing

lech

arac

ter.

The

valu

em

ust

bea

dec

imal

inte

ger.

Ifyo

ud

ono

tse

tth

isat

trib

ute,

the

API

uses

the

glob

alva

lue.

PASS

WORD

_SPA

CES

_NAM

Ese

cPw

dSpa

ces

Secu

rity

Acc

ess

Man

ager

Use

rPo

licy

vR

ead

vA

dd

vD

elet

e

vR

epla

ce

vC

reat

e

vIm

port

Spec

ifie

sw

heth

erto

perm

itsp

ace

and

tabs

inpa

ssw

ord

s.

You

have

2ch

oice

s:

vTr

uepe

rmit

ssp

ace

and

tab

char

acte

rs.

vFa

lse

doe

sno

tpe

rmit

thes

ech

arac

ters

.

Ifyo

ud

ono

tse

tth

isat

trib

ute,

the

API

uses

the

glob

alva

lue.

MAX_

PASS

WORD

_REP

EATE

D_C

HARS

_NAM

Epa

ssw

ordM

axR

epea

tedC

hars

Secu

rity

Acc

ess

Man

ager

Use

rPo

licy

vR

ead

vA

dd

vD

elet

e

vR

epla

ce

vC

reat

e

vIm

port

Spec

ifie

sth

em

axim

umnu

mbe

rof

tim

esa

char

acte

rca

nbe

repe

ated

cons

ecut

ivel

yin

apa

ssw

ord

.

The

valu

em

ust

bea

dec

imal

inte

ger.

The

valu

e-1

ind

icat

esth

atth

ere

isno

limit

onth

enu

mbe

rof

tim

esa

char

acte

rca

nbe

repe

ated

cons

ecut

ivel

y.

Ifyo

ud

ono

tse

tth

isat

trib

ute,

the

API

uses

the

glob

alva

lue.


Tabl

e30

.AP

Iat

trib

ute

deta

ils(c

ontin

ued)

AP

IC

onst

ant

Nam

eE

ntr

yO

per

atio

nD

escr

ipti

on

MIN_

PASS

WORD

_ALP

HAS

_NAM

Epa

ssw

ordM

inA

lpha

Cha

rsSe

curi

tyA

cces

sM

anag

erU

ser

Polic

yv

Rea

d

vA

dd

vD

elet

e

vR

epla

ce

vC

reat

e

vIm

port

Spec

ifie

sth

em

inim

umnu

mbe

rof

alph

abet

icch

arac

ters

for

the

pass

wor

d.

Thi

sse

tco

nsis

tsof

thes

ech

arac

ters

:

vU

PPE

RC

ASE

_LE

TT

ER

:Gen

eral

cate

gory

Luin

the

Uni

cod

esp

ecif

icat

ion.

vL

OW

ER

CA

SE_L

ET

TE

R:G

ener

alca

tego

ryLl

inth

eU

nico

de

spec

ific

atio

n.

vT

ITL

EC

ASE

_LE

TT

ER

:Gen

eral

cate

gory

Ltin

the

Uni

cod

esp

ecif

icat

ion.

vM

OD

IFIE

R_L

ET

TE

R:G

ener

alca

tego

ryLm

inth

eU

nico

de

spec

ific

atio

n.

vO

TH

ER

_LE

TT

ER

:Gen

eral

cate

gory

Loin

the

Uni

cod

esp

ecif

icat

ion.

Use

only

dec

imal

inte

ger

valu

es.I

fyo

ud

ono

tse

tth

isat

trib

ute,

the

API

uses

the

glob

alva

lue.

MIN_

PASS

WORD

_NON

_ALP

HAS

_NAM

Epa

ssw

ordM

inO

ther

Cha

rsSe

curi

tyA

cces

sM

anag

erU

ser

Polic

yv

Rea

d

vA

dd

vD

elet

e

vR

epla

ce

vC

reat

e

vIm

port

Spec

ifie

sth

em

inim

umnu

mbe

rof

non-

alph

abet

icch

arac

ters

inth

epa

ssw

ord

.

Thi

sse

tco

mpl

emen

tsM

IN_P

ASS

WO

RD

_ALP

HA

S_N

AM

E.U

seon

lyd

ecim

alin

tege

rva

lues

.If

you

do

not

set

this

attr

ibut

e,th

eA

PIus

esth

egl

obal

valu

e.

MAX_

PASS

WORD

_AGE

_NAM

Epa

ssw

ordM

axA

geSe

curi

tyA

cces

sM

anag

erU

ser

Polic

yv

Rea

d

vA

dd

vD

elet

e

vR

epla

ce

vC

reat

e

vIm

port

Spec

ifie

sth

enu

mbe

rof

seco

nds

afte

rth

ela

stpa

ssw

ord

chan

geti

me

for

whi

chth

epa

ssw

ord

isva

lid.

Ava

lue0

(zer

o)in

dic

ates

that

ther

eis

nolim

iton

the

max

imum

num

ber

ofse

cond

s.If

you

do

not

set

this

attr

ibut

e,th

eA

PIus

esth

egl

obal

valu

e.


Tabl

e30

.AP

Iat

trib

ute

deta

ils(c

ontin

ued)

AP

IC

onst

ant

Nam

eE

ntr

yO

per

atio

nD

escr

ipti

on

ACCO

UNT_

EXPI

RY_

DATE

_NAM

Ese

cAcc

tExp

ires

Secu

rity

Acc

ess

Man

ager

Use

rPo

licy

vR

ead

vA

dd

vD

elet

e

vR

epla

ce

vC

reat

e

vIm

port

Spec

ifie

sti

me

atw

hich

the

LD

AP

acco

unt

expi

res

inG

reen

wic

hM

edia

nTi

me.

The

form

atis

YY

YY

MM

DD

hhm

mss

.tZw

here

:

vY

YY

Y=

year

(for

exam

ple,

2009

)

vM

M=

mon

th(w

here

Janu

ary

=01

)

vD

D=

day

ofth

em

onth

(beg

inni

ngw

ith

01)

vhh

=ho

ur(0

0->

23)

vm

m=

min

ute

(00

->59

)

vss

=se

cond

(00

->59

)

v.=

peri

odch

arac

ter

vt

=on

ete

nth

ofth

ese

cond

(0->

9).T

his

isig

nore

dan

dsh

ould

bese

tto

0

vZ

=th

isis

the

'Z'c

hara

cter

.It

ind

icat

esth

eti

me

zone

isG

MT.

API

reco

gniz

eson

lyth

isfo

rmat

.

Asp

ecia

lva

lue

unlim

ited

isac

cept

edan

dis

conv

erte

din

toa

valu

esu

itab

lefo

rst

orag

ein

the

und

erly

ing

regi

stry

.N

ote:

Upo

nre

adin

gth

isva

lue,

itis

not

conv

erte

din

toun

limit

ed,i

nste

adit

isth

eva

lue

itw

asco

nver

ted

to.I

fyo

ud

ono

tse

tth

isat

trib

ute,

the

API

uses

the

glob

alva

lue.

DISA

BLE_

TIME

_INT

ERVA

L_NA

MEti

meE

xpir

eLoc

kout

Secu

rity

Acc

ess

Man

ager

Use

rPo

licy

vR

ead

vA

dd

vD

elet

e

vR

epla

ce

vC

reat

e

vIm

port

Spec

ifie

sth

ed

urat

ion

inse

cond

sfo

rw

hich

the

acco

unt

islo

cked

afte

rM

AX

_LO

GIN

_FA

ILU

RE

S_N

AM

Elo

gin

failu

res

have

occu

rred

.

Ava

lue

of0

(zer

o)d

isab

les

the

acco

unt.

The

valu

em

ust

bea

dec

imal

inte

ger

>=

0(z

ero)

.

Ifyo

ud

ono

tse

tth

isat

trib

ute,

the

API

uses

the

glob

alva

lue.


Tabl

e30

.AP

Iat

trib

ute

deta

ils(c

ontin

ued)

AP

IC

onst

ant

Nam

eE

ntr

yO

per

atio

nD

escr

ipti

on

MAX_

LOGI

N_F

AILU

RES_

NAME

Secu

rity

Acc

ess

Man

ager

Use

rPo

licy

vR

ead

vA

dd

vD

elet

e

vR

epla

ce

vC

reat

e

vIm

port

Spec

ifie

sth

enu

mbe

rof

logi

nfa

ilure

sth

atca

noc

cur

befo

reth

eso

ftw

are

lock

ord

isab

les

the

acco

unt.

Dis

ablin

gor

the

tim

epe

riod

for

the

lock

out

dep

end

son

DISA

BLE_

TIME

_INT

ERVA

L_NA

ME.

The

valu

em

ust

bea

dec

imal

inte

ger

>=

0(z

ero)

.Se

eth

eld

ap.l

ogin

-fai

lure

-per

sist

ent

and

ldap

.lat

e-lo

ckou

t-no

tifi

cati

onco

nfig

urat

ion

opti

ons.

Ifyo

ud

ono

tse

tth

isat

trib

ute,

the

API

uses

the

glob

alva

lue.


Tabl

e30

.AP

Iat

trib

ute

deta

ils(c

ontin

ued)

AP

IC

onst

ant

Nam

eE

ntr

yO

per

atio

nD

escr

ipti

on

TOD_

ACCE

SS_N

AME

max

Faile

dLog

ins

Secu

rity

Acc

ess

Man

ager

Use

rPo

licy

vR

ead

vA

dd

vD

elet

e

vR

epla

ce

vC

reat

e

vIm

port

Lim

its

auth

enti

cati

onto

part

icul

ard

ays

ofth

ew

eek

and

asp

ecif

icra

nge

ofti

me

dur

ing

the

day

.The

form

atof

the

polic

yis

days

:sta

rt:e

nd:z

one

whe

re:

vda

ys-

ad

ecim

alin

tege

rth

atre

pres

ents

abi

tm

ask

ofd

ays

ofth

ew

eek.

–SU

ND

AY

=1

–M

ON

DA

Y=

2

–T

UE

SDA

Y=

4

–W

ED

NE

SDA

Y=

8

–T

HU

RSD

AY

=16

–FR

IDA

Y=

32

–SA

TU

RD

AY

=64

vst

art

-th

ed

ecim

alin

tege

rth

atre

pres

ents

the

star

ting

min

ute

ofth

ed

ayof

allo

wed

acce

ss.

ven

d-

ad

ecim

alin

tege

rth

atre

pres

ents

the

end

ing

min

ute

ofth

ed

ayof

allo

wed

acce

ss.

vzo

ne-

ad

ecim

alin

tege

rth

at,w

hen

set

to1,

ind

icat

esth

atG

MT

mus

tbe

used

tod

eter

min

eth

ecu

rren

tti

me

ofd

ayan

dth

ed

ayof

the

wee

kag

ains

tw

hich

toev

alua

teth

ispo

licy.

Ifyo

use

tan

yot

her

valu

e,th

elo

cal

def

ault

tim

ezo

neis

used

.

Ifyo

ud

ono

tse

tth

isat

trib

ute,

the

API

uses

the

glob

alva

lue.

Not

e:

Whe

nyo

use

ta

pass

wor

dpo

licy,

you

prov

ide

alis

tof

day

s,st

art

tim

e,an

den

dti

me.

The

star

tti

me

and

end

tim

eap

ply

toea

chd

ayon

the

list.

Ifth

esp

ecif

ied

star

tti

me

isla

ter

than

the

spec

ifie

den

dti

me,

then

the

acce

ssis

allo

wed

unti

lth

esp

ecif

ied

end

tim

eis

reac

hed

the

next

day

.


Tabl

e30

.AP

Iat

trib

ute

deta

ils(c

ontin

ued)

AP

IC

onst

ant

Nam

eE

ntr

yO

per

atio

nD

escr

ipti

on

MAX_

CONC

URRE

NT_W

EB_S

ESSI

ONS_

NAME

secT

OD

Acc

essF

Secu

rity

Acc

ess

Man

ager

Use

rPo

licy

vR

ead

vA

dd

vD

elet

e

vR

epla

ce

vC

reat

e

vIm

port

The

max

imum

num

ber

ofco

ncur

rent

web

logi

nfo

rth

eus

er.T

his

API

doe

sno

tus

eth

isva

lue

dir

ectl

y,bu

tot

her

appl

icat

ions

use

this

valu

e.T

heva

lue

mus

tbe

ava

lidd

ecim

alin

tege

r.T

here

are

spec

ial

nega

tive

valu

es,w

hich

are:

v-3

Whe

nse

t,a

new

logi

nd

ispl

aces

(log

out)

othe

rlo

gin

sess

ions

ofth

esa

me

user

.

v-4

Whe

nse

t,th

enu

mbe

rof

conc

urre

ntlo

gins

are

not

limit

ed.

Ifyo

ud

ono

tse

tth

isat

trib

ute,

the

API

uses

the

glob

alva

lue.

SEC_

ACCT

_VAL

ID_N

AME

secA

cctV

alid

Secu

rity

Acc

ess

Man

ager

Use

rv

Rea

d

vR

epla

ce

vC

reat

e

vIm

port

Ind

icat

esth

eac

coun

tva

lidit

yst

atus

.The

perm

itte

dva

lues

are

true

and

fals

e.W

hen

set

tofa

lse,

you

cann

otlo

gin

toan

acco

unt.

SEC_

PWD_

VALI

D_NA

MEse

cPw

dVal

idSe

curi

tyA

cces

sM

anag

erU

ser

vR

ead

vR

epla

ce

vC

reat

e

vIm

port

Ind

icat

esth

epa

ssw

ord

valid

ity

sett

ing.

Thi

sat

trib

ute

can

bese

ton

lyto

true

and

fals

e.W

hen

set

tofa

lse,

the

user

mus

tch

ange

the

pass

wor

dat

next

logo

n.

SEC_

DN_N

AME

secD

NSe

curi

tyA

cces

sM

anag

erU

ser

vR

ead

Inte

rnal

use

only

.Use

getN

ativ

eId(

)in

stea

dof

SEC_

DN_N

AME.

SEC_

UUID

_NAM

Ese

cUU

IDSe

curi

tyA

cces

sM

anag

erU

ser

vR

ead

vC

reat

e

vIm

port

Spec

ifie

sth

eU

nive

rsal

lyU

niqu

eID

.

Thi

sat

trib

ute

isno

rmal

lyge

nera

ted

byth

eA

PIfo

rth

eus

er.I

tis

mos

tly

used

byth

eA

utho

riza

tion

API

whe

nve

rify

ing

AC

Ls.

You

can

supp

lyth

isva

lue

whe

nyo

ucr

eate

orim

port

aus

er.

You

cann

otm

odif

yth

isva

lue

afte

ryo

use

tit

.

Do

not

spec

ify

any

valu

efo

rth

ispa

ram

eter

exce

ptw

hen

you

reco

ver

acco

unts

that

wer

eac

cid

enta

llyd

elet

ed.

SEC_

LOGI

N_TY

PE_N

AME

secL

ogin

Type

Secu

rity

Acc

ess

Man

ager

Use

rv

Rea

dIn

tern

alus

eon

ly.

SEC_

CERT

_DN_

NAME

secC

ertD

NSe

curi

tyA

cces

sM

anag

erU

ser

vR

ead

Inte

rnal

use

only

.


Tabl

e30

.AP

Iat

trib

ute

deta

ils(c

ontin

ued)

AP

IC

onst

ant

Nam

eE

ntr

yO

per

atio

nD

escr

ipti

on

SEC_

CERT

_SER

IAL

_NUM

BER_

NAME

secC

ertS

eria

lNum

ber

Secu

rity

Acc

ess

Man

ager

Use

rv

Rea

dIn

tern

alus

eon

ly.

SEC_

HAS_

POLI

CY_N

AME

secH

asP

olic

ySe

curi

tyA

cces

sM

anag

erU

ser

vR

ead

Inte

rnal

use

only

.

SEC_

AUTH

ORIT

Y_NA

MEse

cAut

hori

tySe

curi

tyA

cces

sM

anag

erU

ser

vR

ead

Inte

rnal

use

only

.

PRIN

CIPA

L_NA

ME_N

AME

prin

cipa

lNam

eSe

curi

tyA

cces

sM

anag

erU

ser

vR

ead

Inte

rnal

use

only

.Use

getI

d()

inst

ead

ofth

isat

trib

ute.

SEC_

PWD_

FAIL

URES

_NAM

Ese

cPw

dFai

lure

sSe

curi

tyA

cces

sM

anag

erU

ser

Polic

ySt

ate

vR

ead

Inte

rnal

use

only

.

Spec

ifie

sth

enu

mbe

rof

cons

ecut

ive

auth

enti

cati

onfa

ilure

sbe

caus

eof

wro

ngpa

ssw

ord

.

Thi

spo

licy

isa

mec

hani

smto

enfo

rce

the

MAX_

LOGI

N_FA

ILUR

ES_N

AME

polic

yon

lyif

the

ldap

.logi

n-fa

ilure

s-pe

rsis

tent

opti

onis

enab

led

.

SEC_

PWD_

LAST

_CHA

NGED

_NAM

Ese

cPw

dLas

tCha

nged

Secu

rity

Acc

ess

Man

ager

Use

rPo

licy

Stat

e

vR

ead

Spec

ifie

sth

eti

me

whe

nth

epa

ssw

ord

was

last

chan

ged

.

Thi

spo

licy

isa

mec

hani

smto

enfo

rce

the

MAX_

PASS

WORD

_AGE

_NAM

Epo

licy.

The

valu

eis

upd

ated

toth

ecu

rren

td

ate

whe

nSE

C_PW

D_VA

LID_

NAME

isse

tto

true

.

SEC_

PWD_

LAST

_USE

D_N

AME

secP

wdL

astU

sed

Secu

rity

Acc

ess

Man

ager

Use

rPo

licy

Stat

e

vR

ead

Spec

ifie

sth

ela

stti

me

the

that

user

logg

edin

.

Thi

sva

lue

isup

dat

edev

ery

tim

eSe

curi

tyA

cces

sM

anag

ersu

cces

sful

lyau

then

tica

tes

aus

er.

Thi

sva

lue

isup

dat

edon

lyfo

rpa

ssw

ord

-bas

edau

then

tica

tion

.

The

opti

onld

ap.e

nabl

e-la

st-l

ogin

isse

tto

true

.

SEC_

DOMA

IN_I

D_NA

MEse

cDom

ainI

dSe

curi

tyA

cces

sM

anag

erU

ser

vR

ead

Inte

rnal

use

only

.


Tabl

e30

.AP

Iat

trib

ute

deta

ils(c

ontin

ued)

AP

IC

onst

ant

Nam

eE

ntr

yO

per

atio

nD

escr

ipti

on

SEC_

PWD_

LAST

_FAI

LED

_NAM

Ese

cPw

dLas

tFai

led

Secu

rity

Acc

ess

Man

ager

Use

rPo

licy

Stat

e

vR

ead

Inte

rnal

use

only

.

Rec

ord

sth

eti

me

ofth

ela

stfa

iled

logi

nto

auth

enti

cate

wit

hth

eco

rrec

tpa

ssw

ord

.

Thi

sva

lue

isa

part

ofth

em

echa

nism

toen

forc

eth

eDI

SABL

E_TI

ME_I

NTER

VAL_

NAME

polic

y.N

ote:

Som

eop

erat

ions

mig

htbe

rest

rict

edby

the

LD

AP.

SEC_

PWD_

UNLO

CK_T

IME

_NAM

Ese

cPw

dUnl

ockT

ime

Secu

rity

Acc

ess

Man

ager

Use

rPo

licy

Stat

e

vR

ead

Inte

rnal

use

only

.Rec

ord

sth

ed

urat

ion

for

whi

chth

eac

coun

tis

lock

ed.T

his

valu

eis

apa

rtof

the

mec

hani

smto

enfo

rce

the

DISA

BLE_

TIME

_INT

ERVA

L_NA

MEpo

licy.

COMM

ON_N

AME_

NAME

cnN

ativ

eU

ser

and

Nat

ive

Gro

upv

Rea

d

vA

dd

vD

elet

e

vR

epla

ce

vC

reat

e

vIm

port

Req

uire

dw

hen

you

crea

teus

ers

orgr

oups

.N

ote:

LD

AP

serv

erm

ight

rest

rict

som

eop

erat

ions

.

SURN

AME_

NAME

snN

ativ

eU

ser

vR

ead

vA

dd

vD

elet

e

vR

epla

ce

vC

reat

e

vIm

port

Req

uire

dw

hen

you

crea

teus

ers.

Not

e:L

DA

Pse

rver

mig

htre

stri

ctso

me

oper

atio

ns.

UID_

NAME

uid

Nat

ive

Use

rv

Rea

d

vA

dd

vD

elet

e

vR

epla

ce

vC

reat

e

vIm

port

Spec

ifie

sth

eL

DA

PU

niqu

eID

attr

ibut

ena

me.

Thi

sat

trib

ute

isan

opti

onal

attr

ibut

ew

hen

you

crea

teaRg

yUse

r.

Ifyo

ud

ono

tsp

ecif

ya

valu

e,th

ispa

ram

eter

isse

tto

theus

erId

orui

dva

lue

inth

ele

adin

gR

DN

®of

theus

erNa

tive

Id.

Not

e:L

DA

Pse

rver

mig

htre

stri

ctso

me

oper

atio

ns.


Tabl

e30

.AP

Iat

trib

ute

deta

ils(c

ontin

ued)

AP

IC

onst

ant

Nam

eE

ntr

yO

per

atio

nD

escr

ipti

on

OBJE

CT_C

LASS

_NAM

Eob

ject

Cla

ssN

ativ

eU

ser

and

Nat

ive

Gro

upv

Rea

d

vC

reat

e

Inte

rnal

use

only

.

Ind

icat

esth

eL

DA

Pob

ject

clas

sat

trib

ute

nam

e.

Thi

sat

trib

ute

cont

ains

the

nati

veL

DA

Pob

ject

Clas

sva

lues

for

the

nati

veen

try.

DESC

RIPT

ION_

NAME

desc

ript

ion

Nat

ive

Use

ran

dN

ativ

eG

roup

vR

ead

vA

dd

vD

elet

e

vR

epla

ce

vC

reat

e

vIm

port

Ind

icat

esth

eL

DA

Pd

escr

ipti

onat

trib

ute

nam

e.

Opt

iona

lat

trib

ute

whe

ncr

eati

nga

new

RgyU

ser

orRg

yGro

up.

Not

e:L

DA

Pse

rver

mig

htre

stri

ctso

me

oper

atio

ns.

IS_S

EC_E

NTIT

Y_NA

MEis

SecE

ntit

ySe

curi

tyA

cces

sM

anag

erU

ser

and

Secu

rity

Acc

ess

Man

ager

Gro

up

vR

ead

Set

totr

ueif

the

acco

unt

isa

Secu

rity

Acc

ess

Man

ager

enab

led

acco

unt.

Thi

sat

trib

ute

isvi

rtua

l,an

dis

dyn

amic

ally

det

erm

ines

inst

ead

ofbe

ing

stor

edin

the

LD

AP

regi

stry

.

IS_G

SO_U

SER_

NAME

isG

SOU

ser

Secu

rity

Acc

ess

Man

ager

Use

rv

Rea

dSe

tto

true

ifth

eac

coun

tis

aG

loba

lSi

gn-O

n(w

ebSS

O)

enab

led

acco

unt.

Thi

sat

trib

ute

isvi

rtua

l,an

dis

dyn

amic

ally

det

erm

ines

inst

ead

ofbe

ing

stor

edin

the

LD

AP

regi

stry

.

**

Nat

ive

Use

rv

Rea

d

vA

dd

vD

elet

e

vR

epla

ce

vC

reat

e

vIm

port

Ind

icat

esa

nati

veus

eren

try

that

mig

htha

vead

dit

iona

lat

trib

utes

for

the

user

.If

the

LD

AP

serv

erpe

rmit

s,th

eva

lues

are

upd

ated

ord

elet

ed.

Not

e:L

DA

Pse

rver

sm

ight

rest

rict

som

eop

erat

ions

.


Tabl

e30

.AP

Iat

trib

ute

deta

ils(c

ontin

ued)

AP

IC

onst

ant

Nam

eE

ntr

yO

per

atio

nD

escr

ipti

on

RESO

URCE

_CRE

DENT

IALS

_NAM

Ere

sour

ceC

rede

ntia

lsSe

curi

tyA

cces

sM

anag

erU

ser

vR

ead

Ifth

eac

coun

tis

agl

obal

sign

on-e

nabl

edan

dha

sre

sour

cecr

eden

tial

scr

eate

dfo

rit

,the

nth

isat

trib

ute

will

cont

ain

the

reso

urce

cred

enti

als

ofth

eus

er.

Thi

sis

avi

rtua

lat

trib

ute

that

isno

tst

ored

dir

ectl

yin

the

LD

AP

regi

stry

.Rat

her,

itis

dyn

amic

ally

det

erm

ined

from

mul

tipl

een

try

attr

ibut

esin

LD

AP.

Eac

hva

lue

for

the

attr

ibut

ere

pres

ents

one

reso

urce

cred

enti

alan

dha

sth

ere

sour

ces

cred

enti

alva

lues

cond

ense

din

toon

est

ring

.

The

API

prov

ide

met

hod

sto

expa

ndth

ese

reso

urce

cred

enti

alva

lues

into

sepa

rate

stri

ngs.


Error and trace logging

Error and trace logging use the Java logging mechanism. The Java logger namesare: com.tivoli.pd.rgy.authz and com.tivoli.pd.rgy.ldap. For basic Java Runtimeinstallation, the configuration of the logger output is in the lib/logging.properties file. Graphic user interfaces (GUI) are available forenvironments such as WebSphere® to configure and enable various log levels. Thetrace level CONFIG is also available for tracing configuration options.

Basic JRE example output

If the lib/logging.properties file is set to use java.util.logging.XMLFormatterfor debug logging, the output appears as follows:<?xml version="1.0" encoding="UTF-8" standalone="no"?><!DOCTYPE log SYSTEM "logger.dtd"><log><record><date>2009-11-16T16:28:35</date><millis>1258417715058</millis><sequence>0</sequence><logger>com.tivoli.pd.rgy.ldap</logger><level>FINER</level><class>com.tivoli.pd.rgy.ldap.LdapRgyRegistry</class><method>LdapRgyRegistry</method><thread>10</thread><message>RETURN</message></record><record><date>2009-11-16T16:28:35</date><millis>1258417715136</millis><sequence>1</sequence><logger>com.tivoli.pd.rgy.ldap</logger><level>FINER</level><class>com.tivoli.pd.rgy.ldap.LdapRgyRegistry</class><method>configure</method><thread>10</thread><message>ENTRY</message></record>

AuditingThe Registry Direct API provides a set of Java interfaces. The code used formanipulating the LDAP (the equivalent of the Security Access Manager IRA Ccode) implements these interfaces.

The auditing feature does not support Common Audit and Reporting Services(CARS). The auditing feature supports Security Access Manager XML file auditing.

Java logger behaviorThis section describes how the auditing feature behaves.

The auditing feature uses a Java logger framework, but directs the output to aconfigurable file. The name of the audit Java logger is visible on the Java loggerinterfaces.

You can enable or disable the output to the logger and adjust the level of logoutput by varying the log level in the Java run time.


The audit code uses a custom formatter. This means that the output format is theSecurity Access Manager XML audit file format. The Java logger namespace forauditing has a configurable component that allows each Java API exploiter to havea separate audit file and namespace.

The following are the loggers for authentication and management auditing:com.tivoli.pd.rgy.audit.{blade}.authn - Authentication audit loggingcom.tivoli.pd.rgy.audit.{blade}.mgmt - Management audit logging

where {blade} is the value of the configuration property appsvr-servername.

Note: If there are two separate instances of RgyRegistry in the same JVM, that usethe same appsvr-servername value, the instance shares one audit log file. Theinstance that was created first defines the audit log file to be used. The secondinstance continues to use any existing logger of the same name.

File formatThe Policy Server output is emulated by the Registry Direct Java API.

Information that is unavailable is either hardcoded to a pre-set value or isexcluded.

Start and stop events:

The two audit components mgmt and authn mimic the output of the auditcomponents of the same name in the Security Access Manager Policy Server.

These components generate:v an audit start event when the RgyRegistry instance is generated.v an audit stop event when the RgyRegistry instance is closed.

Sample start event for mgmt component is as follows:<event rev="1.2"><date>2009-11-19-10:34:45.380-08:00I-----</date><outcome status="0">0</outcome><originator blade="testapp-tam611"><component rev="1.1">mgmt</component><event_id>117</event_id><action>0</action><location>localhost</location></originator><target resource="5"><object></object></target><data><audit event="Start"/></data></event>

Sample start event for authn component is as follows:<event rev="1.2"><date>2009-11-19-10:34:45.492-08:00I-----</date><outcome status="0">0</outcome><originator blade="testapp-tam611"><component rev="1.1">authn</component><event_id>117</event_id><action>0</action><location>localhost</location></originator>


<target resource="7"><object></object></target><data><audit event="Start"/></data></event>

Management events:

This section provides a sample output of a management operation.

A sample output of a management operation such as RgyRegistry.authenticate()is:<event rev="1.2"><date>2009-11-19-10:34:45.580-08:00I-----</date><outcome status="0">0</outcome><originator blade="testapp-tam611"><component rev="1.1">mgmt</component><event_id>13401</event_id><action>13401</action><location>tam611.ibm.com</location></originator><accessor name=""><principal auth="IV_UNAUTH_V3.0" domain="Default">unauthenticated</principal></accessor><target resource="5"><object></object></target><mgmtinfo><command>USER CREATE</command><objname>testuser0</objname><objtype>user</objtype><objname_rgy>cn=testuser0,o=ibm,c=us</objname_rgy<parm><name>gsouser</name><value>false</value></parm><parm><name>nopwdpolicy</name><value>false</value></parm><parm><name>dn</name><value>cn=testuser0,o=ibm,c=us</value></parm><parm><name>loginid</name><value>testuser0</value></parm><parm><name>accountvalid</name><value>TRUE</value></parm><parm><name>maxloginfailures</name><value>2</value></parm><parm><name>cn</name><value>testuser0</value></parm><parm><name>minpasswordlength</name><value>8</value></parm><parm><name>accountexpirydate</name><value>20091119193445.0Z</value></parm><parm><name>sn</name><value>user0</value></parm><parm><name>disabletimeinterval</name><value>0</value></parm></mgmtinfo><data></data></event>

The preceding sample demonstrates how to provide additional attributes to theexisting API. The attribute names are mapped, wherever possible, to existing APIaudit attribute names.

You can create this output using createUser():registry = LdapRgyRegistryFactory.getRgyRegistryInstance(propertiesUrl, null);String sn = "user0”;String id = "test"+sn;String nativeId = "cn="+id+",o=ibm,c=us”;RgyAttributes rgyAttributes = registry.newRgyAttributes();rgyAttributes.putAttribute(RgyAttributes.COMMON_NAME_NAME, id);rgyAttributes.putAttribute(RgyAttributes.SURNAME_NAME, sn);rgyAttributes.putAttribute(RgyAttributes.MIN_PASSWORD_LENGTH_NAME, "8");rgyAttributes.putAttribute(RgyAttributes.MAX_LOGIN_FAILURES_NAME, "2");rgyAttributes.putAttribute(RgyAttributes.DISABLE_TIME_INTERVAL_NAME, "0");


Date currentTime = new Date();currentTime.setTime(currentTime.getTime() + (3600 * 1000L));String registryDate = null;registryDate = registry.toRegistryDate(currentTime);rgyAttributes.putAttribute(RgyAttributes.ACCOUNT_EXPIRY_DATE_NAME, registryDate);rgyAttributes.putAttribute(RgyAttributes.SEC_ACCT_VALID_NAME,RgyAttributes.BOOL_TRUE_VALUE);RgyUser user = registry.createUser(null, id, nativeId,"passw0rd".toCharArray(), false, rgyAttributes, null);

Authentication events:

This section provides a sample output of an authentication operation.

Authentication methods such as RgyUser.authenticate() produces output asfollows:<event rev="1.2"><date>2009-11-19-10:34:49.175-08:00I-----</date><outcome status="1" exception="com.tivoli.pd.rgy.exception.

InvalidCredentialsRgyException">1</outcome><originator blade="testapp-tam611"><component rev="1.1">authn</component><event_id>101</event_id><action>0</action><location>tam611.ibm.com</location></originator><accessor name=""><principal auth="IV_LDAP_V3.0" domain="Default">testuser0</principal><name_in_rgy>cn=testuser0,o=ibm,c=us</name_in_rgy></accessor><target resource="7"><object></object></target><authntype>formsPassword</authntype><data>Password Failure: testuser0</data></event>

The preceding example is generated using the authenticate() method as shown inthe following sample code:testuser = registry.getUser(null, "testuser0");testuser.authenticate("passw1rd".toCharArray());

Java logger namespace:

This section describes the Java logger namespace.

The Java logger namespaces and their descriptions are provided in the followingtable:

Table 31. Java logger namespace

Package Description

com.tivoli.pd.rgy.ldap LDAP LdapRgyRegistry trace and logging

com.tivoli.pd.rgy.authz Authorization and audit AuthzRgyRegistrytrace and logging

com.tivoli.pd.rgy.audit.{blade}.authn Authentication audit logging

com.tivoli.pd.rgy.audit.{blade}.mgmt Management audit logging


AuthorizationThis section describes the API authorization configuration.

The API authorization cannot fully emulate the authorization performed by thePolicy Server (pdmgrd). The group and user delegation cannot be emulated andthe API assumes that the functionality is not being used.

You can configure the Registry Direct Java API to not support delegated user andgroup administration. By default, the API does not support ACLs placed on childobjects of /Management/Groups. Unlike the Security Access Manager Java API, theRegistry Direct Java API does not create and delete protected objects under/Management/Groups. But the registry API affects authorization operations.

No ACLs are placed on child objects of /Management/Groups.

Authorization permission checksThe table in this section describes administrative operations and correspondingauthorization permissions.

The information in the table assumes that:v No ACLs are added on delegation protected objects under /Management/Groups

without taking advantage of delegated user and group management.v All delegation protected objects under /Management/Groups inherit the same ACL

that /Management/Groups uses.You do not have to verify whether each group has protected objects that areassociated with it. Verifying /Management/Groups is sufficient.

v adminid as the account that is requesting administration operation.


Tabl

e32

.Aut

horiz

atio

npe

rmis

sion

sfo

rgr

oups

Ad

min

istr

ativ

eop

erat

ion

sP

erm

issi

onV

erif

icat

ion

ofp

erm

issi

ons

RgyR

egis

try.

crea

teUs

er({

grou

ps})

“N”

Ifno

grou

pex

ists

,che

ckpe

rmis

sion

on/M

anag

emen

t/U

sers

.O

ther

wis

e,ch

eck

perm

issi

onon

/Man

agem

ent/

Gro

ups.

RgyU

ser.

impo

rtNa

tive

User

({gr

oup}

)“N

”If

the

spec

ifie

dgr

oup{g

roup

}d

oes

not

exis

tch

eck

the

perm

issi

onon

/Man

agem

ent/

Use

rs.O

ther

wis

e,ch

eck

the

perm

issi

onon

/Man

agem

ent/

Gro

ups.

RgyU

ser.

attr

ibut

eAdd

()Rg

yUse

r.at

trib

uteD

elet

e()

RgyU

ser.

Attr

ibut

eRep

lace

()fo

rus

er{u

seri

d}fo

ral

lat

trib

utes

exce

pt:s

ecAc

ctVa

lidse

cPwd

Vali

dal

lpo

licy

attr

ibut

es.

“m”

Che

ckpe

rmis

sion

on/M

anag

emen

t/G

roup

sif

not

perm

itte

d.I

fth

eus

erd

oes

not

have

grou

pm

embe

rshi

p,d

eny

acce

ssan

dch

eck

perm

issi

onon

/Man

agem

ent/

Gro

ups.

RgyU

ser.

attr

ibut

eAdd

()Rg

yUse

r.at

trib

uteD

elet

e()

RgyU

ser.

Attr

ibut

eRep

lace

()fo

rus

er{u

seri

d}fo

rat

trib

utes

:sec

Acct

Vali

dse

cPwd

Vali

d

“m”

Ifth

e{u

seri

d}is

the

sam

eas

{adm

inid

}d

eny

acce

ss.O

ther

wis

e,ch

eck

perm

issi

onon

/Man

agem

ent/

Use

rs.I

f{u

seri

d}ha

sno

grou

pm

embe

rshi

p,d

eny

acce

ss.O

ther

wis

e,ch

eck

perm

issi

onon

/Man

agem

ent/

Gro

ups.

RgyU

ser.

setP

assw

ord(

)fo

rus

er{u

seri

d}“W

”If

the{u

seri

d}is

the

sam

eas

{adm

inid

}pe

rmit

acce

ss.O

ther

wis

e,ch

eck

perm

issi

ons

on/M

anag

emen

t/U

sers

.If{u

seri

d}ha

sno

grou

pm

embe

rshi

p,d

eny

acce

ss.O

ther

wis

e,ch

eck

perm

issi

onon

/Man

agem

ent/

Gro

ups.

RgyR

egis

try.

dele

teUs

er({

user

id})

“d”

Ifth

e{u

seri

d}is

the

sam

eas

{adm

inid

}d

eny

acce

ss.O

ther

wis

e,ch

eck

perm

issi

ons

on/M

anag

emen

t/U

sers

.If{u

seri

d}ha

sno

grou

pm

embe

rshi

p,d

eny

acce

ss.o

ther

wis

e,ch

eck

perm

issi

onon

/Man

agem

ent/

Gro

ups.

RgyU

ser.

list

Grou

ps()

RgyU

ser.

list

Nati

veGr

oups

()T

hepe

rmis

sion

chec

kth

atis

perf

orm

edfo

rRg

yReg

istr

y.ge

tUse

r()

was

suff

icie

nt.P

erm

itac

cess

.

RgyR

egis

try.

getU

ser(

{use

rid}

)“v

”If

the{u

seri

d}is

the

sam

eas

{adm

inid

}pe

rmit

acce

ss.O

ther

wis

e,ch

eck

perm

issi

onon

/Man

agem

ent/

Use

rs.I

f{u

seri

d}d

oes

not

belo

ngto

agr

oup,

den

ype

rmis

sion

.Oth

erw

ise,

chec

kpe

rmis

sion

on/M

anag

emen

t/U

sers

.

RgyR

egis

try.

getN

ativ

eUse

r({d

n})

“v”

Map

the

dis

ting

uish

edna

me{d

n}to

the

grou

p{g

roup

id}.

Ifm

appi

ngd

oes

not

exis

ts,p

erm

it.I

fa

map

ping

exis

ts,t

hen

chec

kpe

rmis

sion

on/M

anag

emen

t/U

sers

.If{u

seri

d}d

oes

not

have

any

grou

p,ch

eck

perm

issi

onon

the

/Man

agem

ent/

Use

rs.

RgyU

ser.

getA

ttri

bute

Valu

es()

RgyU

ser.

getO

neAt

trib

uteV

alue

()fo

ral

lno

n-po

licy

attr

ibut

es.

The

perm

issi

onch

eck

don

efo

rRg

yReg

istr

y.ge

tUse

r()

was

suff

icie

nt.

Perm

itac

cess

.

RgyR

egis

try.

list

User

s()

RgyR

egis

try.

list

Nati

veUs

ers(

)T

here

are

del

egat

ion

effe

cts

onth

eop

erat

ion

resu

lts

inth

efo

llow

-up

tabl

e.

RgyR

egis

try.

crea

teGr

oup(

)“N

”C

heck

perm

issi

onon

/Man

agem

ent/

Gro

ups.

RgyR

egis

try.

dele

teGr

oup(

)“d

”C

heck

perm

issi

onon

/Man

agem

ent/

Gro

ups.

RgyG

roup

.imp

ortN

ativ

eGro

up()

“N”

Che

ckpe

rmis

sion

on/M

anag

emen

t/G

roup

s.


Tabl

e32

.Aut

horiz

atio

npe

rmis

sion

sfo

rgr

oups

(con

tinue

d)

Ad

min

istr

ativ

eop

erat

ion

sP

erm

issi

onV

erif

icat

ion

ofp

erm

issi

ons

RgyR

egis

try.

list

Grou

ps()

RgyR

egis

try.

list

Nati

veGr

oups

()Pe

rmit

(the

rear

ed

eleg

atio

nef

fect

son

the

oper

atio

nre

sult

sin

the

follo

w-u

pta

ble)

.

RgyG

roup

.add

Memb

ers(

)“A

”C

heck

perm

issi

onon

/Man

agem

ent/

Gro

ups.

grou

pmo

dify

{gro

upid

}de

scri

ptio

n“m

”C

heck

perm

issi

onon

/Man

agem

ent/

Gro

ups.

RgyG

roup

.rem

oveM

embe

rs()

“A”

Che

ckpe

rmis

sion

on/M

anag

emen

t/G

roup

s.

RgyR

egis

try.

getG

roup

()“v

”C

heck

perm

issi

onon

/Man

agem

ent/

Gro

ups.

RgyR

egis

try.

getN

ativ

eGro

up({

dn})

“v”

Map

the

dis

ting

uish

edna

me

{dn}

toth

egr

oup

{gro

upid

}.

Ifno

map

ping

exis

ts,p

erm

it.

Oth

erw

ise,

chec

kpe

rmis

sion

on/M

anag

emen

t/G

roup

s.

RgyG

roup

.lis

tMem

berI

ds()

RgyG

roup

.lis

tMem

berN

ativ

eIds

()

“v”

Che

ckpe

rmis

sion

on/M

anag

emen

t/G

roup

s.

RgyU

ser.

getA

ttri

bute

Valu

es()

RgyU

ser.

getO

neAt

trib

uteV

alue

()fo

ral

lpo

licy

attr

ibut

es.

Thi

sd

iffe

rsfr

omth

epe

rmis

sion

chec

kpe

rfor

med

byth

ere

gula

rSe

curi

tyA

cces

sM

anag

erA

PI.

The

regu

lar

Secu

rity

Acc

ess

Man

ager

API

chec

ksfo

rth

epe

rmis

sion

IVA

CT

ION

_VIE

W“v

”on

/Man

agem

ent/

Pol

icy.

Thi

sA

PId

oes

not

perf

orm

any

add

itio

nal

perm

issi

onch

ecks

.It

com

plet

espe

rmis

sion

chec

kw

hen

fetc

hing

the

user

usin

gRg

yReg

istr

y.ge

tUse

r()

met

hod

.

RgyU

ser.

attr

ibut

eAdd

()Rg

yUse

r.at

trib

uteD

elet

e()

RgyU

ser.

Attr

ibut

eRep

lace

()fo

ral

lpo

licy

attr

ibut

es.

“m”

Che

ckpe

rmis

sion

on/M

anag

emen

t/G

roup

s.


When you use the Registry Direct Java API, you must fetch the user before youmodify the user. Assign view permission (v) and modify permission (m ) for theadministrator to modify either a user or a group.

Residual effects of delegated administration on admin resultsIf operations are permitted, additional permissions can be verified by the API todetermine if a different subset of result must be returned. The permission check inthis case does not permit or deny the whole operation. It affects only the result setreturned, instead.

The following table shows the additional effects of delegated administration on theresult set. It also assumes that no ACLs are added on delegation protected objectsunder /Management/Groups. This assumption reduces many of the delegatedadministration complexities into simpler behavior.


Tabl

e33

.Li

stof

oper

atio

nsan

dpe

rmis

sion

sto

bech

ecke

d

Op

erat

ion

Per

mis

sion

tob

ech

eck

ed

RgyU

ser.

list

Grou

ps()

RgyU

ser.

list

Nati

veGr

oups

()C

heck

perm

issi

onDE

LADM

IN_V

IEW(

“v”)

on"/

Mana

geme

nt/U

sers

".If

perm

itte

dre

turn

grou

pli

stel

sech

eck

perm

issi

onDE

LADM

IN_V

IEWon

"/Ma

nage

ment

/Gro

ups"

.If

perm

itte

dre

turn

grou

pli

stel

sere

turn

anem

pty

list.

RgyR

egis

try.

list

User

s({p

atte

rn})

Che

ckpe

rmis

sion

DELA

DMIN

_VIE

W(“v

”)on

"/Ma

nage

ment

/Use

rs".

Ifpe

rmit

ted

,ret

urn

list

ofus

ers

mat

chin

g{p

atte

rn}e

lse

chec

kpe

rmis

sion

DELA

DMIN

_VIE

W(“v

”)on

"/Ma

nage

ment

/Gro

ups"

.

Ifpe

rmit

ted

,ret

urn

list

ofus

ers

mat

chin

gth

epat

tern

.In

this

case

,the

curr

ent

API

retu

rns

only

user

sth

atar

ea

mem

ber

ofat

leas

ton

eSe

curi

tyA

cces

sM

anag

ergr

oup,

this

API

will

not

enfo

rce

this

rest

rict

ion

else

retu

rnan

empt

ylis

t.

RgyR

egis

try.

list

Nati

veUs

ers(

{pat

tern

})C

heck

perm

issi

onDE

LADM

IN_V

IEW(

“v”)

on"/

Mana

geme

nt/U

sers

".

Ifpe

rmit

ted

,ret

urn

list

ofus

ersdn

sw

ith

attr

ibut

em

atch

ing

patt

ern

(bot

hSe

curi

tyA

cces

sM

anag

eran

dno

n-Se

curi

tyA

cces

sM

anag

erus

erdn

)el

sech

eck

perm

issi

onDE

LADM

IN_V

IEW(

“v”)

on"/

Mana

geme

nt/G

roup

s".

Ifpe

rmit

ted

,ret

urn

list

ofus

erdn

wit

hat

trib

ute

mat

chin

gpa

tter

n.In

this

case

,the

curr

ent

API

only

retu

rnsdn

whe

reth

eac

tual

dnm

atch

esth

epa

tter

nan

don

lydn

ofSe

curi

tyA

cces

sM

anag

erus

ers,

that

are

am

embe

rof

atle

ast

one

Secu

rity

Acc

ess

Man

ager

grou

pel

sere

turn

empt

ylis

t.

RgyR

egis

try.

crea

teGr

oup(

)N

ewco

de

isun

able

tocr

eate

grou

pd

eleg

atio

npr

otec

ted

obje

ct.

RgyG

roup

.imp

ortN

ativ

eGro

up()

New

cod

eis

unab

leto

crea

tegr

oup

del

egat

ion

prot

ecte

dob

ject

.

RgyR

egis

try.

dele

teGr

oup(

)N

ewco

de

isun

able

tod

elet

egr

oup

del

egat

ion

prot

ecte

dob

ject

,if

itex

ists

.

RgyR

egis

try.

list

Grou

ps({

patt

ern}

)L

ist

all

grou

psw

ith

Secu

rity

Acc

ess

Man

ager

IDm

atch

ingpa

tter

n.C

heck

conf

igur

atio

nop

tion

"[de

lega

ted-

admi

n]au

thor

ize-

grou

p-li

st=ye

s/no

"if

auth

oriz

e-gr

oup-

list

retu

rngr

oupL

ist.

Oth

erw

ise,

chec

kpe

rmDE

LADM

IN_V

IEW(

“v”)

on"/

Mana

geme

nt/G

roup

s".

Ifpe

rmit

ted

,ret

urn

thegr

oupL

ist.

Oth

erw

ise,

retu

rnem

ptyli

st.

RgyR

egis

try.

list

Nati

veGr

oups

({pa

tter

n})

grou

pLis

t=

list

all

grou

pDN

swi

that

trib

ute

matc

hing

{pat

tern

}ch

eck

conf

igop

tion

"[de

lega

ted-

admi

n]au

thor

ize-

grou

p-li

st=

yes/

no"

if!a

utho

rize

-gro

up-l

ist:

retu

rngr

oupL

ist

else

chec

kpe

rmis

son

DELA

DMIN

_VIE

W(“v

”)on

"/Ma

nage

ment

/Gro

ups"

ifpe

rmit

ted:

retu

rngr

oupL

ist

else

retu

rnem

pty

list


API SpecificationsSee the Javadoc for packages under com.tivoli.pd.rgy.

Installation and configurationYou can install, configure, and upgrade the Registry Direct API by following theseinstructions.

Federated LDAP serversUse the fed-server option so that you can add individual suffixes of multipleLDAP registries into the IBM Security Access Manager registry. Federated ActiveDirectory suffixes are also supported.

For more information about using the fed-server option, see “Configurationoptions” on page 100.

Upgrade

Use the PD.jar available with the Registry Direct Java API Reference to configurethe features. The WebSphere Application Server installation program includesPD.jar in the JRE class path. Update the class path manually or avoid references tothis PD.jar when configuring the Registry Direct API along with the SecurityAccess Manager Java API. After configuration, you can use the Registry Direct APIalong with the earlier versions of PD.jar.

Installation and packagingThe Registry Direct API PD.jar package includes the PDjrte package, which isinstalled during the API installation.

The exploiter of the API must include the Registry Direct API PD.jar JAR file intheir application class path.

The Registry Direct API JAR file is com.tivoli.pd.rgy.jar. This file is installed inthe PolicyDirector/java/export/rgy directory.

ConfigurationThere are two configuration options for configuring the Registry Direct API andthe Security Access Manager Java API.

Two configuration options are available:v Standalone usage - the configuration permits stand-alone usage of the Registry

Direct API.v Combined usage - the configuration allows convenient and combined use of

both Security Access Manager Java API and the Registry Direct API.

Using both Security Access Manager Java API and the RegistryDirect APIThis section describes how to use SvrSslCfg to configure the Security AccessManager Java API and the Registry Direct API at the same time.

The SvrSslCfg that is provided in PD.jar is enhanced to permit simultaneousconfiguration of the current Java API and Registry Direct Java API.


Both configurations share the same LDAP identity and configuration propertiesfile. This feature is useful if authorization is enabled in the new API, whichrequires the current API to provide the identity and configuration properties file.

If SvrSslCfg has –ldap_mgmt set to true, it creates a Security Access Manageridentity for the application, the identity is also added to the Security AccessManager group, SecurityGroup. This group membership gives the underlying LDAPidentity the required privileges to administer user and groups in LDAP.SvrSslCfggenerates a random password, if a password is not supplied, for the identity. Itobfuscates and stores the password in the configuration file. The underlying LDAPidentity and password that are stored in the configuration file is used by theRegistry Direct API to bind to LDAP to perform administration and authentication.

Stand-alone configurationThis section describes the stand-alone configuration.

To use the authz.enable-authorization option in the Registry Direct API, aPDAuthorizationContext instance from the Security Access Manager Java API mustbe used. In such a case, it is better to use SvrSslCfg.

The configuration tool RgyConfig is provided in the JAR file along with the newAPI. The usage is as follows:

Usage:java com.tivoli.pd.rgy.util.RgyConfig <file> <command> [options]<file> configuration properties file path name<command> is one of:

create <mgmt_domain> <local_domain> <ldap.svrs><ldap.bind_dn> <ldap.bind_pwd> [<ldap.ssl_truststore><ldap.ssl_truststore_pwd>load <input properties file>

set <name> <value>remove <name>get <name>list

The usage for a non-SSL example is:java com.tivoli.pd.rgy.util.RgyConfig /tmp/testapi.properties create Default Default"ldaphostname:389:readwrite:5" "cn=testapi,o=ibm,c=us" passw0rd

After you create the properties file, you can manipulate the additional properties.The example to set ldap.enable-last-login property is as follows:java com.tivoli.pd.rgy.util.RgyConfig /tmp/testapi.properties set ldap.enable-last-login true

When you use the RgyConfig tool, you must manually create the server identity.Ensure that the Security Access Manager subdomains include the server identity inthe remote-acl-users group of Security Access Manager management domain. IfSecurity Access Manager domain is not the default domain, the followingadditional steps are needed.1. Create a file groupmodify.ldif with the following contents:

dn: cn=remote-acl-users,cn=SecurityGroups,secAuthority=Defaultchangetype: modifyadd: membermember: cn=testapp/tam611,cn=SecurityDaemons,secAuthority=testdom,cn=Subdomains,secAuthority=Default


Where member is the LDAP DN of your application. This value is provided asldap.bind_dnargument to java com.tivoli.pd.rgy.util.RgyConfig. Alternately,you can determine this value from ldap.bind-dn stored in the generatedproperties file.

2. Update LDAP by using ldapmodify command.ldapmodify -p 389 -h localhost -D "cn=root" -w passw0rd -f groupmodify.ldif

Replace localhost and passw0rd with values appropriate for your setup.

Note: You do not have to install or configure Security Access Manager to use thenew API in stand-alone mode.

Configuration optionsThe following table describes the configuration options for the Security AccessManager Java API and the Registry Direct API.


Tabl

e34

.C

onfig

urat

ion

optio

ns

Java

Op

tion

Nam

eE

xist

ing

Com

par

able

Op

tion

Exi

sten

cein

curr

ent

Java

Con

fig

Def

ault

Val

idR

ange

Des

crip

tion

ldap.mgmt

[ldap]

enabled

New

,Opt

iona

lfa

lse

true

,fal

seSe

tth

isop

tion

true

toen

able

LD

AP

man

agem

ent.

mgmt_domain

[manager]management-

domain

Alr

ead

yPr

esen

t,R

equi

red

valid

dom

ain

stri

ngSe

curi

tyA

cces

sM

anag

erM

anag

emen

tD

omai

nna

me.

Req

uire

dto

det

erm

ine

the

loca

tion

ofsu

bdom

ain

inth

ere

gist

ry.S

ubd

omai

nsar

elo

cate

dre

lati

veto

the

Man

agem

ent

Dom

ain

LD

AP

loca

tion

.

local_domain

[ssl]ssl-local-domain

Alr

ead

yPr

esen

t,O

ptio

nal

valid

dom

ain

stri

ngT

hena

me

ofth

ed

efau

ltd

omai

nth

atis

used

whe

nth

eM

anag

emen

tA

PId

oes

not

prov

ide

ad

omai

nna

me.

Ifyo

ud

ono

tpr

ovid

ea

valu

e,th

eva

lue

from

mgmt_domain

conf

igur

atio

nop

tion

isus

ed.

ldap.dynamic-groups-enabled

[ldap]

dynamic-groups-enabled

New

,Opt

iona

lfa

lse

true

,fal

seE

nabl

essu

ppor

tof

dyn

amic

grou

psfo

rso

me

LD

AP

serv

erty

pes

byus

ing

thememberURL

attr

ibut

e.Se

curi

tyA

cces

sM

anag

ersu

ppor

tsd

ynam

icgr

oups

wit

hTi

voli

Dir

ecto

rySe

rver

rega

rdle

ssof

this

sett

ing.

Thi

sst

anza

entr

yis

supp

orte

dfo

rO

racl

eSy

stem

Dir

ecto

rySe

rver

.

ldap.enable-last-login

[ldap]enable-

last-login

New

,Opt

iona

ltr

ue,f

alse

Sets

anop

tion

tost

ore

the

last

logi

nd

ate

inL

DA

Pea

chlo

gin.

ldap.mgmt-domain-suffix

[ldap]

secauthority-

suffix

New

,Opt

iona

lW

illbe

auto

mat

ic-

ally

loca

ted

.va

lidLD

AP

suffi

xst

ring

Spec

ify

the

valid

LD

AP

suff

ixst

ring

for

the

Dom

ain

Man

agem

ent

ofth

eSe

curi

tyA

cces

sM

anag

er.

ldap.ignore-suffix

[ldap]

ignore-suffix

New

,Opt

iona

lE

mpt

ylis

tlis

tof

valid

LDA

Psu

ffix

stri

ngs

Igno

reL

DA

Pse

rver

suff

ixw

hen

sear

chin

gfo

rus

eran

dgr

oup

info

rmat

ion.

Suff

ixes

cn=localhost

,cn=pwdpolicy,

cn=configuration

,and

the

suff

ixes

that

are

spec

ifie

din

thesubschemasubentry

andchangelog

valu

esar

eal

way

sig

nore

d.

SvrSslCfg

acce

pts

mul

tipl

eva

lues

byus

ing

",,"

(dou

ble

com

ma)

sepa

rato

r.T

heco

nfig

urat

ion

file

uses

";"

(sem

icol

ons)

inte

rnal

lyas

ase

para

tor.

ldap.max-server-connections

[ldap]

max-server-connections

New

,Opt

iona

l16

2->

4096

Ind

icat

esth

em

axim

umnu

mbe

rof

conn

ecti

ons

that

can

exis

tto

the

LD

AP

serv

er.

ldap.user-objectclass

[ldap]

user-objectclass

New

,Opt

iona

lD

efau

lts

vary

depe

ndin

gon

LDA

Pse

rver

type

Whe

npr

ovid

edto

the

conf

igur

atio

nto

ol,i

tco

ntai

nsa

list

ofco

mm

a-se

para

ted

obje

ctcl

ass

nam

esto

set

whe

ncr

eati

nga

nati

veus

eren

try

inL

DA

P.

For

exam

ple:

top,

pers

on,o

rgan

izat

iona

lPer

son,

inet

Org

Per

son,

ePer

son.

SvrSslCfg

that

mod

ifie

sth

elis

tto

be";

"(s

emic

olon

)se

para

ted

whe

nit

plac

esit

inth

eco

nfig

urat

ion

prop

erti

esfi

le.

ldap.static-group-objectclass

[ldap]

static-group-

objectclass

New

,Opt

iona

lD

efau

lts

vary

depe

ndin

gon

LDA

Pse

rver

type

Whe

npr

ovid

edto

the

conf

igur

atio

nto

ol,i

tco

ntai

nsa

list

ofco

mm

a-se

para

tedobjectClass

nam

esto

set

whe

ncr

eati

nga

nati

vegr

oup

entr

yin

LD

AP.

Onl

yno

n-d

ynam

icgr

oups

are

crea

ted

bySe

curi

tyA

cces

sM

anag

er.F

orex

ampl

e,to

p,gr

oupO

fNam

es.

SvrSslCfg

mod

ifie

sth

elis

tto

be‘;'

(sem

icol

on)

sepa

rate

dw

hen

itpl

aces

itin

the

conf

igur

atio

npr

oper

ties

file

.


Tabl

e34

.C

onfig

urat

ion

optio

ns(c

ontin

ued)

Java

Op

tion

Nam

eE

xist

ing

Com

par

able

Op

tion

Exi

sten

cein

curr

ent

Java

Con

fig

Def

ault

Val

idR

ange

Des

crip

tion

ldap.user-search-filter

[ldap]

user-search-filter

New

,Opt

iona

lD

efau

lts

vary

dep

end

ing

onL

DA

Pse

rver

type

.

valid

LDA

Pse

arch

filte

rst

ring

An

LD

AP

sear

chfi

lter

that

sele

cts

any

nati

veus

eren

try.

For

exam

ple:

(|(o

bjec

tcla

ss=

ePer

son)

(obj

ectc

lass

=P

erso

n)).

ldap.group-search-filter

[ldap]

group-search-filter

New

,Opt

iona

lD

efau

lts

vary

dep

end

ing

onL

DA

Pse

rver

type

.

valid

LDA

Pse

arch

filte

rst

ring

An

LD

AP

sear

chfi

lter

that

sele

cts

any

nati

vegr

oup

entr

y.Fo

rex

ampl

e:

(|(objectclass=accessGroup)

(objectclass=groupOfNames)

(objectclass=groupOfUniqueNames)

(objectclass=groupOfURLs))

ldap.svrs

[ldap]

host,port,

ssl-port,andreplica

New

,Req

uire

dva

lidho

stst

ring

,por

t1

->65

535,

type

read

wri

teor

read

only

,pre

f0

->10

Aco

mm

a-se

para

ted

list

ofL

DA

Pse

rver

det

ails

.Eac

hse

rver

det

ail

isa

colo

nse

para

ted

set

ofat

trib

utes

ofth

efo

rm:

host:port:type:rank[,host2:

port2:type2:rank2[,...]]

whe

retype

isei

ther

readwrite

orreadonly

and

rank

isa

valu

efr

om0

to10

.For

exam

ple:

ldaphost:389:readwrite:5

ism

odif

ied

toa

list

ofL

DA

Pse

rver

det

ails

that

are

sepa

rate

dby

';'s.

ldap.ssl-enable

[ldap]

ssl-enable

New

,Opt

iona

lFa

lse

true

,fal

seSe

tth

isop

tion

totr

ueto

enab

leSS

Lto

the

LD

AP

serv

er.

ldap.fips

[ssl]ssl-enable-fips

New

,Opt

iona

lFa

lse

true

,fal

seD

epre

cate

d:r

epla

ced

byldap.compliance.

Use

ldap.compliance=fips

forldap.fips=true

.

Use

ldap.compliance=none

forldap.fips=false.

Set

this

opti

onto

true

tous

eFI

PSm

ode

wit

hth

eT

LS

conn

ecti

ons

toth

eL

DA

Pse

rver

.

ldap.compliance

[ssl]ssl-compliance

New

,Opt

iona

lno

ne,f

ips,

sp80

0-13

1-tr

ansi

tion

,sp

800-

131-

stri

ct,

suit

e-b-

128,

suit

e-b-

192

Sets

the

com

plia

nce

leve

lfo

rSS

Lan

dT

LS

conn

ecti

ons

toth

eL

DA

Pse

rver

.

Thi

sva

lue

isno

tus

edw

hen

runn

ing

wit

hin

aW

ebSp

here

JVM

beca

use

the

com

plia

nce

leve

lis

auto

mat

ical

lyd

eter

min

edba

sed

onho

wW

ebSp

here

isco

nfig

ured

.

ldap.ssl-v3-enable

[ssl]ssl-v3-enable

New

,Opt

iona

lTr

uetr

ue,f

alse

Ena

bles

ord

isab

les

the

use

ofSS

Lve

rsio

n3

toth

eL

DA

Pse

rver

.

For

som

essl.compliance

valu

es,t

his

para

met

eris

alw

ays

dis

able

d.

Thi

spa

ram

eter

isal

way

sd

isab

led

for

com

plia

nce

leve

lssp800-131-strict

,suite-b-128

,and

suite-b-192.

ldap.tls-v10-enable

[ssl]tls-v10-enable

New

,Opt

iona

lTr

uetr

ue,f

alse

Ena

bles

ord

isab

les

the

use

ofT

LS

vers

ion

1.0

toth

eL

DA

Pse

rver

.

For

som

essl.compliance

valu

es,t

his

para

met

eris

alw

ays

dis

able

d.

Thi

spa

ram

eter

isal

way

sd

isab

led

for

com

plia

nce

leve

lssp800-131-strict

,suite-b-128

,and

suite-b-192.


Tabl

e34

.C

onfig

urat

ion

optio

ns(c

ontin

ued)

Java

Op

tion

Nam

eE

xist

ing

Com

par

able

Op

tion

Exi

sten

cein

curr

ent

Java

Con

fig

Def

ault

Val

idR

ange

Des

crip

tion

ldap.tls-v11-enable

[ssl]tls-v11-enable

New

,Opt

iona

lTr

uetr

ue,f

alse

Ena

bles

ord

isab

les

the

use

ofT

LS

vers

ion

1.1

toth

eL

DA

Pse

rver

.

For

som

essl.compliance

valu

es,t

his

para

met

eris

alw

ays

dis

able

d.

Thi

spa

ram

eter

isal

way

sd

isab

led

for

com

plia

nce

leve

lssp800-131-strict

,suite-b-128

,and

suite-b-192.

ldap.tls-v12-enable

[ssl]tls-v12-enable

New

,Opt

iona

lTr

uetr

ue,f

alse

Ena

bles

ord

isab

les

the

use

ofT

LS

vers

ion

1.2

toth

eL

DA

Pse

rver

.

For

som

essl.compliance

valu

es,t

his

para

met

eris

alw

ays

dis

able

d.

Thi

spa

ram

eter

isal

way

sen

able

dfo

rsp800-131-strict

,suite-b-128

,an

dsuite-b-192.

ldap.cipher-suites

[ssl]

ssl-v3-cipher-specs,

[ssl]

tls-v10-cipher-

specs,[ssl]

tls-v11-cipher-

specs,[ssl]

tls-v12-cipher-specs

New

,Opt

iona

lJa

vad

efau

lts

[sem

icol

onlis

tof

Java

ciph

erna

mes

]Sp

ecif

ies

whi

chci

pher

suit

esto

use

for

all

SSL

and

TL

Spr

otoc

ols.

Exa

mpl

e:SS

L_D

HE

_DSS

_WIT

H_3

DE

S_E

DE

_CB

C_S

HA

;SS

L_D

HE

_DSS

_WIT

H_A

ES_

128_

CB

C_S

HA

;SS

L_D

HE

_DSS

_WIT

H_A

ES_

128_

CB

C_S

HA

256

For

info

rmat

ion

abou

tth

eci

pher

suit

ena

mes

,see

http

://

publ

ib.b

ould

er.ib

m.c

om/

info

cent

er/

java

7sd

k/v7

r0/

ind

ex.js

p?to

pic=

%2F

com

.ibm

.java

.sec

urit

y.co

mpo

nent

.doc

%2F

secu

rity

-com

pone

nt%

2Fjs

se2D

ocs%

2Fci

pher

suit

es.h

tml.

ldap.ssl-truststore

New

,Opt

iona

lFi

lena

me

stri

ngT

hefi

lena

me

ofa

Java

JCE

KS

keys

tore

that

cont

ains

the

trus

ted

CA

sign

ers

for

the

LD

AP

serv

erC

erti

fica

te.

The

API

conv

erts

the

valu

eth

atis

plac

edin

the

conf

igur

atio

nfi

lein

toU

RL

form

at.

The

API

supp

orts

only

file:

prot

ocol

.If

you

do

not

prov

ideFilename

string

inth

eU

RL

,spe

cify

java.naming.ldap.factory.socket,

ifyo

uen

able

dldap.ssl-enable.

ldap.ssl-truststore-pwd

New

,Req

uire

don

lyif

ldap

.ssl

-tru

stst

ore

issp

ecif

ied

Pas

swor

dst

ring

The

pass

wor

dfo

rth

eld

ap.s

sl-t

rust

stor

e.T

his

pass

wor

dis

obfu

scat

edby

SvrSslCfg

andRgyConfig

whe

nse

t.Pr

ovid

eth

epa

ssw

ord

ifld

ap.s

sl-t

rust

sore

isse

t.

ldap.login-failures-persistent

[ldap]

login-failures-

persistent

New

,Opt

iona

lFa

lse

true

,fal

seL

ogin

failu

res

are

used

wit

hth

eth

ree-

stri

kes

polic

y.If

you

set

this

opti

onto

false,

each

proc

ess

byus

ing

this

API

stor

esth

enu

mbe

rof

logi

nfa

ilure

sin

mem

ory.

Ifm

ulti

ple

serv

ers

are

invo

lved

,the

tota

lnu

mbe

rof

logi

nfa

ilure

sto

trig

ger

ast

rike

-out

mig

htva

ry.

Ifyo

use

tth

isop

tion

totrue

,the

stri

keco

unt

isst

ored

inL

DA

Pan

dsh

ared

acro

ssal

lse

rver

s.A

nac

cura

teco

unt

can

beke

ptin

am

ulti

serv

eren

viro

nmen

t.

ldap.auth-using-compare

[ldap]

auth-using-compare

New

,Opt

iona

lD

efau

lts

vary

dep

end

ing

onL

DA

Pse

rver

type

.

true

,fal

seSe

tth

isop

tion

tofa

lse

tova

lidat

eev

ery

dn/

pass

wor

dby

usin

ga

new

conn

ecti

onto

LD

AP,

and

asi

mpl

ebi

nd.S

etth

isop

tion

totrue

toco

mpa

reth

eL

DA

Pag

ains

tth

epa

ssw

ord

attr

ibut

eto

valid

ate

the

pass

wor

d.S

ome

LD

AP

serv

ers

do

not

supp

ort

this

sett

ing

and

igno

res

it.


http://publib.boulder.ibm.com/infocenter/java7sdk/v7r0/index.jsp?topic=%2Fcom.ibm.java.security.component.doc%2Fsecurity-component%2Fjsse2Docs%2Fciphersuites.html




Tabl

e34

.C

onfig

urat

ion

optio

ns(c

ontin

ued)

Java

Op

tion

Nam

eE

xist

ing

Com

par

able

Op

tion

Exi

sten

cein

curr

ent

Java

Con

fig

Def

ault

Val

idR

ange

Des

crip

tion

ldap.bind-dn

[ldap]

bind-dn

New

,Req

uire

dva

lidLD

AP

DN

stri

ngT

heD

Nto

sim

ple

bind

toL

DA

Pfo

ral

lm

anag

emen

tL

DA

Pop

erat

ions

.

ldap.bind-pwd

[ldap]

bind-pwd

New

,Req

uire

dva

lidpa

ssw

ord

stri

ngT

heL

DA

Pbind-dn

acco

unt

pass

wor

d.S

vrSs

lCfg

and

Rgy

Con

figob

fusc

ates

this

valu

ein

the

conf

igur

atio

nfi

le.

ldap.bind-auth-and-pwdchg

[ldap]

bind-auth-and-pwdchg

New

,Opt

iona

lFa

lse

true

,fal

sev

Ifse

tto

true

,Reg

istr

yD

irec

tA

PIus

esbi

ndto

auth

enti

cate

user

san

da

conn

ecti

onth

atis

boun

das

the

user

toch

ange

thei

rpa

ssw

ord

inca

ses

whe

reth

eol

dan

dne

wpa

ssw

ord

sar

epr

ovid

ed.


isig

nore

dfo

rth

ese

rver

.

vA

sing

leL

DA

Pop

erat

ion

that

com

bine

sbo

thre

mov

eol

dpa

ssw

ord

and

add

new

pass

wor

dar

eus

edas

requ

ired

byso

me

LD

AP

serv

ersu

chas

Act

ive

Dir

ecto

ry.U

sers

mus

tal

soha

veap

prop

riat

eL

DA

P/A

DA

CL

sth

atal

low

them

toch

ange

thei

row

npa

ssw

ord

.Fo

rA

ctiv

eD

irec

tory

,thi

sse

ttin

gis

the

def

ault

.For

othe

rL

DA

Ps,a

nA

CL

may

need

tobe

add

ed.

ldap.follow-referrals

[ldap]

follow-referrals

New

,Opt

iona

lFa

lse

true

,fal

sev

Ifse

tto

true

,the

LD

AP

clie

nt,J

ND

I,fo

llow

sth

eL

DA

Pre

ferr

als

toot

her

serv

ers.

Iffa

lse,

itig

nore

sre

ferr

als.

ldap.return-registry-id

[ldap]

cache-return-registry-

id

New

,Opt

iona

lFa

lse

true

,fal

seIf

set

totr

ue,R

gyUser.RgyEntity.getId()

retu

rns

the

Secu

rity

Acc

ess

Man

ager

user

IDfo

rth

esp

ecif

icus

erth

atis

stor

edin

the

LD

AP

regi

stry

.

Ifse

tto

fals

e,RgyUser.RgyEntity.getId()

retu

rns

the

Secu

rity

Acc

ess

Man

ager

user

IDfo

rth

eus

erth

atw

aspa

ssed

into

the

RgyRegistry.getUser()

met

hod

.

Secu

rity

Acc

ess

Man

ager

IDs

are

not

case

-sen

siti

ve.T

heus

erID

retu

rned

dif

fers

ifth

eca

seof

the

IDpa

ssed

toRgyRegistry.getUser()

isd

iffe

rent

from

the

case

ofth

eva

lue

that

isst

ored

inL

DA

P.

ldap.user-self-care-objectclass

New

,Opt

iona

lE

mpt

yva

lidLD

AP

obje

ctC

lass

stri

ngT

hena

me

ofan

AU

XIL

LA

RY

obje

ctC

lass

toen

sure

wha

tus

eren

trie

sha

veso

that

self

-car

eat

trib

utes

can

bead

ded

toex

isti

ngan

dne

wna

tive

user

LD

AP

entr

ies.

ldap.default-policy-override-support

[ldap]

default-policy-

override-support

New

,Opt

iona

lFa

lse

true

,fal

seIf

set

totrue

,the

Secu

rity

Acc

ess

Man

ager

per-

user

polic

yis

not

used

.In

stea

d,t

hegl

obal

polic

yta

kes

effe

ct.

java.naming.ldap.

factory.

socket

New

,Opt

iona

lna

me

ofcl

ass

Mak

esit

poss

ible

for

the

calle

rto

prov

ide

thei

row

nSS

Lso

cket

fact

ory

tous

ew

ith

JND

Ito

the

LD

AP

serv

ers.

ldap.cache-policy-expire-time

[ldap]

cache-policy-expire-

time

New

,Opt

iona

l60

0(s

econ

ds)

0->

8640

0T

hed

urat

ion

inse

cond

sfo

rw

hich

the

glob

alpo

licy

isca

ched

inth

em

emor

ybe

fore

bein

gre

adag

ain

from

LD

AP.

ldap.max-auth-connections

[ldap]

max-auth-connections

New

,Opt

iona

l0

0->

3276

8N

on-z

ero

valu

eth

atse

tsth

enu

mbe

rof

sim

ulta

neou

sL

DA

Pco

nnec

tion

sth

atar

eus

edto

auth

enti

cate

user

s(w

hen

auth

-usi

ng-c

ompa

re=

fals

e)

ldap.group-map-size

1024

0->

Max

imum

Inte

ger

The

num

ber

ofen

trie

sin

am

apth

atis

used

toco

nver

tgr

oup

nati

vena

mes

(DN

s)in

toSe

curi

tyA

cces

sM

anag

erID

s.A

nL

RU

algo

rith

mto

enab

les

crea

tion

ofne

wen

trie

s.


http://msdn.microsoft.com/en-us/library/cc223248.aspx

Tabl

e34

.C

onfig

urat

ion

optio

ns(c

ontin

ued)

Java

Op

tion

Nam

eE

xist

ing

Com

par

able

Op

tion

Exi

sten

cein

curr

ent

Java

Con

fig

Def

ault

Val

idR

ange

Des

crip

tion

ldap.group-map-lifespan

600

->86

400

Dur

atio

nin

seco

nds

for

whi

chth

een

try

stay

sin

the

map

,use

dto

conv

ert

grou

pna

tive

nam

es(D

Ns)

into

Secu

rity

Acc

ess

Man

ager

IDs.

ldap.late-lockout-notification

Fals

etr

ue,f

alse

Not

ifie

sth

eus

erw

hen

the

acco

unt

islo

cked

due

tose

vera

lpa

ssw

ord

logi

nat

tem

pts

dur

ing

the

n+1th

logi

nra

ther

than

the

nth.H

ere,

nis

the

valu

eof

max

Faile

dLog

ins

polic

yat

trib

ute

inef

fect

for

the

user

.

ldap.basic-user-support

[ldap]

basic-user-support

New

,Opt

iona

lFa

lse

true

,fal

seIf

the

valu

eis

set

totr

ue,t

hen

basi

cus

ersu

ppor

tis

enab

led

.All

Full

and

Bas

icSe

curi

tyA

cces

sM

anag

erus

erac

coun

tsar

elo

cate

dby

usin

gth

eldap.basic-user-principal-attribute

attr

ibut

ein

thei

rL

DA

PN

ativ

eus

eren

try.

Thi

sal

soin

clud

esex

isti

ngSe

curi

tyA

cces

sM

anag

erFu

llus

ers.

Soif

the

Secu

rity

Acc

ess

Man

ager

Full

user

prin

cipa

lna

me

doe

sno

tm

atch

the

valu

eof

thei

rat

trib

ute

that

issp

ecif

ied

byldap.basic-user-principal-attribute,

then

thei

rID

will

chan

ge.

ldap.basic-user-search-suffix

[ldap]

basic-user-search-

suffix

New

,Opt

iona

lIf

ava

lue

isno

tpr

ovid

ed,i

tus

esth

ese

tof

suff

ixes

norm

ally

used

bySe

curi

tyA

cces

sM

anag

er.I

fsp

ecif

ied

,it

mus

tlis

tal

lsu

ffix

esth

atar

eto

bese

arch

edfo

rB

asic

and

Full

Secu

rity

Acc

ess

Man

ager

user

s.If

the

suff

ixth

atco

ntai

nsth

eSe

curi

tyA

cces

sM

anag

erd

omai

n,sec_master

,an

dSe

curi

tyA

cces

sM

anag

erse

rver

acco

unts

isno

tsp

ecif

ied

,it

isau

tom

atic

ally

add

edas

this

suff

ixis

requ

ired

.

Eac

hsu

ffix

isse

para

ted

bya

sem

icol

on(;)

char

acte

r.

ldap.basic-user-no-duplicates

[ldap]

basic-user-no-

duplicates

New

,Opt

iona

lTr

uetr

ue,f

alse

Ifth

eva

lue

isse

tto

true

,the

nth

eco

de

sear

ches

all

ldap.basic-user-search-suffixes

for

am

atch

toth

eFu

llor

Bas

icus

erpr

inci

pal

ID.I

fm

ore

than

one

mat

chis

foun

d,t

heus

eris

repo

rted

asno

t-fo

und

.

Ifth

eva

lue

isse

tto

fals

e,th

enth

ese

arch

stop

saf

ter

am

atch

isfo

und

.T

hese

arch

still

det

ects

dup

licat

eson

the

sam

esu

ffix

,but

not

acro

ssd

iffe

rent

suff

ixes

.The

adva

ntag

eof

this

opti

onis

that

ifth

ead

min

istr

ator

can

guar

ante

eth

atd

uplic

ates

do

not

exis

tac

ross

suff

ixes

,the

nth

eus

erca

nbe

loca

ted

quic

ker

asso

me

suff

ixse

arch

esco

uld

besk

ippe

d.

ldap.basic-user-suffix-optimizer

[ldap]

basic-user-suffix-

optimizer

New

,Opt

iona

lTr

uetr

ue,f

alse

Thi

sop

tion

has

noef

fect

ifldap.basic-user-no-duplicates

isse

tto

true

.

Ifth

eva

lue

isse

tto

true

,the

nth

eba

sic

user

suff

ixes

are

sear

ched

inan

opti

miz

edor

der

base

don

hit

coun

t(s

ucce

ssfu

llylo

cati

nga

user

inth

esu

ffix

).T

his

can

help

red

uce

the

num

ber

ofsu

ffix

esse

arch

ed.

Ifth

eva

lue

isse

tto

fals

e,th

enth

epr

ovid

edor

der

ofldap.basic-user-search-suffix

isus

ed.I

fno

t,an

inte

rnal

lyse

lect

edor

der

isus

ed.

authz.enable-authorization

New

,Opt

iona

lFa

lse

true

,fal

seW

hen

Ldap

Rgy

Reg

istr

yFac

tory

.get

Rgy

Reg

istr

yIns

tanc

e(U

RL

propertiesUrl,

Mapenhancements

)is

used

,it

reco

gniz

esth

eop

tion

and

enab

les

the

auth

oriz

atio

nof

the

API

oper

atio

ns.P

rovi

de

auth

z.pd

auth

oriz

aton

cont

ext-

user

,use

das

adm

inus

eran

dau

thor

izes

each

acce

ss.


Tabl

e34

.C

onfig

urat

ion

optio

ns(c

ontin

ued)

Java

Op

tion

Nam

eE

xist

ing

Com

par

able

Op

tion

Exi

sten

cein

curr

ent

Java

Con

fig

Def

ault

Val

idR

ange

Des

crip

tion

authz.pdauthorization

context-user

New

,Opt

iona

l

(con

dit

iona

l)

Secu

rity

Acc

ess

Man

ager

user

IDW

hen

auth

z.en

able

-aut

hori

zati

onis

set,

this

user

IDis

auth

oriz

edin

API

oper

atio

ns.I

fau

thz.

pdau

thor

izat

onco

ntex

t-pw

dis

also

spec

ifie

d,t

hen

the

Secu

rity

Acc

ess

Man

ager

user

acco

unt

has

anad

dit

iona

lpu

rpos

e.

The

user

acco

unt

ispa

ssed

wit

hth

epa

ssw

ord

toth

eco

nstr

ucti

onof

the

PD

Aut

hori

zati

onC

onte

xtco

nstr

ucte

dby

the

API

.

Ifre

quir

ed,y

ouca

nov

erri

de

the

join

tus

age

byca

lling

Aut

hzR

gyR

egis

tryF

acto

ry.u

pdat

eAdm

inId

(Rgy

Reg

istr

yrg

yReg

istr

y,St

ring

adm

inU

serI

d).D

oing

soch

ange

sth

eSe

curi

tyA

cces

sM

anag

erID

used

inth

eau

thor

izat

ion

dec

isio

n.

authz.pdauthorization

context-pwd

New

,Opt

iona

lSe

curi

tyA

cces

sM

anag

erus

erpa

ssw

ord

Ifyo

usp

ecif

yau

thz.

pdau

thor

izat

onco

ntex

t-pw

dal

ong

wit

hau

thz.

pdau

thor

izat

onco

ntex

t-us

er,t

heSe

curi

tyA

cces

sM

anag

erus

eran

dpa

ssw

ord

are

pass

edto

the

cons

truc

tion

ofth

eP

DA

utho

riza

tion

Con

text

.Thi

sis

cons

truc

ted

byth

eA

PIus

edto

prov

ide

auth

oriz

atio

nd

ecis

ion

outc

omes

for

API

oper

atio

ns.

authz.enable-audit

New

,Opt

iona

lFa

lse

true

,fals

eW

hen

you

useLdapRgyRegistryFactory.getRgyRegistryInstance(URL

propertiesUrl,

Mapenhancements),

itre

cogn

izes

this

opti

on,

and

enab

leth

eA

PIop

erat

ion

aud

itin

g.If

you

do

not

enab

leau

thz.

enab

le-a

utho

riza

tion

opti

on,t

heus

erw

hod

oes

this

oper

atio

nis

anun

auth

enti

cate

dus

er.

authz.audit-file-pattern

New

,Opt

iona

l

(con

dit

iona

l)

File

nam

epa

tter

nE

nabl

esau

thz.

enab

le-a

udit

.Pas

sth

isat

trib

ute

toth

eJa

vaja

va.u

til.l

oggi

ng.F

ileH

andl

erco

nstr

ucto

rto

prov

ide

appr

opri

ate

des

crip

tion

for

the

doc

umen

tati

on.

authz.audit-file-limit

New

,Opt

iona

l0

0->

MA

XIN

TE

GE

RPa

ssed

toth

eJa

vaja

va.u

til.l

oggi

ng.F

ileH

andl

erco

nstr

ucto

rso

that

doc

umen

tati

onha

sth

eap

prop

riat

ed

escr

ipti

on.

authz.audit-file-count

New

,Opt

iona

l1

1,81

92Pa

ssed

toth

eJa

vaja

va.u

til.l

oggi

ng.F

ileH

andl

erco

nstr

ucto

rto

ensu

reth

atth

ed

ocum

enta

tion

has

the

appr

opri

ate

des

crip

tion

.

appsvr-servername

Alr

eady

pres

ent,

Opt

iona

l

(con

dit

iona

l)

stri

ngSe

tth

isop

tion

ifau

thz.

enab

le-a

udit

isen

able

d.

Use

this

opti

onto

segr

egat

eth

eap

plic

atio

nby

usin

gth

ene

wR

egis

try

Dir

ect

Java

API

inJa

vaL

ogge

rna

me

spac

efo

rau

dit

logg

ing.

For

exam

ple,

The

aud

itna

mes

are

com

.tivo

li.pd

.rgy

.aut

hz.

test

app-

tam

611.

mgm

tan

dco

m.ti

voli.

pd.r

gy.a

uthz

.test

app-

tam

611.

auth

n.te

stap

p-ta

m61

1is

the

stri

ngpa

ssed

.N

ote:

Alt

houg

hth

eau

dit

logg

eris

liste

din

the

Java

Log

ger

nam

esp

ace,

itou

tput

sth

ere

cord

sin

toit

sow

nfi

le.Y

ouca

nen

able

ord

isab

leth

eou

tput

toth

eau

dit

log

file

byin

crea

sing

ord

ecre

asin

gth

eJa

valo

ggin

gle

vel

for

the

aud

itlo

gger

nam

es.

authz.authorize-group-list

[delegated-admin]

authorize-group-list

New

,Opt

iona

lFa

lse

true

,fal

seIn

dic

ates

whe

ther

the

API

mus

tch

eck

the

auth

oriz

atio

non

the

listGroup()

andlistNativeGroups()

.


Tabl

e34

.C

onfig

urat

ion

optio

ns(c

ontin

ued)

Java

Op

tion

Nam

eE

xist

ing

Com

par

able

Op

tion

Exi

sten

cein

curr

ent

Java

Con

fig

Def

ault

Val

idR

ange

Des

crip

tion

sepa

rate

dlis

tof

LD

AP

serv

erd

etai

ls.

Eac

hse

rver

det

ail

isa

colo

nse

para

ted

set

ofat

trib

utes

ofth

efo

rm:

host:port:type:rank[,host2:

port2:type2:rank2[,...]]

whe

retype

isei

ther

readwrite

orreadonly

and

rank

isa

valu

efr

om0

to10

.For

exam

ple:

ldaphost:389:readwrite:5

ism

odif

ied

toa

list

ofL

DA

Pse

rver

det

ails

that

are

sepa

rate

dby

';'s.

fed-server.<serverid>.

ldap.bind-dn

[server:

<serverid>]bind-dn

New

,Req

uire

dT

heD

Nto

sim

ple

bind

toL

DA

Pfo

ral

lm

anag

emen

tL

DA

Pop

erat

ions

.


ldap.bind-pwd

[server:

<serverid>]bind-pwd

New

,Req

uire

dT

heL

DA

Pbind-dn

acco

unt

pass

wor

d.S

vrSs

lCfg

and

Rgy

Con

figob

fusc

ates

this

valu

ein

the

conf

igur

atio

nfi

le.


ldap.ssl-enable

[server:

<serverid>]ssl-enable

New

,Opt

iona

lFa

lse

Set

this

opti

onto

true

toen

able

SSL

toth

eL

DA

Pse

rver

.


ldap.ssl-server-start-tls

[server:

<serverid>]

ssl-server-start-tls

New

,Opt

iona

lFa

lse

true

,fal

sev

Ifse

tto

true

,Reg

istr

yD

irec

tA

PIup

grad

esth

eun

encr

ypte

dT

CP

LD

AP

conn

ecti

onto

encr

ypte

dby

usin

gth

eLDAP

START_TLS

exte

nded

oper

atio

n.

vldap.ssl-enable

mus

tbe

fals

eif

set

totr

ue.


ldap.suffix=

suffixA;[suffixB;[...]]

[server:

<serverid>]suffix

New

,Req

uire

d';'

sepa

rate

dlis

tof

LD

AP

DN

stri

ngs.

Spec

ifie

sth

esu

ffix

esto

use

from

this

fed

erat

edL

DA

Pse

rver

.

fed-server.<serverid>.ldap

.bind-auth-and-pwdchg

[server:

<serverid>]

bind-auth-and-pwdchg

New

,Opt

iona

lFa

lse

true

,fal

sev

Ifse

tto

true

,Reg

istr

yD

irec

tA

PIus

esbi

ndto

auth

enti

cate

user

san

da

conn

ecti

onth

atis

boun

das

the

user

toch

ange

thei

rpa

ssw

ord

inca

ses

whe

reth

eol

dan

dne

wpa

ssw

ord

sar

epr

ovid

ed.


isig

nore

dfo

rth

ese

rver

.

vA

sing

leL

DA

Pop

erat

ion

that

com

bine

sbo

thre

mov

eol

dpa

ssw

ord

and

add

new

pass

wor

dar

eus

edas

requ

ired

byso

me

LD

AP

serv

ersu

chas

Act

ive

Dir

ecto

ry.U

sers

mus

tal

soha

veap

prop

riat

eL

DA

P/A

DA

CL

sth

atal

low

them

toch

ange

thei

row

npa

ssw

ord

.Fo

rA

ctiv

eD

irec

tory

,thi

sse

ttin

gis

the

def

ault

.For

othe

rL

DA

Ps,a

nA

CL

may

need

tobe

add

ed.


ldap.max-server-connections

[server:

<serverid>]

max-server-connections

New

,Opt

iona

l16

Ind

icat

esth

em

axim

umnu

mbe

rof

conn

ecti

ons

that

can

exis

tto

the

LD

AP

serv

er.


ldap.dynamic-groups-enabled

[server:

<serverid>]

dynamic-groups-enabled

New

,Opt

iona

lFa

lse

vSo

me

regi

stri

esm

ight

not

supp

ort

this

opti

on.

vFo

rTi

voli

Dir

ecto

rySe

rver

,thi

sse

ttin

gis

alw

ays

enab

led

beca

use

ofth

eus

eof

ibm-allGroups.


http://msdn.microsoft.com/en-us/library/cc223248.aspx

Tabl

e34

.C

onfig

urat

ion

optio

ns(c

ontin

ued)

Java

Op

tion

Nam

eE

xist

ing

Com

par

able

Op

tion

Exi

sten

cein

curr

ent

Java

Con

fig

Def

ault

Val

idR

ange

Des

crip

tion


ldap.user-objectclass

[server:

<serverid>]

user-objectclass

Def

ault

valu

eis

LD

AP

serv

erty

ped

epen

den

t.

Whe

npr

ovid

edto

the

conf

igur

atio

nto

ol,i

tco

ntai

nsa

list

ofco

mm

a-se

para

ted

obje

ctcl

ass

nam

esto

set

whe

ncr

eati

nga

nati

veus

eren

try

inL

DA

P.

For

exam

ple:

top,

pers

on,o

rgan

izat

iona

lPer

son,

inet

Org

Per

son,

ePer

son.

SvrSslCfg

that

mod

ifie

sth

elis

tto

be";

"(s

emic

olon

)se

para

ted

whe

nit

plac

esit

inth

eco

nfig

urat

ion

prop

erti

esfi

le.


ldap.static-group-

objectclass

[server:

<serverid>]

static-group-

objectclass

Def

ault

valu

eis

LD

AP

serv

erty

ped

epen

den

t.

Whe

npr

ovid

edto

the

conf

igur

atio

nto

ol,i

tco

ntai

nsa

list

ofco

mm

a-se

para

tedobjectClass

nam

esto

set

whe

ncr

eati

nga

nati

vegr

oup

entr

yin

LD

AP.

Onl

yno

n-d

ynam

icgr

oups

are

crea

ted

bySe

curi

tyA

cces

sM

anag

er.F

orex

ampl

e,to

p,gr

oupO

fNam

es.

SvrSslCfg

mod

ifie

sth

elis

tto

be‘;'

(sem

icol

on)

sepa

rate

dw

hen

itpl

aces

itin

the

conf

igur

atio

npr

oper

ties

file

.


ldap.user-search-filter

[server:

<serverid>]

user-search-filter

Def

ault

valu

eis

LD

AP

serv

erty

ped

epen

den

t.

An

LD

AP

sear

chfi

lter

that

sele

cts

any

nati

veus

eren

try.

For

exam

ple:

(|(o

bjec

tcla

ss=

ePer

son)

(obj

ectc

lass

=P

erso

n)).


ldap.group-search-filter

[server:

<serverid>]

group-search-filter

Def

ault

valu

eis

LD

AP

serv

erty

ped

epen

den

t.

An

LD

AP

sear

chfi

lter

that

sele

cts

any

nati

vegr

oup

entr

y.Fo

rex

ampl

e:

(|(objectclass=accessGroup)

(objectclass=groupOfNames)

(objectclass=groupOfUniqueNames)

(objectclass=groupOfURLs))


ldap.is-member-of-attribute

[server:

<serverid>]

is-member-of-attribute

New

,Opt

iona

lD

efau

ltva

lue

isL

DA

Pse

rver

type

dep

end

ent.

The

nam

eof

anat

trib

ute

inus

eren

trie

sth

atpr

ovid

esa

list

ofgr

oup

DN

sth

eus

eris

am

embe

rof

.Thi

sis

anop

tim

izat

ion

prov

ided

byso

me

LD

AP

serv

ers.


ldap.follow-referrals

[server:

<serverid>]

follow-referrals

New

,Opt

iona

lFa

lse

true

,fal

sev

Ifse

tto

true

,the

LD

AP

clie

nt,J

ND

I,fo

llow

sth

eL

DA

Pre

ferr

als

toot

her

serv

ers.

Iffa

lse,

itig

nore

sre

ferr

als.


ldap.basic-user-principal

-attribute

[server:

<serverid>]

basic-user-principal-

attribute

New

,Opt

iona

lIf

ava

lue

isno

tpr

ovid

ed,t

hesy

stem

uses

ad

efau

ltva

lue

that

dep

end

son

the

type

ofL

DA

Pse

rver

.For

exam

ple,

for

ISD

S,uid

isus

edby

def

ault

;for

AD

,userPrincipalName

isus

edby

def

ault

.


ldap.basic-user-principal

-add

[server:

<serverid>]

basic-user-principal-

add

New

,Opt

iona

lIf

ava

lue

isno

tsp

ecif

ied

,it

def

ault

sto

the

empt

yst

ring

.

Ifa

valu

eis

spec

ifie

d,t

hen

the

valu

est

ring

isap

pend

edto

the

prin

cipa

lID

prov

ided

toth

eA

PIbe

fore

sear

chin

gfo

rth

eB

asic

orFu

llus

er,a

ndre

mov

edw

hene

ver

the

Bas

icor

Full

user

prin

cipa

lID

isre

turn

edby

the

API

.

Thi

sop

tion

isty

pica

llyus

edby

the

AD

mig

rati

onto

olto

allo

wFe

der

ated

AD

regi

stri

esto

avoi

dus

ing

the

trai

ling@domain

stri

ngbu

tst

illus

eth

euserPrincipalName

attr

ibut

e.


Example usage

Creating an instance of RgyRegistry

After creating the configuration file, use this API with the corresponding LDAPaccount on the existing Security Access Manager registry. If the configuration file islocated at /opt/testapp/testapp.properties, then the sample configuration file isas follows:URL propertiesUrl = null;try {propertiesUrl = new URL("file:///opt/testapp/testapp.properties");}catch (MalformedURLException e) {e.printStackTrace();System.exit(1);}

RgyRegistry rgyRegistry = null;try {rgyRegistry = LdapRgyRegistryFactory.getRgyRegistryInstance(propertiesUrl, null);}catch (RgyException e) {e.printStackTrace();System.exit(1);}

Ending use of RgyRegistry

Close the RgyRegistry instance when your application does not use the instanceanymore. The sample usage is as follows:rgyRegistry.close();

Groups

Creating a group

The following sample demonstrates how to create a Security Access Managergroup called testgroup with LDAP DN cn=testgroup,o=ibm,c=us.

Example:String groupId = "testgroup";String groupCn = “testgroup”;String groupNativeId = "cn=testgroup,o=ibm,c=us”;RgyAttributes rgyAttributes = rgyRegistry.newRgyAttributes();rgyAttributes.putAttribute(RgyAttributes.COMMON_NAME_NAME, groupCn);rgyAttributes.putAttribute(RgyAttributes.DESCRIPTION_NAME,"This is a test Group");RgyGroup rgyGroup = null;try {rgyGroup = rgyRegistry.createGroup(“Default”, groupId, groupNativeId,rgyAttributes);}catch (RgyException e) {e.printStackTrace();System.exit(1);}


This example obtains a RgyAttributes instance to create the group and set thegroup attributes, assuming that the Security Access Manager domain is default andthat it contains a suffix o=ibm,c=us in LDAP.

Showing group details

The following sample displays the information about the group.// Fetch the groupString groupId = “testgroup”;RgyGroup rgyGroup = null;try {rgyGroup = rgyRegistry.getGroup(“Default”, groupId);}catch (RgyException e) {e.printStackTrace();System.exit(1);}// Ensure the group was foundif (rgyGroup == null) {System.out.println(“Group does not exist”);System.exit(1);}System.out.println(“Group ID: “+rgyGroup.getId());System.out.println(“LDAP DN: “+rgyGroup.getNativeId());String description =String) rgyGroup. getOneAttributeValue(RgyAttributes.DESCRIPTION_NAME);if (description == null) {description = “”;}System.out.println(“Description: “+description);System.out.println(“LDAP CN: “+rgyGroup. getOneAttributeValue(RgyAttributes.COMMON_NAME_NAME);String isSecEntity =String) rgyGroup.getOneAttributeValue(RgyAttributes. IS_SEC_ENTITY_NAME);if (isSecEntity.equalsCaseIgnore(RgyAttributes. BOOL_TRUE_VALUE)) {isSecEntity = “Yes”;}else {isSecEntity = “No”;}System.out.println(“Is SecGroup: “+isSecEntity);

Deleting a groupThe following sample code displays the steps to delete the Security AccessManager group testgroup from the Security Access Manager domain Default andremove the native LDAP entry.

The last parameter of deleteGroup() is set to true.

If the native LDAP entry is also a member of another Security Access Managerdomain, or another application places child entries, the removal of the nativeLDAP entry fails. Despite this error, the Security Access Manager component is stillremoved.String groupId = “testgroup”;try {rgyRegistry.deleteGroup(“Default”, groupId, true);}catch (WarningNativeEntityInUseRgyException e) {System.out.println(“Warning: unable to remove native LDAP entry”);// Ignore}


catch (RgyException e) {e.printStackTrace();System.exit(1);}

Importing a native group

Existing native LDAP groups can be imported as Security Access Manager groups.Obtain the native LDAP group information as aRgyGroup instance, then invoke theRgyGroup.importNativeGroup() method.

The following sample shows the sample code to import the native group asSecurity Access Manager group:// First fetch the Native EntityString groupNativeId = "cn=testgroup,o=ibm,c=us”;RgyGroup rgyGroup = null;try {rgyGroup = rgyRegistry.getNativeGroup(“Default”, groupNativeId);}catch (RgyException e) {e.printStackTrace();System.exit(1);}// Ensure the group was foundif (rgyGroup == null) {System.out.println(“Group does not exist”);System.exit(1);}// Only import, if not already a TAM group (isSecEntity=FALSE)String isSecEntity = (String) rgyGroup.getOneAttributeValue(RgyAttributes. IS_SEC_ENTITY_NAME);if (isSecEntity.equalsIgnoreCase(RgyAttributes. BOOL_FALSE_VALUE)) {String groupId = "testgroup";RgyAttributes rgyAttributes = rgyRegistry.newRgyAttributes();try {rgyGroup.importNativeGroup(groupId, rgyAttributes);}catch (RgyException e) {e.printStackTrace();System.exit(1);}}

Listing group members

The following sample displays the sample code to list the members belonging to aspecific group. Ensure that you fetch the group before you list its members. Themembers are returned as a set of string values.// Fetch the groupString groupId = “testgroup”;RgyGroup rgyGroup = null;try {rgyGroup = rgyRegistry.getGroup(“Default”, groupId);}catch (RgyException e) {e.printStackTrace();System.exit(1);}// Ensure the group was foundif (rgyGroup == null) {System.out.println(“Group does not exist”);System.exit(1);}


// Get Set of group’s member IDsSet userIds = null;try {userIds = rgyGroup.listMemberIds();}catch (RgyException e) {e.printStackTrace();System.exit(1);}// Display the member IDsSystem.out.print("Members=");Iterator iter = userIds.iterator();while (iter.hasNext()) {String userId = (String) iter.next();System.out.print(userId+", ");}System.out.println();

A list of the groups members as native user IDs can be obtained usingrgyGroup.listMemberNativeIds(). The native ID Set includes non-TAM users.

Add or remove group members

The following example displays the code to add or remove the group members.Before modifying, ensure that you fetch the user.// Fetch the groupString groupId = “testgroup”;RgyGroup rgyGroup = null;try {rgyGroup = rgyRegistry.getGroup(“Default”, groupId);}catch (RgyException e) {e.printStackTrace();System.exit(1);}// Ensure the group was foundif (rgyGroup == null) {System.out.println(“Group does not exist”);System.exit(1);}// Create a List of user IDs and add to groupList userIds = new ArrayList();userIds.add(“testuser”);try {rgyGroup.addMembers(userIds);}catch (RgyException e) {e.printStackTrace();System.exit(1);}// Remove List of user IDs from the grouptry {rgyGroup.removeMembers(userIds);}catch (RgyException e) {e.printStackTrace();System.exit(1);}

Modifying group attributeThe following example demonstrates how to modify the groups descriptionattribute.


Before you modify a group, you must fetch the group.

Groups do not have many attributes that can be modified.// Fetch the groupString groupId = “testgroup”;RgyGroup rgyGroup = null;try {rgyGroup = rgyRegistry.getGroup(“Default”, groupId);}catch (RgyException e) {e.printStackTrace();System.exit(1);}// Ensure the group was foundif (rgyGroup == null) {System.out.println(“Group does not exist”);System.exit(1);}// Replace the current attributetry {rgyGroup.attributeReplace(RgyAttributes.DESCRIPTION_NAME,“Replacement Description”);}catch (RgyException e) {e.printStackTrace();System.exit(1);}// Remove the description attributetry {rgyGroup.attributeDelete(RgyAttributes.DESCRIPTION_NAME);}catch (RgyException e) {e.printStackTrace();System.exit(1);}

Users and per-user policy

Assuming that the Security Access Manager domain is Default and that there is asuffix o=ibm,c=us in LDAP, the following code creates a Security Access Manageruser called testuser. This testuser has the LDAP DN cn=testuser,o=ibm,c=us.First, obtain an RgyAttributes instance to set the users attributes and then createthe user. A few optional attributes set for the user during the time of creationinclude account and password policy and account state.// Setup the required attributesRgyAttributes rgyAttributes = registry.newRgyAttributes();rgyAttributes.putAttribute(RgyAttributes.COMMON_NAME_NAME,“testuser”);rgyAttributes.putAttribute(RgyAttributes.SURNAME_NAME, “user”);// Setup some optional attributesrgyAttributes.putAttribute(RgyAttributes.MIN_PASSWORD_LENGTH_NAME, "8");rgyAttributes.putAttribute(RgyAttributes.MAX_LOGIN_FAILURES_NAME, "2");rgyAttributes.putAttribute(RgyAttributes.DISABLE_TIME_INTERVAL_NAME, "0");Date currentTime = new Date();currentTime.setTime(currentTime.getTime() + (3600 * 1000L));String registryDate = null;try {registryDate = registry.toRegistryDate(currentTime);}catch (RgyException e) {e.printStackTrace();System.exit(1);}rgyAttributes.putAttribute(RgyAttributes.ACCOUNT_EXPIRY_DATE_NAME,registryDate);


rgyAttributes.putAttribute(RgyAttributes.SEC_ACCT_VALID_NAME,RgyAttributes.BOOL_TRUE_VALUE);// Create the userString userId = "testuser”;String userNativeId = "cn=testuser,o=ibm,c=us”;RgyUser rgyUser = null;try {user = registry.createUser(“Default”, userId, userNativeId, "passw0rd".toCharArray(), true, rgyAttributes, null);}catch (RgyException e) {e.printStackTrace();System.out.println("FAILED: Unable to create user: "+id);System.exit(1);}

Showing user details

The following example displays the user details such as User ID, Native ID,Common name, Surname, and descriptive name.RgyUser rgyUser = null;try {rgyUser = registry.getUser(null, userId);}catch (RgyException e) {e.printStackTrace();System.exit(1);}if (rgyUser == null) {System.out.println(“User not found”);System.exit(1);}System.out.println(“Login ID: “+rgyUser.getId());System.out.println(“LDAP DN: “+rgyUser.getNativeId());System.out.println(“LDAP CN: “+rgyUer.getOneAttributeValue(RgyAttributes.COMMON_NAME_NAME);System.out.println(“LDAP SN: “+rgyUser.getOneAttributeValue(RgyAttributes.SURNAME_NAME);String description = (String) rgyUser.getOneAttributeValue(RgyAttributes.DESCRIPTION_NAME);if (description == null) {description = “”;}System.out.println(“Description: “+description);System.out.println(“Is SecUser: “+yesNo(rgyUser, RgyAttributes. IS_SEC_ENTITY_NAME);System.out.println(“Is GSO user: “+yesNo(rgyUser, RgyAttributes. IS_GSO_USER_NAME));System.out.println(“Account valid: “+yesNo(rgyUser, RgyAttributes. SEC_ACCT_VALID_NAME));System.out.println(“Password valid: “+yesNo(rgyUser, RgyAttributes. SEC_PWD_VALID_NAME));

//-----

String yesNo(RgyEntity rgyEntity, String attributeName){String value = (String) rgyGroup.getOneAttributeValue(attributeName);if (value.equalsCaseIgnore(RgyAttributes. BOOL_TRUE_VALUE)) {value = “Yes”;}else {


value = “No”;}return value;}

Deleting a userIf the native LDAP entry is a member of another Security Access Manager domain,or another application has placed child entries beneath it, the removal of the nativeLDAP entry fails. An exception is thrown from the API but the Security AccessManager component is still removed.

The following example deletes the Security Access Manager user testuser from theDefault Security Access Manager domain and removes the native LDAP entry. Lastparameter of deleteUser() is set to true.String userId = “testuser”;try {rgyRegistry.deleteUser(“Default”, userId, true);}catch (WarningNativeEntityInUseRgyException e) {System.out.println(“Warning: unable to remove native LDAP entry”);// Ignore}catch (RgyException e) {e.printStackTrace();System.exit(1);}

Importing a native user

You can import the existing native LDAP users as Security Access Manager users.The native LDAP user information must be obtained as an RgyUser instance, thenthe RgyUser.importNativeGroup() method can be invoked. The following exampleimports a Default native user as a Security Access Manager user testuser fromthe native LDAP entry. Last parameter of deleteUser() is set to true./ First fetch the Native EntityString userNativeId = "cn=testuser,o=ibm,c=us”;RgyUser rgyUser = null;try {rgyUser = rgyRegistry.getNativeUser(“Default”, userNativeId);}catch (RgyException e) {e.printStackTrace();System.exit(1);}// Ensure the Native user was foundif (rgyUser == null) {System.out.println(“Group does not exist”);System.exit(1);}// Only import, if not already a TAM user (isSecEntity=FALSE)String isSecEntity = (String) rgyUser.getOneAttributeValue(RgyAttributes. IS_SEC_ENTITY_NAME);if (isSecEntity.equalsIgnoreCase(RgyAttributes. BOOL_FALSE_VALUE)) {String userId = "testuser";RgyAttributes rgyAttributes = rgyRegistry.newRgyAttributes();// Setup an optional attributergyAttributes.putAttribute(RgyAttributes.SEC_ACCT_VALID_NAME,RgyAttributes.BOOL_TRUE_VALUE);try {rgyUser.importNativeUser(userId, rgyAttributes, null);}catch (RgyException e) {


e.printStackTrace();System.exit(1);}}

Listing a user's group memberships

Fetch the user before listing its group memberships. Returns the groups the userbelongs to as a set of string:// Fetch the userString userId = “testuser”;RgyUser rgyUser = null;try {rgyUser = rgyRegistry.getUser(“Default”, userId);}catch (RgyException e) {e.printStackTrace();System.exit(1);}// Ensure the user was foundif (rgyUser == null) {System.out.println(“Group does not exist”);System.exit(1);}// Get Set of group IDs the user is a memberofSet groupIds = null;try {groupIds = rgyUser.listGroups();}catch (RgyException e) {e.printStackTrace();System.exit(1);}// Display the group IDsSystem.out.print("Groups=");Iterator iter = GroupIds.iterator();while (iter.hasNext()) {String groupId = (String) iter.next();System.out.print(groupId+", ");}System.out.println();

A list of the user group memberships as group native ID can also be obtainedusing rgyUser.listNativeGroups () instead. The native ID set can include groupsthat are not Security Access Manager groups.

Modifying user attributesEnsure that you fetch the user before you modify the user attributes.// Fetch the userString userId = “testuser”;RgyUser rgyUser = null;try {rgyUser = rgyRegistry.getUser(“Default”, userId);}catch (RgyException e) {e.printStackTrace();System.exit(1);}// Ensure the user was foundif (rgyUser == null) {System.out.println(“Group does not exist”);System.exit(1);}


// Set the password-validtry {rgyUser.attributeReplace(RgyAttributes.SEC_PWD_VALID_NAME,RgyAttributes.BOOL_TRUE_VALUE);}catch (RgyException e) {e.printStackTrace();System.exit(1);}// Unset the max-login-failures policytry {rgyUser.attributeDelete(RgyAttributes. MAX_LOGIN_FAILURES_NAME);}catch (RgyException e) {e.printStackTrace();System.exit(1);}// Set the min-password-length policy to 7try {rgyUser.attributeReplace(RgyAttributes.MIN_PASSWORD_LENGTH_NAME, “7”);}catch (RgyException e) {e.printStackTrace();System.exit(1);}

Resetting the user passwordThis action is the equivalent to pdamin command user modify testuser passwordchangeme.

The following example shows how to perform an administrative reset of the userpassword:// Fetch the userString userId = testuser;RgyUser rgyUser = null;try {rgyUser = rgyRegistry.getUser(Default, userId);}catch (RgyException e) {e.printStackTrace();System.exit(1);}// Ensure the user was foundif (rgyUser == null) {System.out.println(Group does not exist);System.exit(1);}try {rgyUser = rgyUser.setPassword(changeme.toCharArray());}catch (RgyException e) {e.printStackTrace();System.exit(1);}

Changing the user passwordTo change the user password, authenticate the old password and request to set anew password.

This operation is similar to a pkmspasswd of WebSEAL. The following exampleshows the sample code for changing the oldpassword to newpassword for a usertestuser:


// Fetch the userString userId = “testuser”;RgyUser rgyUser = null;try {rgyUser = rgyRegistry.getUser(“Default”, userId);}catch (RgyException e) {e.printStackTrace();System.exit(1);}// Ensure the user was foundif (rgyUser == null) {System.out.println(“Group does not exist”);System.exit(1);}try {rgyUser = rgyUser.changePassword(“oldpassword”.toCharArray(),“newpassword”.toCharArray());}catch (RgyException e) {e.printStackTrace();System.exit(1);}

Authenticating the user PasswordThis section provides an example showing the authentication script.

The following example shows about authentication the default user passwordpassw0rd .// Fetch the userString userId = “testuser”;RgyUser rgyUser = null;try {rgyUser = rgyRegistry.getUser(“Default”, userId);}catch (RgyException e) {e.printStackTrace();System.exit(1);}// Ensure the user was foundif (rgyUser == null) {System.out.println(“Group does not exist”);System.exit(1);}try {rgyUser = rgyUser.authenticate(“passw0rd”.toCharArray());}catch (RgyException e) {e.printStackTrace();System.exit(1);}


Appendix C. User registry differences

Each user registry presents unique concerns when integrated with Security AccessManager.

Security Access Manager supports the following LDAP user registries:v Tivoli Directory Serverv IBM z/OS® Security Server LDAP Serverv Microsoft Active Directory Lightweight Directory Services (AD LDS) (Windows

2008)v Novell eDirectory Serverv Sun Java System Directory Server, version 7.0

General concerns

The following concerns are specific to all the supported user registries:v Avoid using the forward slash (/) character when defining the names for users

and groups when that name is defined using distinguished names strings. Eachuser registry treats this character differently.

v Avoid using leading and trailing blanks in user and group names. Each userregistry treats blanks in a different manner.

LDAP concerns

The following concerns are specific to all the supported LDAP user registries:v There are no configuration steps required for Security Access Manager to

support the Password Policy of LDAP. Security Access Manager does not assumethe existence or non-existence of the Password Policy of the LDAP at all.Security Access Manager enforces its own Password Policy first. Security AccessManager attempts to update password in LDAP only when the providedpassword passes Password Policy check of Security Access Manager.After that, Security Access Manager tries to accommodate the Password Policyof LDAP to the best of its ability using the return code that it gets from LDAPduring a password-related update.If Security Access Manager can map the return code without any ambiguity withthe corresponding Security Access Manager error code, it does so and returns aproper error message.

v To take advantage of the multi-domain support in Security Access Manager, youmust use an LDAP user registry.

v When using an LDAP user registry, the capability to own global sign-oncredentials must be explicitly granted to a user. After this capability is granted, itcan be removed.

v Leading and trailing blanks in user names and group names are ignored whenusing an LDAP user registry in a Security Access Manager secure domain. Toensure consistent processing regardless of the user registry, define user namesand group names without leading or trailing blanks.

v Attempting to add a single duplicate user to a group does not produce an errorwhen using an LDAP user registry.


v The Security Access Manager authorization API provides a credential attributeentitlements service. This service retrieves user attributes from a user registry.When this service is used with an LDAP user registry, the retrieved attributescan be string data or binary data.

Sun Java System Directory Server concernsThe following task describes how to modify the default value for the look-throughlimit on the directory server.

The following concerns are specific to Sun Java System Directory Server:

If the user registry contains more entries than the defined look-through limit, thedirectory server might return the following status that Security Access Managertreats as an error:LDAP_ADMINLIMIT_EXCEEDED

When the directory server is installed, the default value is 5000. To modify thisvalue, perform the following steps from the Sun Java System Directory ServerConsole:1. Select the Configuration tab.2. Expand the Data entry.3. Select Database Settings.4. Select the LDBM Plug-in Settings tab.5. In the Look-through Limit field, type the maximum number of entries that you

want the server to check in response to the search, or type -1 to define nomaximum limit.If you bind the directory as the Directory Manager, the look-through limit isunlimited and overrides any settings specified in this field.

Microsoft Active Directory Lightweight Directory Service (ADLDS) concerns

This section describes concerns specific to Microsoft Active Directory LightweightDirectory Service (AD LDS).

The following concerns are specific to AD LDS.v Policy Server configuration allows you to select between a standard or minimal

data model for the user registry. Because AD LDS allows only a single namingattribute to be used when creating LDAP objects, AD LDS requires the minimaldata model. Regardless of which data model is chosen during Policy Serverconfiguration, Security Access Manager will always use the minimal data modelwhen AD LDS is selected as the user registry.

v Because the common name (cn) value in AD LDS must be single valued, thevalue specified for the cn attribute must be the same value used for thedistinguished name (dn) when a user or group is created and cn is used as thenaming attribute in the dn.

Microsoft Active Directory Server concernsThe following concerns are specific to Microsoft Active Directory Server:v Users that are created in Active Directory might have an associated primary

group. The Active Directory default primary group is Domain Users.


However, the Active Directory does not add the primary group information tothe user memberOf or the group member attribute. When Security Access Managerqueries for a list of group members, the result does not include any memberswho belong to the primary group. When Security Access Manager queries for allthe groups where the user belongs, the result does not display the primarygroup of the user.For this reason, do not use a Security Access Manager group as the ActiveDirectory primary group for Security Access Manager users.

v Security Access Manager does not support cross domain group membership oruniversal groups. Security Access Manager does not support importing thesetypes of groups.

v When Security Access Manager imports a dynamic group, the ivacld-serversand remote-acl-users groups apply read permission on each authorization storeto which the dynamic group belongs.The read permission enables Security Access Manager blade servers, such asWebSEAL, to read permission to the registry authorization store. Thus, the bladeserver reads dynamic group data, such as group membership for buildingSecurity Access Manager credentials.Manually removing the read permission while Security Access Manager isconfigured to the Active Directory registry results in adverse behavior, such asinaccurate group membership.

v If the option to change the user password by using LDAP APIs is enabled in anenvironment where:– Security Access Manager is configured to use the Active Directory user

registry, and– Security Access Manager blade servers use LDAP APIs to communicate with

the Active Directory server

then Security Access Manager must be configured with Secure Socket Layer(SSL) to allow connections between the LDAP client and the Active Directoryserver. The Active Directory environment must also be enabled to accept LDAPconnections over Secure Socket Layer (SSL).

v When you use an Active Directory user registry in a Security Access Managerconfiguration with blade servers that use LDAP APIs to communicate with theActive Directory server, Security Access Manager supports user passwordchange requests by using either the Policy Server or LDAP APIs. Change userpassword requests by using the LDAP APIs do not require the Policy Server torun.The use of LDAP APIs to communicate with the Active Directory Server forblade servers is a multiplatform support that allows blade servers to be installedon systems that are not clients of the same domain as the policy server. In thisconfiguration, the policy server must be installed and configured on a Windowsoperating system.

v When you use an Active Directory user registry, each user name and each groupname in a domain must be unique. User and group short name values that arestored in the sAMAccountName attribute of Active Directory user objects and groupobjects. Active Directory user objects and group objects both have thesAMAccountName attribute as one of their attributes. Microsoft requires that thesAMAccountName attributes be unique within an Active Directory domain.

v When you use a multi-domain Active Directory user registry, multiple users andgroups can be defined with the same short name if they are in differentdomains. However, the full name of the user or group, including the domainsuffix, must always be specified to Security Access Manager.

Appendix C. User registry differences 121

v The following items are ignored when you use Microsoft Active Directory Serveras the user registry in a Security Access Manager secure domain:– Leading and trailing blanks in user names– Group names

To ensure consistent processing regardless of the user registry, define user namesand group names without leading or trailing blanks.

v Security Access Manager supports the use of an email address or other formatsof the userPrincipalName attribute of the Active Directory registry user object asa Security Access Manager user identity. When the option is enabled, both thedefault and the email address or another userPrincipalName format can co-existin the Security Access Manager environment.The default format of the userPrincipalName registry attribute isuser_id@domain_suffix, where domain_suffix is the Active Directory domainwhere the user identity is created.For example, [email protected] is the value of the userPrincipalName;example.com is the Active Directory domain where the user identity is created.The Security Access Manager user identity corresponding to the registry user inthis example is [email protected] or johndoe. It depends on whetherSecurity Access Manager is configured to use Active Directory with multipledomains or a single domain.The alternative format of the userPrincipalName attribute is user_id@any_suffix.any_suffix can be any domain (Active Directory or non-Active Directory) otherthan the Active Directory domain in which the user identity is created.For example, if the registry user johndoe@other_domain.com is created in ActiveDirectory example.com, and the registry user [email protected] is created inActive Directory domain child_domain.example.com. Both users can be SecurityAccess Manager users, and their user identities are johndoe@other_domain.comand [email protected] the alternative user principal name (UPN) support in all Security AccessManager runtime environments. Doing so ensures that Security Access Manageruser identities work properly with alternative UPNs.When the use of alternative UPN format as user identity is enabled, it cannot bereversed without breaking Security Access Manager functions.

v Although users and groups can be created with names that use a distinguishedname string, subsequent operations on the object might fail. A distinguishedname string contains a forward slash (/) character. Some Active Directoryfunctions interpret the forward slash character as a separator between the objectname and the host name. To avoid the problem, do not use a forward slashcharacter to define the user.

Length of namesThe maximum lengths of various names that are associated with Security AccessManager vary depending on the user registry that is being used.

See the Table 35 on page 123 section for a comparison of the maximum lengths thatare allowed and the maximum length to use to ensure compatibility with all theuser registries that are supported by Security Access Manager.


Table 35. Maximum lengths for names by user registry and the optimal length across user registries

Name IBM TivoliDirectory

Server

IBM z/OSSecurityServer

NovelleDirectory

Server

Sun JavaSystem

DirectoryServer

MicrosoftActive

DirectoryServer

ActiveDirectory

LightweightDirectory

Server (ADLDS)

Optimallength

First name(LDAP CN)

256 256 64 256 64 64 64

Middle name 128 128 128 128 64 64 64

Last name(surname)

128 128 128 128 64 64 64

Registry uid(LDAP DN)

1024 1024 1024 1024 2048 1024 255

SecurityAccessManager useridentity

256 256 256 256 64 64 64

Userpassword

unlimited unlimited unlimited unlimited 256 128 256

Userdescription

1024 1024 1024

Group name 256 256 256 256 64 64 64

Groupdescription

1024 1024 1024

Single sign-onresourcename

240 240 240 240 60 240 60

Single sign-onresourcedescription

1024 1024 1024

Single sign-onuser ID

240 240 240 240 60 240 60

Single sign-onpassword

unlimited unlimited unlimited unlimited 256 unlimited 256

Single sign-ongroup name

240 240 240 240 60 240 60

Single sign-ongroupdescription

1024 1024 1024

Action name 1 1 1

Actiondescription,action type

unlimited unlimited unlimited

Object name,objectdescription


Object spacename, objectspacedescription


Appendix C. User registry differences 123

Table 35. Maximum lengths for names by user registry and the optimal length across user registries (continued)

Name IBM TivoliDirectory

Server

IBM z/OSSecurityServer

NovelleDirectory

Server

Sun JavaSystem

DirectoryServer

MicrosoftActive

DirectoryServer

ActiveDirectory

LightweightDirectory

Server (ADLDS)

Optimallength

ACL name,ACLdescriptions


POP name,POPdescription


Although, the maximum length of an Active Directory distinguished name(registry uid) is 2048, the maximum length of each relative distinguished name(RDN) is 64.

If you configure Security Access Manager to use multiple Active Directorydomains, the maximum length of the user identity and group name does notinclude the domain suffix.

When you use multiple domains, the format of a user identity isuser_id@domain_suffix.

The maximum length of 64 characters applies only to the user_id portion. If youuse an email address or other format for the Security Access Manager user identityin the Active Directory, the maximum name length remains the same, but includesthe suffix.

Although the lengths of some names can be unlimited, excessive lengths mightresult in a policy that is difficult to manage. A policy that is difficult to managemight result in poor system performance. Choose maximum values that are logicalfor your environment.


Appendix D. Accessibility features for IBM Security AccessManager

Accessibility features help users who have a disability, such as restricted mobilityor limited vision, to use information technology products successfully.

IBM Security Access Manager partially conforms to Section 508 standards foraccessibility. Detailed compliance information is available by requesting VoluntaryProduct Accessibility Templates (VPATs) at http://www.ibm.com/able/product_accessibility/index.html.

The following list includes the major accessibility features in IBM Security AccessManager:v Keyboard-only operationv Interfaces that are commonly used by screen readersv Keys that are discernible by touch but do not activate just by touching themv Industry-standard devices for ports and connectorsv The attachment of alternative input and output devices

See the IBM Human Ability and Accessibility Center for more information aboutthe commitment that IBM has to accessibility.


http://www.ibm.com/able/product_accessibility/index.html

http://www.ibm.com/able/product_accessibility/index.html

http://www.ibm.com/able

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-1785 U.S.A.

For license inquiries regarding double-byte character set (DBCS) information,contact the IBM Intellectual Property Department in your country or sendinquiries, in writing, to:

Intellectual Property LicensingLegal and Intellectual Property LawIBM Japan, Ltd.19-21, Nihonbashi-Hakozakicho, Chuo-kuTokyo 103-8510, 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 or implied warranties in certaintransactions, therefore, this statement might not apply to 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 Web


sites. The materials at those Web sites are not part of the materials for this IBMproduct and use of those Web sites is at your own risk.

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

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

IBM Corporation2Z4A/10111400 Burnet RoadAustin, TX 78758 U.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 document 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.

Any performance data contained herein was determined in a controlledenvironment. Therefore, the results obtained in other operating environments mayvary significantly. Some measurements may have been made on development-levelsystems and there is no guarantee that these measurements will be the same ongenerally available systems. Furthermore, some measurement may have beenestimated through extrapolation. Actual results may vary. Users of this documentshould verify the applicable data for their specific environment.

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.

All IBM prices shown are IBM's suggested retail prices, are current and are subjectto change without notice. Dealer prices may vary.

This information is for planning purposes only. The information herein is subject tochange before the products described become available.

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.

Each copy or any portion of these sample programs or any derivative work, mustinclude a copyright notice as follows:

© (your company name) (year). Portions of this code are derived from IBM Corp.Sample Programs. © Copyright IBM Corp. _enter the year or years_. All rightsreserved.

If you are viewing this information in softcopy form, the photographs and colorillustrations might not be displayed.

Terms and conditions for product documentation

Permissions for the use of these publications are granted subject to the followingterms and conditions.

ApplicabilityThese terms and conditions are in addition to any terms of use for the IBMwebsite.

Personal useYou may reproduce these publications for your personal, noncommercialuse provided that all proprietary notices are preserved. You may notdistribute, display or make derivative work of these publications, or anyportion thereof, without the express consent of IBM.

Commercial useYou may reproduce, distribute and display these publications solely withinyour enterprise provided that all proprietary notices are preserved. Youmay not make derivative works of these publications, or reproduce,distribute or display these publications or any portion thereof outside yourenterprise, without the express consent of IBM.

Rights Except as expressly granted in this permission, no other permissions,licenses or rights are granted, either express or implied, to the publicationsor any information, data, software or other intellectual property containedtherein.

IBM reserves the right to withdraw the permissions granted hereinwhenever, in its discretion, the use of the publications is detrimental to itsinterest or, as determined by IBM, the above instructions are not beingproperly followed.

You may not download, export or re-export this information except in fullcompliance with all applicable laws and regulations, including all UnitedStates export laws and regulations

Notices 129

IBM MAKES NO GUARANTEE ABOUT THE CONTENT OF THESEPUBLICATIONS. THE PUBLICATIONS ARE PROVIDED "AS-IS" ANDWITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED ORIMPLIED, INCLUDING BUT NOT LIMITED TO IMPLIED WARRANTIESOF MERCHANTABILITY, NON-INFRINGEMENT, AND FITNESS FOR APARTICULAR PURPOSE.

Trademarks

IBM, the IBM logo, and ibm.com are trademarks or registered trademarks ofInternational Business Machines Corp., registered in many jurisdictions worldwide.Other product and service names might be trademarks of IBM or other companies.A current list of IBM trademarks is available on the web at http://www.ibm.com/legal/copytrade.shtml.

Adobe, Acrobat, PostScript and all Adobe-based trademarks are either registeredtrademarks or trademarks of Adobe Systems Incorporated in the United States,other countries, or both.

IT Infrastructure Library is a registered trademark of the Central Computer andTelecommunications Agency which is now part of the Office of GovernmentCommerce.

Intel, Intel logo, Intel Inside, Intel Inside logo, Intel Centrino, Intel Centrino logo,Celeron, Intel Xeon, Intel SpeedStep, Itanium, and Pentium are trademarks orregistered trademarks of Intel Corporation or its subsidiaries in the United Statesand other countries.

Linux is a trademark of Linus Torvalds in the United States, other countries, orboth.

Microsoft, Windows, Windows NT, and the Windows logo are trademarks ofMicrosoft Corporation in the United States, other countries, or both.

ITIL is a registered trademark, and a registered community trademark of the Officeof Government Commerce, and is registered in the U.S. Patent and TrademarkOffice.

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

Java and all Java-based trademarks and logos are trademarks or registeredtrademarks of Oracle and/or its affiliates.

Cell Broadband Engine is a trademark of Sony Computer Entertainment, Inc. in theUnited States, other countries, or both and is used under license therefrom.

Linear Tape-Open, LTO, the LTO Logo, Ultrium, and the Ultrium logo aretrademarks of HP, IBM Corp. and Quantum in the U.S. and other countries.


http://www.ibm.com/legal/copytrade.shtml

http://www.ibm.com/legal/copytrade.shtml

Index

Aaccess control 32

administration 31definition 31list entries

any-authenticated user 32any-other user 32

listsentry types 32table of methods 32

accessibility ixaccounts administration 20, 21action group 35

methods, table 35overview 34

administration objectslisting 14manipulating 12

APISee also com.tivoli.pd.rgyauthorization 93error codes 71overview 1published 60

Factory classes 60Java Interfaces 60

specificationsSee com.tivoli.pd.rgy 98

using 7application servers

configuring 51methods, table 51overview 51SSL

configuration 51applications, building 2attributes 78

group modification 113protected object policy settings 40user modification 116

auditcomponents 90start event 90stop event 90

audit logprotected object policy settings 39

audit recordsprotected object policy settings 39

authenticationcertificate-based 11events 92level, IP

PDPop.IPAuthInfo object 38password 118PDPop.IPAuthInfo object 38user ID and password-based 10

authorizationpermissions 93rules

administering 43methods table 43

auto-database-update-notify stanza entrynotifying replica databases 54

Ccertificate

maintenance 52com.tivoli.pd.jcfg.SvrSslCfg 3, 71com.tivoli.pd.jcfg.SvrSslCfg class 51com.tivoli.pd.rgy.ldap.AuthzRgyRegistryFactory 70com.tivoli.pd.rgy.ldap.LdapRgyRegistryFactory 68com.tivoli.pd.rgy.ldap.RgyAttributes 67com.tivoli.pd.rgy.RgyEntity 63com.tivoli.pd.rgy.RgyGroup 66com.tivoli.pd.rgy.RgyIterator 67com.tivoli.pd.rgy.RgyRegistry 60com.tivoli.pd.rgy.RgyUser 64com.tivoli.pd.rgy.util.RgyConfig 71commands

pdjrtecfg 2createGroup method 25createUser method 19credential, resource 47

Ddatabase notification 55deprecated classes and methods 2domain

management 49domains

administration 49management 49methods, table 49

Eeducation xerror codes 71example program, Java administration API 3exception errors 16extended actions 35extended attributes 40extended attributes methods, table 34

GgetLocalDomainName 49getMgmtDomainName 49group 109

access control list entry type 32attributes

table 26create 109details

display 110functions

table 25


group (continued)members

add 112list 111remove 112

nativeimport 111

overview 19resource 46

groupsattributes 78

IIBM

Software Support xSupport Assistant x

IBM Security Access Manager Runtime for Javaconfiguration 2

IPaddresses 38authentication levels 38

JJava

loggeroutput file 89

logger namecom.tivoli.pd.rgy.authz 89com.tivoli.pd.rgy.ldap 89

logging 89error and trace 89

Java administration APIapplication

deployment 3components 2demonstration program 3deployment 3equivalents 2example 3

Java classesadministration

configure 3objects administered 1overview 1trace logs 5

Java loggerauthentication auditing logger 89behavior 89framework 89management auditing logger 89namespaces 92

com.tivoli.pd.rgy.audit.{blade}.authn 92com.tivoli.pd.rgy.audit.{blade}.mgmt 92com.tivoli.pd.rgy.authz 92com.tivoli.pd.rgy.ldap 92

Java runtimeconfigure

component 2environment 2

Javadocdocumentation 2

JREsample output

basic 89

LLDAP_ADMINLIMIT_EXCEEDED 120local domain

administration 49log files

tracing files 5logging

message files 4PDJTracelogger 4

look-through limit 120

Mmanagement events 91max-notifier-threads stanza entry

setting maximum number 54message logging

gathering logs 4messages object 15methods

PDAcl.listAcls 14PDAuthzRule.listAuthzRules 15PDDomain.listDomains 15PDGroup.createGroup 25PDGroup.importGroup 25PDGroup.listGroups 14PDPolicy.acctDisableTimeEnforced 22PDPolicy.acctDisableTimeUnlimited 22PDPolicy.acctExpDateEnforced 22PDPolicy.acctExpDateUnlimited 22PDPolicy.getAccessEndTime 22PDPolicy.getAccessibleDays 22PDPolicy.getAccessStartTime 22PDPolicy.getAccessTimezone 22PDPolicy.getAcctDisableTimeInterval 22PDPolicy.getAcctExpDate 22PDPolicy.getMaxConcurrentWebSessions 22PDPolicy.getMaxFailedLogins 22PDPolicy.maxConcurrentWebSessionsDisplaced 22PDPolicy.maxConcurrentWebSessionsEnforced 22PDPolicy.maxFailedLoginsEnforced 22PDPolicy.setAcctDisableTime 23PDPolicy.setAcctExpDate 22PDPolicy.setMaxConcurrentWebSessions 23PDPolicy.setMaxFailedLogins 23PDPolicy.setTodAccess 23PDPolicy.todAccessEnforced 23PDProtObject.listProtObjects 14PDProtObject.listProtObjectsByAcl 14PDProtObjectSpace.listProtObjectSpaces 14PDUser.createUser 12, 19, 20PDUser.deleteUser 15, 19PDUser.getDescription 14, 20PDUser.getFirstName 20PDUser.getGroups 21PDUser.getId 20PDUser.getLastLogin 20PDUser.getLastName 20PDUser.getPolicy 20PDUser.getRgyName 20PDUser.getUserRgy 22PDUser.importUser 19, 20PDUser.isAccountValid 21PDUser.isPDUser 21PDUser.isSSOUser 21PDUser.listUsers 15, 20


methods (continued)PDUser.setAccountValid 14, 21PDUser.setDescription 21PDUser.setPassword 21PDUser.setPasswordValid 21PDUser.setSSOUser 21PDUser.User 20

Microsoft Active Directory Lightweight Directory Service (ADLDS) 120

Nnetmask

PDPop.IDAuthInfo object 38notification

manual 54threads

setting maximum number 54wait time

setting 54notification, automatic

automatic 54notifier-wait-time stanza entry

setting notification wait time 54

Oobject values

reading 14setting 14

objectsadministration

obtaining local copy 13common classes 9manipulating 12PDAcl 8, 31, 32PDAclEntry 8, 32PDAclEntryAnyOther 8, 32PDAclEntryGroup 8, 32PDAclEntryUnAuth 8, 32PDAclEntryUser 8, 32PDAction 8PDActionGroup 8PDAdmSvcPobj 8PDAppSvrInfo 9PDAppSvrSpecLocal 9PDAppSvrSpecRemote 9PDAttrs 9PDAttrValue 10PDAttrValueList 10PDAttrValues 10PDAuthzRule 7, 43PDContext 7PDDomain 7PDException 9PDGroup 7, 25PDMessage 9, 15PDMessages 9, 15PDPolicy 8, 21PDPop 8, 37PDProtObject 8, 28, 37PDProtObjectSpace 8, 27PDRgyGroupName 8PDRgyName 9PDRgyUserName 8PDServer 9, 55

objects (continued)PDSSOCred.CredID 9PDSSOCred.CredInfo 9PDSSOResource 9PDSSOResourceGroup 9PDSvrInfo 9PDUser 7, 19

objects, administrationcreate 12delete 15list 7

onlinepublications ixterminology ix

optionsPDAppSvrConfig 51PDDomain 49

Ppassword

administrationuser account policies 21user password policies 23

functions, tableadministering, policies 23

policyLDAP 119

user 118change 117reset 117

PD.jar fileadministration Java classes 1

PDAppSvrConfig optionapplication servers

configuration 51PDAuthzRule objects

authorization rulesadministration 43

PDContextdesign considerations 16

PDDomainobject

domain administration 49PDGroup

group informationadministration 25

groupsadministration 25

PDJlog.propertiesmessage logs

collection 4trace logs

collection 5pdjrtecfg command

Java runtime componentconfiguration 2

PDJTraceLoggerenable tracing 4

PDPop objectsadministration 37

PDProtObject objectadministration 28

PDProtObject objectsadministration 37

Index 133

PDServerserver

administration 53PDServer object

serversadministration 53

PDServer objectsservers

administration 55PDServer.replicateServer

notifying replica databases 54PDUser

usersadministration 19

PDUser.deleteUser methodusers

administration 19policy

administration method errors 74per-user 113

policy serverdomains

administration 49POP

administration 27problem determination

gathering information 4problem-determination xprotected object policy

settings 39protected object policy settings, table

administering 39protected objects 28, 37

extended attributes 30functions, table 28management 28overview 27policy

extended attributes 40managing 37methods, table 37, 40objects 37overview 27

spacesmanagement 27methods, table 28overview 27

publicationsaccessing online ixlist of for this product ix

RRegistry Direct API

audit 89configuration options

combined usage 98stand-alone usage 98

design 59installation 98packaging 98

Registry Direct Java API 59administration API errors 74authenticate 71changePassword 71file format 90local mode 59

replica databasesautomatic notification 54configuration commands 52manual notification 54notification of updates 53notification threads 54notification wait time 54

resourcecredential

methods table 47group

methods table 46Web

methods table 45RgyRegistry

close 109instance 109

creating 109

Ssecurity

requirements 3Security Access Manager

configurationoptions 100stand-alone 99

delegated administration effects 96Java API illustration 59name length 122

security contextoverview 10

serveradministration tasks

overview 53methods table 55Microsoft Active Directory 120

concerns 120ignored items 120

overview 53single sign-on (SSO) capability

administering 45SSL

session 1Sun Java System Directory Server

LDAP_ADMINLIMIT_EXCEEDED 120look-through limit 120

svrsslcfgcommand line utility 51

SvrSslCfg 98

Tterminology ixthreads, notification 54training xtroubleshooting x

Uunauthenticated user 32Unicode 16user

account functions, table 22accounts

administration 20


user (continued)administration 19administration, authenticated users 32administration, other users 32administration, unauthenticated users 32delete 115details

display 114functions, table 20group administration 19group membership

list 116native

import 115password

functions, table 23policies 23

passwordsaccount policies 21

registry differences 119supported registries

concerns 119user registry

maximum values 123users

attributes 78UTF-8 16

Wwait time, notification 54warning attribute 39Web resources 45

Index 135

��

Printed in USA

Administration Java Classes Developer Reference

Documents

Transcript of Administration Java Classes Developer Reference