Chapter 3 LighthouseContext API

LighthouseContext is the name of a Java API that is used to configure the Service Provider server and access provisioning services. Customer-developed web applications, which can be deployed on a portal server, use this API.

Refer to the Javadocs and the sample Java file (ApiUsage.java) in the REF kit for more details about the LighthouseContext API with Service Provider.

Obtaining a LighthouseContext

There are four varieties of context:

• Local Anonymous

• Local Authenticated

• Remote Anonymous

• Remote Authenticated

A local context calls the Identity Manager classes directly, while remote access can be achieved using SPML. Note that the Service Provider SPML handler does not perform authentication. The authentication should be executed by the portal application.

An anonymous context does not require a user name and password. If auditing is performed, it will use a system defined name. There is an anonymous local context, the internal context, that is used in the implementation of the Service Provider server. The internal context may also be accessed by application code, though note that you will lose the ability to record specific end-user names in the audit log.

All varieties of context are obtained from factory methods on the SessionFactory class. The factory methods are:

Persistent Objects and Views

Users in the LDAP directory can be accessed as persistent objects. In addition to retrieving the normal attributes stored in the directory, the context also retrieves extended provisioning information stored in special attributes. This includes information about links to other accounts associated with the directory user. This extended information is only available through the context API, it cannot be accessed by pure LDAP applications.

A second object model called Views may also be accessed through the context. View objects are not stored in the directory, rather they are assembled at runtime from one or more persistent objects. User objects in the directory are most often accessed through a view rather than a persistent object. The user view contains all of the information found in the persistent object, but may in addition contain attribute from other accounts linked to this user. Manipulating a user view is how all provisioning operations are performed in Service Provider.

Views are represented in memory using a generic memory model based on simple Java data types such as lists and hash maps. This regular structure allows views to be easily manipulated by technologies such as forms, and makes the view attributes easier to associate with HTTP form fields. For more information about views, see Chapter 4, IDMXUser View.

Persistent Object Identification

Persistent objects are identified by the following pieces of information.

• A Type object that specifies a repository storage type.

• A String that specifies the object’s unique repository ID or repository name.

Service Provider uses the IDMXUser object type. Its corresponding static Type instance is Type.IDMX_USER.

A unique repository ID is generated by the system and may be used programmatically, but it is normally not intelligible to an end-user. Once assigned, the repository ID cannot be changed. The format of the identifier is considered unspecified, and the application should make no assumptions about the characters it contains. Note that the ID might contain fragments of a DN, but this DN does not necessarily match the actual DN of the object.

The repository name is specified by the user. When displaying the name of a persistent object in a UI application, you should always display the name rather than the ID. The object name is guaranteed to be unique among the objects of the same type, but is not necessarily unique among objects of different types. Object names may be changed.

Because object names can change, it is generally more reliable for an application to use repository IDs, if they are available. For interactive applications, this may not be possible if the names are being entered by the user. For this reason, the LighthouseContext methods will accept either an identifier or a name.

Option Maps

Many of the LighthouseContext methods take an argument of type java.util.Map called an option map. This provides an extensible way to pass additional information into the function rather than through a lengthy list of arguments, or a large collection of different method signatures.

The map keys are always strings. The map values are usually strings or lists of strings. When an option value is treated as a boolean, the value may either be the strings true and false or a java.lang.Boolean object. When an object value is treated as an integer, it may either be a string or a java.lang.Integer object.

The options recognized by a particular method will be described in the documentation for that method. The following table lists some common options recognized by many methods.

LighthouseContext in Service Provider

This section describes how the LighthouseContext is used differently within Service Provider.

Object Locks

Service Provider does not support object locks.

Do not use the following methods, which are defined in the ObjectSource interface:

• lockobject

• unlockobject

• getLock

• breakLock

Persistent Object Queries

If you are writing a generic repository browsing application, you will need perform searches to discover the objects in the repository. There are two styles of searches, a listing search (listObjects) and a fetching search (getObjects). A listing search retrieves the name and a few attributes of the object, but does not bring the entire object into memory. A fetching search loads the entire object into memory.

You should always use listing searches when querying IDMXUser objects, because there can be a large number of users in the directory.

The listObjects, getObjects, and deleteObjects methods recognize an options map argument, in which search criteria and other options may be specified. When building an options map, it is recommend that you use a set of constant string objects. The following table lists the valid query option names and their corresponding constant object.

Service Provider enforces a maximum number of results that a query can return. This maximum is specified by the maxRows option.

User Objects

Since Service Provider users are also persistent objects, you can create and modify them in the same way as configuration objects. While this is the fastest way to create users in the directory, it is important to understand that the provisioning of resource accounts does not happen when you use the persistent object methods. If you want to perform provisioning you must use the IDMX User View and the view methods.

The IDMXUser class is a subclass of Composite, which provides a generic model to represent an object with a collection of attributes, assignments to resources, and links to the associated objects on those resources. The structure of the IDMXUser class is similar to the Identity Manager WSUser class, but the field and method names are slightly different, because the model is intended for use with entities other than user accounts.

The following table shows the correspondence of some of the major classes and field names in the two products.

When you set the attributes of an IDMXUser, it is important to know how these attributes are being mapped to attributes in the directory. This mapping is defined by a Resource definition in the repository, which is named Service Provider End-User Directory in the examples.

This resource is available in Identity Manager by default. The resource has a schema map set up to work with the Service Provider example end user pages.

The full DN of this user will be built according to the identity template defined in the resource. If you want to assign a DN whose structure differs from that in the identity template, call the setIdentity method to specify the full DN.

Any attribute that you set on an IDMXUser that is not defined in the directory schema map will be stored as an extended attribute. Extended attributes are stored in the XML blob with the other object metadata, they are not directly accessible in the directory.

When you no longer need a persistent object, it may be deleted to reclaim space and reduce clutter in searches. Service Provider does not perform reference checks before deleting an object. This means that it is possible to delete a Resource object, for example, while that object is still being referenced by a Role object.