LDAP

The Lightweight Directory Access Protocol, or LDAP is an application protocol for querying and modifying directory services running over TCP/IP.^[1]

A directory is a set of objects with similar attributes organised in a logical and hierarchical manner. The most common example is the telephone directory, which consists of a series of names (either of persons or organizations) organized alphabetically, with each name having an address and phone number attached.

An LDAP directory tree often reflects various political, geographic, and/or organizational boundaries, depending on the model chosen. LDAP deployments today tend to use Domain name system (DNS) names for structuring the topmost levels of the hierarchy. Deeper inside the directory might appear entries representing people, organizational units, printers, documents, groups of people or anything else that represents a given tree entry (or multiple entries).

Origin and influences

Telecommunication companies introduced the concept of directory services to information technology and computer networking, as their understanding of directory requirements was well-developed after some 70 years of producing and managing telephone directories. The culmination of this input was the comprehensive X.500 specification^[2], a suite of protocols produced by the International Telecommunication Union (ITU) in the 1980s.

X.500 directory services were traditionally accessed via the X.500 Directory Access Protocol (DAP), which required the Open Systems Interconnection (OSI) protocol stack. LDAP was originally intended to be a lightweight alternative protocol for accessing X.500 directory services through the simpler (and now widespread) TCP/IP protocol stack. This model of directory access was borrowed from the DIXIE and Directory Assistance Service protocols.

Standalone LDAP directory servers soon followed, as did directory servers supporting both DAP and LDAP. The latter has become popular in enterprises, as LDAP removed any need to deploy an OSI network. Today, X.500 directory protocols including DAP can also be used directly over TCP/IP.

The protocol was originally created by Tim Howes of the University of Michigan, Steve Kille of Isode Limited, and Wengyik Yeong of Performance Systems International, circa 1993. Further development has been done via the Internet Engineering Task Force.

In the early engineering stages of LDAP, it was known as Lightweight Directory Browsing Protocol, or LDBP. It was renamed as the scope of the protocol was expanded to include not only directory browsing and searching functions, but also directory update functions.

LDAP has influenced subsequent Internet protocols, including later versions of X.500, XML Enabled Directory (XED), Directory Service Markup Language (DSML), Service Provisioning Markup Language (SPML), and the Service Location Protocol (SLP)

Protocol overview

A client starts an LDAP session by connecting to an LDAP server, by default on TCP port 389. The client then sends an operation request to the server, and the server sends responses in turn. With some exceptions, the client need not wait for a response before sending the next request, and the server may send the responses in any order.

The client may request the following operations:

• Start TLS — use the LDAPv3 Transport Layer Security (TLS) extension for a secure connection
• Bind — authenticate and specify LDAP protocol version
• Search — search for and/or retrieve directory entries
• Compare — test if a named entry contains a given attribute value
• Add a new entry
• Delete an entry
• Modify an entry
• Modify Distinguished Name (DN) — move or rename an entry
• Abandon — abort a previous request
• Extended Operation — generic operation used to define other operations
• Unbind — close the connection (not the inverse of Bind)

In addition the server may send “Unsolicited Notifications” that are not responses to any request, e.g. before it times out a connection.

A common alternate method of securing LDAP communication is using an SSL tunnel. This is denoted in LDAP URLs by using the URL scheme “ldaps”. The default port for LDAP over SSL is 636. The use of LDAP over SSL was common in LDAP Version 2 (LDAPv2) but it was never standardized in any formal specification. This usage has been deprecated along with LDAPv2, which was officially retired in 2003.

LDAP is defined in terms of ASN.1, and protocol messages are encoded in the binary format BER. It uses textual representations for a number of ASN.1 fields/types, however.

Directory structure

The protocol accesses LDAP directories, which follow the 1993 edition of the X.500 model:

• A directory is a tree of directory entries.
• An entry consists of a set of attributes.
• An attribute has a name (an attribute type or attribute description) and one or more values. The attributes are defined in a schema (see below).
• Each entry has a unique identifier: its Distinguished Name (DN). This consists of its Relative Distinguished Name (RDN) constructed from some attribute(s) in the entry, followed by the parent entry’s DN. Think of the DN as a full filename and the RDN as a relative filename in a folder.

Be aware that a DN may change over the lifetime of the entry, for instance, when entries are moved within a tree. To reliably and unambiguously identify entries, a UUID might be provided in the set of the entry’s operational attributes.

An entry can look like this when represented in LDAP Data Interchange Format (LDIF) (LDAP itself is a binary protocol):

 dn: cn=John Doe,dc=example,dc=com
 cn: John Doe
 givenName: John
 sn: Doe
 telephoneNumber: +1 888 555 6789
 telephoneNumber: +1 888 555 1232
 mail: john@example.com
 manager: cn=Barbara Doe,dc=example,dc=com
 objectClass: inetOrgPerson
 objectClass: organizationalPerson
 objectClass: person
 objectClass: top

dn is the name of the entry; it’s not an attribute nor part of the entry. “cn=John Doe” is the entry’s RDN, and “dc=example,dc=com” is the DN of the parent entry, where dc denotes Domain Component. The other lines show the attributes in the entry. Attribute names are typically mnemonic strings, like “cn” for common name, “dc” for domain component, “mail” for e-mail address and “sn” for surname.

