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.

Implementation Class

Interface SmDmsApi is implemented by the class SmDmsApiImpl. Use this class as the starting point for the DMS API.

This class lets you determine how you want to access the information in the SmDmsDirectory object. You can do so by providing either of two kinds of information:

• The name or OID of the target user directory. To provide this information, call getDirectoryContext().
• The OID of the protected realm that the user is attempting to access. To provide this information, call getDmsContext().

These methods fill the context object that is passed into them.

Context Class

The getDirectoryContext() and getDmsContext() methods in class SmDmsApiImpl create a context object—either SmDmsDirectoryContext or SmDmsContext. The context object contains information such as user directory, session, and connection information. The context object is so-named because its information is derived within the context of the provided realm OID or the user directory name or OID. When you have a context object, you call its getDmsDirectory() method to retrieve an SmDmsDirectory object. This object represents an LDAP or other namespace and gives you access to organizations and other elements in the namespace.

Object Class

The Object class, SmDmsObject, and its subclasses provide methods for creating and managing directory objects. SmDmsObject includes the following subclasses:

• SmDmsDirectory represents a user namespace, such as LDAP. It provides access to the information in an entire directory.
• SmDmsOrganization represents an organization, such as Engineering or Human Resources, within a directory. A SiteMinder user directory is a conceptual view of an organization. It is managed by an organization administrator and uniquely identified by an organization DN.
• SmDmsGroup represents a group within an organization. Groups are sets of objects that have something in common—for example, a group of employees who have been with the company for less than a year. With group objects, users can be assigned privileges collectively instead of individually.
• SmDmsRole represents a role within an organization. A role describes a user’s function in an organization. This allows the user to be managed with other users who have the same privileges. For example, a user who can order items online and view an inventory list may have the role buyer.
• SmDMSUser represents a user within an organization. Users can be end users or administrators.

Object Model

When performing an operation on a directory, organization, group, role, or user object, you sometimes have a choice of using the generic SmDmsObject or one of its subclasses. However, for object-specific operations (such as authenticating a user, changing a user’s password, or getting a user’s privileges), you have to use an object-specific subclass.

The objects corresponding to the subclasses are distinguished by a class identifier, such as DMSOBJECT_CLASS_USER for a user object. These identifiers are defined in SmDmsObject. When you create an object using a subclass, such as creating a user with SmDmsUser, and then you call addObject(), the class identifier is automatically set. However, if you create a generic directory, organization, group, role, or user object with SmDmsObject, you must set the class identifier before calling addObject().

Search Class

The Search class, SmDmsSearch, represents a configuration object for the search operation. It holds the search base and the filter. The filter expects a string-based search expression for the object class.

The search class returns a list of distinguished names paired with the corresponding class identifier, and optionally, selected attribute information for the items retrieved in the search.

Cursor Class

The SmDmsCursor class lets you define sorting and paging behavior for result set operations—for example:

• Set the sort parameter of the SmDmsCursor constructor to specify the columns to use for sorting rows.
• Call setBlockSize() to define the maximum number of rows that can be returned from a result set at one time—that is, the maximum number of rows in a page.
• Call setOffset() to specify the starting offset (row number) of the block returned from the result set.
• Call isSortingCritical() to specify whether a result set must be sorted.
  • If you specify true, a result set will be retrieved only if it can be sorted.
  • If you specify false, an unsorted result set will be sent if it cannot be sorted. An isSorted() call on the same SmDmsCursor object will return false.
• Call isPagingCritical() to specify whether a result set must be paginated.
  • If you specify true, a result set will be retrieved only if it can be paginated.
  • If you specify false, a complete result set will be sent if it cannot be sorted. An isPaginated() call on the same SmDmsCursor object will return false.

Searches that Support Cursor Operations

You can perform sorting and paging operations by passing a defined SmDmsCursor object into any of the following methods:

• One of the search methods in SmDmsOrganization:
  • search()
  • searchForward()
  • searchBack()
  • searchRefresh()
• SmDmsObject.getGroups()
• SmDmsOrganization.getGroups()
• SmDmsGroups.getMembers()

Note: getGroups() and getMembers() are not supported in searches of ODBC directories.

Searches of Microsoft LDAP Directories

