ruby-net-ldap 0.0.3 → 0.0.4

data/ChangeLog

@@ -1,5 +1,17 @@
 = Net::LDAP Changelog
 
+== Net::LDAP 0.0.4: August 15, 2006
+* Undeprecated Net::LDAP#modify. Thanks to Justin Forder for
+  providing the rationale for this.
+* Added a much-expanded set of special characters to the parser
+  for RFC-2254 filters. Thanks to Andre Nathan.
+* Changed Net::LDAP#search so you can pass it a filter in string form.
+  The conversion to a Net::LDAP::Filter now happens automatically.
+* Implemented Net::LDAP#bind_as (preliminary and subject to change).
+  Thanks for Simon Claret for valuable suggestions and for helping test.
+* Fixed bug in Net::LDAP#open that was preventing #open from being
+  called more than one on a given Net::LDAP object.
+
 == Net::LDAP 0.0.3: July 26, 2006
 * Added simple TLS encryption.
   Thanks to Garett Shulman for suggestions and for helping test.

data/lib/net/ldap.rb

@@ -1,4 +1,4 @@
-# $Id: ldap.rb 144 2006-07-26 21:35:38Z blackhedd $
+# $Id: ldap.rb 154 2006-08-15 09:35:43Z blackhedd $
 #
 # Net::LDAP for Ruby
 #
@@ -263,7 +263,7 @@ module Net
 
     class LdapError < Exception; end
 
-    VERSION = "0.0.3"
+    VERSION = "0.0.4"
 
 
     SearchScope_BaseObject = 0
@@ -543,6 +543,7 @@ module Net
       @open_connection.bind @auth
       yield self
       @open_connection.close
+      @open_connection = nil
     end
 
 
@@ -692,9 +693,9 @@ module Net
     # on it. Otherwise, connect, bind, and disconnect.
     # The latter operation is obviously useful only as an auth check.
     #
-    def bind
+    def bind auth=@auth
       if @open_connection
-        @result = @open_connection.bind @auth
+        @result = @open_connection.bind auth
       else
         conn = Connection.new( :host => @host, :port => @port , :encryption => @encryption)
         @result = conn.bind @auth
@@ -706,18 +707,64 @@ module Net
 
     #
     # #bind_as is for testing authentication credentials.
-    # Most likely a "standard" name (like a CN or an email
-    # address) will be presented along with a password.
-    # We'll bind with the main credential given in the
-    # constructor, query the full DN of the user given
-    # to us as a parameter, then unbind and rebind as the
-    # new user.
     #
-    # <i>This method is currently an unimplemented stub.</i>
+    # 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 <b>re-bind</b> as that user with the
+    # password (or other authenticator) that you supply.
+    #
+    # #bind_as takes the same parameters as #search, <i>with the addition of an
+    # authenticator.</i> Currently, this authenticator must be <tt>:password</tt>.
+    # 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:
     #
-    def bind_as
+    #  require 'net/ldap'
+    #  
+    #  user,psw = "joe_user@yourcompany.com", "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
+    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
 
+
     # Adds a new entry to the remote LDAP server.
     # Supported arguments:
     # :dn :: Full DN of the new entry
@@ -757,8 +804,6 @@ module Net
     end
 
 
-    # _DEPRECATED_ - Please use #add_attribute, #replace_attribute, or #delete_attribute.
-    #
     # 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)
@@ -768,6 +813,9 @@ module Net
     # 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,
@@ -786,14 +834,15 @@ module Net
     # 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
-    # to add a value that already exists.
+    # 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.
+    # to a :delete operation, the _entire_ _attribute_ will be deleted, along
+    # with all of its values.
     #
     # For example:
     #
@@ -808,13 +857,14 @@ module Net
     # <i>(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 it would be a schema violation.)</i>
+    # because that would be a schema violation.)</i>
     #
     # 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
@@ -825,6 +875,14 @@ module Net
     # 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.
     #
     def modify args
       if @open_connection
@@ -1067,6 +1125,7 @@ module Net
     #
     def search args = {}
       search_filter = (args && args[:filter]) || Filter.eq( "objectclass", "*" )
+      search_filter = Filter.construct(search_filter) if search_filter.is_a?(String)
       search_base = (args && args[:base]) || "dc=example,dc=com"
       search_attributes = ((args && args[:attributes]) || []).map {|attr| attr.to_s.to_ber}
       return_referrals = args && args[:return_referrals] == true

data/lib/net/ldap/filter.rb

@@ -1,4 +1,4 @@
-# $Id: filter.rb 132 2006-06-27 17:35:18Z blackhedd $
+# $Id: filter.rb 151 2006-08-15 08:34:53Z blackhedd $
 #
 #
 #----------------------------------------------------------------------------
@@ -292,6 +292,7 @@ class Filter
 end # class Net::LDAP::Filter
 
 
+
 class FilterParser #:nodoc:
 
   attr_reader :filter
@@ -349,13 +350,16 @@ class FilterParser #:nodoc:
     end
   end
 
+  # Added a greatly-augmented filter contributed by Andre Nathan
+  # for detecting special characters in values. (15Aug06)
   def parse_filter_branch scanner
     scanner.scan /\s*/
     if token = scanner.scan( /[\w\-_]+/ )
       scanner.scan /\s*/
       if op = scanner.scan( /\=|\<\=|\<|\>\=|\>|\!\=/ )
         scanner.scan /\s*/
-        if value = scanner.scan( /[\w\*\.]+/ )
+        #if value = scanner.scan( /[\w\*\.]+/ ) (ORG)
+        if value = scanner.scan( /[\w\*\.\+\-@=#\$%&!]+/ )
           case op
           when "="
             Filter.eq( token, value )

metadata

@@ -3,8 +3,8 @@ rubygems_version: 0.8.11
 specification_version: 1
 name: ruby-net-ldap
 version: !ruby/object:Gem::Version 
-  version: 0.0.3
-date: 2006-07-27 00:00:00 -04:00
+  version: 0.0.4
+date: 2006-08-15 00:00:00 -04:00
 summary: A pure Ruby LDAP client library.
 require_paths: 
 - lib