The LDAP cache can be populated using information from an ldap server, or from information supplied via a user defined script. Use of the script allows the administrator to use PowerShell, batch files, shell scripts or executables to write ldap information to a file in either xml or json. This information is then read by the cache component and loaded in to caches.

LDAP Caches

All information returned by the LDAP cache component is provided from caches. There are three caches to support the requests of other components:

• (external) Group Expansion cache
  • A map of user names against the LDAP or Active Directory groups to which they belong. This database belongs to the Group Expansion Manager service
• User Ldap attributes cache
  • A map of username against LDAP or Active Directory attributes for the user. Note that all attributes are held as strings and any binary attributes will be encoded using Base32.
• User/Group cache
  • A list of users and groups found in LDAP or Active Directory.

Cache Population

All three of the caches are refreshed at the same time. A scheduler periodically send an Aspire job to the cache component which begins the process of rebuilding the caches

The rebuilding process will gather all of the users and groups from LDAP or Active Directory, either by connection to a server or by running the configured script and reading its output.

During configuration, the administrator supplies the names of a number of attributes. These are described below:

As well as attributes, the administrator must also specify whether user objects hold references to the groups to which they belong or if the groups hold reference to the users that are members.

This information is then used to construct a map of users against the groups to which they belong. As ldap information is downloaded from the server, or read from a script response, it is inserted in to a temporary cache with a key taken from the attribute specified in the user key or group key attribute. At the end of this stage, we have a map of the unique identifiers against the LDAP or Active Directory object themselves.

What happens next depends on whether user objects hold references to the groups to which they belong or if the groups hold reference to the users that are members. If user objects hold references to groups, then each user is processed in turn. The group name is taken from the value of the group name attribute and the value(s) of the (repeated) attribute given as the group mapping are collected. These values hold the unique identifier of the groups to which the user belongs. These identifiers are looked up in the temporary cache to get the group objects and the names of these are found by looking at the value of the group name attribute of each group. Finally (as we now have a user name and a set of group names) the user and groups are added to the group expansion cache.

If groups hold references to users that belong to it, the process is similar, but instead the groups are processed in turn. Their group mapping attribute is found to give the identifiers of the member user objects. These users are located from the temporary cache and the names obtained from user name attributes. Then the group and users are added to the group expansion cache.

When the group expansion cache is complete, we can extract information to fill the other caches – the cache of users against ldap information and the external user and group list.

Note: The above assumes that the attributes are populated with values. With both server and script processing, you must ensure that the attributes you choose are present and populated to make the expansion work correctly.

Connection to an LDAP Server

If you wish to connect to an ldap server and download ldap information from there you will need to specify the connection parameters. You will also need to specify queries to obtain all the users you are interested in and all the groups you are interested in. Note that there is no requirement for the query to return all of the users or groups. It only needs to return those you are interested in. For performance reasons you should try to make the results set as small as possible.

By default, the response from the ldap queries will return all of the attributes the returned object has. However it is unlikely that you will need all of the attributes and the cache allows you to filter the attributes that are returned. Note however, if you choose to filter, you should ensure that the return include the attributes you select for the user and group keys and names and for the group mapping.

Using a Script

The LDAP cache can be configure to use a script to obtain its user and group information. This script could be a Windows batch file, Power Shell or executable, or Linux shell script or executable.

When the cache rebuild begins and the ldap cache is configured to use a script, the cache component creates an empty temporary file and passes the file name to the script. The script can return either xml or json and should write its output the given file. The format of the xml or json is given below.

The script can do whatever is required to gather the users and groups (for example connect to a database, ldap server or other repository) and then write the information to the file. Once the script completes, the ldap cache component will read the information from the file and load the groups. If the script encounters an error, it can report this back to the component via the file.

Assuming that the processing of the file completes successfully, the temporary file is deleted. If the ldap cache encounters an error while processing the file, the file is left on disk to aid debugging.

Xml format

If returning xml from the script, the following format must be used:

