Programming Guides › Programming Guide for Java › Delegated Management Services API › Write a Directory Management Application

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();