IBM Security Access Manager for WebVersion 8.012 December 2014
Administration Java Classes DeveloperReference
���
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
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
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
4 IBM Security Access Manager for Web Version 8.0 12 December 2014: Administration Java Classes Developer Reference
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
6 IBM Security Access Manager for Web Version 8.0 12 December 2014: Administration Java Classes Developer Reference
Chapter 2. Using the administration API
Each Java application that uses the administration API must perform certain tasksnecessary for API initialization, shut down, and error handling. The administrationAPI provides methods for each of these tasks.
The following sections in this chapter describe the supported functions:v “Administration objects”v “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.
© Copyright IBM Corp. 2002, 2014 7
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.
8 IBM Security Access Manager for Web Version 8.0 12 December 2014: Administration Java Classes Developer Reference
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.
10 IBM Security Access Manager for Web Version 8.0 12 December 2014: Administration Java Classes Developer Reference
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
Chapter 2. Using the administration API 11
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
12 IBM Security Access Manager for Web Version 8.0 12 December 2014: Administration Java Classes Developer Reference
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
Chapter 2. Using the administration API 13
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
14 IBM Security Access Manager for Web Version 8.0 12 December 2014: Administration Java Classes Developer Reference
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
Chapter 2. Using the administration API 15
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.
16 IBM Security Access Manager for Web Version 8.0 12 December 2014: Administration Java Classes Developer Reference
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 2. Using the administration API 17
18 IBM Security Access Manager for Web Version 8.0 12 December 2014: Administration Java Classes Developer Reference
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
© Copyright IBM Corp. 2002, 2014 19
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.
20 IBM Security Access Manager for Web Version 8.0 12 December 2014: Administration Java Classes Developer Reference
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.
For detailed reference information about these methods, see the Javadoc HTMLdocumentation.
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.
22 IBM Security Access Manager for Web Version 8.0 12 December 2014: Administration Java Classes Developer Reference
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.
For detailed reference information about these methods, see the Javadoc HTMLdocumentation.
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.
Chapter 3. Administering users and groups 23
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.
For detailed reference information about these methods, see the Javadoc HTMLdocumentation.
24 IBM Security Access Manager for Web Version 8.0 12 December 2014: Administration Java Classes Developer Reference
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.
For detailed reference information about these methods, see the Javadoc HTMLdocumentation.
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.
Chapter 3. Administering users and groups 25
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.
For detailed reference information about these methods, see the Javadoc HTMLdocumentation.
26 IBM Security Access Manager for Web Version 8.0 12 December 2014: Administration Java Classes Developer Reference
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.
© Copyright IBM Corp. 2002, 2014 27
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.
For detailed reference information about these methods, see the Javadoc HTMLdocumentation.
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.
28 IBM Security Access Manager for Web Version 8.0 12 December 2014: Administration Java Classes Developer Reference
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
For detailed reference information about these methods, see the Javadoc HTMLdocumentation.
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.
For detailed reference information about these methods, see the Javadoc HTMLdocumentation.
30 IBM Security Access Manager for Web Version 8.0 12 December 2014: Administration Java Classes Developer Reference
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:
© Copyright IBM Corp. 2002, 2014 31
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.
For detailed reference information about these methods, see the Javadoc HTMLdocumentation.
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.
32 IBM Security Access Manager for Web Version 8.0 12 December 2014: Administration Java Classes Developer Reference
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.
For detailed reference information about these methods, see the Javadoc HTMLdocumentation.
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.
For detailed reference information about these methods, see the Javadoc HTMLdocumentation.
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.
34 IBM Security Access Manager for Web Version 8.0 12 December 2014: Administration Java Classes Developer Reference
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.
For detailed reference information about these methods, see the Javadoc HTMLdocumentation.
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.
For detailed reference information about these methods, see the Javadoc HTMLdocumentation.
Chapter 5. Administering access control 35
36 IBM Security Access Manager for Web Version 8.0 12 December 2014: Administration Java Classes Developer Reference
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.
© Copyright IBM Corp. 2002, 2014 37
For detailed reference information about these methods, see the Javadoc HTMLdocumentation.
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.
38 IBM Security Access Manager for Web Version 8.0 12 December 2014: Administration Java Classes Developer Reference
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.
For detailed reference information about these methods, see the Javadoc HTMLdocumentation.
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.
40 IBM Security Access Manager for Web Version 8.0 12 December 2014: Administration Java Classes Developer Reference
For detailed reference information about these methods, see the Javadoc HTMLdocumentation.
Chapter 6. Administering protected object policies 41
42 IBM Security Access Manager for Web Version 8.0 12 December 2014: Administration Java Classes Developer Reference
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.
For detailed reference information about these methods, see the Javadoc HTMLdocumentation.
© Copyright IBM Corp. 2002, 2014 43
44 IBM Security Access Manager for Web Version 8.0 12 December 2014: Administration Java Classes Developer Reference
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.
© Copyright IBM Corp. 2002, 2014 45
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.
For detailed reference information about these methods, see the Javadoc HTMLdocumentation.
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.
46 IBM Security Access Manager for Web Version 8.0 12 December 2014: Administration Java Classes Developer Reference
Depending on the LDAP server in your environment, any attempt to remove anon-existing resource from a group, might generate an error.
For detailed reference information about these methods, see the Javadoc HTMLdocumentation.
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.
For detailed reference information about these methods, see the Javadoc HTMLdocumentation.
Chapter 8. Administering single sign-on resources 47
48 IBM Security Access Manager for Web Version 8.0 12 December 2014: Administration Java Classes Developer Reference
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.
For detailed reference information about these methods, see the Javadoc HTMLdocumentation.
© Copyright IBM Corp. 2002, 2014 49
50 IBM Security Access Manager for Web Version 8.0 12 December 2014: Administration Java Classes Developer Reference
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.
For detailed reference information about these methods, see the Javadoc HTMLdocumentation.
© Copyright IBM Corp. 2002, 2014 51
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.
For detailed reference information about these methods, see the Javadoc HTMLdocumentation.
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.
For detailed reference information about these methods, see the Javadoc HTMLdocumentation.
52 IBM Security Access Manager for Web Version 8.0 12 December 2014: Administration Java Classes Developer Reference
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.
© Copyright IBM Corp. 2002, 2014 53
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.
54 IBM Security Access Manager for Web Version 8.0 12 December 2014: Administration Java Classes Developer Reference
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.
For detailed reference information about these methods, see the Javadoc HTMLdocumentation.
Chapter 11. Administering servers 55
56 IBM Security Access Manager for Web Version 8.0 12 December 2014: Administration Java Classes Developer Reference
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.
© Copyright IBM Corp. 2002, 2014 57
58 IBM Security Access Manager for Web Version 8.0 12 December 2014: Administration Java Classes Developer Reference
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.
© Copyright IBM Corp. 2002, 2014 59
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
60 IBM Security Access Manager for Web Version 8.0 12 December 2014: Administration Java Classes Developer Reference
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:
62 IBM Security Access Manager for Web Version 8.0 12 December 2014: Administration Java Classes Developer Reference
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();
Appendix B. Registry Direct Java API 63
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()
64 IBM Security Access Manager for Web Version 8.0 12 December 2014: Administration Java Classes Developer Reference
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
Appendix B. Registry Direct Java API 65
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;
66 IBM Security Access Manager for Web Version 8.0 12 December 2014: Administration Java Classes Developer Reference
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()
Appendix B. Registry Direct Java API 67
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.
68 IBM Security Access Manager for Web Version 8.0 12 December 2014: Administration Java Classes Developer Reference
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;}
Appendix B. Registry Direct Java API 69
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()
getRgyRegistryInstance()
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;
getRgyRegistryInstance()
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()
70 IBM Security Access Manager for Web Version 8.0 12 December 2014: Administration Java Classes Developer Reference
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:
Appendix B. Registry Direct Java API 71
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
AZN_S_U_PASSWORD_TOO
_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
AZN_S_U_PASSWORD_TOO
_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
.
72 IBM Security Access Manager for Web Version 8.0 12 December 2014: Administration Java Classes Developer Reference
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]
enhanced-pwd-policy=yes)
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]
enhanced-pwd-policy=yes)
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
Appendix B. Registry Direct Java API 73
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:
74 IBM Security Access Manager for Web Version 8.0 12 December 2014: Administration Java Classes Developer Reference
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
.
Appendix B. Registry Direct Java API 75
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.
76 IBM Security Access Manager for Web Version 8.0 12 December 2014: Administration Java Classes Developer Reference
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
.
Appendix B. Registry Direct Java API 77
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:
78 IBM Security Access Manager for Web Version 8.0 12 December 2014: Administration Java Classes Developer Reference
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.
Appendix B. Registry Direct Java API 79
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.
80 IBM Security Access Manager for Web Version 8.0 12 December 2014: Administration Java Classes Developer Reference
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.
Appendix B. Registry Direct Java API 81
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.
82 IBM Security Access Manager for Web Version 8.0 12 December 2014: Administration Java Classes Developer Reference
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
.
Appendix B. Registry Direct Java API 83
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
.
84 IBM Security Access Manager for Web Version 8.0 12 December 2014: Administration Java Classes Developer Reference
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
.
Appendix B. Registry Direct Java API 85
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.
86 IBM Security Access Manager for Web Version 8.0 12 December 2014: Administration Java Classes Developer Reference
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
.
Appendix B. Registry Direct Java API 87
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.
88 IBM Security Access Manager for Web Version 8.0 12 December 2014: Administration Java Classes Developer Reference
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.
Appendix B. Registry Direct Java API 89
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>
90 IBM Security Access Manager for Web Version 8.0 12 December 2014: Administration Java Classes Developer Reference
<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");
Appendix B. Registry Direct Java API 91
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
92 IBM Security Access Manager for Web Version 8.0 12 December 2014: Administration Java Classes Developer Reference
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.
Appendix B. Registry Direct Java API 93
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.
94 IBM Security Access Manager for Web Version 8.0 12 December 2014: Administration Java Classes Developer Reference
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.
Appendix B. Registry Direct Java API 95
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.
96 IBM Security Access Manager for Web Version 8.0 12 December 2014: Administration Java Classes Developer Reference
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
Appendix B. Registry Direct Java API 97
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.
98 IBM Security Access Manager for Web Version 8.0 12 December 2014: Administration Java Classes Developer Reference
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
Appendix B. Registry Direct Java API 99
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.
100 IBM Security Access Manager for Web Version 8.0 12 December 2014: Administration Java Classes Developer Reference
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
.
Appendix B. Registry Direct Java API 101
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.
102 IBM Security Access Manager for Web Version 8.0 12 December 2014: Administration Java Classes Developer Reference
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.
Appendix B. Registry Direct Java API 103
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.
ldap.auth-using-compare
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.
104 IBM Security Access Manager for Web Version 8.0 12 December 2014: Administration Java Classes Developer Reference
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.
Appendix B. Registry Direct Java API 105
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()
.
106 IBM Security Access Manager for Web Version 8.0 12 December 2014: Administration Java Classes Developer Reference
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
.
fed-server.<serverid>.
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.
fed-server.<serverid>.
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
.
fed-server.<serverid>.
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.
fed-server.<serverid>.
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.
ldap.auth-using-compare
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.
fed-server.<serverid>.
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.
fed-server.<serverid>.
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.
Appendix B. Registry Direct Java API 107
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
fed-server.<serverid>.
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.
fed-server.<serverid>.
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
.
fed-server.<serverid>.
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)).
fed-server.<serverid>.
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))
fed-server.<serverid>.
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.
fed-server.<serverid>.
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.
fed-server.<serverid>.
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
.
fed-server.<serverid>.
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.
108 IBM Security Access Manager for Web Version 8.0 12 December 2014: Administration Java Classes Developer Reference
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);}
Appendix B. Registry Direct Java API 109
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}
110 IBM Security Access Manager for Web Version 8.0 12 December 2014: Administration Java Classes Developer Reference
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);}
Appendix B. Registry Direct Java API 111
// 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.
112 IBM Security Access Manager for Web Version 8.0 12 December 2014: Administration Java Classes Developer Reference
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);
Appendix B. Registry Direct Java API 113
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 {
114 IBM Security Access Manager for Web Version 8.0 12 December 2014: Administration Java Classes Developer Reference
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) {
Appendix B. Registry Direct Java API 115
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);}
116 IBM Security Access Manager for Web Version 8.0 12 December 2014: Administration Java Classes Developer Reference
// 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:
Appendix B. Registry Direct Java API 117
// 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);}
118 IBM Security Access Manager for Web Version 8.0 12 December 2014: Administration Java Classes Developer Reference
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.
© Copyright IBM Corp. 2002, 2014 119
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.
120 IBM Security Access Manager for Web Version 8.0 12 December 2014: Administration Java Classes Developer Reference
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.
122 IBM Security Access Manager for Web Version 8.0 12 December 2014: Administration Java Classes Developer Reference
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
unlimited unlimited unlimited
Object spacename, objectspacedescription
unlimited unlimited unlimited
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
unlimited unlimited unlimited
POP name,POPdescription
unlimited unlimited unlimited
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.
124 IBM Security Access Manager for Web Version 8.0 12 December 2014: Administration Java Classes Developer Reference
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.
© Copyright IBM Corp. 2002, 2014 125
126 IBM Security Access Manager for Web Version 8.0 12 December 2014: Administration Java Classes Developer Reference
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
© Copyright IBM Corp. 2002, 2014 127
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:
128 IBM Security Access Manager for Web Version 8.0 12 December 2014: Administration Java Classes Developer Reference
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.
130 IBM Security Access Manager for Web Version 8.0 12 December 2014: Administration Java Classes Developer Reference
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
© Copyright IBM Corp. 2002, 2014 131
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
132 IBM Security Access Manager for Web Version 8.0 12 December 2014: Administration Java Classes Developer Reference
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
134 IBM Security Access Manager for Web Version 8.0 12 December 2014: Administration Java Classes Developer Reference
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
136 IBM Security Access Manager for Web Version 8.0 12 December 2014: Administration Java Classes Developer Reference
����
Printed in USA