LDAP Connect User's Guide
CHAPTER 1
Welcome to the Novell Integration Manager LDAP Connect User's Guide. This Guide is a companion to the Integration Manager User's Guide, which details how to use all the standard features of Integration Manager except for those specific to the Connect Component Editors. So, if you haven't looked at the Integration Manager User's Guide yet, you should familiarize yourself with it before using this Guide.
Novell Integration Manager provides separate Component Editors for each Connect. The special features of each component editor are described in separate Guides like this one.
If you have been using Integration Manager, and are familiar with the core editors (such as the XML Map Component Editor), then this Guide will help you become productive with the LDAP Component Editor in minimal time.
Novell Integration Manager is a tool for building (and deploying) your own XML-enabled integration applications.
Integration Manager comes in two parts. The design-side part (which is what we mean when we say "Integration Manager" in this guide) is an integrated development environment (IDE) for creating your own custom applications. The runtime part (called Integration Manager Enterprise Server, or "Integration Manager Server" for short) is the server-resident execution engine for your apps. (You do not need access to Integration Manager Server in order to design, test, and debug your services, however.)
The services you build and deploy using Integration Manager can be triggered (invoked) in any number of ways. A common option is to have a service invoked by a servlet that "listens" on a URL. (For more information on invocation and deployment options, see the Integration Manager User's Guide as well as the Integration Manager Server Guide for your particular app server).
This guide will show you how to build LDAP Components that you can use in your Integration Manager-built services. Typically, you will:
Create a project (a Integration Manager or Workbench.spf file).
Create an LDAP Component and its associated resources (such as a Connection Resource).
Optionally create other components (XML Map, JDBC, etc.) that carry out additional "business logic" operations.
Create a service (or "Service Component") that calls your other components. The service, in other words, "wrappers" your lower-level components.
Package and deploy your service in JAR, WAR, or EAR form as appropriate.
The service provides the invocation layer for a component (or group of components). It can be exposed as a WSDL-described Web Service, or it can run locally, with no public-facing interface, on the app server.
Novell Integration Manager is built on a simple hub-and-spoke architecture. The hub is a robust XML transformation engine that accepts XML documents, processes the documents, and returns an XML document created according to the particular requirements of the business process in question. The spokes, or Connects, are add-in modules that "XML-enable" sources of data that are not XML-aware. That is, Connects make it possible for non-XML data—whether from legacy COBOL-VSAM managed information systems, Telnet or other terminal streams, message queues, EDI, etc.—to be captured in XML form (or the reverse: repackage XML data so the endpoint system can understand it). Integration Manager Connects are natively able to read, write, and transform XML using industry-standard parsers and transcoders.
All of this is done in a non-intrusive/non-invasive manner, such that there is no impact on existing systems or infrastructure. (For example, there is no need to load any new software on existing systems, aside from the app server itself.)
Integration Manager comes with two core Connects, for JDBC and LDAP. (JDBC is the subject of a separate User's Guide.)
Other Connects are available for CICS RPC, Telnet, 3270, 5250, HP3000, Tandem, Data General, JMS, SAP, EDI, and HTML data sources. These additional Connects are not part of the core Integration Manager installation but represent value-adds that can be purchased separately.
Just as the JDBC Connect lets you build and deploy XML integration applications that are database-aware, the LDAP Connect lets you build components and services that are directory-aware. Your component or service acquires the power to act as an LDAP client. It can make queries against (or even update the contents of) any directory—regardless of vendor—that supports the LDAP protocol.
The key to the power and flexibility of Integration Manager's LDAP Connect is its ability to work with DSML (Directory Services Markup Language), which is an industry-standard XML grammar for encoding directory requests and responses. (See the more detailed discussion further below.) Since DSML is just a dialect of XML, it shares all of XML's advantages in terms of being human-readable, machine-parsable, transportable, firewall-friendly, etc. The data in a DSML document is easily accessed, transformed, and repurposed.
NOTE: You will not need to create, or keep on hand, actual DSML documents in order to work with the LDAP Connect. Integration Manager will create the necessary DSML for you, on the fly.
We will have more to say about DSML later on.
A directory is a structured data store. As such, it has many of the characteristics of a relational database (which is perhaps the best known type of structured data store). But a directory differs from a traditional database in a number of key ways:
Whereas a database is designed to accommodate large chunks of potentially volatile data (data that may be subject to frequent updates), a directory is more suited to handling small, highly granularized bits of data that don't need frequent updating.
Directories allow administrators to aggregate data in vertical object hierarchies built on flexible naming and containment rules. (Traditional databases follow a less vertical approach to organizing data.)
Every data element (or entry) in a directory is directly addressable via a unique ID (known as its distinguished name). The address of a directory entry is constructed (and deconstructed) piecewise, much the same way a URL is, so that there can be relative versus fully qualified names. In a database, data elements are not directly addressable.
As with a database, data in a directory can be queried as well as written (updated) or removed. Databases can be queried via one flavor or another of SQL (Structured Query Language). With directories, queries follow a syntax described in RFCs 2251 and 2254. The query "language" for LDAP is well standardized.
The diagram above shows how applications communicate with the two basic types of structured data stores (directories and databases). Applications go through LDAP to query and/or update directories. They go through SQL and appropriate drivers to access data in a database.
Directories store data as entries. Collections of entries are usually called objects. Objects can contain other objects as entries.
The data within directory objects consists of attribute-value pairs. Some attributes are said to be single-valued; others are multi-valued. For example, a person might have more than one phone number: In this case, the attribute under which phone numbers are stored for this person would probably be a multi-valued attribute. This would be specified in the directory's schema. (A directory schema is not to be confused with an XML schema. The two are completely distinct.)
When entries contain other entries, the containing entry is called a container object.
A contained entry is said to be the subordinate entry of the container. The container, on the other hand, is said to be the superior of the contained entry.
NOTE: An entry can be both a container (superior) as well as a subordinate to another entry, much the same way that a DOM node can be both a parent and a child.
Nesting of entries is a key characteristic of directories and gives them a treelike structure. (In fact, you will often hear the term Directory Information Tree, or DIT, in reference to a directory.) The tree structure lends itself, in turn, to XML representation.
The above graphic shows how the directory structure for a small company might look. In this example, the top-level node in TinyCompany has an Organization (O) attribute of TinyCompany. Under TinyCompany are containers for the Engineering, Accounting, and Marketing departments. (These are labelled as such in terms of OU or Organization Unit attributes.) Accounting has two organizational units under it (Accounts Payable and Accounts Receivable.) So far, all of these entries have been containers. At the leaf-node level, we reach the CN Common Name) entries for the various personnel under the containers. Note that Marketing has no employees at the moment. But they do have a printer.
Any item in the tree can be addresses by a concatenation (or federation) of namespaces: Judy Yo can be addressed unambiguously by means of:
cn=Judy Yo,ou=R&D,ou=Engineering,o=TinyCompany
This "fully qualified" name is called a distinguished name (usually abbreviated "DN" or "dn"). It is analogous to a fully qualified path or URI.
NOTE: Order is important in a DN. Unlike URL or file-system naming schemes, the ordering inside a DN (going left to right) flows from lowest level to highest level of organization (or from child to parent)—always upwards along the ancestor chain.
Because order is important, it would be wrong to rewrite the above DN as
cn=Judy Yo,ou=Engineering,ou=R&D,o=TinyCompany
This DN states the hierarchy of relationships incorrectly, since R&D belongs under Engineering. The DN shown here would not resolve correctly given the object hierarchy shown in the foregoing graphic.
We will talk more about naming and other conventions in later chapters.
LDAP (Lightweight Directory Access Protocol) is a messaging protocol for communicating with directories. It implements a compact subset of the functionality specified in the more elaborate Directory Access Protocol. Full DAP is a feature-rich, far-reaching, rigorous ("heavyweight") protocol for communicating with X.500 directory servers. By comparison, LDAP is a lightweight protocol with a reduced feature set and relatively modest learning curve for those wishing to use it. You can think of LDAP as a kind of complexity-reduced version of DAP based on ordinary TCP/IP for messaging as opposed to DAP's use of the less-common OSI network protocol stack.
In many circles, LDAP has come to mean more than just the network protocol described in RFC 3377. When people talk about LDAP, they may be talking about:
The LDAP functional model: that is to say, the kinds of operations you can perform on a directory
The LDAP namespace model: The ways in which data groupings can be distinguished or identified by name
The LDAP data model, which defines the kinds of information that can be stored in a directory, and rules for organizing that data
Many of these concepts stem from International Telephone Union (ITU) Technical Recommendation X.500: "The Directory: Overview of Concepts, Models and Service"(1993). LDAP remains, at its core, a network protocol (like HTTP), but its semantics are tightly bound to the conceptual framework defined by ITU's X.500, X.501, and X.511 standards.
With LDAP, you can establish communications with (or "bind to") a directory, access (read) information in the directory, and/or update (write information to) the directory.
The LDAP v3 specification is at http://www.ietf.org/rfc/rfc2251.txt.
For additional information on LDAP, consult http://www.openldap.org.
LDAP is a protocol for communicating with directories. Like any network protocol, LDAP has its own "handshake" conventions and a vocabulary of keywords with implied semantics. There are 20 verbs, total (see the section following this one), describing various types of operations:
Bind—The bind operation establishes an LDAP session between a client application and a directory server. (This operation also allows a client application to pass authentication information to the server.)
Unbind—The unbind operation terminates an LDAP session and signals to the server that the "connection" can be discarded.
Search—The search operation allows an LDAP-enabled client application to exploit the lookup services offered by a directory server. Depending on the parameters in the client application's search request, the server will return information from a single entry, from all of the entries below a particular entry on the directory tree, or from an entire branch of the directory tree.
NOTE: In addition to allowing client applications to define the scope of a particular search, LDAP 3 parameters allow a client application to define search filters; a size limit for the number of entries returned; and a time limit within which the search should be performed.
Modify—The modify operation allows a client to modify the value of an attribute for a particular entry. Parameters of the modify operation allow a client application to add values for attributes, to delete values for attributes, and to change values for attributes. For example, a client application might request an add, delete, or replace operation.
Add a telephone number to the telephoneNumber attribute of a particular user entry.
Delete a telephone number from the telephoneNumber attribute.
Replace the existing telephone number with a new telephone number.
Modify Distinguished Name (DN). The modify-DN operation allows a client application to change an entry's distinguished name by changing the leftmost element of that name. (Distinguished names are discussed further below.)
Compare—The compare operation allows a client application to compare a stated attribute value with the value of an attribute in a particular entry. For example, a client application might verify a particular user's password using the compare operation.
Abandon—The abandon operation allows a client application to abandon an operation that has not yet been completed.
LDAP 3 also defines an indirection capability—that is, a means by which a directory can refer a client application to another LDAP 3 directory. For example, suppose a client application were to request information about a particular entry from LDAP Directory A, but Directory A could not find the requested entry. If Directory A knew that Directory B that might contain the desired info, A could refer the client to B, and the search could continue (possibly along an extended series of referrals).
When the host silently implements its own referral-following scheme, it's called chaining. In LDAP, the client has no knowledge of nor (generally speaking) any control over chaining, since it's totally under the server's control.
Referral-following, on the other hand, is under the client's control: The client must decide whether to act on each referral as it is received, and what kind of security to use on each "hop."
NOTE: The current version of the LDAP Connect for Integration Manager does not provide native support for referral-following. You can, however, build your own action-model logic to accomplish this, using ordinary looping constructs and dynamic connection-resource parameter values.
The above discussion presented LDAP operations in "non-programmer" terms. At a lower level, LDAP operations are specified by LDAP verbs.
The current list of LDAP verbs (including those that are unique to Version 3 of the spec) looks like this:
These verbs are presented here merely to give you an idea of the kinds of operations that are possible in LDAP. You do not need to understand how to work with these verbs directly in order to use the Integration Manager LDAP Connect.
For more information on the uses and meanings of these commands, refer to the developer documentation at http://developer.novell.com/ndk/.
Directory Services Markup Language, or DSML, allows directory information and/or directory queries to be represented as an XML document.
NOTE: If you are already experienced with LDAP, you can think of DSML as the XML analog of an LDIF file. (LDIF is the LDAP Data Interchange Format, a text format for specifying directory entries and LDAP queries. LDIF is described in RFC 2849)
The DSML specification (see http://www.oasis-open.org) was created in order to make it easy for XML-based enterprise applications to leverage resource information stored in directories, using firewall-friendly mechanisms like SOAP (Simple Object Access Protocol).
DSML allows XML and directories to work together. It provides a generalized mechanism by which XML-based applications can access directory-based information. The goal of DSML is simply to make it possible for an ever-growing number of XML-based enterprise applications to be directory-aware.
NOTE: You do not need to understand DSML in order to use the Integration Manager LDAP Connect. Many of the LDAP Connect's features are wizard-driven. Based on your input to the wizard dialogs, Integration Manager's LDAP Connect will build any necessary DSML documents or DOMs for you, dynamically.
With the aid of the LDAP Connect and Integration Manager, you can build "directory awareness" into your XML integration applications (whether they're Web Services or private apps running in a local context). Your LDAP-aware app can push data into or pull data from any LDAP-accessible data store, using XML as the interchange format. (DSML is the XML dialect that is actually used.) And you can do this without having to know anything about DSML. For example, you can write a component (perhaps part of a larger web service) that retrieves the phone number, e-mail address, and title of a company employee from a company directory. If the information your app needs resides in two or more directories, you can merge the information from separate directories before displaying it to the user or passing it to another component in your application.
LDAP applications typically use SSL and TLS (Transport Layer Security) for authentication of LDAP endpoints and encryption of LDAP session data.
TLS is a generic wrapper for various kinds of transport-layer security. The participants in a TLS session agree, at the beginning of a session, to use one of several available security mechanisms (a typical choice being Secure Socket Layer technology); then the participants use that mechanism to conduct a "secure session."
When TLS is enabled, all communications are encrypted; no passwords (and no data) are ever sent in the clear.
Host authentication is also a component of TLS. By default, the host sends its X.509 certificate information to the client and the client verifies (authenticates) the host, confirming that the host in question is indeed the LDAP server that the client was expecting.
NOTE: There are other possible authentication handshakes, including authentication of the client by the host without authentication of the host by the client, as well as two-way mutual authentication; but the LDAP Connect for Integration Manager currently supports only the most common handshake scenario, in which the server provides its certificate info to the client.
Additional discussion of LDAP Connect security will come later (in "Getting Started with the LDAP Component Editor").
For more information on Transport Layer Security, see RFC 2246 at http://www.faqs.org/rfcs/rfc2246.html.
Access control is different from "security" of the kind discussed above: Rather than addressing authentication and encryption, access control has to do with authorization, operational privilege levels (read-only vs. read-write), inheritance rules for privileges, object and attribute visibilities, etc., and assignment, management, and enforcement of these properties on a per-user and per-group basis.
ITU X.501 addresses (in a characteristically abstract way) directory access control concepts, but does not specify access control mechanisms in enough architectural detail to enable directory vendors to implement access control in a standard way. Therefore, access control features have necessarily tended to be implemented in vendor-specific ways. There is no one "standard" way to implement access control.
Novell's eDirectory offers a rich, flexible, robust access control architecture centered on an attribute called ACL (for "Access Control List"). The ACL attribute is an optional, multivalued attribute that (in eDirectory and NDS) is defined on the Top object class. Since all objects derive from Top, all object classes can avail themselves of the ACL attribute.
The ACL attribute is an attribute on the object that is being accessed. Each ACL value specifies who can access the object; what type of rights the accessor has been granted; and whether children of the accessor inherit those rights. When an object has been granted rights to another object, the accessor is called a trustee of the target object.
Since the ACL attribute is multivalued, any object that uses an ACL attribute can store any number of values in it. Typically, there is one value per trustee. Therefore, an ACL might contain a great many values. But some trustees might actually be container objects representing large groups. The rights of an entire group of directory objects can be controlled through a single ACL entry.
ACL-based access control is based on very simple principles, but the ramifications of those principles are far-reaching. For a technical overview of ACL concepts, you should consult the NDS Technical Overview documentation (in particular, the chapter on eDirectory Security) available online at http://developer.novell.com/ndk. ACL is also discussed later in this guide, in the discussion of "Access Control List (ACL) Methods."
The web has many good LDAP and directory resources. A good place to start is http://developer.novell.com/edirectory/ndsldap.htm, which has links to many LDAP-related articles, specifications, and developer resources.
Links to the RFCs covering LDAP, along with other resources, can be found at http://nldap.com/nldap/. Some of the RFCs include the following:
RFC 2253 - LDAP (v3): UTF-8 String Representation of Distinguished Names
RFC 2256 - A Summary of the X.500(96) User Schema for use with LDAPv3
A public LDAP test directory is maintained by Novell at http://nldap.com. You can use it to set up a private container for test purposes, if you don't have a local LDAP server against which to test your LDAP Connect components and services.
Information on the X.500 directory standard (and DAP) can be found at the web site of the International Telecommunication Union, http://www.itu.int. (Note: ITU's standards must be purchased before they can be downloaded.)
Copyright © 2004 Novell, Inc. All rights reserved. Copyright © 1997, 1998, 1999, 2000, 2001, 2002, 2003 SilverStream Software, LLC. All rights reserved. more ...