From 8210feaf86b3c51232d49d35bdd1aaa4f02877b9 Mon Sep 17 00:00:00 2001 From: Mark Craig <mark.craig@forgerock.com> Date: Thu, 26 May 2011 16:00:27 +0000 Subject: [PATCH] First draft of dev guide chapter on Understanding LDAP. --- opendj-sdk/opendj3/src/main/docbkx/dev-guide/images/data-organization.png | 0 opendj-sdk/opendj3/src/main/docbkx/dev-guide/chap-understanding-ldap.xml | 245 +++++++++++++++++++++++++++++++++++++++++++++++- opendj-sdk/opendj3/src/main/docbkx/dev-guide/images/ldap-lifecycle.png | 0 3 files changed, 239 insertions(+), 6 deletions(-) diff --git a/opendj-sdk/opendj3/src/main/docbkx/dev-guide/chap-understanding-ldap.xml b/opendj-sdk/opendj3/src/main/docbkx/dev-guide/chap-understanding-ldap.xml index 80c28b9..a93899b 100644 --- a/opendj-sdk/opendj3/src/main/docbkx/dev-guide/chap-understanding-ldap.xml +++ b/opendj-sdk/opendj3/src/main/docbkx/dev-guide/chap-understanding-ldap.xml @@ -30,21 +30,254 @@ xmlns:xlink='http://www.w3.org/1999/xlink' xmlns:xinclude='http://www.w3.org/2001/XInclude'> <title>Understanding LDAP</title> - - <para>TODO</para> + + <para>A directory resembles a dictionary or a phone book. If you know a + word, you can look it up its entry in the dictionary to learn its definition + or its pronunciation. If you know a name, you can look it up its entry in the + phone book to find the telephone number and street address associated with the + name. If you are bored, curious, or have lots of time, you can also read + through the dictionary, phone book, or directory, entry after entry.</para> + + <para>Where a directory differs from a paper dictionary or phone book is + in how entries are indexed. Dictionaries typically have one index: words + in alphabetical order. Phone books, too: names in alphabetical order. + Directories entries on the other hand are often indexed for multiple + attributes, names, user identifiers, email addresses, telephone numbers. + This means you can look up a directory entry by the name of the user the + entry belongs to, but also by her user identifier, her email address, or + her telephone number, for example.</para> <section> - <title>Data Organization In LDAP Directories</title> - <para>TODO</para> + <title>How Directories & LDAP Evolved</title> + + <para>Phone companies have been managing directories for many decades. The + Internet itself has relied on distributed directory services like DNS since + the mid 1980s.</para> + + <para>It was not until the late 1980s, however, that experts from what is now + the International Telecommunications Union brought forth the X.500 set of + international standards, including Directory Access Protocol. The X.500 + standards specify Open Systems Interconnect (OSI) protocols and + data definitions for general-purpose directory services. The X.500 standards + were design to meet the needs of systems built according to the X.400 + standards, covering electronic mail services.</para> + + <para>Lightweight Directory Access Protocol has been around since the early + 1990s. LDAP was originally developed as an alternative protocol that would + allow directory access over Internet protocols rather than OSI protocols, + and be lightweight enough for desktop implementations. By the mid 1990, LDAP + directory servers became generally available and widely used.</para> + + <para>Until the late 1990s, LDAP directory servers were designed primarily + with quick lookups and high availability for lookups in mind. LDAP directory + servers replicate data, so when an update is made, that update gets pushed + out to other peer directory servers. Thus if one directory server goes down + lookups can continue on other servers. Furthermore, if a directory service + needs to support more lookups, the administrator can simply add another + directory server to replicate with its peers.</para> + + <para>As organizations rolled out larger and larger directories serving more + and more applications, they discovered that they needed high availability + not only for lookups, but also for updates. Around 2000 directories began + to support multi-master replication, that is replication with multiple + read-write servers. Soon thereafter the organizations with the very largest + directories started to need higher update performance as well as + availability.</para> + + <para>The OpenDJ code base began in the mid 2000s, when engineers solving the + update performance issue decided the cost of adapting the existing C-based + directory technology for high performance updates would be higher than the + cost of building a next generation, high performance directory using Java + technology.</para> + </section> + + <section> + <title>Data In LDAP Directories</title> + <para>LDAP directory data is organized into entries, similar to the entries + for words in the dictionary, or for subscriber names in the phone book. + A sample entry follows.</para> + + <programlisting language="LDIF">dn: uid=bjensen,ou=People,dc=example,dc=com +uid: bjensen +cn: Babs Jensen +cn: Barbara Jensen +facsimileTelephoneNumber: +1 408 555 1992 +gidNumber: 1000 +givenName: Barbara +homeDirectory: /home/bjensen +l: Cupertino +mail: bjensen@example.com +objectClass: inetOrgPerson +objectClass: organizationalPerson +objectClass: person +objectClass: posixAccount +objectClass: top +ou: People +ou: Product Development +roomNumber: 0209 +sn: Jensen +telephoneNumber: +1 408 555 1862 +uidNumber: 1076 +</programlisting> + + <para>Barbara Jensen's entry has a number of attributes, such as + <literal>uid: bjensen</literal>, + <literal>telephoneNumber: +1 408 555 1862</literal>, and + <literal>objectClass: posixAccount</literal><footnote><para>The + <literal>objectClass</literal> attribute type indicates which types of + attributes are allowed and optional for the entry. As the entries object + classes can be updated online, and even the definitions of object classes + and attributes are expressed as entries that can be updated online, directory + data is extensible on the fly.</para></footnote>. When you lookup her entry + in the directory, you specify one or more attributes and values to match + in the entries that come back as the result of your search. Typically the + attributes you search for are indexed in the directory, so the directory + server can retrieve them more quickly.<footnote><para>Attribute values + do not have to be strings. The directory can use base64 encoding, however, + to make binary attribute values, such as passwords, certificates, or photos, + portable in text format.</para></footnote></para> + + <para>The entry also has a unique identifier, show at the top of the entry, + <literal>dn: uid=bjensen,ou=People,dc=example,dc=com</literal>. DN stands + for distinguished name. No two entries in the directory have the same + distinguished name.</para> + + <para>LDAP entries are arranged hierarchically in the directory. The + hierarchical organization resembles a file system on a PC or a web server, + often imagined as an upside-down tree structure, looking similar to a + pyramid.<footnote><para>Hence pyramid icons are associated with directory + servers.</para></footnote>The distinguished name consists of components + separated by commas, + <literal>uid=bjensen,ou=People,dc=example,dc=com</literal>. Those components + reflect the hierarchy of directory entries.</para> + + <mediaobject> + <imageobject> + <imagedata fileref="images/data-organization.png" format="PNG" /> + </imageobject> + <caption><para>Hierarchy of directory data shown in the left pane of + the Manage Entries browser</para></caption> + </mediaobject> + + <para>Barbara Jensen's entry is located under an entry with DN + <literal>ou=People,dc=example,dc=com</literal>, an organization unit and + parent entry for the people at Example.com. The + <literal>ou=People</literal> entry is located under the entry with DN + <literal>dc=example,dc=com</literal>, the root entry for Example.com. + DC stands for domain component. The directory has other root entries, such + as <literal>cn=config</literal>, under which the configuration is accessible + through LDAP, and potentially others such as + <literal>dc=mycompany,dc=com</literal> or <literal>o=myOrganization</literal>. + Thus when you lookup entries, you specify the parent entry to look under + in the same way you need to know whether to look in the New York, Paris, + or Tokyo phone book to find someone's telephone number.<footnote> + <para>The root entry for the directory, technically the entry with DN + <literal>""</literal> (the empty string), is called the root DSE, and + contains information about what the server supports, including the other + root entries it serves.</para></footnote></para> </section> <section> <title>LDAP Client & Server Communication</title> - <para>TODO</para> + <para>You may be used to web service client server communication, where + each time the web client has something to request of the web server, a + connection is set up and then torn down. LDAP has a different model. In + LDAP the client application connects to the server and authenticates, then + requests any number of operations perhaps processing results in between + requests, and finally disconnects when done.</para> + + <mediaobject> + <imageobject> + <imagedata fileref="images/ldap-lifecycle.png" format="PNG" /> + </imageobject> + <caption><para>Schematic of LDAP client-server session</para></caption> + </mediaobject> + + <itemizedlist> + <para>The standard operations are as follows.</para> + <listitem> + <para>Bind (authenticate). The first operation in an LDAP session involves + the client binding to the LDAP server, with the server authenticating the + client. Authentication identifies the client's identity in LDAP terms, the + identity which is later used by the server to authorize (or not) access + to directory data that the client wants to lookup or change.</para> + </listitem> + <listitem> + <para>Search (lookup). After binding, the client can request the server to + return entries based on an LDAP filter, which is an expression that the + server uses to find entries that match the request, and a base DN under + which to search. For example, to lookup all entries for people with email + address <literal>bjensen@example.com</literal> in data for Example.com, + you would specify a base DN such as + <literal>ou=People,dc=example,dc=com</literal> and the filter + <literal>(mail=bjensen@example.com)</literal>.</para> + </listitem> + <listitem> + <para>Modify. After binding, the client can request that the server + change one or more attribute values stored on one or more entries. Often + administrators do not allow clients to change directory data, so request + that your administrator set appropriate access rights for your client + application if you want to update data.</para> + </listitem> + <listitem> + <para>Add. After binding, the client can request to add one or more + new LDAP entries to the server. </para> + </listitem> + <listitem> + <para>Delete. After binding, the client can request that the server + delete one or more entries. To delete and entry with other entries + underneath, first delete the children, then then parent.</para> + </listitem> + <listitem> + <para>Modify DN. After binding, the client can request that the server + change the distinguished name of the entry. For example, if Barbara + changes her unique identifier from <literal>bjensen</literal> to something + else, her DN would have to change. For another example, if you decide + to consolidate <literal>ou=Customers</literal> and + <literal>ou=Employees</literal> under <literal>ou=People</literal> + instead, all the entries underneath much change distinguished names. + <footnote><para>Renaming entire branches of entries can be a major + operation for the directory, so avoid moving entire branches if you + can.</para></footnote></para> + </listitem> + <listitem> + <para>Unbind. When done making requests, the client should request an + unbind operation to release resources right away for other clients.</para> + </listitem> + <listitem> + <para>Abandon. When a request seems to be taking too long to complete, + or when a search request returns many more matches than desired, the client + can send an abandon request to the server to drop the operation in + progress. The server then drops the connection without a reply to the + client.</para> + </listitem> + </itemizedlist> </section> <section> <title>Standard LDAPv3 & Extensions</title> - <para>TODO</para> + <para>LDAP has standardized two mechanisms for extending the kinds of + operations that directory servers can perform. One mechanism involves using + LDAP controls. The other mechanism involves using LDAP extended + operations.</para> + + <para>LDAP controls are information added to an LDAP message to further + specify how an LDAP operation should be processed. For example, the + Server Side Sort Request Control modifies a search to request that the + directory server return entries to the client in sorted order. The Subtree + Delete Request Control modifies a delete to request that the server + also remove child entries of the entry targetted for deletion.</para> + + <para>LDAP extended operations are additional LDAP operations not included + in the original standard list. For example, the Cancel Extended Operation + works like an abandon operation, but finishes with a response from the + server after the cancel is complete. The StartTLS Extended Operation allows + a client to connect to a server on an unsecure port, but then start + Transport Layer Security negotiations to protect communications.</para> + + <para>Both LDAP controls and extended operations are demonstrated later in + this guide. OpenDJ directory server supports many LDAP controls and a few + LDAP extended operations, controls and extended operations matching those + demonstrated in this guide.</para> </section> </chapter> diff --git a/opendj-sdk/opendj3/src/main/docbkx/dev-guide/images/data-organization.png b/opendj-sdk/opendj3/src/main/docbkx/dev-guide/images/data-organization.png new file mode 100644 index 0000000..f02b8fb --- /dev/null +++ b/opendj-sdk/opendj3/src/main/docbkx/dev-guide/images/data-organization.png Binary files differ diff --git a/opendj-sdk/opendj3/src/main/docbkx/dev-guide/images/ldap-lifecycle.png b/opendj-sdk/opendj3/src/main/docbkx/dev-guide/images/ldap-lifecycle.png new file mode 100644 index 0000000..3b0ec69 --- /dev/null +++ b/opendj-sdk/opendj3/src/main/docbkx/dev-guide/images/ldap-lifecycle.png Binary files differ -- Gitblit v1.10.0