A server holds a subtree starting from a specific entry, e.g. “dc=example,dc=com” and its children. Servers may also hold references to other servers, so an attempt to access “ou=department,dc=example,dc=com” could return a referral or continuation reference to a server which holds that part of the directory tree. The client can then contact the other server. Some servers also support chaining, which means the server contacts the other server and returns the results to the client.

LDAP rarely defines any ordering: The server may return the values of an attribute, the attributes in an entry, and the entries found by a search operation in any order. This follows from the formal definitions – an entry is defined as a set of attributes, and an attribute is a set of values, and sets need not be ordered.

Operations

The client gives each request a positive Message ID, and the server response has the same Message ID. The response includes a numeric result code which indicates success, some error condition or some other special cases. Before the response, the server may send other messages with other result data – for example each entry found by the Search operation is returned in such a message.

Expand discussion of referral responses to various operations, especially modify, for example where all modifies must be directed from replicas to a master directory.

StartTLS

The StartTLS operation establishes Transport Layer Security (the descendant of SSL) on the connection. That can provide data confidentiality (cannot be read by third parties) and/or data integrity protection (protect from tampering). During TLS negotiation the server sends its X.509 certificate to prove its identity. The client may also send a certificate to prove its identity. After doing so, the client may then use SASL/EXTERNAL to have this identity used in determining the identity used in making LDAP authorization decisions.

Servers also often support the non-standard “LDAPS” (“Secure LDAP”, commonly known as “LDAP over SSL”) protocol on a separate port, by default 636. LDAPS differs from LDAP in two ways: 1) upon connect, the client and server establish TLS before any LDAP messages are transferred (without a Start TLS operation) and 2) the LDAPS connection must be closed upon TLS closure.

LDAPS was primarily used with LDAPv2, because the StartTLS operation had not yet been defined. The use of LDAPS is deprecated, and modern software should only use StartTLS.

Bind (authenticate)

The Bind operation authenticates the client to the server. Simple Bind can send the user’s DN and password in plaintext, so the connection should be protected using Transport Layer Security (TLS). The server typically checks the password against the userPassword attribute in the named entry. Anonymous Bind (with empty DN and password) resets the connection to anonymous state. SASL (Simple Authentication and Security Layer) Bind provides authentication services through a wide range of mechanisms, e.g. Kerberos or the client certificate sent with TLS.

Bind also sets the LDAP protocol version. Normally clients should use LDAPv3, which is the default in the protocol but not always in LDAP libraries.

Bind had to be the first operation in a session in LDAPv2, but is not required in LDAPv3 (the current LDAP version).

Search and Compare

The Search operation is used to both search for and read entries. Its parameters are:

baseObject

The DN (Distinguished Name) of the entry at which to start the search,

scope

BaseObject (search just the named entry, typically used to read one entry), singleLevel (entries immediately below the base DN), or wholeSubtree (the entire subtree starting at the base DN).

filter

How to examine each entry in the scope. E.g. (&(objectClass=person)(|(givenName=John)(mail=john*))) – search for persons who either have given name John or an e-mail address starting with john.

derefAliases

Whether and how to follow alias entries (entries which refer to other entries),

attributes

Which attributes to return in result entries.

sizeLimit, timeLimit

Max number of entries, and max search time.

typesOnly

Return attribute types only, not attribute values.

The server returns the matching entries and maybe continuation references (in any order), followed by the final result with the result code.

The Compare operation takes a DN, an attribute name and an attribute value, and checks if the named entry contains that attribute with that value.

Update Data

Add, Delete, and Modify DN – all require the DN of the entry that is to be changed.

Modify takes a list of attributes to modify and the modifications to each: Delete the attribute or some values, add new values, or replace the current values with the new ones.

Add operations also can have additional attributes and values for those attributes.

Modify DN (move/rename entry) takes the new RDN (Relative Distinguished Name), optionally the new parent’s DN, and a flag which says whether to delete the value(s) in the entry which match the old RDN. The server may support renaming of entire directory subtrees.

An update operation is atomic: Other operations will see either the new entry or the old one. On the other hand, LDAP does not define transactions of multiple operations: If you read an entry and then modify it, another client may have updated the entry in the mean time. Servers may implement extensions which support this, however.

Extended operations

The Extended Operation is a generic LDAP operation which can be used to define new operations. Examples include the Cancel, Password Modify and Start TLS operations.

Abandon

The Abandon operation requests that the server aborts an operation named by a message ID. The server need not honor the request. Unfortunately, neither Abandon nor a successfully abandoned operation send a response. A similar Cancel extended operation has therefore been defined which does send responses, but not all implementations support this.

Unbind

The Unbind operation abandons any outstanding operations and closes the connection. It has no response. The name is of historical origin: It is not the opposite of the Bind operation.

Clients can abort a session by simply closing the connection, but they should use Unbind. Otherwise the server cannot tell the difference between a failed network connection (or a truncation attack) and a discourteous client.