The LDAP group store is a small scale store that you can use to draw membership information from an LDAP server.  It may also be useful in low volume environments where no one group has very many members.  It has already inspired a number of offspring, including Matthew Ling's "Just in time LDAP group store" and the "Person Attributes Group Store" that are aimed at larger scale deployments. 

The LDAP group store gets its entity memberships from LDAP and its group structure from a configuration file, properties/groups/LDAPGroupStoreConfig.xml.  The configuration file also defines the location of the native group store.  (The dtd for LDAPGroupStoreConfig.xml is LDAPGroupStore.dtd.)  Understanding the configuration file is crucial to understanding how the group store works.  

Configuration file elements.  The configuration file has a single config element that describes the LDAP connection and some number of group elements that establish the groups structure and ultimately, map LDAP queries to groups.  The config element currently points to the Columbia University public LDAP server:

<config>
    <url>ldap://ldap.columbia.edu:389/o=Columbia%20University,c=US</url>
    <logonid></logonid>
    <logonpassword></logonpassword>
    <keyfield>uni</keyfield>
    <namefield>cn</namefield>
    <usercontext></usercontext>
    <refresh-minutes>120</refresh-minutes>
</config>

Group elements.  The group element contains the IEntityGroup attributes key,name and description.  Just as an IEntityGroup can contain groups and entities, a group element can contain other member group elements, and it can contain member entities in the form of a single entity-set.  At its simplest, an entity-set can contain a filter element that defines an LDAP query that returns entities.  Or it may contain a union, intersection, difference or subtract element, which, in turn, contains entity-sets whose results are combined through one of the following operations:

union	all entities from all contained entity-sets
intersection	all common entities from all contained entity-sets
difference	all entities that occur in only one contained entity-set
subtract	all entities in the first entity-set minus any that occur in the rest

The Group Samples.  The samples provide examples of each of these entity-set types.  The configuration file ships with 7 sample groups, described below.  They form the following structure (the group key is in parentheses):

All LDAP Groups (all)
    Vigdors(1)
    Fracapanes and Ellentucks (2)
    Union test (3)
    Intersection test (4)
    Difference test (5)
    Subtract test (6)


• All LDAP Groups (all) contains groups "1" thru "6" but contains no member entities.  It does not (directly) pull information from LDAP.
  
  
• Vigdors (1) contains an entity-set with a filter element whose String value is cn=*vigdor.  The members of Vigdors are the entities returned by this query.
  
  
• Fracapanes and Ellentucks (2) contains an entity-set with a union element that or's the results of two entity-set elements, each of which has a filter element describing an LDAP query.  The resulting entity-set contains those entities returned by LDAP from the query cn=*fracapane plus those entities returned by cn=*ellentuck.
  
  
• Union test (3) is similar to Fracapanes and Ellentucks (2) in that it contains an entity-set with a union element containing 2 entity-sets each of which has a filter element.  The resulting entity-set contains the union of cn=donald f* and cn=*frac*.
  
  
• Intersection test (4) contains an entity-set with an intersection element that and's the results of two entity-set elements, each of which has a filter element.  The resulting entity-set contains the intersection of cn=donald f* and cn=*frac*.
  
  
• Difference test (5) contains an entity-set with a difference element that exclusive-or's the results of two entity-set elements, each of which has a filter element.  The resulting entity-set contains the entities returned by one but not both of cn=donald f* and cn=*frac*.
  
  
• Subtract test (6) contains an entity-set with a subtract element that subtracts the results of one entity-set from another.  Each entity-set has a filter element, and the resulting entity-set contains the entities returned by cn=donald f* but not by cn=*frac*.
  

Limitations of the LDAP Group Store.  It is important to understand what the LDAPGroupStore does and does not do and why it does not support updates.  The store queries LDAP to discover entities that are group members, but it looks at its configuration file to discover groups and their relationships.  As a result, the store will discover an entity added to LDAP (provided it is returned by an entity-set defined in the configuration file.)  But it will not discover any group beyond those defined in the configuration file.  The way to add a group to the store is to add a group element to the configuration document.  Likewise, the way to make a group a member of another group in the store is to add a group element to another group element in the configuration document.  On the other hand, the way to add an entity to a group from the store is to add or update the entity in LDAP.  The LDAP group store could support updates to the group structure (adding or deleting member groups) if it had the ability to update the configuration document.  It could support updates to entity memberships if it had the ability to update LDAP.   

Deploying the LDAP Group Store Locally.  The configuration file as delivered points to the Columbia University public LDAP server and defines a few not-terribly-useful groups.  To implement a local LDAP group service that uses the LDAPGroupStore, modify the configuration file so that the config element points to your LDAP server.  Then, replace the entity-sets and filters with queries that return meaningful results.  When you do this, give your groups appropriate names and make sure their keys are unique.   For example, you might create a structure like:

All LDAP Groups (all)
    Faculty Groups (1)
        Biology Department (3)
        Chemistry Department (4)
    Portal Staff (2)
        Portal Administrators (5)
        Portal Developers (6)

Now un-comment the "ldap" service element in compositeGroupServices.xml and start up the portal.  In the Groups Manager channel, try adding All LDAP Groups to the root group Everyone.  Be sure to Add Members rather than Create New Member Group since the group All LDAP Groups already exists.  (For instructions on using Groups Manager, see The Groups Manager Channel.)   The groups that you defined in your LDAP configuration file should now be available for browsing in Groups Manager, although you won't be able to update them.

Once you are comfortable with the process of defining groups in the configuration file, you can begin the task of deriving a group structure from LDAP that includes your portal population and models your organization.