Sorting and paging operations are not supported for Active Directories through the AD namespace. Sorting and paging operations are supported for Active Directories through the LDAP namespace.

When communicating with an Active Directory through the AD namespace, SiteMinder responds to sorting and paging requests as follows:

• If both isPagingCritical() and isSortingCritical() return false in the SmDmsCursor object, the result set is returned. No sorting and paging operations are performed.
• If either isPagingCritical() or isSortingCritical() returns true in the SmDmsCursor object, an error occurs. No result set is returned.

You specify whether sorting and paging operations are critical in the SmDmsCursor constructor.

Write a Directory Management Application

To write a Directory Management application

1. Establish a Connection to the Policy Server
2. Obtain a Session Object

   A session object is obtained when a user or administrator successfully logs in:

   • To log in a SiteMinder administrator and establish a SiteMinder administrator session, call the login() method in the SmApiSession class of the Utilities package.

     If login is successful, the session object contains the session specification.

   • To log in an end user, DMS organization administrator, or DMS super administrator, call the login() method in the AgentAPI class of the Agent API package.

     If the login is successful, the session specification is put into the spec field of the SessionDef object. Set the spec value in the SmApiSession object.

3. Pass in the Session Object

   After obtaining a valid session, create a DMS API object by passing the session to the constructor of the SmDmsApiImpl class—for example:

   SmDmsApi dmsApi = new SmDmsApiImpl (apiSession);
   

   In the example, dmsApi is the new DMS API object, and apiSession is the session obtained when the administrator successfully logged in.

   Note: Whenever you create a DMS API object, you pass the session and connection information to the object.

4. Create a Directory Management Context

   To use the DMS API to access a user directory, you need to know either:

   • The OID of a realm that has a self-registration scheme configured for it.

     Call SmDmsApiImpl.getDmsContext() to pass in this information.

   • The SiteMinder user directory where you are operating.

     Call SmDmsApiImpl.getDirectoryContext() to pass in this information.

   The type of information you know or choose to provide determines the directory management context for accessing the user directory, as follows:

DMS context and directory context provide two different avenues for reaching the same destination—an SmDmsDirectory object where you can access and manipulate directory information.

5. Create and Manipulate Objects

After creating a context, you can create and manipulate directory objects using the DMS Object Model. When working with directory objects, you need to know:

• The distinguished name of the object.
• The type of object, such as:
  • Top-level organization
  • Organizational unit
  • Group
  • User
  • Role

DMS Context

DMS context lets you access an SmDmsDirectory object within the context of a realm OID that you provide. The DMS context class is SmDmsContext.

You can create a DMS context object as follows:

SmDmsContext dmsContext = new SmDmsContext();

You can retrieve a DMS context object, use the method getDmsContext() in the class SmDmsApiImpl.

Note: SiteMinder administrator privileges are required for calling getDmsContext().

Before retrieving the DMS context object information, you need to create a realm object to pass into the getDmsContext() call. The realm object must:

• Have a valid object identifier (OID) obtained from an agent call to AgentAPI.isProtected().
• Be configured with a registration scheme.

You create the SmRealm object as follows:

SmRealm realm = new SmRealm();

Then, set the realm OID by calling setOid(). You can call this method through an object that extends the SmObjectImpl class of the Policy Management API.

After setting the OID for the realm object, call getDmsContext() and pass in the realm object.

Example:

An agent calls isProtected() to determine if the resource that a user is attempting to access is protected. The Policy Server indicates that the resource is protected by returning the credentials required for accessing the resource. Included with the return information is the OID of the protected realm. As shown in the example below, you use the returned realm OID (in the example, m_REALM_OID) to set the OID for the realm object you are creating and passing to getDmsContext():

// Create a DMS API object from a valid session.
SmDmsApi dmsApi = new SmDmsApiImpl (apiSession);

// The realm below should contain a registration scheme.
// You can get a directory OID from the registration scheme.
SmRealm realm = new SmRealm ();
realm.setOid (m_REALM_OID);
// Create the DMS context object.
SmDmsContext dmsContext = new SmDmsContext ();

// This call returns the realm, self registration,
// and user directory information through dmsContext.
result = dmsApi.getDmsContext (realm,
                               new SmDmsConfig(),
                               dmsContext);

