Directory Server Access Management Edition Programmer's Guide: Chapter 4 Identity Management And The SDK

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

Management Of Identity-Related Objects

DSAME SDK

The SDK And Cache

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:

Users

Groups

Organizations

Roles

Organization Units

Group Containers

People Containers
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.

Note ums.xml has template definitions for the various directory entries created by the SDK. If it is modified and reloaded with those modifications, there would be inconsistencies between the new entries created and the older ones. Hence, modifications to this file are not recommended unless DSAME is being installed fresh.

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.

class—This attribute represents the name of the Java class that will implement the object. This attribute is fixed and should never be modified.

name—This attribute defines the entry type of the object. For example, an organization object has o=org as its name.

childNode—This attribute specifies the child nodes that will be created in tandem with the object.

template—This attribute specifies the Creation template used to create this object.

filter—This attribute specifies a filter that will be used to identify the object.

priority—This attribute is defined as 0.

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.

name—This attribute defines the name of the object the template will create. It is also the name of the template itself.

javaclass—This attribute defines the name of the Java class used to instantiate the object.

required—This attribute defines the required LDAP attributes for the object.

optional—This attribute defines the optional LDAP attributes for the object.

validated—This attribute is reserved for future use.

namingattribute—This 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.

name—This attribute defines the name of the search template.

searchfilter—This attribute defines the LDAP search filter.

attrs—This 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.

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

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

Code Example 4-1    Create a new organization and one user

...

// instantiate a store connector from SSO Token

AMStoreConnection amsc = new AMStoreConnection(ssoToken);

// create a new top level organization without non-default attributes

AMOrganization org = amsc.createTopOrganization("newtoporg.com", new HashMap());

// set attribute for the newly created organization

org.setStringAttribute("description", "organization description");

// save new attribute to the organization object

org.store();

// create new user "john" with "cn", "sn" attribute

// Map to hold all users to be created, key is the string value for user naming attribute,

// value is a Map which contains all the initial values for the user

Map usersMap = new HashMap();

// Map to hold attributes for the user

Map attrsMap = new HashMap();

// set cn = John Smith

Set values = new HashSet();

values.add("John Smith");

attrsMap.put("cn", values);

// set sn = Smith

values = new HashSet();

values.add("Smith");

attrsMap.put("sn", values);

// set put user john in the usersMap with "cn" & "sn" specified above

usersMap.put("john", attrsMap);

// create user john in the organization

Set users = org.createUsers(usersMap);

...

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.

Code Example 4-2    Retrieve a service's dynamic template

...

// instantiate a store connector from SSO Token

AMStoreConnection amsc = new AMStoreConnection(ssoToken);

// retrieve top level organization by DN

AMOrganization org = amsc.getOrganization("o=toporg.com,o=isp");

// retrieve Dynamic type AMTemplate for iPlanetAMSessionService

AMTemplate template = org.getTemplate("iPlanetAMSessionService", AMTemplate.DYNAMIC_TEMPLATE);

// retrieve attributes

String maxSessionTime = template.getStringAttribute("iplanet-am-session-max-session-time ");

...

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.state—Depending 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.

com.iplanet.services.stats.directory—The value of this property is the directory in which the amSDKStats file is created.

com.iplanet.am.statsInterval—The 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.
Code Example 4-3 is an example of how the statistics will be formatted.

Code Example 4-3    Format of Recorded Statistics

01/15/2002 09:12:35:751 AM PST: Thread[Thread-47,5,main]

SDK Cache Statistics

------------------------------

Interval: <number of get requests during the specified interval>

Hits during interval: <number of hits during this interval>

Hit ratio for this interval: <hit ratio for the interval>

Total number of requests: <overall (total) number of get requests since server re-start>

Total number of Hits: <overall (total) number of hits since server re-start>

Overall Hit ratio: <overall hit ratio since server re-start>

...
// instantiate a store connector from SSO Token
AMStoreConnection amsc = new AMStoreConnection(ssoToken);
// create a new top level organization without non-default attributes
AMOrganization org = amsc.createTopOrganization("newtoporg.com", new HashMap());
// set attribute for the newly created organization
org.setStringAttribute("description", "organization description");
// save new attribute to the organization object
org.store();

// create new user "john" with "cn", "sn" attribute
// Map to hold all users to be created, key is the string value for user naming attribute,
// value is a Map which contains all the initial values for the user
Map usersMap = new HashMap();
// Map to hold attributes for the user
Map attrsMap = new HashMap();
// set cn = John Smith
Set values = new HashSet();
values.add("John Smith");
attrsMap.put("cn", values);
// set sn = Smith
values = new HashSet();
values.add("Smith");
attrsMap.put("sn", values);
// set put user john in the usersMap with "cn" & "sn" specified above
usersMap.put("john", attrsMap);
// create user john in the organization
Set users = org.createUsers(usersMap);
...

...
// instantiate a store connector from SSO Token
AMStoreConnection amsc = new AMStoreConnection(ssoToken);
// retrieve top level organization by DN
AMOrganization org = amsc.getOrganization("o=toporg.com,o=isp");
// retrieve Dynamic type AMTemplate for iPlanetAMSessionService
AMTemplate template = org.getTemplate("iPlanetAMSessionService", AMTemplate.DYNAMIC_TEMPLATE);
// retrieve attributes
String maxSessionTime = template.getStringAttribute("iplanet-am-session-max-session-time ");
...

01/15/2002 09:12:35:751 AM PST: Thread[Thread-47,5,main]
SDK Cache Statistics
------------------------------
Interval: <number of get requests during the specified interval>
Hits during interval: <number of hits during this interval>
Hit ratio for this interval: <hit ratio for the interval>
Total number of requests: <overall (total) number of get requests since server re-start>
Total number of Hits: <overall (total) number of hits since server re-start>
Overall Hit ratio: <overall hit ratio since server re-start>

Previous Contents Index Next
Copyright © 2002 Sun Microsystems, Inc. All rights reserved.

Last Updated May 14, 2002