Mozilla LDAP C SDK Programmer's Guide
Chapter 2 - An Introduction to LDAP
This chapter gives a brief introduction to the Lightweight Directory Access Protocol (LDAP) and the concepts behind LDAP.
LDAP is the Internet directory protocol. Developed at the University of Michigan at Ann Arbor in conjunction with the Internet Engineering Task Force, LDAP is a protocol for accessing and managing directory services.
The chapter is organized into the following sections:
- How Directory Services Work
- How LDAP Servers Organize Directories
- How LDAP Clients and Servers Work
- Support for the LDAPv3 Protocol
How Directory Services Work
A directory consists of entries containing descriptive information. For example, a directory might contain entries describing people or network resources, such as printers or fax machines.
The descriptive information is stored in
the attributes of the entry. Each attribute describes a specific
type of information. For example, attributes describing a person
might include the person's name (common name, or
telephone number, and email address.
The entry for
might have the following attributes:
cn: Barbara Jensen mail: firstname.lastname@example.org telephoneNumber: 555-1212 roomNumber: 3995
An attribute can have more than one value. For example, a person might have two common names (a formal name and a nickname) or two telephone numbers:
cn: Jennifer Jensen cn: Jenny Jensen mail: email@example.com telephoneNumber: 555-1213 telephoneNumber: 555-2059 roomNumber: 3996
Attributes can also contain binary data. For example, attributes of a person might include the JPEG photo of the person or the voice of the person recorded in an audio file format.
A directory service is a distributed database application designed to manage the entries and attributes in a directory. A directory service also makes the entries and attributes available to users and other applications. Netscape Directory Server is an example of a directory service.
For example, a user might use the directory service to look up someone's telephone number. Another application might use the directory service to retrieve a list of email addresses.
LDAP is a protocol defining a directory service and access to that service. LDAP is based on a client-server model. LDAP servers provide the directory service, and LDAP clients use the directory service to access entries and attributes.
An example of an LDAP server is Netscape Directory Server, which manages and provides information about users and organizational structures of users, such as groups and departments. Examples of LDAP clients include the HTTP gateway to the Netscape Directory Server, and the Mozilla addressbook and email clients. The gateway uses the directory service to find, update, and add information about users.
How LDAP Servers Organize Directories
Because LDAP is intended to be a global directory service, data is organized hierarchically, starting at a root and branching down into individual entries.
At the top level of the hierarchy, entries represent larger organizations. Under these larger organizations in the hierarchy might be entries for smaller organizations. The hierarchy might end with entries for individual people or resources.
Figure 2-1 illustrates an example of a hierarchy of entries in an LDAP directory service.
Figure 2-1 - A hierarchy of entries in the directory
Each entry is uniquely identified by a distinguished name. A
distinguished name consists of a name that uniquely identifies
the entry at that hierarchical level (for example,
kjensen are different user
IDs that identify different entries at the same level) and a path
of names that trace the entry back to the root of the tree.
For example, this might be the
distinguished name for the
uid=bjensen, ou=People, dc=example,dc=com
uid represents the
user ID of the entry,
ou represents the
organizational unit in which the entry belongs, and
represents the larger organization in which the entry belongs.
The following diagram shows how distinguished names are used to identify entries uniquely in the directory hierarchy.
Figure 2-2 - An example of a
distinguished name in the directory
The data stored in a directory can be
distributed among several LDAP servers. For example, one LDAP
example.com might contain entries
representing North American organizational units and
employees, while another LDAP server might contain entries
representing European organizational units and employees.
Some LDAP servers are set up to refer
requests to other LDAP servers. For example, if the LDAP
example.com receives a request for
information about an employee in a Pacific Rim branch, that
server can refer the request to the LDAP server at the Pacific
Rim branch. In this way, LDAP servers can appear to be a single
source of directory information. Even if an LDAP server does
not contain the information you request, the server can refer
you to another server that does contain the information.
How LDAP Clients and Servers Work
In the LDAP client-server model, LDAP servers make information about people, organizations, and resources accessible to LDAP clients. The LDAP protocol defines operations that clients use to search and update the directory. An LDAP client can perform these operations, among others:
- earch for and retrieve entries from the directory.
- Add new entries to the directory.
- Update entries in the directory.
- Delete entries from the directory.
- Rename entries in the directory.
For example, to update an entry in the directory, an LDAP client submits the distinguished name of the entry with updated attribute information to the LDAP server. The LDAP server uses the distinguished name to find the entry and performs a modify operation to update the entry in the directory.
To perform any of these LDAP operations, an LDAP client needs to establish a connection with an LDAP server. The LDAP protocol specifies the use of TCP/IP port number 389, although servers may run on other ports.
The LDAP protocol also defines a simple method for authentication. LDAP servers can be set up to restrict permissions to the directory. Before an LDAP client can perform an operation on an LDAP server, the client must authenticate itself to the server by supplying a distinguished name and password. If the user identified by the distinguished name does not have permission to perform the operation, the server does not execute the operation.
Support for the LDAPv3 Protocol
Many LDAP servers support version 2 of the LDAP protocol. LDAPv2 is specified in RFC 1777. You can find a copy of this RFC at the following site:
The most recent proposed standard of the LDAP protocol is version 3 (LDAPv3), which is specified in RFC 2251. This RFC can be found at the following URL site:
Pv2 by default. To override the default LDAP version, use the
There are certain functions that are specific to LDAPv3 included in this SDK. The functions that are specific to LDAPv3 are marked as such in the Reference section of this manual.