Previous Topic: Customizing a SAML AssertionNext Topic: Programming Guide for the Federation .NET SDK


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):

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:

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):

Graphic showing an organization with two organizational units

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:

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:

An illustration describing the attribute-based delegation.

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:

DMS Users

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

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:

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:

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:

Searches that Support Cursor Operations

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

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:

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:

  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 type of information you know or choose to provide determines the directory management context for accessing the user directory, as follows:

If You Know...

And...

Then Use...

The OID of a realm that contains a self-registration scheme

The user is a SiteMinder administrator

Delegated Management Services (DMS) context

The SiteMinder user directory name or OID

Directory context

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:

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:

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

An illustration describing how to create an object using the API.

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:

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:

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

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:

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:

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

Parameter

Default

Set Method

Definition

classId

Unknown (not set yet)

setClassId()

Class identifier.

filter

" "

setFilter()

Search filter, or the string you want to find.

Can also be set when the search object is created.

maxItems

50

setMaxItems()

Maximum number of result set items to display at a time.

Can also be set when the search object is created.

nMaxResults

-1

setMaxResults()

Maximum number of items for the result set.

For example, if nMaxResults is 500, but 750 items match the search criteria, only the first 500 matches will be returned from the search.

nextItem

-1

setNextItem()

The item to start with on the next search forward—for example:

nextItem += maxItems

previousItem

-1

setPreviousItem()

The item to start with on the next search backward—for example:

previousItem-=maxItems

propertyNames

null

setPropertyNames()

Properties to return from the search.

Can also be set when the search object is created.

root

" "

setRoot()

Directory entry where the search should start.

Can also be set when the search object is created.

Valid for LDAP searches only.

scope

None

setScope()

Levels searched.

For LDAP searches only.

timeout

-1

setTimeout()

Maximum duration of the search, in seconds.

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

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

Code Source

Portion of SQL Statement

SRCH_FILTER parameter of
SmDmsSearch constructor

from SmGroup

SortOrder parameter of
SmDmsCursor constructor

order by uid asc

prop parameter of
setPropertyNames()

select Name, 'Group' as Class

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:

Direction

Integer Value

Reset

0

Forward

1

Back

2

Refresh

3

  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.

Password State Attribute

Method

Description

Login failures

setLoginFailures()
getLoginFailures()

Sets or retrieves the number of times the user failed to log in since the user’s last successful login.

Last login time

setLastLoginTime()
getLastLoginTime()

Sets or retrieves the time the user last logged in successfully.

Previous login time

setPrevLoginTime()
getPrevLoginTime()

Sets or retrieves the next-to-last time the user logged in successfully.

Disabled time

setDisabledTime()
getDisabledTime()

Sets or retrieves the time the user object was disabled.

Password history

SmDmsUser.
setUserPWState()

Optionally, clears the user’s password history when setting the password state object for the user.

You cannot retrieve password history or set password history entries.

Last password change time

setLastPWChangeTime()
getLastPWChangeTime()

Sets or retrieves the time the user’s password was last changed.

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:

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:

Method

Minimum Privilege Level and Class

addObject()

Organization administrator session
SmDmsObject and subclasses

addToGroup()

Organization administrator session
SmDmsObject and subclasses

addToRole()

Organization administrator session
SmDmsUser class

authenticate()

End user session
SmDmsUser class

changePassword()

End user session
SmDmsUser class

deleteObject()

Organization administrator session
SmDmsObject and subclasses

getCapabilities()

End user session
SmDmsDirectory class

getDirectoryContext()

End user session
SmDmsApiImpl class

getDisabledState()

End user session
SmDmsUser class

getDmsContext()

SiteMinder administrator session
SmDmsApiImpl class

getDmsRoles()

Organization administrator session
SmDmsDirectory class

getGroups()

End user session
SmDmsObject and subclasses

getGroups()

Organization administrator session
SmDmsOrganization class

getMembers()

Organization administrator session
SmDmsGroup class

getMembers()

Organization administrator session
SmDmsRole class

getObject()

End user session
SmDmsObject and subclasses

getOrganizations()

Organization administrator session
SmDmsOrganization class

getRoles()

End User session
SmDmsUser class

getRoles()

Organization administrator session
SmDmsOrganization class

getUserChallengeText()

Super administrator session
SmDmsDirectory class

getUserPWState()

End user session
SmDmsUser class

getUserTempPassword()

Super administrator session
SmDmsDirectory class

login()

No session
SmApiSession class

logout()

SiteMinder administrator session
SmApiSession class

modifyObject()

End user session
SmDmsObject and subclasses

removeFromGroup()

Organization administrator session
SmDmsObject and subclasses

search()

Organization administrator session
SmDmsOrganization class

searchBack()

Organization administrator session
SmDmsOrganization class

searchForward()

Organization administrator session
SmDmsOrganization class

searchRefresh()

Organization administrator session
SmDmsOrganization class

setDisable()

Organization administrator session
SmDmsUser class

setDisabledState()

Organization administrator session
SmDmsUser class

setEnable()

Organization administrator session
SmDmsUser class

modifyObjectClass()

Organization administrator session
SmDmsObject and subclasses

setPasswordMustChange()

End user session
SmDmsUser class

setUserPWState()

End user session
SmDmsUser class