To get complete directory information from the dmsContext object, call dmsContext.getDmsDirectory().

To get just the directory OID, call dmsContext.getSelfReg(), and then call SmSelfReg.getUserDir().

Directory Context

Directory context lets you access an SmDmsDirectory object within the context of a user directory name or OID that you provide. The directory context class is SmDmsDirectoryContext. To get a directory context, use the method getDirectoryContext() in the class SmDmsApiImpl.

In the following example, an SmDmsDirectoryContext object is returned in dirContext. Call getDmsDirectory() to get the information about the directory object.

// Create a DMS API object from a valid session.

SmDmsApi dmsApi = new SmDmsApiImpl (apiSession);

// Create the directory context object.
SmDmsDirectoryContext dirContext=new SmDmsDirectoryContext();

// Directory object to pass in to getDirectoryContext().
SmUserDirectory userDir = new SmUserDirectory ();

// setOid() method can take the name of the user directory.
userDir.setOid ("smdev");

// This call returns directory information through dirContext.
result=dmsApi.getDirectoryContext(userDir,
                                  new SmDmsConfig(),
                                  dirContext);

Change the User Type in DMS Context

In a directory context, you can perform operations on behalf of any user type—super administrator, SiteMinder administrator, organization administrator, or end user. But to create a DMS context object, you must call the method getDmsContext(), and SiteMinder administrator privileges are required to call this method.

After getDmsContext() is called and DMS context is established for the session, it’s possible to change the user type for subsequent operations in the session. For example, after a SiteMinder administrator opens a session in DMS context, you might want an end user to modify his user profile later in the same session. To make the profile request on the end user’s behalf rather than the SiteMinder administrator’s, you need to change the user type.

To create a DMS context object, you call SmDmsApiImpl.getDmsContext(). When you do so, connection information and the SiteMinder administrator’s session specification are included the DMS context object.

As a chain of subsequent objects is created in the session (for example, SmDmsDirectory/SmDmsOrganization/SmDmsUser), the connection and session information is passed from object to object. To change the user type for a given object, you replace the SiteMinder administrator’s session specification for that object with the session specification for the new user type on whose behalf subsequent calls will be made. You can change the session specification at any object level.

To change the user type for an object created in DMS context

1. Create the object that will be the target of requests by the new user type.

   For example, to make requests against the new user object dmsUser in organization dmsOrg on behalf of an end user with the distinguished name USER_DN:

   SmDmsUser dmsUser = dmsOrg.newUser(USER_DN);
   

   In the example, the SiteMinder administrator session specification in the dmsOrg object is passed to the dmsUser object.

2. Get a session specification for the new user in either of these ways:
   • With standard SiteMinder agents, use the default HTTP header HTTP_SM_SERVERSESSIONSPEC.
   • With custom agents, use the Agent API to log in the new user.
3. Pass in the session specification for the new user and DMS object. For example, if sessionSpec is the session specification:

   dmsUser.getApiSession().setSessionSpec(sessionSpec);
   

More Information:

Context Class

Create an Object

To create an object, such as an organization object, a group object, a user object, or a role object:

1. Use the context to get a directory object by calling getDmsDirectory() on a DMS context or directory context. For example, using a DMS context:

   SmDmsDirectory dmsDir = dmsContext.getDmsDirectory();
   

2. Use the directory object to create an organization object by calling newOrganization() in class SmDmsDirectory. Pass in the distinguished name of the organization, such as o=swdev.com. For example:

   SmDmsOrganization org=dmsDir.newOrganization("o=swdev.com");
   

3. Use the organization object to create other objects, such as group objects or organizational unit objects. The following example creates a group object named grp with the distinguished name ou=UI,ou=eng, o=swdev.com.

   SmDmsGroup grp=org.newGroup("ou=UI,ou=eng,o=swdev.com");
   

Note: This code does not add the group to the directory.

The following figure illustrates the DMS API flow for creating directory objects:

Get Directory Entry Attributes

To retrieve a value for a specific attribute, call getAttribute() in class SmDmsObject and pass in the attribute name as a string. Attribute values are available after you fetch the attributes with getObject(). The method getAttribute() returns a member of the java.lang.Object class. If the attribute is multi-valued, the returned object will contain multiple values delimited by a caret (^).

