Programming Guides › Programming Guide for Java › Delegated Management Services API

Delegated Management Services API

This section contains the following topics:

About the DMS API

The Required JAR File

SiteMinder User Directories

Attribute-based Delegation

DMS Users

Implementation Class

Context Class

Object Class

Search Class

Cursor Class

Write a Directory Management Application

Searches

User Password State

ODBC Support

Restricted Methods

About the DMS API

Directory management consists of managing objects within a SiteMinder user directory. For example, a user of your directory management application can create organizations, add groups to organizations, and add end users to groups. Your application performs directory management operations with the DMS API.

The Delegated Management Services (DMS) API lets you perform directory management operations on LDAP and ODBC directories.

With LDAP directories, you can use the DMS API to write a client application that allows a user with the specified privileges to perform tasks such as (but not limited to):

• Creating an organization
• Creating a group
• Adding a group to an organization
• Adding a user to a group
• Modifying the profile of a user

With ODBC directories, you can perform many but not all DMS API operations.

Note: The DMS API (available in Java only) has different functionality than the DMS Workflow API (available in C/C++ only). The DMS API lets you develop directory management applications that perform similar operations as the SiteMinder DMS product. The DMS Workflow API works in conjunction with DMS and fires when certain pre-process and post-process DMS events occur, allowing you to develop applications that perform additional functionality before and/or after these events.

The Required JAR File

The JAR file smjavasdk2.jar is required for building and running Delegated Management applications. The JAR file is stored in the following locations:

• Windows platforms:

  <install_path>\sdk\java

• UNIX platforms:

  <install_path>/sdk/java

SiteMinder User Directories

A SiteMinder user directory is a conceptual view of a single organizational unit (such as Engineering or Human Resources) within a larger entity (such as a corporation). SiteMinder user directories make managing an entire directory structure easier by breaking up the directory into smaller, more manageable, and logically related segments.

The methods in your custom DMS application reference a particular SiteMinder user directory by specifying its unique organization DN. The organization DN points to the root, or top level, of the SiteMinder user directory’s inverted tree structure or to one of its sub-levels.

Every DMS request references an organization DN. In the following illustration, two SiteMinder user directories are enclosed in broken-line boxes. The directories are identified by the organization DNs ou=eng, o=swdev.com (representing the Engineering organizational unit) and ou=hr, o=swdev.com (representing the Human Resources organizational unit):

SiteMinder user directories can exist within other SiteMinder user directories. In the preceding illustration, the Engineering organizational unit has three SiteMinder user directories within it. These have the attribute and organization names ou=dev, ou=qa, and ou=doc. The Human Resources organizational unit has two SiteMinder user directories within it—ou=benefits and ou=recruit.

SiteMinder User Directory Containers

An organization DN in a SiteMinder user directory typically has one or more sub DNs. Sub DNs are also called "containers" because they contain lists of information. The default names of these containers and the information they contain are:

• people—End users in the Siteminder user directory.
• roles—Roles used in the SiteMinder user directory.
• groups—Groups used in the SiteMinder user directory.
• orgadmin—Group for administrators who can manage the organizational unit.

Sub DNs are managed by the class SmDmsConfig. When you create an SmDmsConfig object, you can keep the default sub DN names or assign new ones.

Organization administrators are listed in the orgadmin container. In a hierarchical organization, an organization administrator listed in a given orgadmin container can manage the organizational unit associated with that container and any organizational units below it.

Attribute-based Delegation

In addition to hierarchical organization, DMS also provides an administration model for sites that have implemented a flat directory structure. In this model, delegation is based on attributes in user profiles instead of hierarchical levels.

In a flat directory, DMS adds attribute/value pairs to user profiles to group users together. Once users are grouped together, another attribute/value pair determines which users can manage the groups.

DMS groups users into organizations by adding an attribute/value pair to user profiles. For example, users who belong to the organization East Bank have the attribute/value pair ou=East Bank in their profiles, where ou is the attribute that indicates the organization to which a user belongs.

An organization administrator can only manage organizations that are listed in the organization administrator’s profile. The list of organizations is assigned to a profile attribute that you specify in the SmDmsConfig constructor. For example, if you specify departmentnumber as the attribute that contains the organizations that an organization administrator can manage, the attribute/value pair departmentnumber=East Bank means that the organization administrator can manage the East Bank organization and no others.

The following illustration describes how attribute-based delegation is implemented:

In this example, Donna Gibson is an organization administrator for East Bank and North Bank. She can manage Edward Johnson and Carrie Winham because they belong to organizations that are listed in the departmentnumber attribute in Donna’s user profile.

Configure Attribute-based Delegation

You specify the attributes that enable attribute-based delegation in the SmDmsConfig constructor. Three attributes are required to identify the following information:

• A user as an organization administrator. This attribute can be any attribute in your LDAP directory that you are not using to store other information—for example, o.

  You specify a user as an organization administrator through the constructor’s OrgAdminSubDn parameter, as in the following example:

  OrgAdminSubDn="(title=OrgAdmin)";

• The organization(s) that an organization administrator can manage. By default, DMS uses the departmentnumber attribute to store managed organizations.

  You specify this attribute through the constructor’s OrgAdminOrgs parameter—for example:

  OrgAdminOrgs="departmentnumber";

• The organization to which a user belongs. By default, DMS uses the ou attribute.

  You specify this attribute through the constructor’s DnOrgs parameter—for example:

  DnOrgs="ou";

DMS Users

DMS users are assigned one of the following categories of directory management privileges. The categories are listed below from lowest to highest:

• End user—Can manage certain information about the end user’s own account, such as changing the user’s password and viewing (but not adding) the roles that the user is a member of.
• Organization administrator—Can manage an entire organization and any organizations below it.
• SiteMinder administrator—Can manage directories in one or more domains.

  SiteMinder administrator privileges can vary. With DMS, SiteMinder administrators must have system-level Manage User privileges, and they must be present in at least one domain.

• Super administrator—Can manage all directories in all domains.

You use different login() methods to log in different categories of DMS users.