<ldap>
  <users>
    <user>
      <attribute name="attr-u1">value1</attribute>
      <attribute name="attr-u2">value2</attribute>
      .
      .
    </user>
  </users>
  <groups>
    <group>
      <attribute name="attr-g1">value1</attribute>
      <attribute name="attr-g2">value2</attribute>
      .
      .
    </group>
  </groups>
</ldap>

Note: you should ensure you have a value for each attribute you configure for user key, user name, group key, group name and group mapping.

Json Format

If returning json from the script, the following format must be used:

{
  "ldap": {
    "users": {
      "user": [
        {
         "attribute": [
           {
             "@name": "attr-u1",
             "$": "value1"
           },
           {
             "@name": "attr-u2",
             "$": "value2"
           }
         ]
       },
       {
         "attribute": [
           {
             "@name": "attr-u1",
             "$": "value1"
           },
           {
             "@name": "attr-u2",
             "$": "value2"
           }
         ]
       }
     ]
   },
   "groups": {
     "group": [
       {
         "attribute": [
           {
             "@name": "attr-g1",
             "$": "value1"
           },
           {
             "@name": "attr-g2",
             "$": "value2"
           }
         ]
       },
       {
         "attribute": [
           {
             "@name": "attr-g1",
             "$": "value1"
           },
           {
             "@name": "attr-g2",
             "$": "value2"
           }
         ]
     ]
   }
 }
}

Note: you should ensure you have a value for each attribute you configure for user key, user name, group key, group name and group mapping.

Specifying Group Membership

When using a script, it is possible for you to return information that defines the groups to which a user belongs, rather than have the cache calculate it for you. To do this, make your script return a <membership> node (as a child of the root <ldap> node).

When specifying membership, no further processing will be done and the only group expansions for a user will be those specified. If you say user U1 is a member of groups G1 and GX2, this is exactly what you will see in the cache, even if group GX2 does not exist in the groups section. Even if attributes suggest U1 is in group G4 this will not be shown via the cache if a <membership> tag is used.

If you use xml, add the following format:

<membership>
  <user name="user1-key">
    <group>group1-key</group>
    <group>group2-key</group>
  </user>
  <user name="user2-key">
    <group>group3-key</group>
    <group>group4-key</group>
  </user>
  .
  .
</membership>

Or in json:

{
  "membership": {
    "user": [
      {
        "@name": "user1-key",
          "group": [
            "group1-key",
            "group2-key"
          ]
      },
      {
        "@name": "user2-key",
          "group": [
            "group3-key",
            "group4-key"
        ]
      }
    ]
  }
}

Errors

If you need your script to report an error, return the following xml:

<error>
  <description>A description of the issue<description>
  <trace>Any stack trace information<trace>
</error>

Or json:

{
  "error":{
    "description":"A description of the issue",
    "trace":"Any stack trace information"
  }
}

LDAP Group expansion

The LDAP cache component stores the users/groups relationships into the GroupExpansion manager database cache, so it can obtain the groups coming from LDAP when requested.

LDAP Information

The LDAP cache component implements the LDAPGroupExpansionServer which allows it to return ldap information for the user from the Ldap Cache to components (including the generic group expander client).

External Group Information

The LDAP cache component implements the ExternalGroupServer interface allowing connector components to attach to it and receive a list of all the know users and groups from ldap.

Username Mapping

The LDAP cache can be used as a username mapper, allowing you to match users from different repositories to use the LDAP version of the username.

For example,

• Lotus Notes user: albertEinstein
• LDAP user: aEinstein

If your search application uses LDAP to authenticate, this particular user wouldn't be able to see documents entitled to the "albertEinstein" groups in Lotus Notes, to make this work you can use the username mapping provided by the LDAP Cache.

This uses an LDAP property of the user to match, for example, in LDAP you can have an attribute that's called "lotusUsername" which you will be able to cache in the LDAP Cache, and then use that attribute to map it when the Lotus Content Source is expanding its groups, so at the end instead of store the user as "albertEinsten" it will be stored as "aEinstein" with the Lotus Groups.