Introduction to LDAP tools

LDAP (Lightweight Directory Access Protocol) is a protocol for accessing information in an information tree. The information tree is called a Directory Information Tree (DIT) and it is made up of parent and child directory entries. Each directory entry has a unique name, called a Distinguished Name (DN). Each entry also has a collection of attributes, which are name/value pairs that contain information about the entry.

The LDAP tools allow CIC to communicate with an LDAP server (LDAP v3 compliant) to retrieve attribute values from the directory entries. We foresee this as an alternative to retrieving user data from CIC's Directory Services. For example, a DIT might contain information about 10,000 users, including first name, last name, and email address. Instead of setting up CIC user accounts for each user, you can use the LDAP tools to look up the user email addresses from the LDAP server.

A sample DIT is shown in the following figure.

An entry's DN is comprised of it's own name, and the names of its parent entries. For example, compare the JDoe entry DN to the previous figure to see how the DN is constructed:

uid=JDoe, ou=subscribers, ou=People, dc=inin, dc=com

Many of the LDAP tools require you to specify the DN you want to query or write to. Your DNs will look different since you have a different DIT. You should discuss your company's DIT structure with your LDAP administrator so that your handlers can construct valid DNs.

All entries contain attributes. Attributes are name/value pairs, and some attributes have more than one value, as illustrated in the following figure.

A person entry, such as JDoe in the previous figure, might contain a uid (user ID), common name (cn), mail, and many more attributes. The LDAP tools enable you to retrieve the value of an attribute in the directory entry you specify. Therefore, you could use the LDAP tools to search for all entries where the last name is Doe and return all email address attributes for those matching entries. Again, you'll need to discuss the entry types and their associated attributes with your LDAP administrator. He or she can give you a list of all entry types and their attribute names. You'll need this information when processing attributes within handlers.

The LDAP tools allow you to create and delete entries, and to read, write, and delete attribute values.

The Connection Cache

The LDAP tools internally maintain a connection cache of recently used LDAP connections. Each time an LDAP session is created, the Session tool first looks at the connection cache to see if there are any available connections for the specified server host name/login-information combination. If none are found, then a new connection is created with the specified LDAP server and that connection is added to the connection cache. When the handler that created that session ends, or when the Close Session tool is explicitly called for that session, the connection will be held in the connection cache for re-use by other handlers. A new connection will be created each time the Session tool is called and there are no available connections in the cache. There is no upper limit to the number of connections that will be held in the connection cache unless one is set by means of the Set Max Cache Size tool.

As an example of how this works, let's assume that no connections have been made to an LDAP server and that the connection cache is empty:

1) An LDAP session is created via the LDAP Session tool. The Session tool first looks in the connection cache to see if there are any available connections for the specified server host name/login-info combination. Finding none, a new connection is made with the specified LDAP server and added to the connection cache.

2) A second handler calls the LDAP Session tool for a second session. This second session tool also looks in the cache to see if an existing connection is available. It finds one connection there, but that connection is still in use. Since the first session is still being used (we didn't close it, and the handler is still running), then a second connection is created and added to the connection cache.

3) The handler that created session 1 then exits. The session is closed and the connection is marked as available in the connection cache. The actual physical connection with the LDAP server is still active at this point, though it is not in use.

4) A third handler then wants a connection to the same server (with the same login info). The session tool looks in the connection cache and sees two sessions. One that's still in use (by the second handler in step 2), and one that's available (the session created from the first handler that has now exited). Instead of having to make a new physical LDAP connection to the LDAP server, it just re-uses the existing LDAP connection established earlier (in step 1), marks it as in use in the cache and returns it to the session tool. Because the physical connection already existed, the new session was connected more or less instantly.

By default, the connection cache has no set limit on how many connections it will cache. An upper limit can be set and adjusted using the Set Max Cache Size tool. This sets the maximum number of connections that will be cached. Note that it does not set the maximum number of connections that can be made, just the number that will be stored in the cache. Other connections made above a set limit will be terminated when no longer in use.

