Appendix A An Introduction to LDAP

The Sun™ Java System Directory Server Resource Kit contains the LDAP SDK for C enabling programmers to write new, or modify existing, applications to connect to, search or update databases managed by directory servers using the Lightweight Directory Access Protocol (LDAP). This appendix offers a brief introduction to the LDAP and it’s concepts. It contains the following sections:

Overview

The LDAP is the Internet directory protocol. Developed at the University of Michigan at Ann Arbor in conjunction with the Internet Engineering Task Force (IETF), it is used for managing, and accessing data from, directory services. LDAP is based on a client/server model in which requests from a client program are transmitted over a network to a server program and results are transmitted back from the server to the client. LDAP servers provide the directory service, and LDAP clients use the directory service to access entries and attributes. It runs directly over the Transmission Control Protocol/Internet Protocol (TCP/IP).



Note	With LDAPv3, DNs should not have spaces after the comma. The format is accepted to be backward compatible with LDAPv2. As an example, the DN of Bab Jensen should be uid=bjensen,ou=People,dc=example,dc=com and not uid=bjensen, ou=People, dc=example, dc=com.

How Directory Services Work

A directory service is a distributed database application designed to manage the entries and attributes in a directory. It also makes the entries and attributes available to users and other applications. 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. The Sun Java System Directory Server is an example of a directory service. It manages and provides information about users and organizational structures, such as groups and departments.

Defining Information Using LDAP

A directory database consists of data entries that contain descriptive information. These entries might describe people or network resources (such as printers or fax machines). The LDAP defines the types of data and units of information that can be stored in a directory. The directory is organized based on entries and attributes. An entry, the base unit of the LDAP, is a collection of attributes which contain information that describes it. Each attribute is comprised of a type and one or more values that describe a particular trait of the object’s entry. The type describes what the information is; the value is the information itself. For example, attributes describing a person’s entry might include one for the person’s name (usually, common name, or cn), a telephone number, and an email address. Code Example A-1 is a sample entry taken from testdata.ldif in the DSRK_base/java/LDAPSubtDel directory. The text before the colon is the type; after the colon is the value. (For information on the LDAP Data Interchange Format, see "The LDIF File Format.")

Code Example A-1 Sample LDAP Entry


dn: uid=person5,ou=People,dc=siroe,dc=com
cn: person5
sn: person5
givenname: person5
objectclass: top
objectclass: person
objectclass: organizationalPerson
objectclass: inetOrgPerson
ou: Product Development
ou: People
l: Menlo Park
uid: person5
mail: person5@siroe.com
telephonenumber: 053-838-9384
facsimiletelephonenumber: 598-054-3814
roomnumber: 76
userpassword: secret

An attribute can have more than one value. Code Example A-2 shows how a person can have two common names (a formal name and a nickname) as well as two telephone numbers.

Code Example A-2 Entry for Jennifer Jensen


...
cn: Jennifer Jensen
cn: Jenny Jensen
mail: jen@corporation.com
telephoneNumber: 555-1213
telephoneNumber: 555-2059
roomNumber: 3996

The LDAP Schema

A base unit entry has a set of attribute types that are required and a set that can be used optionally. For example, the entry for a person is required to have a common name (cn) and a surname (sn). It is allowed to have a telephone number and an email address. This information is stored in a LDAP schema. Your directory server comes with a LDAP schema that is the definition of what can be stored in the directory. It includes object classes and attributes. The object classes are required or allowed and are defined with one or more attributes which are also required or allowed. Each attribute is associated with a syntax that determines what can be stored in that attribute (plain text, encoded data, etc.).

While the object classes and attributes defined in the schema should meet most of your needs, it can be necessary to extend the standard schema with additional object classes and/or attributes.

The LDIF File Format

LDAP Data Interchange Format (LDIF) is used to describe the contents and entries of a directory server in ASCII text format. LDIF is commonly used to build a directory database or to add large numbers of entries to the directory all at once. In addition, LDIF can also used to describe changes to directory entries. For this reason, most of the directory server’s command-line utilities rely on LDIF for input or output.


Note	Attributes can also contain binary data. For example, attributes of a person might include a JPEG photo of the person or their voice recorded in an audio file format.

Each LDIF entry consists a required distinguished name (dn), one or more object classes, and multiple attribute definitions. Code Example A-3 is the basic form of a directory entry represented in LDIF.

Code Example A-3 Generic LDIF Format


dn: <distinguished name>
objectClass: <object class>
objectClass: <object class>
...
<attribute type>[;lang-TAG]:<attribute value>
<attribute type>[;lang-TAG]:<attribute value>
...

You can specify object classes and attributes in any order although the standard is to list all object classes first followed by the attribute type/value pairs. The space after the colon is optional.

Organizing LDAP Within a Directory Server

Because LDAP is intended for 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 large organizational units. Under these larger units might be entries for smaller organizational units. The hierarchy would siphon down to entries for individual people or resources.

Organizing and referring to your data within a directory server entails creating containers into which the base unit entries (explained in Defining Information Using LDAP) can be placed. For example, one container might hold all person entries while another might hold only those person entries defined as Human Resources personnel. Figure A-1 is a simple example of how entries might be organized within containers.

Distinguished Names

Each entry in a directory service is uniquely identified by a distinguished name (dn). The dn is a unique LDAP name that allows you to conclusively refer to any entry. For example, bjensen and kjensen are examples of user IDs that identify two entries at the same level. The dn includes a path of names that trace the entry back to the root of the tree. For the bjensen entry, the DN would be:

Here, uid represents the user ID of the entry, ou represents the organizational unit to which the entry belongs, and o represents the larger organization to which the entry belongs. Figure A-2 shows how distinguished names are used to identify entries uniquely in the directory hierarchy.

Data Distribution

The data stored in a directory can be distributed among several LDAP servers. For example, one LDAP server for a corporation might contain entries representing North American organizational units and employees, while another might contain entries representing European organizational units and employees. Thus, if the North American LDAP server receives a request for information about an employee in the European branch, it can refer the request to the LDAP server in the European branch. In this way, LDAP servers appear to be a single source of directory information.