Class: Net::LDAP

Inherits:
Object
  • Object
show all
Defined in:
lib/net/ldap.rb,
lib/net/ldap.rb

Overview

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

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.

Defined Under Namespace

Modules: LdapControls Classes: Connection, DN, Dataset, Entry, Filter, LdapError, PDU, Password

Constant Summary collapse

VERSION = 
"0.2.2"
SearchScope_BaseObject = 
0
SearchScope_SingleLevel = 
1
SearchScope_WholeSubtree = 
2
SearchScopes = 
[ SearchScope_BaseObject, SearchScope_SingleLevel,
SearchScope_WholeSubtree ]
AsnSyntax = 
Net::BER.compile_syntax(:application => application,
:context_specific => context_specific)
DefaultHost = 
"127.0.0.1"
DefaultPort = 
389
DefaultAuth = 
{ :method => :anonymous }
DefaultTreebase = 
"dc=com"
StartTlsOid = 
"1.3.6.1.4.1.1466.20037"
ResultStrings = 
{
  0 => "Success",
  1 => "Operations Error",
  2 => "Protocol Error",
  3 => "Time Limit Exceeded",
  4 => "Size Limit Exceeded",
  12 => "Unavailable crtical extension",
  14 => "saslBindInProgress",
  16 => "No Such Attribute",
  17 => "Undefined Attribute Type",
  20 => "Attribute or Value Exists",
  32 => "No Such Object",
  34 => "Invalid DN Syntax",
  48 => "Inappropriate Authentication",
  49 => "Invalid Credentials",
  50 => "Insufficient Access Rights",
  51 => "Busy",
  52 => "Unavailable",
  53 => "Unwilling to perform",
  65 => "Object Class Violation",
  68 => "Entry Already Exists"
}

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(args = {}) ⇒ LDAP

Instantiate an object of type Net::LDAP to perform directory operations. This constructor takes a Hash containing arguments, all of which are either optional or may be specified later with other methods as described below. The following arguments are supported:

  • :host => the LDAP server’s IP-address (default 127.0.0.1)

  • :port => the LDAP server’s TCP port (default 389)

  • :auth => a Hash containing authorization parameters. Currently supported values include: => :anonymous and {:method => :simple, :username => your_user_name, :password => your_password } The password parameter may be a Proc that returns a String.

  • :base => a default treebase parameter for searches performed against the LDAP server. If you don’t give this value, then each call to #search must specify a treebase parameter. If you do give this value, then it will be used in subsequent calls to #search that do not specify a treebase. If you give a treebase value in any particular call to #search, that value will override any treebase value you give here.

  • :encryption => specifies the encryption to be used in communicating with the LDAP server. The value is either a Hash containing additional parameters, or the Symbol :simple_tls, which is equivalent to specifying the Hash => :simple_tls. There is a fairly large range of potential values that may be given for this parameter. See #encryption for details.

Instantiating a Net::LDAP object does not result in network traffic to the LDAP server. It simply stores the connection and binding parameters in the object.



376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
 
# File 'lib/net/ldap.rb', line 376

def initialize(args = {})
  @host = args[:host] || DefaultHost
  @port = args[:port] || DefaultPort
  @verbose = false # Make this configurable with a switch on the class.
  @auth = args[:auth] || DefaultAuth
  @base = args[:base] || DefaultTreebase
  encryption args[:encryption] # may be nil

  if pr = @auth[:password] and pr.respond_to?(:call)
    @auth[:password] = pr.call
  end

  # This variable is only set when we are created with LDAP::open. All of
  # our internal methods will connect using it, or else they will create
  # their own.
  @open_connection = nil
end

Instance Attribute Details

#base ⇒ Object

Returns the value of attribute base.



347
348
349
 
# File 'lib/net/ldap.rb', line 347

def base
  @base
end

#host ⇒ Object

Returns the value of attribute host.



345
346
347
 
# File 'lib/net/ldap.rb', line 345

def host
  @host
end

#port ⇒ Object

Returns the value of attribute port.



346
347
348
 
# File 'lib/net/ldap.rb', line 346

def port
  @port
end

Class Method Details

.open(args) ⇒ Object

