Previous Contents Index Next |
Directory Server Access Management Edition Programmer's Guide |
Chapter 4 Identity Management And The SDK
The Identity Management module of DSAME contains XML templates and application programming interfaces (APIs) that can provide functionality to, among other operations, create, delete and managing identity entries in the directory. This chapter offers information on these public API. It contains the following sections:
Overview
The Identity Management module of DSAME provides interfaces for creating and managing identity-related objects in the iPlanet Directory Server (DS). The management functions that can be performed include the creation and deletion of the specific objects as well as the ability to get, add, modify, or remove attributes of these objects. The interfaces provided for this feature are a Java SDK to embed the management functions with applications or services, and a set of configuration parameters (defined in the ums.xml). The following sections describe the configuration Templates and the DSAME SDK.
Management Of Identity-Related Objects
The ums.xml provides a set of configuration parameters, known as Templates, that contain LDAP configuration information for identity-related objects. (It can be found in the Install_Directory/SUNWam/config/ums directory.) The identity-related objects are:The templates are used by the DSAME SDK for the creation of these objects in the DS, as well as the dynamic generation of the object's roles and the construction of object searches. (These templates can be modified by administrators to alter the behavior of the Java interfaces.) Using these templates and the LDIF schema, parameters are configured for all identity-related objects.
When DSAME is installed, the ums.xml file is stored in the DS as the DAI service. (DAI is a service in DSAME whose configuration is not made available through the DSAME console.) The DSAME SDK gets the configuration information from this node when it is being asked to create an identity-related object, generate a role or perform a search. Any attribute specified in the ums.xml can be set for a created object.
Structure of ums.xml
The ums.xml defines three templates: Structure, Creation and Search. Structure templates define the DS DIT attributes for the object. Creation templates define an LDAP template for the object being created. Search templates define guidelines for performing searches using LDAP. These concepts are discussed in depth below.
Structure Templates
Structure templates define the form a DSAME object will take in the DS DIT. This conforms to where the object is located within the DIT; the objects are strictly LDAP entries. There are six attributes that need to be defined for each subschema.
classThis attribute represents the name of the Java class that will implement the object. This attribute is fixed and should never be modified.
nameThis attribute defines the entry type of the object. For example, an organization object has o=org as its name.
childNodeThis attribute specifies the child nodes that will be created in tandem with the object.
templateThis attribute specifies the Creation template used to create this object.
filterThis attribute specifies a filter that will be used to identify the object.
Creation Templates
Every entry that DSAME creates has a corresponding creation template which defines the LDAP schema for the object being created. It specifies what object classes and attributes are mandatory or optional and what default values, if any, should be set. This conforms to the actual LDAP entry in the DS. There are six attributes that need to be defined for each subschema.
nameThis attribute defines the name of the object the template will create. It is also the name of the template itself.
javaclassThis attribute defines the name of the Java class used to instantiate the object.
requiredThis attribute defines the required LDAP attributes for the object.
optionalThis attribute defines the optional LDAP attributes for the object.
validatedThis attribute is reserved for future use.
namingattributeThis attribute specifies the LDAP entry type.
Search Templates
Search templates are used to define how DSAME searches are performed in the DS. This template defines a default search filter and the returning attributes in a search. For example, a search filter is constructed which defines and specifies which attributes and values are to be retrieved from the DS.
nameThis attribute defines the name of the search template.
searchfilterThis attribute defines the LDAP search filter.
attrsThis attribute specifies the LDAP attributes that need to be returned.
Modifying ums.xml
In addition to modifying an XML service file, any new LDAP attributes or object classes must be added to the ums.xml file in order for them to be recognized by DSAME. In most cases, the attributes that service developers might want to add may already exist in the inetorgperson and the inetuser object classes. If, for example, a custom mail service is being added with, specifically, an employee_id attribute, the ums.xml file does not need to be modified because this attribute already exists in the inetorgperson object class. Generally, as in the example, the ums.xml file does not need to be modified. The only circumstances where this file would need to be modified are:
if DSAME is being installed against a legacy DIT.
Additional information on when and how to modify the ums.xml file is covered in the section on installing against a legacy DIT in the iPlanet Directory Server Access Management Edition Installation and Configuration Guide.if new object classes are being added to users or organizations.
if service developers want to change the default organizations or roles.
if service developers need to change an entry's naming attribute.
It is highly recommended that the ums.xml configuration file is duplicated before any modifications are made.
Adding Custom Object Classes
If a service developer wanted to add new or customized object classes to DS for DSAME's use, they would need to modify the templates in the ums.xml file to include them. Then, to manage them from the DSAME console, these new object classes and attributes have to be modelled in the XML service file format and imported into DSAME using the procedures described in this chapter.
DSAME SDK
The DSAME SDK contains APIs for identity management. These interfaces can be used by developers to integrate management functions into external applications or services to be managed by the DSAME. The following sections describe the Java classes.
Note The public Javadocs can be accessed through Install_Directory/SUNWam/docs/index.html.
Identity Management APIs
The Identity Management APIs provide the means to create or delete identity-related objects as well as get, modify, add or delete the object's attributes. The com.iplanet.am.sdk package contains all the interfaces and classes necessary to perform these operations in the DS.
AMConstants
AMConstants is the base interface for all identity-related objects. It is used to define the scope of a search of the DS. It can search for a specific object, a particular level of the DIT or an attribute.
AMObject
AMObject provides basic methods to manage identity-related objects. Since this is a generic class, it does not have any Templates associated with it.
AMOrganization
The AMOrganization interface provides the methods used to manage organizations. Associated with this interface are the following ums.xml Templates that define its behavior at runtime. The name of the structural template used by this class is Organization; the name of the creation template used is BasicOrganization, and the name of the search template is BasicOrganizationSearch.
AMOrganizationalUnit
The AMOrganizationalUnit interface provides the methods used to manage organizational units. Associated with this object are the following ums.xml Templates that define its behavior at runtime. The name of the structural template used by this class is OrganizationalUnit; the name of the creation template used is BasicOrganizationalUnit, and the name of the search template is BasicOrganizationalUnitSearch.
AMPeopleContainer
The AMPeopleContainer interface provides the methods used to manage people containers. Associated with this object are the following ums.xml Templates that define its behavior at runtime. The name of the structural template used by this class is PeopleContainer; the name of the creation template used is BasicPeopleContainer, and the search template is BasicPeopleContainerSearch.
AMGroupContainer
The AMGroupContainer interface provides the methods used to manage group containers. Associated with this object are the following ums.xml Templates that define its behavior at runtime. The name of the structural template used by this class is GroupContainer; the name of the creation template used is BasicGroupContainer, and the search template is BasicGroupContainerSearch.
AMGroup
The AMGroup interface provides the methods used to manage groups. This is the basic class for all derived groups, such as static groups, dynamic groups and assignable dynamic groups. No default templates are defined for this class.
AMStaticGroup
The AMStaticGroup interface provides the methods used to manage static groups. This class extends the base AMGroup interface. The name of the creation template used with this class is BasicGroup; and the search template used is BasicGroupSearch. It does not have a pre-defined structural template.
AMDynamicGroup
The AMDynamicGroup interface provides the methods used to manage dynamic groups. This class extends the base AMGroup interface. Associated with this object are the following ums.xml Templates that define its behavior at runtime. The creation template used is named BasicDynamicGroup; and the search template used is named as BasicDynamicGroupSearch. It does not have a pre-defined structural template.
AMAssignableDynamicGroup
The AMAssignableDynamicGroup interface provides the methods used to manage assignable dynamic groups. This class extends the base AMGroup interface. Associated with this object are the following ums.xml Templates that define its behavior at runtime. The creation template used is named BasicAssignableDynamicGroup; and the search template used is named BasicAssignableDynamicGroupSearch. It does not have a pre-defined structural template.
AMRole
The AMRole interface provides the methods used to manage roles. Associated with this object are the following ums.xml Templates that define its behavior at runtime. The creation template used is named BasicManagedRole; and the search template used is named BasicManagedRoleSearch. It does not have a pre-defined structural template.
AMUser
The AMUser interface provides the methods used to manage users. Associated with this object are the following ums.xml Templates that define its behavior at runtime. The creation template used is named BasicUser; and the search template used is named BasicUserSearch. It does not have a pre-defined structural template.
AMTemplate
The AMTemplate interface represents a service template associated with a AMObject. DSAME distinguishes between virtual and entry attributes. Per iPlanet Directory Server (DS) terminology, a virtual attribute is an attribute not physically stored in an LDAP entry but still returned with it as a result of a LDAP search. Virtual attributes are analogous to inherited attributes. Entry attributes are non-inherited attributes.
Note More information on virtual attributes can be found in "Virtual Attribute" of Chapter 8 "iPlanet Directory Server And DSAME."
For AMOrganization, AMOrganizationalUnit and AMRole, virtual attributes can be grouped in a Template on a per-service basis; there may be one service Template for each service for any given AMObject. Such templates determine the service attributes inherited by the users within the scope of this object. There are three types of templates: POLICY_TEMPLATE, DYNAMIC_TEMPLATE and ORGANIZATION_TEMPLATE. POLICY_TEMPLATE and DYNAMIC_TEMPLATE are implemented using CoS Templates; ORGANIZATION_TEMPLATE does not have virtual attributes.
Template Priority
When any object inherits more than one template for the same service (by virtue of being in the scope of two or more objects with service templates), conflicts between such templates are resolved by the use of template priorities. In this priority scheme, zero is the highest possible priority with the lower priorities extending towards finity. Templates with higher priorities will be favored over and to the exclusion of templates with lower priorities. Templates which do not have an explicitly assigned priority are considered to have the lowest priority possible, or no priority. In the case where two or more templates are being considered for inheritance of an attribute value, and they have the same (or no) priority, the result is undefined, but does not exclude the possibility that a value will be returned, however arbitrarily chosen.
AMStoreConnection
The AMStoreConnection class represents a connection to the DSAME data store. It controls and manages access to the DSAME data store by providing methods to create, remove and get different types of identity-related objects. A SSO Token is required in order to instantiate a AMStoreConnection object.
Sample Code
Following are code samples using the DSAME SDK.
Create Organization
The following code sample creates a new organization with one user by opening a connection to the DS data store with AMStoreConnection. A new top organization (newtoporg.com) is then created with its own attributes. User John Smith is then created as a member of the new organization.
Retrieve Templates
The following code sample retrieves a service's dynamic templates by opening a connection to the DS data store with AMStoreConnection. It retrieves a service's dynamic template by defining the DN of the top organization (toporg.com) as well as the specific string attribute of the specific service to be retrieved.
The SDK And Cache
Caching in the DSAME SDK is for storing all AMObject attributes (i.e., attributes of identity-related objects) that are retrieved from iDS. The cache does not hold AMObject directly. All attributes retrieved from the DS using the interface methods AMObject.getAttribute(String name), AMObject.getAttributes(setAttributeNames) or AMObject.getAttributes() will be cached.
Cache Properties
The following cache properties can be configured by accessing the AMConfig.properties file. They are:
com.iplanet.services.stats.stateDepending on whether this property is set to file or console, the cache statistics will be printed to either a amSDKStats file or the DSAME console.
Code Example 4-3 is an example of how the statistics will be formatted.com.iplanet.services.stats.directoryThe value of this property is the directory in which the amSDKStats file is created.
com.iplanet.am.statsIntervalThe interval at which cache statistics are printed can be specified as the value of this property. It indicates the number of seconds after which the stats will be printed. For example, a value of 3600 would cause the cache statistics to be printed after 3600 seconds. This will be used only if com.iplanet.services.stats.state is set to file or console.
Previous Contents Index Next
Copyright © 2002 Sun Microsystems, Inc. All rights reserved.
Last Updated May 14, 2002