LDAP class

The LDAP class simplifies public searches of an organization's LDAP (Lightweight Directory Access Protocol) directory. The LDAP class is a high level, object oriented interface to client sockets that lets you write a SOUL LDAP request without knowledge of socket level programming or the format of LDAP requests and responses.

The LDAP class methods allow a SOUL program to act as an LDAP client to access and retrieve directory information through an LDAP server. The LDAP server may be running on any platform to which the LDAP client online can make a TCP/IP connection.

You use JANUS commands (DEFINE, START, NAMESERVER) to define and start a TCP/IP CLSOCK port for the LDAP client to use.

Note: To use LDAP objects under versions of Model 204 earlier than 7.5, you must have licensed Janus TCP/IP Base, Janus Sockets, and Janus SOAP. Under version 7.5 and later, you do not require Janus SOAP.

For information about using SOUL objects, see Object oriented programming in SOUL.

Feature summary

The LDAP class provides the following capabilities:

• Read access to X.500 and LDAP v2 directory services.
• One-step connection and login to an LDAP server (with user ID and password passing as well as also anonymous logins).
• Multiple search filters, each in a separate method.
• Text-only retrieval: all returned data is automatically converted from ASCII to EBCDIC. UTF-8 encoding is not supported.
• Automatic deserializing of returned data into XML in an XmlDoc object.
• A limit of approximately 1300 bytes to the data sent in or returned from a single query of the server.
• Optional retrieval of only the directory entry attribute names, that is, the names without the corresponding attribute values.
• Optional SSL (Secure Sockets Layer) data transmission.

The following LDAP features are not currently supported by the LDAP class:

• Kerberos user logins.
• Modifying, deleting, or adding directory content.
• Full compliance with LDAP v3 (for example, UTF-8 is not supported)
• Arbitrary, user-constructed search queries (RFC 1960 syntax featuring boolean operators is not supported).
• Restart of aborted transfers.
• Limiting the quantity of the server data returned or the number of entries returned.

LDAP overview

A directory is a repository for the storage and retrieval of information, and LDAP (Lightweight Directory Access Protocol) is a vendor- and platform-independent standard for accessing computerized directories. LDAP is a subset of X.500, a more complex enterprise directory system. LDAP, like X.500, is both an information model (with namespace) and a protocol for querying and manipulating directory data. Unlike X.500, LDAP is designed to run directly over the TCP/IP stack, and it has a smaller set of query and update functions.

An LDAP directory server runs on a host computer on the Internet, and it provides directory access to client programs that understand the LDAP protocol and can log into the server and look up information. The information is stored in units known as entries. For example, all the data for a particular person is typically contained in a single entry.

Entries are used to store attributes, each of which has an associated type and one or more values. An entry for a person may have a firstname attribute type whose value is Byron, for example. The type determines the attribute's syntax, which defines what kind of information is allowed in the values. The entries are arranged in a tree structure.

LDAP servers index all the data in their entries, and filters are used to select a matching entry or group of entries. A filter specifies attribute types, assertion values, and matching criteria. The LDAP model also defines operations for adding, removing, or changing entries in the directory.

For more information about the LDAP protocol, hear are some relevant Internet RFCs:

