class Net::LDAP

Quick-start for the Impatient

Quick Example of a user-authentication against an LDAP directory:

require 'rubygems'
require 'net/ldap'

ldap = Net::LDAP.new
ldap.host = your_server_ip_address
ldap.port = 389
ldap.auth "joe_user", "opensesame"
if ldap.bind
  # authentication succeeded
else
  # authentication failed
end

Quick Example of a search against an LDAP directory:

require 'rubygems'
require 'net/ldap'

ldap = Net::LDAP.new :host => server_ip_address,
     :port => 389,
     :auth => {
           :method => :simple,
           :username => "cn=manager, dc=example, dc=com",
           :password => "opensesame"
     }

filter = Net::LDAP::Filter.eq("cn", "George*")
treebase = "dc=example, dc=com"

ldap.search(:base => treebase, :filter => filter) do |entry|
  puts "DN: #{entry.dn}"
  entry.each do |attribute, values|
    puts "   #{attribute}:"
    values.each do |value|
      puts "      --->#{value}"
    end
  end
end

p ldap.get_operation_result

Setting connect timeout

By default, Net::LDAP uses TCP sockets with a connection timeout of 5 seconds.

This value can be tweaked passing the :connect_timeout parameter. i.e.

ldap = Net::LDAP.new ...,
                     :connect_timeout => 3

A Brief Introduction to LDAP

We’re going to provide a quick, informal introduction to LDAP terminology and typical operations. If you’re comfortable with this material, skip ahead to “How to use Net::LDAP.” If you want a more rigorous treatment of this material, we recommend you start with the various IETF and ITU standards that relate to LDAP.

Entities

LDAP is an Internet-standard protocol used to access directory servers. The basic search unit is the entity, which corresponds to a person or other domain-specific object. A directory service which supports the LDAP protocol typically stores information about a number of entities.

Principals

LDAP servers are typically used to access information about people, but also very often about such items as printers, computers, and other resources. To reflect this, LDAP uses the term entity, or less commonly, principal, to denote its basic data-storage unit.

Distinguished Names

In LDAP’s view of the world, an entity is uniquely identified by a globally-unique text string called a Distinguished Name, originally defined in the X.400 standards from which LDAP is ultimately derived. Much like a DNS hostname, a DN is a “flattened” text representation of a string of tree nodes. Also like DNS (and unlike Java package names), a DN expresses a chain of tree-nodes written from left to right in order from the most-resolved node to the most-general one.

If you know the DN of a person or other entity, then you can query an LDAP-enabled directory for information (attributes) about the entity. Alternatively, you can query the directory for a list of DNs matching a set of criteria that you supply.

Attributes

In the LDAP view of the world, a DN uniquely identifies an entity. Information about the entity is stored as a set of Attributes. An attribute is a text string which is associated with zero or more values. Most LDAP-enabled directories store a well-standardized range of attributes, and constrain their values according to standard rules.

A good example of an attribute is sn, which stands for “Surname.” This attribute is generally used to store a person’s surname, or last name. Most directories enforce the standard convention that an entity’s sn attribute have exactly one value. In LDAP jargon, that means that sn must be present and single-valued.

Another attribute is mail, which is used to store email addresses. (No, there is no attribute called “email, ” perhaps because X.400 terminology predates the invention of the term email.) mail differs from sn in that most directories permit any number of values for the mail attribute, including zero.

Tree-Base

We said above that X.400 Distinguished Names are globally unique. In a manner reminiscent of DNS, LDAP supposes that each directory server contains authoritative attribute data for a set of DNs corresponding to a specific sub-tree of the (notional) global directory tree. This subtree is generally configured into a directory server when it is created. It matters for this discussion because most servers will not allow you to query them unless you specify a correct tree-base.

Let’s say you work for the engineering department of Big Company, Inc., whose internet domain is bigcompany.com. You may find that your departmental directory is stored in a server with a defined tree-base of

ou=engineering, dc=bigcompany, dc=com

You will need to supply this string as the tree-base when querying this directory. (Ou is a very old X.400 term meaning “organizational unit.” Dc is a more recent term meaning “domain component.”)

LDAP Versions

(stub, discuss v2 and v3)

LDAP Operations

The essential operations are: bind, search, add, modify, delete, and rename.

Bind

bind supplies a user’s authentication credentials to a server, which in turn verifies or rejects them. There is a range of possibilities for credentials, but most directories support a simple username and password authentication.

Taken by itself, bind can be used to authenticate a user against information stored in a directory, for example to permit or deny access to some other resource. In terms of the other LDAP operations, most directories require a successful bind to be performed before the other operations will be permitted. Some servers permit certain operations to be performed with an “anonymous” binding, meaning that no credentials are presented by the user. (We’re glossing over a lot of platform-specific detail here.)

Calling search against the directory involves specifying a treebase, a set of search filters, and a list of attribute values. The filters specify ranges of possible values for particular attributes. Multiple filters can be joined together with AND, OR, and NOT operators. A server will respond to a search by returning a list of matching DNs together with a set of attribute values for each entity, depending on what attributes the search requested.

Add

add specifies a new DN and an initial set of attribute values. If the operation succeeds, a new entity with the corresponding DN and attributes is added to the directory.

Modify

modify specifies an entity DN, and a list of attribute operations. modify is used to change the attribute values stored in the directory for a particular entity. modify may add or delete attributes (which are lists of values) or it change attributes by adding to or deleting from their values. Net::LDAP provides three easier methods to modify an entry’s attribute values: add_attribute, replace_attribute, and delete_attribute.

Delete

delete specifies an entity DN. If it succeeds, the entity and all its attributes is removed from the directory.

Rename (or Modify RDN)

rename (or modify_rdn) is an operation added to version 3 of the LDAP protocol. It responds to the often-arising need to change the DN of an entity without discarding its attribute values. In earlier LDAP versions, the only way to do this was to delete the whole entity and add it again with a different DN.

rename works by taking an “old” DN (the one to change) and a “new RDN, ” which is the left-most part of the DN string. If successful, rename changes the entity DN so that its left-most node corresponds to the new RDN given in the request. (RDN, or “relative distinguished name, ” denotes a single tree-node as expressed in a DN, which is a chain of tree nodes.)

How to use Net::LDAP

To access Net::LDAP functionality in your Ruby programs, start by requiring the library:

require 'net/ldap'

If you installed the Gem version of Net::LDAP, and depending on your version of Ruby and rubygems, you may also need to require rubygems explicitly:

require 'rubygems'
require 'net/ldap'

Most operations with Net::LDAP start by instantiating a Net::LDAP object. The constructor for this object takes arguments specifying the network location (address and port) of the LDAP server, and also the binding (authentication) credentials, typically a username and password. Given an object of class Net:LDAP, you can then perform LDAP operations by calling instance methods on the object. These are documented with usage examples below.

The Net::LDAP library is designed to be very disciplined about how it makes network connections to servers. This is different from many of the standard native-code libraries that are provided on most platforms, which share bloodlines with the original Netscape/Michigan LDAP client implementations. These libraries sought to insulate user code from the workings of the network. This is a good idea of course, but the practical effect has been confusing and many difficult bugs have been caused by the opacity of the native libraries, and their variable behavior across platforms.

In general, Net::LDAP instance methods which invoke server operations make a connection to the server when the method is called. They execute the operation (typically binding first) and then disconnect from the server. The exception is Net::LDAP#open, which makes a connection to the server and then keeps it open while it executes a user-supplied block. Net::LDAP#open closes the connection on completion of the block.