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.)
Search¶ ↑
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.
Constants
- AsnSyntax
- DefaultAuth
- DefaultForceNoPage
- DefaultHost
- DefaultPort
- DefaultTreebase
- DerefAliasesArray
- DerefAliases_Always
- DerefAliases_Find
- DerefAliases_Never
- DerefAliases_Search
- HasOpenSSL
Set to
true
if OpenSSL is available and LDAPS is supported.- PasswdModifyOid
- ResultCodeAdminLimitExceeded
- ResultCodeAffectsMultipleDSAs
- ResultCodeAliasDereferencingProblem
- ResultCodeAliasProblem
- ResultCodeAttributeOrValueExists
- ResultCodeAuthMethodNotSupported
- ResultCodeBusy
- ResultCodeCompareFalse
- ResultCodeCompareTrue
- ResultCodeConfidentialityRequired
- ResultCodeConstraintViolation
- ResultCodeEntryAlreadyExists
- ResultCodeInappropriateAuthentication
- ResultCodeInappropriateMatching
- ResultCodeInsufficientAccessRights
- ResultCodeInvalidAttributeSyntax
- ResultCodeInvalidCredentials
- ResultCodeInvalidDNSyntax
- ResultCodeNamingViolation
- ResultCodeNoSuchAttribute
- ResultCodeNoSuchObject
- ResultCodeNotAllowedOnNonLeaf
- ResultCodeNotAllowedOnRDN
- ResultCodeObjectClassModsProhibited
- ResultCodeObjectClassViolation
- ResultCodeOperationsError
- ResultCodeOther
- ResultCodeProtocolError
- ResultCodeReferral
- ResultCodeSaslBindInProgress
- ResultCodeSizeLimitExceeded
- ResultCodeStrongerAuthRequired
- ResultCodeSuccess
tools.ietf.org/html/rfc4511#section-4.1.9 tools.ietf.org/html/rfc4511#appendix-A
- ResultCodeTimeLimitExceeded
- ResultCodeUndefinedAttributeType
- ResultCodeUnwillingToPerform
- ResultCodesNonError
- ResultCodesSearchSuccess
nonstandard list of “successful” result codes for searches
- ResultStrings
map of result code to human message
- SearchScope_BaseObject
- SearchScope_SingleLevel
- SearchScope_WholeSubtree
- SearchScopes
- StartTlsOid
- VERSION
Attributes
Public Class Methods
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: {:method => :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 tosearch
must specify a treebase parameter. If you do give this value, then it will be used in subsequent calls tosearch
that do not specify a treebase. If you give a treebase value in any particular call tosearch
, 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 theLDAP
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 yourLDAP
server administrator. Pay particular attention to the TCP port you are connecting to. It’s impossible for anLDAP
server to support plaintextLDAP
communications and simple TLS connections on the same port. The standard TCP port for unencryptedLDAP
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 theLDAP
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…# ... 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 thebind
whenever you first try to open a connection to the server. Those methods will throwNet::LDAP::ConnectionError
with a message about certificate verify failing. If yourLDAP
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 547 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
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
# File lib/net/ldap.rb, line 643 def self.open(args) ldap1 = new(args) ldap1.open { |ldap| yield ldap } end
Public Instance Methods
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 => "gsmith@example.com" } Net::LDAP.open(:host => host) do |ldap| ldap.add(:dn => dn, :attributes => attr) end
# File lib/net/ldap.rb, line 963 def add(args) instrument "add.net_ldap", args do |payload| @result = use_connection(args) do |conn| conn.add(args) end @result.success? end end
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, "newmailaddress@example.com"
# File lib/net/ldap.rb, line 1115 def add_attribute(dn, attribute, value) modify(:dn => dn, :operations => [[:add, attribute, value]]) end
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
# File lib/net/ldap.rb, line 602 def authenticate(username, password) password = password.call if password.respond_to?(:call) @auth = { :method => :simple, :username => username, :password => password, } end
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 860 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
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 = "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
# File lib/net/ldap.rb, line 925 def bind_as(args = {}) result = false open do |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 end result end
Internal: Set @open_connection for testing
# File lib/net/ldap.rb, line 1294 def connection=(connection) @open_connection = connection end
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 = "mail=deleteme@example.com, ou=people, dc=example, dc=com" ldap.delete :dn => dn
# File lib/net/ldap.rb, line 1172 def delete(args) instrument "delete.net_ldap", args do |payload| @result = use_connection(args) do |conn| conn.delete(args) end @result.success? end end
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
# File lib/net/ldap.rb, line 1146 def delete_attribute(dn, attribute) modify(:dn => dn, :operations => [[:delete, attribute, nil]]) end
Delete an entry from the LDAP
directory along with all subordinate entries. the regular delete method will fail to delete an entry if it has subordinate entries. This method sends an extra control code to tell the LDAP
server to do a tree delete. (‘1.2.840.113556.1.4.805’)
If the LDAP
server does not support the DELETE_TREE control code, subordinate entries are deleted recursively instead.
Returns True or False to indicate whether the delete succeeded. Extended status information is available by calling get_operation_result
.
dn = "mail=deleteme@example.com, ou=people, dc=example, dc=com" ldap.delete_tree :dn => dn
# File lib/net/ldap.rb, line 1194 def delete_tree(args) if search_root_dse[:supportedcontrol].include? Net::LDAP::LDAPControls::DELETE_TREE delete(args.merge(:control_codes => [[Net::LDAP::LDAPControls::DELETE_TREE, true]])) else recursive_delete(args) end end
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.
This method is deprecated.
# File lib/net/ldap.rb, line 622 def encryption(args) warn "Deprecation warning: please give :encryption option as a Hash to Net::LDAP.new" return if args.nil? @encryption = normalize_encryption(args) end
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.
# File lib/net/ldap.rb, line 667 def get_operation_result result = @result os = OpenStruct.new if result.is_a?(Net::LDAP::PDU) os.extended_response = result.extended_response result = result.result end 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 = Net::LDAP::ResultCodeSuccess end os.message = Net::LDAP.result2string(os.code) os end
Mask auth password
# File lib/net/ldap.rb, line 1287 def inspect inspected = super inspected.gsub! @auth[:password], "*******" if @auth[:password] inspected end
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 an issue on GitHub.
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 = "mail=modifyme@example.com, ou=people, dc=example, dc=com" ops = [ [:add, :mail, "aliasaddress@example.com"], [:replace, :mail, ["newaddress@example.com", "newalias@example.com"]], [: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 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.
# File lib/net/ldap.rb, line 1053 def modify(args) instrument "modify.net_ldap", args do |payload| @result = use_connection(args) do |conn| conn.modify(args) end @result.success? end end
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
# File lib/net/ldap.rb, line 705 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::AlreadyOpenedError, "Open already in progress" if @open_connection instrument "open.net_ldap" do |payload| begin @open_connection = new_connection payload[:connection] = @open_connection payload[:bind] = @result = @open_connection.bind(@auth) yield self ensure @open_connection.close if @open_connection @open_connection = nil end end end
# File lib/net/ldap.rb, line 1277 def paged_searches_supported? # active directory returns that it supports paged results. However # it returns binary data in the rfc2696_cookie which throws an # encoding exception breaking searching. return false if @force_no_page @server_caps ||= search_root_dse @server_caps[:supportedcontrol].include?(Net::LDAP::LDAPControls::PAGED_RESULTS) end
Password
Modify
Change existing password:
dn = 'uid=modify-password-user1,ou=People,dc=rubyldap,dc=com' auth = { method: :simple, username: dn, password: 'passworD1' } ldap.password_modify(dn: dn, auth: auth, old_password: 'passworD1', new_password: 'passworD2')
Or get the LDAP
server to generate a password for you:
dn = 'uid=modify-password-user1,ou=People,dc=rubyldap,dc=com' auth = { method: :simple, username: dn, password: 'passworD1' } ldap.password_modify(dn: dn, auth: auth, old_password: 'passworD1') ldap.get_operation_result.extended_response[0][0] #=> 'VtcgGf/G'
# File lib/net/ldap.rb, line 1091 def password_modify(args) instrument "modify_password.net_ldap", args do |payload| @result = use_connection(args) do |conn| conn.password_modify(args) end @result.success? end end
Rename an entry on the remote DIS by changing the last RDN of its DN
.
Documentation stub
# File lib/net/ldap.rb, line 1153 def rename(args) instrument "rename.net_ldap", args do |payload| @result = use_connection(args) do |conn| conn.rename(args) end @result.success? end end
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, "newmailaddress@example.com"
# File lib/net/ldap.rb, line 1133 def replace_attribute(dn, attribute, value) modify(:dn => dn, :operations => [[:replace, attribute, value]]) end
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.)
-
:time (an integer restricting the maximum time in seconds allowed for a search. Default is zero, no time limit RFC 4511 4.5.1.5)
-
:deref (one of:
Net::LDAP::DerefAliases_Never
,Net::LDAP::DerefAliases_Search
,Net::LDAP::DerefAliases_Find
,Net::LDAP::DerefAliases_Always
. Default is Never.)
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
# File lib/net/ldap.rb, line 774 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 instrument "search.net_ldap", args do |payload| @result = use_connection(args) do |conn| conn.search(args) do |entry| result_set << entry if result_set yield entry if block_given? end end if return_result_set unless @result.nil? if ResultCodesSearchSuccess.include?(@result.result_code) result_set end end else @result.success? end end end
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.
# File lib/net/ldap.rb, line 1215 def search_root_dse rs = search(:ignore_server_caps => true, :base => "", :scope => SearchScope_BaseObject, :attributes => [ :altServer, :namingContexts, :supportedCapabilities, :supportedControl, :supportedExtension, :supportedFeatures, :supportedLdapVersion, :supportedSASLMechanisms, ]) (rs and rs.first) or Net::LDAP::Entry.new end
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
# File lib/net/ldap.rb, line 1255 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
Private Instance Methods
Establish a new connection to the LDAP
server
# File lib/net/ldap.rb, line 1320 def new_connection connection = Net::LDAP::Connection.new \ :host => @host, :port => @port, :hosts => @hosts, :encryption => @encryption, :instrumentation_service => @instrumentation_service, :connect_timeout => @connect_timeout # Force connect to see if there's a connection error connection.socket connection rescue Errno::ECONNREFUSED, Errno::ETIMEDOUT => e @result = { :resultCode => 52, :errorMessage => ResultStrings[ResultCodeUnavailable], } raise e end
Normalize encryption parameter the constructor accepts, expands a few convenience symbols into recognizable hashes
# File lib/net/ldap.rb, line 1342 def normalize_encryption(args) return if args.nil? return args if args.is_a? Hash case method = args.to_sym when :simple_tls, :start_tls { :method => method, :tls_options => {} } end end
Recursively delete a dn and it’s subordinate children. This is useful when a server does not support the DELETE_TREE control code.
# File lib/net/ldap.rb, line 1354 def recursive_delete(args) raise EmptyDNError unless args.is_a?(Hash) && args.key?(:dn) # Delete Children search(base: args[:dn], scope: Net::LDAP::SearchScope_SingleLevel) do |entry| recursive_delete(dn: entry.dn) end # Delete Self unless delete(dn: args[:dn]) raise Net::LDAP::Error, get_operation_result[:error_message].to_s end true end
Yields an open connection if there is one, otherwise establishes a new connection, binds, and yields it. If binding fails, it will return the result from that, and :use_connection: will not yield at all. If not the return value is whatever is returned from the block.
# File lib/net/ldap.rb, line 1304 def use_connection(args) if @open_connection yield @open_connection else begin conn = new_connection result = conn.bind(args[:auth] || @auth) return result unless result.result_code == Net::LDAP::ResultCodeSuccess yield conn ensure conn.close if conn end end end