• RFC 1777

  The best place for detailed information about LDAP is Internet RFC 1777 (http://www.ietf.org/rfc/rfc1777.txt), which specifies the protocol. An excerpt follows:

  "The protocol described in this document is designed to provide access to the X.500 Directory while not incurring the resource requirements of the Directory Access Protocol (DAP). This protocol is specifically targeted at simple management applications and browser applications that provide simple read/write interactive access to the X.500 Directory, and is intended to be a complement to the DAP itself."

• RFC 2256

  This RFC (http://www.ietf.org/rfc/rfc2256.txt), provides a summary of the attribute types and object classes defined for use by LDAP/X.500 directory clients. Although the attribute types implemented by an LDAP server are server-specific, many of the standard types are typically used.

• RFC 2849

  This RFC (http://www.ietf.org/rfc/rfc2849.txt) specifies the format of a directory entry that is returned by the LDAP server.

  The LDAP Data Interchange Format (LDIF) "consists of a series of records separated by line separators. A record consists of a sequence of lines describing a directory entry, or a sequence of lines describing a set of changes to a directory entry. An LDIF file specifies a set of directory entries, or a set of changes to be applied to directory entries, but not both."

  The LDAP class reformats LDAP server responses in an XML document, as described in Working with returned values. This Janus XML formatting does not follow the "DSML" model described in http://www.worldspot.com/dsmlgw-xml-rpc/DSMLGateway.html.

• RFC 1960

  This RFC (http://www.ietf.org/rfc/rfc1960.txt) provides a grammar that can be used to do arbitrary LDAP queries. This grammar is not currently supported by the LDAP class.

Using the LDAP class

The LDAP class makes the information in LDAP directories more easily accessible by removing LDAP protocol concerns from the programmer. To retrieve data from an LDAP server, applications must:

1. Define a Janus CLSOCK port.
   • Use the JANUS DEFINE command to:
     • Create a TCP/IP port for your Model 204 LDAP client application.
     • Indicate the remote LDAP server identifier and port number (or a pattern that allows the specific server to be specified by an LDAP class method).
     • Set a timeout value for the LDAP connections.
   • Use the JANUS NAMESERVER command to let you reference remote hosts by name rather than IP address.
   • Use a JANUS CLSOCK command to specify access rules for your port.
   • Use the JANUS START command to start your port.
2. Bind a connection and log in to an LDAP server.

   In your SOUL request, a single Bind method statement performs these actions.

3. Send a search query to the LDAP server.

   Use one of the multiple Find methods, which provide a variety of search filters. See Using the Find methods.

4. Optionally, extract particular data from the returned value. See Working with returned values.
5. End your session when ready.

   The Unbind method logs off the LDAP user, and it deactivates the connection.

Working with returned values

The directory information returned from an LDAP server in response to a Janus LDAP Find call is stored in an XmlDoc object. This object contains exactly the data strings sent from the server, in whatever case.

The XML structure of such an XmlDoc is shown in this sample fragment, whose features are described after the example:

<result> <entry objectName="cn: Sildar, John R, id=X479, c=US"> <cn> <value>Sildar, John R</value> </cn> <sn> <value>Sildar</value> </sn> </entry> </result>

• The top element is named result. If no matches were found, only an empty result element (<result/>) is present.
• The result element has zero or more entry children.
• Each entry element has one or more child elements, each named for the LDAP attribute type whose returned data it contains (for example, cn, sn, telephonenumber).
• Each attribute-type element has zero or more value child elements that contain that LDAP attribute's value(s). If the Find call specified an AttributesOnly=True argument, any value children are not displayed.
• The entry element in this example has an (XML) attribute named objectName that contains identifying information for the entry (this is the LDAP Distinguished Name field for the entry).

Using XPath to search returned values

In the XmlDoc returned from an LDAP query, the LDAP attribute names themselves are the XmlDoc element names. One consequence of this is that you can use Janus SOAP XmlDoc API method calls with relatively simple XPath-expression arguments to extract particular "fields" from a returned value.

For example, to extract the first value of attribute sn in the first found entry in the returned XmlDoc %doc, you can use the Value property with a straightforward XPath argument:

Print %doc:Value('result/entry/sn/value')

Or, alternatively:

%entry = %doc:selectSingleNode('/result/entry') Print %doc:Value('sn')

For more information about selecting nodes from an XmlDoc, see SelectSingleNode.

To return the first value of sn in the second found entry, in a case where multiple entries were found, you can use:

Print doc:Value('result/entry[2]/sn/value')

And to return the first value of sn in the third (or greater) found entry:

Print doc:Value('result/entry[position()>=3]/sn/value')

Instantiating and discarding LDAP objects

The LDAP class has no explicit constructor or destructor methods. To create or discard an LDAP object instance, you use the system New and Discard methods that are available to all SOUL classes.

The New Constructor allocates and initializes storage for a new LDAP object instance. It takes no arguments. A separate method (Bind) establishes a connection to an LDAP server.

When an LDAP client no longer wants to query the LDAP server, the LDAP Unbind method unauthenticates the LDAP user and severs the connection to the server host. The LDAP object instance remains available for reuse. If no further references to it exist, it gets discarded automatically ("implicitly"). You can also use the generic (Object class) Discard method to discard an LDAP object:

%ldapObject:Discard

The Discard method does not set the ErrorNumber and ErrorText properties.

Using the Find methods

In the LDAP Internet RFC 1777, a filter "defines the conditions that must be fulfilled in order for the search to match a given entry." The RFC specifies the variety of search filters shown below:

Filter ::= CHOICE { and [0] SET OF Filter, or [1] SET OF Filter, not [2] Filter, equalityMatch [3] AttributeValueAssertion, substrings [4] SubstringFilter, greaterOrEqual [5] AttributeValueAssertion, lessOrEqual [6] AttributeValueAssertion, present [7] AttributeType, approxMatch [8] AttributeValueAssertion }

The LDAP class implements many of these filters with the following Find methods:

• FindEQ
• FindStringInCommonName
• FindGE
• FindLE
• FindApprox

The LDAP Internet RFC 1960 specifies a syntax for a string representation of these filters, but SOUL LDAP does not have an implementation of such a syntax.

With one exception, the Janus LDAP Find methods have the same arguments and differ only in how the search strings that they provide are interpreted by the LDAP server. Many of the individual Find method descriptions in the following sections therefore avoid repetition by pointing to the representative and probably most commonly used methods: FindEQ (an equality search of the attribute type you specify) and FindStringInCommonName (a search of the cn attribute type for the substring you specify).

The following are true for all the Find methods:

• The LDAP server's resolution of a search query (its "matching rules") is implementation-specific, varies with the attribute type, and is affected by what the directory database uses for search keys, indices, search algorithms, and so on.
• The scope of the search requested by the Janus client is hard-coded to be "whole subtree," that is, all the levels of attribute=value pairs (nodes) in the directory tree.
• By default, Model 204 uppercases the search string characters you specify before it sends them to the LDAP server. You can use the Model 204 *LOWER command to turn off the default uppercasing.
• It is LDAP server-specific whether you must precede special characters in your search string with an escape character to locate directory values that include those special characters, and the character to use as an escape character is also server-specific. This said, the asterisk (*), left-parenthesis ((), right-parenthesis ()), and backslash (\) characters often require escaping, and a backslash is often the escape character. Escaping the question mark character (?) and other special characters, like equal sign (=), angle brackets (< >), tilde (~), and quotation marks (", '), is often optional. Whether wildcard characters, typically asterisk (*) and question mark (?), are respected by a server search engine is server-specific. A search for the surname ?aldo* may return the names Baldock and Baldona, or it may return an empty result.
• You cannot limit the amount of the server data returned nor, say, the number of entries returned, although LDAP servers will enforce their own limits. For requests sent to the server, the SOUL LDAP client buffers allow for several hundred bytes for any particular substring (for example, the text in an attribute value) and a total of 8184 bytes for any single message.
• To limit the length of time of a search, you set the TIMEOUT parameter value on the JANUS DEFINE command for the Janus port used for connections to the LDAP server.
• The LDAP Find methods store the found entries in an XmlDoc object output argument, and they return an optional status value with information about the success of the search.
• A search that returns no matches is not considered an error. Your returned XmlDoc contains a single empty element: <result/>.
• The LDAP Find methods also have options that let you:
  • Restrict the information reported for each entry to just the attribute types you list
  • Retrieve only the names of the entry attribute types themselves

LDAP class example

The procedure below, which exercises many of the LDAP methods, does the following:

1. Defines a Janus port for an LDAP client.
2. Creates an LDAP object, then connects to an LDAP server.
3. Performs an equality search using a traditional attribute type (sn) to return the names of the attribute types implemented by this LDAP server. This informs the user for the next step.
4. In a repeating loop, prompts the user for an attribute type and search value, performs an equality search with the user-specified values, then searches the returned XmlDoc for the value of a particular attribute.
5. Disconnects from the LDAP server.

UTABLE LPDLST 8000 * JANUS NAMESERVER 198.142.144.8 43 JANUS DRAIN LDSOCK1 JANUS FORCE LDSOCK1 JANUS DELETE LDSOCK1 JANUS DEFINE LDSOCK1 * CLSOCK 5 TIMEOUT 180 MASTER REMOTE * * JANUS START LDSOCK1 JANUS STATUS * Begin %ld Object Ldap %doc Object XmlDoc Auto New %status float %Attrib string len 255 %SearchString string len 255 %PortNumber float %val is longstring *************** %ld = New %status = %ld:Bind(JanusPort='LDSOCK1', - LDAPServer='ldap.college.edu') If %status then Print 'Bad status from Ldap:Bind: ' %status Print ' LDERRNO: ' %ld:ErrorNumber Print ' LDERRMS: <' %ld:ErrorText '>' Stop End If *************** Print 'AttributesOnly result: ' %status = %ld:FindEQ('sn', 'Sildar', %doc, - AttributesOnly=True) If %status then Print 'Bad status from Ldap:FindOP: ' %status Print ' LDERRNO: ' %ld:ErrorNumber Print ' LDERRMS: <' %ld:ErrorText '>' Stop End If %doc:Print * Must clear XmlDoc %doc = New *************** * Ask user for attrib and value for FindEQ test * Either string empty breaks out of the loop Repeat Forever %Attrib = $READ ('What attribute for an EQ search?') If (%Attrib EQ '') then Loop End End If %SearchString = $READ ('What value?') If (%SearchString EQ '') then Loop End End If Print 'Searching for <' %Attrib ' EQ ' %SearchString '>' %status = %ld:FindEQ(%Attrib, %SearchString, %doc) If %status then Print 'Bad status from Ldap:FindEQ: ' %status Print ' LDERRNO: ' %ld:ErrorNumber Print ' LDERRMS: <' %ld:ErrorText '>' Stop End If %doc:Print * Print the email address %val = %doc:Value('result/entry/mail/value') Print 'found value is ' %val %doc = New End Repeat *************** %status = %ld:Unbind If %status then Print 'Bad status from Ldap:Unbind: ' %status Print ' LDERRNO: ' %ld:ErrorNumber Print ' LDERRMS: <' %ld:ErrorText '>' End If End

List of LDAP methods

The List of LDAP methods contains a complete list of the class methods.

See also

• Janus Sockets User Language coding considerations
• Sample Janus Sockets programs
• Socket-level interfaces:
  • $functions
  • Socket class
• Higher-level interfaces:
  • Email class
  • HTTP Helper classes
  • LDAP class
  • Janus FTP Server
  • Janus Telnet Server