Lightweight Directory Access Protocol, or LDAP

LDAP: An Introduction

LDAP is a protocol for accessing existing on-line directory services. It runs directly over TCP and can be used to access a standalone LDAP directory service or to access a directory service that is back-ended by X.500. A directory is like a database, but tends to contain more descriptive, attribute-based information. The information in a directory is generally read much more often than it is written. As a consequence, directories don't usually implement the complicated transaction or rollback schemes regular databases use for doing high-volume complex updates. Directory updates are typically simple all-or-nothing changes, if they are allowed at all. Directories are tuned to give quick-response to high-volume lookup or search operations.

What kind of information is stored in a directory? The LDAP directory service model is based on entries. An entry is a collection of attributes that has a name, called a distinguished name (DN). The DN is used to refer to the entry uniquely, like a Primary Key in a database. Each of the entry's attributes has a type and one or more values. The types are typically like "sn" for last name, "mail" for email address, or "telephonenumber" for telephone numbers.

In an LDAP, directory entries are arranged in a hierarchical tree-like structure that reflects geographic and/or organizational boundaries. Entries representing countries appear at the top of the tree. Below them are entries representing states or national organizations. Below them might be entries representing people, organizational units, printers, documents, or anything else. Figure 2 shows an example LDAP directory tree.

In addition, LDAP allows you to control which attributes are required and allowed in an entry through the use of a special attribute called objectclass. The values of the objectclass attribute determine the schema rules the entry must obey.

Figure 2: An Example LDAP Directory Tree.

An entry in LDAP is referenced by its distinguished name, which is constructed by taking the name of the entry itself (called the relative distinguished name, or RDN) and concatenating the names of its ancestor entries. For example, the entry for Puneet Kukreja in the example above has an RDN of "cn=Puneet Kukreja" and a DN of "cn=Puneet Kukreja, o=Monash University, c=AU". The full DN format is described in RFC 1779, "A String Representation of Distinguished Names" (see http://www.ietf.org/rfc/rfc1779.txt?number=1779).

The Build Process

Having gained an introductory background, we will start the process of building the Web service using the new ColdFusion MX technology and good old Web forms.

All of us are familiar with search because it is performed on every major Web site today and is an essential part of any corporate intranet. The input parameters from our search page will be submitted to the Web service that will run the search against an LDAP server.

Tools to Create a Web Service

The tools that will be used to build this Web service are:

• Any text editor or HTML rendering tool to write our Web form
• Macromedia, Inc.'s ColdFusion MX Server (Beta Edition) to host the Web service
• Macromedia Dreamweaver MX Studio (Beta Edition) to write the Web service and the Web service client

Designing the Application

The Web form will submit the search request to the Web service, which will in turn contact the LDAP server to retrieve the search results. When we start to build this application, we will see how Web Services and ColdFusion Components fit together.

ColdFusion Web Service

Look at some sample code before we write our actual Web service in order to understand the basics.

The cfcomponent tag indicates the CFC, much like the HTML tag indicates the beginning and end of an HTML page.

The cffunction tag indicates the functionality of the component. There can be multiple cffunction tags in a single component. When we invoke the CFC from our ColdFusion page, any one of the functions can be called. This is especially useful if there are sets of related functionality that we want to move to a separate file for maintainability of code. The cffunction tag has five attributes. Dreamweaver MX inserts three attributes as a default:

• Name - The name of the function needs to be unique in the CFC page so that it can be called from the function individually.
• Access - This determines who can access the component method by client type. If we leave the access set to public, then any other CFML page on the ColdFusion server will be able to access the CFC. If we change the access to remote, then that enables the CFC to be called as a Web service.
• Returntype - This attribute gives data type validation for returned values.

Client to Consume the Web Service

Once we have written the CFC it is very easy to call it.

For this article we will call it from a ColdFusion page; in the next article we will call this Web service from a .NET client. In the ColdFusion page where you want to call the CFC, use the cfinvoke tag. In the cfinvoke tag, we can call individual functions inside of the CFC and specify the name of the return variables that are returned from the CFC.

Here is a skeleton code for invoking the Web service. We will write a complete Web service and invoke it in Part 2. This is just to make us aware of what is happening and how the return code is structured.

         component="ComponentName"    

         returnvariable="returnResult"        

         >

      # returnResult#

This explains the basics of building a Web service in ColdFusion and also the client to consume it.

An Explanation of CFLDAP

The CFLDAP tag in ColdFusion helps to query the LDAP server.

Syntax

    PORT="port_number"

    USERNAME="name"

    PASSWORD="password"

    ACTION="action"

    NAME="name"

    TIMEOUT="seconds"

    MAXROWS="number"

    START="distinguished_name"

    SCOPE="scope"

    ATTRIBUTES="attribute, attribute"

    FILTER="filter"

    SORT="sort_order"

    DN="distinguished_name"

    STARTROW="row_number">

SERVER - Required. Host name ("ldap.server.name") or IP address ("111.111.000.000") of the LDAP server.

PORT - Optional. Port defaults to the standard LDAP port, 389.

USERNAME - Optional. If no username is specified, the LDAP connection will be anonymous.

PASSWORD - Optional. Password corresponds to username.

ACTION - Optional. Specifies the LDAP action. There are five possible values:

• Query -- (Default) Returns LDAP entry information only. Requires NAME, START, and ATTRIBUTES attributes.
• Add -- Adds LDAP entries to the LDAP server. Requires ATTRIBUTES.
• Modify -- Modifies LDAP entries on an LDAP server with the exception of the distinguished name ("DN") attribute. Requires DN, ATTRIBUTES.
• ModifyDN -- Modifies the distinguished name attribute for LDAP entries on an LDAP server. Requires DN, ATTRIBUTES.
• Delete -- Deletes LDAP entries on an LDAP server. Requires DN.

NAME - Required for ACTION="Query". The name you assign to the LDAP query.

TIMEOUT - Optional. Specifies the maximum amount of time in seconds to wait for LDAP processing. Defaults to 60 seconds.

MAXROWS - Optional. Specifies the maximum number of entries for LDAP queries.

START - Required for ACTION="Query". Specifies the distinguished name of the entry to be used to start the search.

SCOPE - Optional. Specifies the scope of the search from the entry specified in the START attribute for ACTION="Query". There are three possible values:

• OneLevel -- (Default) Searches all entries one level beneath the entry specified in the START attribute.
• Base -- Searches only the entry specified in the START attribute.
• Subtree -- Searches the entry specified in the START attribute as well all entries at all levels beneath it.

ATTRIBUTES - Required for ACTION="Query", Add, ModifyDN, and Modify. For queries, specifies the comma-separated list of attributes to be returned for queries. Can also be used to specify the list of update columns for ACTION="Add" or "Modify". When used with ACTION="Add" and Action="Modify", separate multiple attributes with a semicolon. When used with ACTION="ModifyDN", ColdFusion passes attributes to the LDAP server without performing any syntax checking.

FILTER - Optional. Specifies the search criteria for ACTION="Query". Attributes are referenced in the form: "(attribute operator value)". Example: "(sn=Kukreja)". Default is "objectclass=*".

SORT - Optional. Specifies the attribute to sort query results by. Enter Asc for an ascending sort and Desc for a descending sort.

DN - Required for ACTION="Add", Modify, ModifyDN, and Delete. Specifies the distinguished name for update actions. Example: "cn=Puneet Kukreja, o=Monash University, c=AU".