Method: Net::LDAP#initialize

Defined in:: lib/net/ldap.rb

#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)
:hosts => an enumerable of pairs of hosts and corresponding ports with which to attempt opening connections (default [[host, port]])
: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.
:force_no_page => Set to true to prevent paged results even if your server says it supports them. This is a fix for MS Active Directory
:instrumentation_service => An object responsible for instrumenting operations, compatible with ActiveSupport::Notifications’ public API.
:connect_timeout => The TCP socket timeout (in seconds) to use when connecting to the LDAP server (default 5 seconds).
:encryption => specifies the encryption to be used in communicating with the LDAP server. The value must be a Hash containing additional parameters, which consists of two keys:
```
method: - :simple_tls or :start_tls
tls_options: - Hash of options for that method
```
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. 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. The :start_tls like the :simple_tls encryption method also encrypts all communcations with the LDAP server. With the exception that it operates over the standard TCP port.

To validate the LDAP server’s certificate (a security must if you’re talking over the public internet), you need to set :tls_options something like this…

Net::LDAP.new(
```
# ... set host, bind dn, etc ...
encryption: {
  method: :simple_tls,
  tls_options: OpenSSL::SSL::SSLContext::DEFAULT_PARAMS,
}
```
)

The above will use the operating system-provided store of CA certificates to validate your LDAP server’s cert. If cert validation fails, it’ll happen during the #bind whenever you first try to open a connection to the server. Those methods will throw Net::LDAP::ConnectionError with a message about certificate verify failing. If your LDAP server’s certificate is signed by DigiCert, Comodo, etc., you’re probably good. If you’ve got a self-signed cert but it’s been added to the host’s OS-maintained CA store (e.g. on Debian add foobar.crt to /usr/local/share/ca-certificates/ and run ‘update-ca-certificates`), then the cert should pass validation. To ignore the OS’s CA store, put your CA in a PEM-encoded file and…

encryption: {
```
method:      :simple_tls,
tls_options: { ca_file:     '/path/to/my-little-ca.pem',
               ssl_version: 'TLSv1_1' },
```
}

As you might guess, the above example also fails the connection if the client can’t negotiate TLS v1.1. tls_options is ultimately passed to OpenSSL::SSL::SSLContext#set_params For more details, see
```
http://ruby-doc.org/stdlib-2.0.0/libdoc/openssl/rdoc/OpenSSL/SSL/SSLContext.html
```

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. That’s why Net::LDAP.new doesn’t throw cert validation errors itself; #bind does instead.

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

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

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

  @instrumentation_service = args[:instrumentation_service]

  # 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

Method: Net::LDAP#initialize

#initialize(args = {}) ⇒ LDAP

#initialize(args = {}) ⇒ `LDAP`