For example, let's say we have 5 in-use connections and a maximum cache size is 5. If another tool needs another session and those other 5 connections are still in use, then a new session will still be created. New connections will never be refused. However, this sixth session object won't be added to the connection cache for later re-use because the maximum cache size has already been reached. When this sixth session handle goes away or is closed, then the LDAP connection will be immediately closed.

The LDAP Tools

This section briefly describes the tools and provides links to each tool’s specific help topic. See the diagram in LDAP: The order in which LDAP tools might be used for more information on using these tools and the order in which they should be used.

Add Entry

Creates a new entry at the location you specify. You may also specify the entry's attributes and their values.

Add Entry Ex

Add Entry Ex creates a new entry like the Add Entry tool, but allows you to use an operation list to assign multiple values to an attribute.

Add Operation

Creates an LDAP operation and adds it to the operation list for execution with the Add Entry Ex or Modify Entry Ex tools. Operation lists are useful in LDAP because they allow you to perform multiple operations on multiple attributes over one connection to the LDAP server. For example, a caller might choose to modify their password and change several other personal settings through an IVR. The handler could add all of these operations to a list, and then execute them. You must specify an integer for the type of operation to perform.

Note: To create a list of multiple operations will probably use many instances of this tool in a handler, or create a loop so that this tool executes several times.

Close Session

The Close Session tool explicitly releases an LDAP session, making it available again in the cache.

Delete Entry

Deletes the specified LDAP entry (and all of its attributes).

Flush Cache

This tool removes all connections from the connection cache that are not currently in use.

Get Cache Size

Retrieves the number of connections presently in the connection cache.

Get Entry Attributes

Get Entry Attributes takes an entry handle (generated by the Read Entry or Next Entry tool) and extracts the value of an attribute you specify. The value must be one of the values you requested with the Read Entry or Search Entry tools. The attribute values are placed in a list of string variables. This is because an attribute can have more than one value.

Login

The Login tool logs a user into an LDAP server. The Login step must execute once in the handler before other LDAP tools are executed. You must specify a Login ID and Password. The other LDAP tools will have permissions based on that user's permissions. For example, if the tool logs in as administrator, the handler might have read/write access to the entire DIT. An individual user's login might grant access to only that user's entry.

Modify Entry

Changes the value of one or more LDAP entry attributes. Note that you may only specify one value for each attribute. However, if an attribute already has a value, you may use this tool to specify one additional value.

Modify Entry Ex

While the Modify Entry tool allows you to modify a single attribute, the Modify Entry Ex tool allows you to modify multiple attributes and to assign multiple values to a single attribute. This is useful because it reduces the network resources required to execute multiple operations. The operations list that this tool executes includes add, delete, and modify entry operations. Use the Add operation tool to create an operation and add it to an operation list. You might use Modify Entry Ex in a handler when a caller selects several configuration options in a single IVR session. Each configuration option could be stored in the handler's operation list and executed simultaneously before the handler ends.

Move Entry

Changes the RDN attribute and changes the parent. All of the attribute values remain unchanged except for the UID attribute.

Next Entry

The Search Entries tool generates the search result object that may contain multiple matching entries. There is an iterator in the search result object that points to one of those entries. The Next Entry tool generates a handle to the entry that the iterator is pointing to, and then moves the iterator to the next entry in the search result object. The entry handle can then be passed to the Get Entry Attribute tool (just like the entry handle the Read Entry tool creates. When all of the entries have been read, this tool takes the End of List exit path.

Read Entry

Read Entry retrieves specified attributes from a specified DS entry. It then creates an entry handle to that entry that you can pass to the Get Entry Attribute tool to extract the attribute value(s).

Rename Entry

Changes the RDN attribute of an LDAP entry without changing its parent. All of the attribute values remain unchanged except for the UID attribute.

Search Entries

Searches a specified portion of a DIT for entries that match one or more search criteria. The search criterion consists of attribute/value pairs and allows several types of wildcard matching. You also specify the attribute/value pairs you want to return for all matching entries. The matches are placed in a search result object.

Session

Session uses the Login ID to generate a session with the LDAP server. Several other LDAP tools that add, modify, and delete entries use the Session ID this tool generates. The session tool typically follows the Login tool.

Set Max Cache Size

Sets an upper limit to the number of connections that will be held in the connection cache.