#open takes the same parameters as #new. #open makes a network connection to the LDAP server and then passes a newly-created Net::LDAP object to the caller-supplied block. Within the block, you can call any of the instance methods of Net::LDAP to perform operations against the LDAP directory. #open will perform all the operations in the user-supplied block on the same network connection, which will be closed automatically when the block finishes.

# (PSEUDOCODE)
auth = { :method => :simple, :username => username, :password => password }
Net::LDAP.open(:host => ipaddress, :port => 389, :auth => auth) do |ldap|
  ldap.search(...)
  ldap.add(...)
  ldap.modify(...)
end



493
494
495
496
 
# File 'lib/net/ldap.rb', line 493

def self.open(args)
  ldap1 = new(args)
  ldap1.open { |ldap| yield ldap }
end

.result2string(code) ⇒ Object

:nodoc:



341
342
343
 
# File 'lib/net/ldap.rb', line 341

def self.result2string(code) #:nodoc:
  ResultStrings[code] || "unknown result (#{code})"
end

Instance Method Details

#add(args) ⇒ Object

Adds a new entry to the remote LDAP server. Supported arguments:

:dn

Full DN of the new entry

:attributes

Attributes of the new entry.

The attributes argument is supplied as a Hash keyed by Strings or Symbols giving the attribute name, and mapping to Strings or Arrays of Strings giving the actual attribute values. Observe that most LDAP directories enforce schema constraints on the attributes contained in entries. #add will fail with a server-generated error if your attributes violate the server-specific constraints.

Here’s an example:

dn = "cn=George Smith, ou=people, dc=example, dc=com"
attr = {
  :cn => "George Smith",
  :objectclass => ["top", "inetorgperson"],
  :sn => "Smith",
  :mail => "[email protected]"
}
Net::LDAP.open(:host => host) do |ldap|
  ldap.add(:dn => dn, :attributes => attr)
end



810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
 
# File 'lib/net/ldap.rb', line 810

def add(args)
  if @open_connection
    @result = @open_connection.add(args)
  else
    @result = 0
    begin
      conn = Connection.new(:host => @host, :port => @port,
                            :encryption => @encryption)
      if (@result = conn.bind(args[:auth] || @auth)) == 0
        @result = conn.add(args)
      end
    ensure
      conn.close if conn
    end
  end
  @result == 0
end

#add_attribute(dn, attribute, value) ⇒ Object

Add a value to an attribute. Takes the full DN of the entry to modify, the name (Symbol or String) of the attribute, and the value (String or Array). If the attribute does not exist (and there are no schema violations), #add_attribute will create it with the caller-specified values. If the attribute already exists (and there are no schema violations), the caller-specified values will be added to the values already present.

Returns True or False to indicate whether the operation succeeded or failed, with extended information available by calling #get_operation_result. See also #replace_attribute and #delete_attribute.

dn = "cn=modifyme, dc=example, dc=com"
ldap.add_attribute dn, :mail, "[email protected]"



941
942
943
 
# File 'lib/net/ldap.rb', line 941

def add_attribute(dn, attribute, value)
  modify(:dn => dn, :operations => [[:add, attribute, value]])
end

#authenticate(username, password) ⇒ Object Also known as: auth

Convenience method to specify authentication credentials to the LDAP server. Currently supports simple authentication requiring a username and password.

