Method: Net::LDAP#bind

Defined in:

lib/net/ldap.rb

#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.

# File 'lib/net/ldap.rb', line 861

def bind(auth = @auth)
  instrument "bind.net_ldap" do |payload|
    if @open_connection
      payload[:connection] = @open_connection
      payload[:bind]       = @result = @open_connection.bind(auth)
    else
      begin
        conn = new_connection
        payload[:connection] = conn
        payload[:bind]       = @result = conn.bind(auth)
      ensure
        conn.close if conn
      end
    end

    @result.success?
  end
end