Add an Object to a Directory

To add an object to a directory:

1. Set the attributes for the object by calling setAttribute() in class SmDmsObject and passing to it the attribute name and its value. Attribute names are defined in your directory system.

   Call setAttribute() as many times as necessary to define the object.

2. Call the method addObject() in class SmDmsObject. For example:

   result = grp.addObject();
   

   In the example, result is an SmApiResult object.

   Note: If you want to call addObject() on a (generic) SmDmsObject object, you must first call setClassId() to set the class identifier.

When adding an object, you can set multiple values for the objectclass attribute, but not for other attributes. When modifying an object with the modifyObject() method, you can set multiple values for any attribute.

To set multiple values for an attribute, you can either:

• Pass in a string, using a caret (^) to delimit the values.
• Pass in a vector of values and have SiteMinder convert the vector to a string.

For example, to pass in a string containing the values top and organizationalunit, you could use the following code:

group.setAttribute("objectclass","top^organizationalunit");

To pass in a vector for the same values, you could use the following code:

Vector objectclass = new Vector();
objectclass.add("top");
objectclass.add("organizationalunit");
group.setAttribute("objectclass", objectclass);

Note: For existing objects, object class can be modified through the modifyObjectClass() method. This method also allows you to set multiple values for object class.

Add a User to a Group

To add a user to a group, call the addToGroup() method in class SmDmsObject. In the following example, the user user1 is added to the group devGroup:

SmDmsDirectory dmsDir = dmsContext.getDmsDirectory();
SmDmsOrganization org = dmsDir.newOrganization(ORG_ROOT);
SmDmsGroup devGroup = org.newGroup(GROUP_DN);
SmDmsUser user1 = org.newUser(USER_DN1);
result = devGroup.addToGroup(user1);

Add a User to a Role

To add a user to a role, call the addToRole() method (class SmDmsUser). In the following example, the user user1 is added to the role role:

SmDmsDirectory dmsDir = dmsContext.getDmsDirectory();
SmDmsOrganization org = dmsDir.newOrganization(ORG_ROOT);
SmDmsRole role = org.newRole(ROLE_DN);
SmDmsUser user1 = org.newUser(USER_DN1);
result = user1.addToRole(role);

Get, Modify, or Delete an Object

To get or modify an object’s attributes, or to delete an object, call getObject(), modifyObject(), or deleteObject(). These methods are defined in class SmDmsObject.

For example, to get the attributes of the organization org whose DN is referenced by ORG_ROOT in the directory namespace dmsDir:

ORG_ROOT="o=swdev.com";
SmDmsDirectory dmsDir = dmsContext.getDmsDirectory();
SmDmsOrganization org = dmsDir.newOrganization(ORG_ROOT);
SmApiResult result = org.getObject();

To modify an object’s attributes, you first fetch the existing attributes with getObject(). Then, you set the new attribute(s) by calling setAttribute() (in class SmDmsObject), just as you do when adding an object.). For example, to modify the user USER_DN1 in the organization org above by setting attribute l to the value Boston:

SmDmsUser user = org.newUser(USER_DN1);
result = user.getObject();
user.setAttribute("l", "Boston");
result = user.modifyObject();

You can modify multiple values for all attributes, not just the objectclass attribute.

To delete the user in the previous example:

SmDmsUser user = org.newUser(USER_DN1);
result = user.deleteObject();

Searches

You can search LDAP directories and ODBC directories. You search an organization using one of the search... methods in the class SmDmsOrganization.

You define a search using the following objects:

• SmDmsSearch to set search parameters such as the search starting point, the maximum number of records to retrieve, and the search filter. The following sections describe the use of this object.
• SmDmsCursor to define optional sorting and paging preferences.

You can specify the search parameters to use when searching the directory. There are two times when you can specify search parameters:

• When you create the search object
• After you create the search object

You can use either option or both options. They are not mutually exclusive.

Set Search Parameters When Creating the Search Object

To specify a search parameter when you create a search object, pass one or more search parameter names to the constructor of the SmDmsSearch class.

There are some search parameters that you cannot specify during creation of the search object—for example, scope. The constructor for the SmDmsSearch class accepts only the following search parameters:

• filter
• root
• propertyNames
• maxItems

You can create an SmDmsSearch object without passing any search parameters to the constructor.

Set Search Parameters After Creating the Search Object

After a search object is created, you can use the set... methods in the SmDmsSearch class to:

• Set additional search parameters.
• Reset search parameters that you set when the search object was created.

By using the set... methods, you can set or reset any of the parameters shown in the following table:

Set the Search Filter

The search filter defines the items you want to retrieve in the search. You can set the search filter through an SmDmsSearch constructor or through the SmDmsSearch method setFilter().

The search filter is described differently for LDAP directories and ODBC directories.

Set the Search Filter for LDAP Directories

With LDAP directories, you provide a complete LDAP search filter in the filter parameter of an SmDmsSearch constructor or setFilter() method. For example, if you pass filter and root to the SmDmsSearch constructor to search the organization swdev.com for groups, you could specify the following:

SmDmsSearch search = new SmDmsSearch (
              "(&(objectclass=organizationalUnit) (ou=groups))",
               "o=swdev.com");

Set the Search Filter for ODBC Directories

A search of an ODBC directory is performed through a SQL query. The DMS API supports the SQL SELECT statement.

The information you provide in the search filter depends on whether your search uses an SmDmsCursor object to provide sorting and paging operations:

• With ODBC searches that do not pass an SmDmsCursor object to the search method, use a fully defined SQL SELECT statement in the search filter.
• With ODBC searches that do pass an SmDmsCursor object to the search method, use a partial SQL SELECT statement in the search filter, consisting only of FROM and WHERE clauses.

With ODBC database searches that pass an SmDmsCursor object to the search method, the DMS API constructs the complete SQL SELECT statement from various sources, as follows:

• The FROM and WHERE clauses are taken from the filter parameter of an SmDmsSearch constructor or setFilter() method.
• The SELECT columns portion of the query is taken from attributes specified in either of the following parameters:
  • The propertyNames parameter of setPropertyNames(). These attributes are used when an SmDmsSearch object is passed to one of the search methods in SmDmsOrganization.
  • The attrNames parameter of a getGroups() or getMembers() method.
• The ORDER BY keywords portion is taken from the order of the attributes you specify in the sort parameter of the SmDmsCursor constructor.

Consider the following code fragment:

String DIR_ROOT = "root";
String SRCH_FILTER ="from SmGroup";
SmDmsSearch search = new SmDmsSearch(SRCH_FILTER);
String[] prop = {"Name", "'Group' as Class"};
search.setPropertyNames(prop);
Vector SortOrder = new Vector(); 
SortOrder.add("uid");
SmDmsCursor cursor = new SmDmsCursor(SortOrder,blockSize,false,true);

The DMS API uses the information in the previous example to build the following SQL statement:

SELECT Name, 'Group' AS Class FROM SmGroup ORDER BY uid ASC

Search an Organization

In the DMS API, searches are performed on an organization object.

To search an organization:

1. Create a search object. This search object holds the search parameters.

   For example, the following SmDmsSearch constructor call creates a search object to search for groups. The root parameter specifies a start point of o=swdev.org.

   SmDmsSearch mySearch = new SmDmsSearch (
              "(&(objectclass=organizationalUnit) (ou=groups))",
               "o=swdev.org");
   

   Note: The root is the top level of the SiteMinder user directory to search. It is not necessarily the top level of the entire directory structure.

   Use the set... methods in the SmDmsSearch class to set any other search parameters—for example:

   mySearch.setScope(2);
   

2. Optionally, define sorting and paging preferences in the SmDmsCursor object.
3. Call the search() method in class SmDmsOrganization on the organization you want to search—for example:

   result = targetOrg.search (mySearch, 1);
   

   The second parameter of the search() method indicates the direction to search, as shown in the following table:
   

1. To get the items returned from the search, call getResults() on the search object—for example:

   Vector mySearchResults = search.getResults();
   

   The first element of the results vector contains the search parameters in a SmDmsSearchResultParams object. The remaining elements are SmDmsObject objects. To distinguish object types, the classId attribute of each object is set through the setClassId() method. For example, if the classId is DMSOBJECT_CLASS_USER, the object is a user. If the classId is DMSOBJECT_CLASS_GROUP, the object is a group.