Observe that on most LDAP servers, the username is a complete DN. However, with A/D, it’s often possible to give only a user-name rather than a complete DN. In the latter case, beware that many A/D servers are configured to permit anonymous (uncredentialled) binding, and will silently accept your binding as anonymous if you give an unrecognized username. This is not usually what you want. (See #get_operation_result.)

Important: The password argument may be a Proc that returns a string. This makes it possible for you to write client programs that solicit passwords from users or from other data sources without showing them in your code or on command lines.

require 'net/ldap'

ldap = Net::LDAP.new
ldap.host = server_ip_address
ldap.authenticate "cn=Your Username, cn=Users, dc=example, dc=com", "your_psw"

Alternatively (with a password block):

require 'net/ldap'

ldap = Net::LDAP.new
ldap.host = server_ip_address
psw = proc { your_psw_function }
ldap.authenticate "cn=Your Username, cn=Users, dc=example, dc=com", psw



426
427
428
429
430
431
432
433
 
# File 'lib/net/ldap.rb', line 426

def authenticate(username, password)
  password = password.call if password.respond_to?(:call)
  @auth = {
    :method => :simple,
    :username => username,
    :password => password
  }
end

#bind(auth = @auth) ⇒ Object

#bind connects to an LDAP server and requests authentication based on the :auth parameter passed to #open or #new. It takes no parameters.

User code does not need to call #bind directly. It will be called implicitly by the library whenever you invoke an LDAP operation, such as #search or #add.

It is useful, however, to call #bind in your own code when the only operation you intend to perform against the directory is to validate a login credential. #bind returns true or false to indicate whether the binding was successful. Reasons for failure include malformed or unrecognized usernames and incorrect passwords. Use #get_operation_result to find out what happened in case of failure.

Here’s a typical example using #bind to authenticate a credential which was (perhaps) solicited from the user of a web site:

require 'net/ldap'
ldap = Net::LDAP.new
ldap.host = your_server_ip_address
ldap.port = 389
ldap.auth your_user_name, your_user_password
if ldap.bind
  # authentication succeeded
else
  # authentication failed
  p ldap.get_operation_result
end

Here’s a more succinct example which does exactly the same thing, but collects all the required parameters into arguments:

require 'net/ldap'
ldap = Net::LDAP.new(:host => your_server_ip_address, :port => 389)
if ldap.bind(:method => :simple, :username => your_user_name,
             :password => your_user_password)
  # authentication succeeded
else
  # authentication failed
  p ldap.get_operation_result
end

You don’t need to pass a user-password as a String object to bind. You can also pass a Ruby Proc object which returns a string. This will cause bind to execute the Proc (which might then solicit input from a user with console display suppressed). The String value returned from the Proc is used as the password.

You don’t have to create a new instance of Net::LDAP every time you perform a binding in this way. If you prefer, you can cache the Net::LDAP object and re-use it to perform subsequent bindings, provided you call #auth to specify a new credential before calling #bind. Otherwise, you’ll just re-authenticate the previous user! (You don’t need to re-set the values of #host and #port.) As noted in the documentation for #auth, the password parameter can be a Ruby Proc instead of a String.



710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
 
# File 'lib/net/ldap.rb', line 710

def bind(auth = @auth)
  if @open_connection
    @result = @open_connection.bind(auth)
  else
    begin
      conn = Connection.new(:host => @host, :port => @port,
                            :encryption => @encryption)
      @result = conn.bind(auth)
    ensure
      conn.close if conn
    end
  end

  @result == 0
end

#bind_as(args = {}) ⇒ Object

#bind_as is for testing authentication credentials.

As described under #bind, most LDAP servers require that you supply a complete DN as a binding-credential, along with an authenticator such as a password. But for many applications (such as authenticating users to a Rails application), you often don’t have a full DN to identify the user. You usually get a simple identifier like a username or an email address, along with a password. #bind_as allows you to authenticate these user-identifiers.

#bind_as is a combination of a search and an LDAP binding. First, it connects and binds to the directory as normal. Then it searches the directory for an entry corresponding to the email address, username, or other string that you supply. If the entry exists, then #bind_as will re-bind as that user with the password (or other authenticator) that you supply.

#bind_as takes the same parameters as #search, with the addition of an authenticator. Currently, this authenticator must be :password. Its value may be either a String, or a proc that returns a String. #bind_as returns false on failure. On success, it returns a result set, just as #search does. This result set is an Array of objects of type Net::LDAP::Entry. It contains the directory attributes corresponding to the user. (Just test whether the return value is logically true, if you don’t need this additional information.)

Here’s how you would use #bind_as to authenticate an email address and password:

require 'net/ldap'

user, psw = "[email protected]", "joes_psw"

ldap = Net::LDAP.new
ldap.host = "192.168.0.100"
ldap.port = 389
ldap.auth "cn=manager, dc=yourcompany, dc=com", "topsecret"

result = ldap.bind_as(:base => "dc=yourcompany, dc=com",
                      :filter => "(mail=#{user})",
                      :password => psw)
if result
  puts "Authenticated #{result.first.dn}"
else
  puts "Authentication FAILED."
end



772
773
774
775
776
777
778
779
780
781
782
783
784
 
# File 'lib/net/ldap.rb', line 772

def bind_as(args = {})
  result = false
  open { |me|
    rs = search args
    if rs and rs.first and dn = rs.first.dn
      password = args[:password]
      password = password.call if password.respond_to?(:call)
      result = rs if bind(:method => :simple, :username => dn,
                          :password => password)
    end
  }
  result
end

#delete(args) ⇒ Object

Delete an entry from the LDAP directory. Takes a hash of arguments. The only supported argument is :dn, which must give the complete DN of the entry to be deleted.

Returns True or False to indicate whether the delete succeeded. Extended status information is available by calling #get_operation_result.

dn = "[email protected], ou=people, dc=example, dc=com"
ldap.delete :dn => dn



1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
 
# File 'lib/net/ldap.rb', line 1007

def delete(args)
  if @open_connection
    @result = @open_connection.delete(args)
  else
    @result = 0
    begin
      conn = Connection.new(:host => @host, :port => @port,
                            :encryption => @encryption)
      if (@result = conn.bind(args[:auth] || @auth)) == 0
        @result = conn.delete(args)
      end
    ensure
      conn.close
    end
  end
  @result == 0
end

#delete_attribute(dn, attribute) ⇒ Object

Delete an attribute and all its values. Takes the full DN of the entry to modify, and the name (Symbol or String) of the attribute to delete.

Returns True or False to indicate whether the operation succeeded or failed, with extended information available by calling #get_operation_result. See also #add_attribute and #replace_attribute.

dn = "cn=modifyme, dc=example, dc=com"
ldap.delete_attribute dn, :mail



972
973
974
 
# File 'lib/net/ldap.rb', line 972

def delete_attribute(dn, attribute)
  modify(:dn => dn, :operations => [[:delete, attribute, nil]])
end

#encryption(args) ⇒ Object

Convenience method to specify encryption characteristics for connections to LDAP servers. Called implicitly by #new and #open, but may also be called by user code if desired. The single argument is generally a Hash (but see below for convenience alternatives). This implementation is currently a stub, supporting only a few encryption alternatives. As additional capabilities are added, more configuration values will be added here.

Currently, the only supported argument is { :method => :simple_tls }. (Equivalently, you may pass the symbol :simple_tls all by itself, without enclosing it in a Hash.)

The :simple_tls encryption method encrypts all communications with the LDAP server. It completely establishes SSL/TLS encryption with the LDAP server before any LDAP-protocol data is exchanged. There is no plaintext negotiation and no special encryption-request controls are sent to the server. The :simple_tls option is the simplest, easiest way to encrypt communications between Net::LDAP and LDAP servers. It’s intended for cases where you have an implicit level of trust in the authenticity of the LDAP server. No validation of the LDAP server’s SSL certificate is performed. This means that :simple_tls will not produce errors if the LDAP server’s encryption certificate is not signed by a well-known Certification Authority. If you get communications or protocol errors when using this option, check with your LDAP server administrator. Pay particular attention to the TCP port you are connecting to. It’s impossible for an LDAP server to support plaintext LDAP communications and simple TLS connections on the same port. The standard TCP port for unencrypted LDAP connections is 389, but the standard port for simple-TLS encrypted connections is 636. Be sure you are using the correct port.

[Note: a future version of Net::LDAP will support the STARTTLS LDAP control, which will enable encrypted communications on the same TCP port used for unencrypted connections.]



470
471
472
473
474
475
476
 
# File 'lib/net/ldap.rb', line 470

def encryption(args)
  case args
  when :simple_tls, :start_tls
    args = { :method => args }
  end
  @encryption = args
end

#get_operation_result ⇒ Object

Returns a meaningful result any time after a protocol operation (#bind, #search, #add, #modify, #rename, #delete) has completed. It returns an #OpenStruct containing an LDAP result code (0 means success), and a human-readable string.

unless ldap.bind
  puts "Result: #{ldap.get_operation_result.code}"
  puts "Message: #{ldap.get_operation_result.message}"
end

Certain operations return additional information, accessible through members of the object returned from #get_operation_result. Check #get_operation_result.error_message and #get_operation_result.matched_dn.

– Modified the implementation, 20Mar07. We might get a hash of LDAP response codes instead of a simple numeric code. ++



517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
 
# File 'lib/net/ldap.rb', line 517

def get_operation_result
  os = OpenStruct.new
  if @result.is_a?(Hash)
    # We might get a hash of LDAP response codes instead of a simple
    # numeric code.
    os.code = (@result[:resultCode] || "").to_i
    os.error_message = @result[:errorMessage]
    os.matched_dn = @result[:matchedDN]
  elsif @result
    os.code = @result
  else
    os.code = 0
  end
  os.message = Net::LDAP.result2string(os.code)
  os
end

#modify(args) ⇒ Object

Modifies the attribute values of a particular entry on the LDAP directory. Takes a hash with arguments. Supported arguments are:

:dn

(the full DN of the entry whose attributes are to be modified)

:operations

(the modifications to be performed, detailed next)

This method returns True or False to indicate whether the operation succeeded or failed, with extended information available by calling #get_operation_result.

Also see #add_attribute, #replace_attribute, or #delete_attribute, which provide simpler interfaces to this functionality.

The LDAP protocol provides a full and well thought-out set of operations for changing the values of attributes, but they are necessarily somewhat complex and not always intuitive. If these instructions are confusing or incomplete, please send us email or create a bug report on rubyforge.

The :operations parameter to #modify takes an array of operation-descriptors. Each individual operation is specified in one element of the array, and most LDAP servers will attempt to perform the operations in order.

Each of the operations appearing in the Array must itself be an Array

with exactly three elements: an operator

must be :add, :replace, or

:delete an attribute name

the attribute name (string or symbol) to

modify a value

either a string or an array of strings.

The :add operator will, unsurprisingly, add the specified values to the specified attribute. If the attribute does not already exist, :add will create it. Most LDAP servers will generate an error if you try to add a value that already exists.

:replace will erase the current value(s) for the specified attribute, if there are any, and replace them with the specified value(s).

:delete will remove the specified value(s) from the specified attribute. If you pass nil, an empty string, or an empty array as the value parameter to a :delete operation, the entire attribute will be deleted, along with all of its values.

For example:

dn = "[email protected], ou=people, dc=example, dc=com"
ops = [
  [:add, :mail, "[email protected]"],
  [:replace, :mail, ["[email protected]", "[email protected]"]],
  [:delete, :sn, nil]
]
ldap.modify :dn => dn, :operations => ops

(This example is contrived since you probably wouldn’t add a mail value right before replacing the whole attribute, but it shows that order of execution matters. Also, many LDAP servers won’t let you delete SN because that would be a schema violation.)

It’s essential to keep in mind that if you specify more than one operation in a call to #modify, most LDAP servers will attempt to perform all of the operations in the order you gave them. This matters because you may specify operations on the same attribute which must be performed in a certain order.

Most LDAP servers will stop processing your modifications if one of them causes an error on the server (such as a schema-constraint violation). If this happens, you will probably get a result code from the server that reflects only the operation that failed, and you may or may not get extended information that will tell you which one failed. #modify has no notion of an atomic transaction. If you specify a chain of modifications in one call to #modify, and one of them fails, the preceding ones will usually not be “rolled back, ” resulting in a partial update. This is a limitation of the LDAP protocol, not of Net::LDAP.

The lack of transactional atomicity in LDAP means that you’re usually better off using the convenience methods #add_attribute, #replace_attribute, and #delete_attribute, which are are wrappers over #modify. However, certain LDAP servers may provide concurrency semantics, in which the several operations contained in a single #modify call are not interleaved with other modification-requests received simultaneously by the server. It bears repeating that this concurrency does not imply transactional atomicity, which LDAP does not provide.



908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
 
# File 'lib/net/ldap.rb', line 908

def modify(args)
  if @open_connection
    @result = @open_connection.modify(args)
  else
    @result = 0
    begin
      conn = Connection.new(:host => @host, :port => @port,
                            :encryption => @encryption)
      if (@result = conn.bind(args[:auth] || @auth)) == 0
        @result = conn.modify(args)
      end
    ensure
      conn.close if conn
    end
  end
  @result == 0
end

#open ⇒ Object

Opens a network connection to the server and then passes self to the caller-supplied block. The connection is closed when the block completes. Used for executing multiple LDAP operations without requiring a separate network connection (and authentication) for each one. Note: You do not need to log-in or “bind” to the server. This will be done for you automatically. For an even simpler approach, see the class method Net::LDAP#open.

# (PSEUDOCODE)
auth = { :method => :simple, :username => username, :password => password }
ldap = Net::LDAP.new(:host => ipaddress, :port => 389, :auth => auth)
ldap.open do |ldap|
  ldap.search(...)
  ldap.add(...)
  ldap.modify(...)
end

Raises:



550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
 
# File 'lib/net/ldap.rb', line 550

def open
  # First we make a connection and then a binding, but we don't do
  # anything with the bind results. We then pass self to the caller's
  # block, where he will execute his LDAP operations. Of course they will
  # all generate auth failures if the bind was unsuccessful.
  raise Net::LDAP::LdapError, "Open already in progress" if @open_connection

  begin
    @open_connection = Net::LDAP::Connection.new(:host => @host,
                                                 :port => @port,
                                                 :encryption =>
                                                 @encryption)
    @open_connection.bind(@auth)
    yield self
  ensure
    @open_connection.close if @open_connection
    @open_connection = nil
  end
end

#paged_searches_supported? ⇒ Boolean

– Convenience method to query server capabilities. Only do this once per Net::LDAP object. Note, we call a search, and we might be called from inside a search! MUST refactor the root_dse call out. ++

Returns:

  • (Boolean) 


1093
1094
1095
1096
 
# File 'lib/net/ldap.rb', line 1093

def paged_searches_supported?
  @server_caps ||= search_root_dse
  @server_caps[:supportedcontrol].include?(Net::LDAP::LdapControls::PagedResults)
end

#rename(args) ⇒ Object Also known as: modify_rdn

Rename an entry on the remote DIS by changing the last RDN of its DN.

Documentation stub



979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
 
# File 'lib/net/ldap.rb', line 979

def rename(args)
  if @open_connection
    @result = @open_connection.rename(args)
  else
    @result = 0
    begin
      conn = Connection.new(:host => @host, :port => @port,
                            :encryption => @encryption)
      if (@result = conn.bind(args[:auth] || @auth)) == 0
        @result = conn.rename(args)
      end
    ensure
      conn.close if conn
    end
  end
  @result == 0
end

#replace_attribute(dn, attribute, value) ⇒ Object

Replace the value of an attribute. #replace_attribute can be thought of as equivalent to calling #delete_attribute followed by #add_attribute. It takes the full DN of the entry to modify, the name (Symbol or String) of the attribute, and the value (String or Array). If the attribute does not exist, it will be created with the caller-specified value(s). If the attribute does exist, its values will be discarded and replaced with the caller-specified values.

Returns True or False to indicate whether the operation succeeded or failed, with extended information available by calling #get_operation_result. See also #add_attribute and #delete_attribute.

dn = "cn=modifyme, dc=example, dc=com"
ldap.replace_attribute dn, :mail, "[email protected]"



959
960
961
 
# File 'lib/net/ldap.rb', line 959

def replace_attribute(dn, attribute, value)
  modify(:dn => dn, :operations => [[:replace, attribute, value]])
end

#search(args = {}) ⇒ Object

Searches the LDAP directory for directory entries. Takes a hash argument with parameters. Supported parameters include:

  • :base (a string specifying the tree-base for the search);

  • :filter (an object of type Net::LDAP::Filter, defaults to objectclass=*);

  • :attributes (a string or array of strings specifying the LDAP attributes to return from the server);

  • :return_result (a boolean specifying whether to return a result set).

  • :attributes_only (a boolean flag, defaults false)

  • :scope (one of: Net::LDAP::SearchScope_BaseObject, Net::LDAP::SearchScope_SingleLevel, Net::LDAP::SearchScope_WholeSubtree. Default is WholeSubtree.)

  • :size (an integer indicating the maximum number of search entries to return. Default is zero, which signifies no limit.)

#search queries the LDAP server and passes each entry to the caller-supplied block, as an object of type Net::LDAP::Entry. If the search returns 1000 entries, the block will be called 1000 times. If the search returns no entries, the block will not be called.

#search returns either a result-set or a boolean, depending on the value of the :return_result argument. The default behavior is to return a result set, which is an Array of objects of class Net::LDAP::Entry. If you request a result set and #search fails with an error, it will return nil. Call #get_operation_result to get the error information returned by the LDAP server.

When :return_result => false, #search will return only a Boolean, to indicate whether the operation succeeded. This can improve performance with very large result sets, because the library can discard each entry from memory after your block processes it.

treebase = "dc=example, dc=com"
filter = Net::LDAP::Filter.eq("mail", "a*.com")
attrs = ["mail", "cn", "sn", "objectclass"]
ldap.search(:base => treebase, :filter => filter, :attributes => attrs,
            :return_result => false) do |entry|
  puts "DN: #{entry.dn}"
  entry.each do |attr, values|
    puts ".......#{attr}:"
    values.each do |value|
      puts "          #{value}"
    end
  end
end



616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
 
# File 'lib/net/ldap.rb', line 616

def search(args = {})
  unless args[:ignore_server_caps]
    args[:paged_searches_supported] = paged_searches_supported?
  end

  args[:base] ||= @base
  return_result_set = args[:return_result] != false
  result_set = return_result_set ? [] : nil

  if @open_connection
    @result = @open_connection.search(args) { |entry|
      result_set << entry if result_set
      yield entry if block_given?
    }
  else
    @result = 0
    begin
      conn = Net::LDAP::Connection.new(:host => @host, :port => @port,
                                       :encryption => @encryption)
      if (@result = conn.bind(args[:auth] || @auth)) == 0
        @result = conn.search(args) { |entry|
          result_set << entry if result_set
          yield entry if block_given?
        }
      end
    ensure
      conn.close if conn
    end
  end

  if return_result_set
    @result == 0 ? result_set : nil
  else
    @result == 0
  end
end

#search_root_dse ⇒ Object

This method is experimental and subject to change. Return the rootDSE record from the LDAP server as a Net::LDAP::Entry, or an empty Entry if the server doesn’t return the record. – cf. RFC4512 graf 5.1. Note that the rootDSE record we return on success has an empty DN, which is correct. On failure, the empty Entry will have a nil DN. There’s no real reason for that, so it can be changed if desired. The funky number-disagreements in the set of attribute names is correct per the RFC. We may be called by #search itself, which may need to determine things like paged search capabilities. So to avoid an infinite regress, set :ignore_server_caps, which prevents us getting called recursively. ++



1038
1039
1040
1041
1042
1043
1044
1045
 
# File 'lib/net/ldap.rb', line 1038

def search_root_dse
  rs = search(:ignore_server_caps => true, :base => "",
              :scope => SearchScope_BaseObject,
              :attributes => [ :namingContexts, :supportedLdapVersion,
                :altServer, :supportedControl, :supportedExtension,
                :supportedFeatures, :supportedSASLMechanisms])
  (rs and rs.first) or Net::LDAP::Entry.new
end

#search_subschema_entry ⇒ Object

Return the root Subschema record from the LDAP server as a Net::LDAP::Entry, or an empty Entry if the server doesn’t return the record. On success, the Net::LDAP::Entry returned from this call will have the attributes :dn, :objectclasses, and :attributetypes. If there is an error, call #get_operation_result for more information.

ldap = Net::LDAP.new
ldap.host = "your.ldap.host"
ldap.auth "your-user-dn", "your-psw"
subschema_entry = ldap.search_subschema_entry

subschema_entry.attributetypes.each do |attrtype|
  # your code
end

subschema_entry.objectclasses.each do |attrtype|
  # your code
end

– cf. RFC4512 section 4, particulary graff 4.4. The :dn attribute in the returned Entry is the subschema name as returned from the server. Set :ignore_server_caps, see the notes in search_root_dse. ++



1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
 
# File 'lib/net/ldap.rb', line 1071

def search_subschema_entry
  rs = search(:ignore_server_caps => true, :base => "",
              :scope => SearchScope_BaseObject,
              :attributes => [:subschemaSubentry])
  return Net::LDAP::Entry.new unless (rs and rs.first)

  subschema_name = rs.first.subschemasubentry
  return Net::LDAP::Entry.new unless (subschema_name and subschema_name.first)

  rs = search(:ignore_server_caps => true, :base => subschema_name.first,
              :scope => SearchScope_BaseObject,
              :filter => "objectclass=subschema",
              :attributes => [:objectclasses, :attributetypes])
  (rs and rs.first) or Net::LDAP::Entry.new
end