Examples of a Search

The following example searches an organization using the search parameters set through the search.set... methods below. The results of the forward search are assigned to the vector vsearch and are printed along with the search parameters.

SmDmsContext dmsContext = new SmDmsContext();
SmDmsDirectory dmsDir = dmsContext.getDmsDirectory();
SmApiResult result = new SmApiResult();
SmDmsOrganization org = dmsDir.newOrganization (DIR_ROOT);

// Search
SmDmsOrganization test = org.newOrganization("");
SmDmsSearch search = new SmDmsSearch (
              "(&(objectclass=organizationalUnit) (ou=groups))",
               "o=swdev.com");
// Define search parameters
search.setScope(2);           // Number of levels to search.
search.setNextItem(0);        // Initialize forward search start
search.setMaxItems(20);       // Max number of items to display
search.setPreviousItem(0);    // Initialize back search start
search.setMaxResults(500);    // Max items in the result set
result = test.search(search, 1);
Vector vsearch = search.getResults();
System.out.println("Search object vector size " + vsearch.size());
SmDmsSearchResultParams searchParams = 
                  (SmDmsSearchResultParams)vsearch.firstElement();
System.out.println("***Search Parameters***");
System.out.println(searchParams.toString());
System.out.println("removed element at 0");
vsearch.removeElementAt(0);
System.out.println("Search object vector size " + vsearch.size());
for (int i=0; i<vsearch.size(); i++)
{
   SmDmsObject dmsObj = (SmDmsObject)vsearch.elementAt(i);
   System.out.println("***Search**** " + dmsObj);
   printObject (dmsObj, result);
}

Hashtable attrs = dmsObj.getAttributes();
Enumeration keys = attrs.keys();
Enumeration values = attrs.elements();
while(values.hasMoreElements() )

The following code fragment configures sorting and paging features through an SmDmsCursor object and performs a search. The parameters for the SmDmsSearch object search would be defined in the same way as in the previous example:

Vector SortOrder = new Vector();
SortOrder.add("uid");
int blockSize = 20;
SmDmsCursor cursor=new SmDmsCursor(SortOrder,blockSize,false,true);
cursor.setOffset(15);
result = org.search(search, cursor, 1);     //Forward search
System.out.println(keys.nextElement() + " = " +
                                          values.nextElement() );

User Password State

Password state refers to activities relating to a given user’s password—for example, the last time the password was changed, and the last time the password was used to log in the user. To retrieve an existing SmDmsUserPWState object for a user, or to set a new password state object with any attribute changes, call getUserPWState() or setUserPWState() in SmDmsUser.

The following table lists the password state attributes you can access for a given user, and the method used to set or retrieve an attribute value. All methods are in the class SmDmsUserPWState, unless otherwise noted.

If you change a password state attribute, the change applies to the current password state object only. To apply the change to a password state object that may be subsequently retrieved, pass the current password state object in a call to SmDmsUser.setUserPWState(). This method sets a new password state object containing the attribute values passed into the method.

ODBC Support

When operating against ODBC-based user directories, you can use the following DMS API methods:

• SmDmsApiImpl.getDirectoryContext(SmUserDirectory,
               SmDmsConfig, SmDmsDirectoryContext)
• SmDmsDirectory.getCapabilities(Vector)
• SmDmsDirectory.getUserChallengeText(String)
• SmDmsDirectory.getUserTempPassword(String, String)
• SmDmsObject.getGroups(Vector, boolean)
• SmDmsObject.getObject()
• SmDmsObject.getObject(Vector)
• All search... methods in SmDmsOrganization
• SmDmsUser.authenticate(String)
• SmDmsUser.changePassword(String, String, boolean)

DMS roles are not supported. Also not supported are operations such as adding and deleting users and groups, adding users to a group, and removing users from a group.

Restricted Methods

Some of the methods in the DMS API can only be called within a session established at a minimum level of the user privilege hierarchy or higher. For example, adding an end user to a role requires an organization administrator session, Siteminder administrator session, or super administrator session.

The following table shows the DMS methods (plus the login() and logout() methods in the apiutil package) that have security restrictions, the minimum privilege level required to call the methods, and the classes that the methods are called from: