ldap_lookup 0.1.7 → 2.0.0

data/lib/ldap_lookup.rb

@@ -1,158 +1,503 @@
-require_relative "helpers/configuration"
+require_relative 'helpers/configuration'
+require 'net/ldap'
+require 'openssl'
 
 module LdapLookup
-  require "net/ldap"
-
   extend Configuration
 
   define_setting :host
-  define_setting :port, "389"
+  define_setting :port, '389'
   define_setting :base
   define_setting :dept_attribute
   define_setting :group_attribute
+  define_setting :username
+  define_setting :password
+  define_setting :bind_dn  # Optional: custom bind DN (for service accounts). If not set, uses uid=username,ou=People,base
+  define_setting :encryption, :start_tls  # :start_tls or :simple_tls (LDAPS)
+  define_setting :debug, false
 
-  # this was developed using guidence from this gist:
-  # https://gist.githubusercontent.com/jeffjohnson9046/7012167/raw/86587b9637ddc2ece7a42df774980fa9c0aac9b3/ruby-ldap-sample.rb
-
-  #######################################################################################################################
-  ## HELPER/UTILITY METHOD
-  ##   This method interprets the response/return code from an LDAP bind operation (bind, search, add, modify, rename,
-  ##   delete).  This method isn't necessarily complete, but it's a good starting point for handling the response codes
-  ##   from an LDAP bind operation.
-  ##
-  ##   Additional details for the get_operation_result method can be found here:
-  ##   http://net-ldap.rubyforge.org/Net/LDAP.html#method-i-get_operation_result
-  ########################################################################################################################
-  def self.get_ldap_response(ldap)
-    msg = "Response Code: #{ldap.get_operation_result.code}, Message: #{ldap.get_operation_result.message}"
-    raise msg unless ldap.get_operation_result.code == 0
+  def self.debug_log(message)
+    return unless debug
+
+    puts "[LDAP DEBUG] #{message}"
   end
 
-  #######################################################################################################################
-  # SET UP LDAP CONNECTION
-  # Setting up a connection to the LDAP server using .new() does not actually send any network traffic to the LDAP
-  # server.  When you call an operation on ldap (e.g. add or search), .bind is called implicitly.  *That's* when the
-  # connection is made to the LDAP server.  This means that each operation called on the ldap object will create its own
-  # network connection to the LDAP server.
-  #######################################################################################################################
-  def self.ldap_connection
-    ldap = Net::LDAP.new host: host, # your LDAP host name or IP goes here,
-                         port: port, # your LDAP host port goes here,
-                         base: base, # the base of your AD tree goes here,
-                         auth: {
-                           :method => :anonymous,
-                         }
+  def self.perform_search(ldap, base: nil, filter:, attributes: nil, label: nil, options: {})
+    search_base = base || ldap.base
+    filter_str = filter.respond_to?(:to_s) ? filter.to_s : filter.inspect
+    attrs_list = attributes ? Array(attributes).map(&:to_s) : ['*']
+    label_prefix = label ? "#{label} " : ""
+
+    debug_log("#{label_prefix}search base=#{search_base} filter=#{filter_str} attrs=#{attrs_list.join(',')}")
+
+    params = { base: search_base, filter: filter }
+    params[:attributes] = attributes if attributes
+    params.merge!(options) if options && !options.empty?
+
+    results = ldap.search(params) || []
+    entry_count = results ? results.size : 0
+    returned_attrs = []
+    if results && !results.empty?
+      returned_attrs = results.first.attribute_names.map(&:to_s).sort
+    end
+
+    debug_log("#{label_prefix}search results count=#{entry_count} returned_attrs=#{returned_attrs.join(',')}")
+
+    results
   end
 
-  # GET THE DISPLAY NAME FOR A SINGLE USER
-  def self.get_simple_name(uniqname = nil)
-    ldap = ldap_connection
-    search_param = uniqname # the AD account goes here
-    result_attrs = ["displayName"] # Whatever you want to bring back in your result set goes here
-    # Build filter
-    search_filter = Net::LDAP::Filter.eq("uid", search_param)
-    # Execute search
-    result = ldap.search(filter: search_filter, attributes: result_attrs)
-      if result.length != 0
-        return result.first.displayname.first
+  def self.operation_details(response)
+    details = {
+      code: response.code,
+      message: response.message
+    }
+
+    if response.respond_to?(:error_message) && response.error_message && !response.error_message.empty?
+      details[:error_message] = response.error_message
+    end
+
+    if response.respond_to?(:matched_dn) && response.matched_dn && !response.matched_dn.empty?
+      details[:matched_dn] = response.matched_dn
+    end
+
+    if response.respond_to?(:referrals) && response.referrals && !response.referrals.empty?
+      details[:referrals] = response.referrals
+    end
+
+    details
+  end
+
+  def self.get_ldap_response(ldap)
+    response = ldap.get_operation_result
+    unless response.code.zero?
+      error_msg = "Response Code: #{response.code}, Message: #{response.message}"
+      if response.respond_to?(:error_message) && response.error_message && !response.error_message.empty?
+        error_msg += ", Diagnostic: #{response.error_message}"
+      end
+      if response.respond_to?(:matched_dn) && response.matched_dn && !response.matched_dn.empty?
+        error_msg += ", Matched DN: #{response.matched_dn}"
+      end
+      # Provide more helpful error messages for common codes
+      case response.code
+      when 19
+        error_msg += " (Constraint Violation - may require administrative access)"
+      when 49
+        error_msg += " (Invalid Credentials - check username/password)"
+      when 50
+        error_msg += " (Insufficient Access Rights)"
+      when 81
+        error_msg += " (Server Unavailable)"
+      end
+      raise error_msg
+    end
+  end
+
+  # Diagnostic method to test LDAP connection and bind
+  def self.test_connection
+    username_present = username && !username.to_s.strip.empty?
+    password_present = password && !password.to_s.strip.empty?
+    auth_dn = if bind_dn
+      bind_dn
+    elsif username_present
+      "uid=#{username},ou=People,#{base}"
+    end
+
+    search_base = username_present ? "ou=People,#{base}" : base
+    search_filter = username_present ? "(uid=#{username})" : "(objectClass=*)"
+
+    result = {
+      bind_dn: auth_dn,
+      username: username,
+      host: host,
+      port: port,
+      encryption: encryption,
+      base: base,
+      auth_mode: (username_present && password_present) ? 'authenticated' : 'anonymous'
+    }
+
+    begin
+      ldap = ldap_connection
+
+      bind_response = nil
+      bind_exception = nil
+
+      # Try an explicit bind for diagnostics only (can return Code 19 even if searches work)
+      begin
+        bind_success = ldap.bind
+        bind_response = ldap.get_operation_result
+      rescue => e
+        bind_success = false
+        bind_exception = { class: e.class.name, message: e.message }
+      end
+
+      # Net::LDAP binds automatically when performing operations (search, etc.)
+      # Explicit bind may fail with Code 19 on STARTTLS, but actual operations work fine
+      # Test by performing an actual search operation instead of explicit bind
+      
+      # Try a simple search - this will trigger automatic bind
+      search_result = perform_search(
+        ldap,
+        base: search_base,
+        filter: search_filter,
+        attributes: ['uid', 'mail', 'displayName', 'cn', 'givenName', 'sn'],
+        label: "diagnostic",
+        options: { size: 1 }
+      )
+      search_response = ldap.get_operation_result
+      returned_attributes = []
+      if search_result && !search_result.empty?
+        entry = search_result.first
+        returned_attributes = entry.attribute_names.map(&:to_s).sort
+      end
+
+      if search_response.code.zero? || (search_response.code == 4 && (search_result && !search_result.empty?))
+        # Success! Bind worked (automatically during search)
+        result.merge!(
+          success: true,
+          bind_successful: true,
+          bind_attempted: true,
+          bind_result: bind_success,
+          bind_details: bind_response ? operation_details(bind_response) : nil,
+          bind_exception: bind_exception,
+          bind_code: 0,
+          bind_message: "Bind successful (via automatic bind during search)",
+          search_code: search_response.code,
+          search_message: search_response.message,
+          search_details: operation_details(search_response),
+          search_base: search_base,
+          search_filter: search_filter,
+          search_entry_count: search_result ? search_result.size : 0,
+          search_returned_attributes: returned_attributes,
+          note: "Explicit bind may show Code 19, but operations work correctly"
+        )
       else
-        return "No such user"
+        # Search failed - check if it's a bind issue or search issue
+        result.merge!(
+          success: false,
+          bind_successful: false,
+          bind_attempted: true,
+          bind_result: bind_success,
+          bind_details: bind_response ? operation_details(bind_response) : nil,
+          bind_exception: bind_exception,
+          search_code: search_response.code,
+          search_message: search_response.message,
+          search_details: operation_details(search_response),
+          search_base: search_base,
+          search_filter: search_filter,
+          search_entry_count: search_result ? search_result.size : 0,
+          search_returned_attributes: returned_attributes,
+          error: "Search failed: Code #{search_response.code}, #{search_response.message}"
+        )
+
+        case search_response.code
+        when 19
+          result[:suggestion] = "Constraint Violation. Your account may not be enabled for LDAP access or may need administrative access for this operation."
+        when 49
+          result[:suggestion] = "Invalid Credentials. Check your username and password."
+        when 50
+          result[:suggestion] = "Insufficient Access Rights. Your account may need LDAP access enabled."
+        when 4
+          result[:suggestion] = "Size Limit Exceeded. Try a more specific search base or ensure filters are indexed."
+        end
       end
-    get_ldap_response(ldap)
+
+    rescue OpenSSL::SSL::SSLError => e
+      # Certificate or SSL/TLS connection error
+      result.merge!(
+        success: false,
+        error: "SSL/TLS Error: #{e.message}",
+        exception: e.class.name,
+        suggestion: "Certificate verification failed. Most systems trust InCommon certificates. If needed, download USERTrust RSA Certification Authority root certificate from ITS: SSL Server Certificates"
+      )
+    rescue => e
+      result.merge!(
+        success: false,
+        error: e.message,
+        exception: e.class.name
+      )
+    end
+
+    result
   end
 
-  # GET THE PRIMARY DEPARTMENT FOR A SINGLE USER
-  def self.get_dept(uniqname = nil)
-    ldap = ldap_connection
-    search_param = uniqname # the AD account goes here
-    result_attrs = [dept_attribute] # Whatever you want to bring back in your result set goes here
-    # Build filter
-    search_filter = Net::LDAP::Filter.eq("uid", search_param)
-    # Execute search
-    ldap.search(filter: search_filter, attributes: result_attrs) { |item|
-      return dept_name = item.umichpostaladdressdata.first.split("}:{").first.split("=")[1] unless item.umichpostaladdressdata.first.nil?
+  def self.ldap_connection
+    connection_params = {
+      host: host,
+      port: port.to_i,
+      base: base
     }
-    get_ldap_response(ldap)
+
+    # Configure encryption - REQUIRED for authenticated binds per UM documentation
+    # UM requires secure connection: TLS on port 389 (STARTTLS) or SSL on port 636 (LDAPS)
+    # Most operating systems already trust InCommon certificates per UM documentation
+    tls_verify = ENV.fetch('LDAP_TLS_VERIFY', 'true').to_s.downcase != 'false'
+    tls_options = {
+      verify_mode: tls_verify ? OpenSSL::SSL::VERIFY_PEER : OpenSSL::SSL::VERIFY_NONE
+    }
+    ca_cert_path = ENV['LDAP_CA_CERT']
+    tls_options[:ca_file] = ca_cert_path if ca_cert_path && !ca_cert_path.to_s.strip.empty?
+
+    if encryption == :start_tls
+      connection_params[:encryption] = {
+        method: :start_tls,
+        tls_options: tls_options
+      }
+    elsif encryption == :simple_tls
+      connection_params[:encryption] = {
+        method: :simple_tls,
+        tls_options: tls_options
+      }
+    end
+
+    # Configure authenticated bind (if username/password provided)
+    # Note: "simple" bind method = authenticated bind with username/password (not anonymous)
+    auth_username = username.to_s.strip
+    auth_password = password.to_s
+    if !auth_username.empty? && !auth_password.empty?
+      # Use custom bind_dn if provided (for service accounts), otherwise build standard DN
+      auth_bind_dn = bind_dn || "uid=#{auth_username},ou=People,#{base}"
+      connection_params[:auth] = {
+        method: :simple,  # Simple bind = authenticated bind with username/password
+        username: auth_bind_dn,
+        password: auth_password
+      }
+    end
+
+    ldap = Net::LDAP.new(connection_params)
+
+    # For STARTTLS, ensure TLS is started before returning connection
+    # Net::LDAP should handle this automatically, but let's be explicit
+    if encryption == :start_tls
+      begin
+        # The bind will trigger STARTTLS automatically, but we can verify connection works
+        # by attempting a bind (which will fail if TLS isn't established)
+      rescue => e
+        raise "Failed to establish TLS connection: #{e.message}"
+      end
+    end
+
+    ldap
   end
 
-  # GET THE E-MAIL ADDRESS FOR A SINGLE USER
-  def self.get_email(uniqname = nil)
+  def self.get_user_attribute(uniqname, attribute, default_value = nil)
     ldap = ldap_connection
-    search_param = uniqname # the AD account goes here
-    result_attrs = ["mail"] # Whatever you want to bring back in your result set goes here
-    # Build filter
-    search_filter = Net::LDAP::Filter.eq("uid", search_param)
-    # Execute search
-    ldap.search(filter: search_filter, attributes: result_attrs) { |item|
-      return item.mail.first
-    }
-    get_ldap_response(ldap)
+    search_param = uniqname
+    result_attrs = [attribute]
+    found_value = nil
+
+    search_filter = Net::LDAP::Filter.eq('uid', search_param)
+
+    perform_search(
+      ldap,
+      filter: search_filter,
+      attributes: result_attrs,
+      label: "get_user_attribute",
+      options: { size: 1 }
+    ).each do |item|
+      value = item[attribute]&.first
+      if value
+        found_value = value
+        break
+      end
+    end
+
+    # Check response - Code 19 may occur even when data is found
+    response = ldap.get_operation_result
+    if (response.code == 19 || response.code == 4) && found_value.nil?
+      # Constraint violation and no data found - may need admin access
+      return default_value
+    elsif response.code != 0 && found_value.nil?
+      # Other error and no data found
+      raise "Response Code: #{response.code}, Message: #{response.message}"
+    end
+
+    # Return found value or default
+    found_value || default_value
   end
 
-  # ---------------------------------------------------------------------------------------------------------------------
-  # Check if the UID is a member of an LDAP group. This function returns TRUE
-  # if uid passed in is a member of group_name passed in. Otherwise it will
-  # return false.
-  def self.is_member_of_group?(uid = nil, group_name = nil)
+  def self.get_nested_attribute(uniqname, nested_attribute)
     ldap = ldap_connection
-    # GET THE MEMBERS OF AN E-MAIL DISTRIBUTION LIST
-    search_param = group_name # the name of the distribution list you're looking for goes here
-    result_attrs = ["member"]
-    # Build filter
-    search_filter = Net::LDAP::Filter.eq("cn", search_param)
-    group_filter = Net::LDAP::Filter.eq("objectClass", "group")
-    composite_filter = Net::LDAP::Filter.join(search_filter, group_filter)
-    # Execute search, extracting the AD account name from each member of the distribution list
-    ldap.search(filter: composite_filter, attributes: result_attrs) do |item|
-      if item.attribute_names.include?(:member)
-        item.member.each do |entry|
-          if entry.split(",").first.split("=")[1] == uid
-            return true
+    search_param = uniqname
+    # Specify the full nested attribute path using dot notation
+    attr_name = nested_attribute.split('.').first
+    # Try using the configured attribute name if available, otherwise use the provided name
+    search_attr = dept_attribute || attr_name
+    result_attrs = [search_attr]
+    found_value = nil
+
+    search_filter = Net::LDAP::Filter.eq('uid', search_param)
+
+    perform_search(
+      ldap,
+      filter: search_filter,
+      attributes: result_attrs,
+      label: "get_nested_attribute",
+      options: { size: 1 }
+    ).each do |item|
+      # Net::LDAP::Entry provides case-insensitive access, try the search attribute first
+      string1 = item[search_attr]&.first || item[attr_name]&.first
+      if string1
+        key_value_pairs = string1.split('}:{')
+        # Find the key-value pair for the nested attribute
+        target_pair = key_value_pairs.find { |pair| pair.include?("#{nested_attribute.split('.').last}=") }
+        # Extract the target value
+        if target_pair
+          target_pair_value = target_pair.split('=').last
+          if target_pair_value
+            found_value = target_pair_value
+            break
           end
         end
       end
     end
-    return false
-    get_ldap_response(ldap)
+
+    # Check response - Code 19 may occur even when data is found
+    response = ldap.get_operation_result
+    if (response.code == 19 || response.code == 4) && found_value.nil?
+      # Constraint violation and no data found - may need admin access
+      return nil
+    elsif response.code != 0 && found_value.nil?
+      # Other error and no data found
+      raise "Response Code: #{response.code}, Message: #{response.message}"
+    end
+
+    found_value
   end
 
-  # ---------------------------------------------------------------------------------------------------------------------
-  # Get the Name email and members of an LDAP group as a hash
-  def self.get_email_distribution_list(group_name = nil)
+  # method to check if a uid exist in LDAP
+  def self.uid_exist?(uniqname)
     ldap = ldap_connection
-    result_hash = {}
-    member_hash = {}
-    # GET THE MEMBERS OF AN E-MAIL DISTRIBUTION LIST
-    search_param = group_name # the name of the distribution list you're looking for goes here
-    result_attrs = ["cn", group_attribute, "member"]
-    # Build filter
-    search_filter = Net::LDAP::Filter.eq("cn", search_param)
-    group_filter = Net::LDAP::Filter.eq("objectClass", "group")
-    composite_filter = Net::LDAP::Filter.join(search_filter, group_filter)
-    # Execute search, extracting the AD account name from each member of the distribution list
-    ldap.search(filter: composite_filter, attributes: result_attrs) do |item|
-      result_hash["group_name"] = item.cn.first
-      result_hash["group_email"] = item.umichGroupEmail.first
-      individual_array = []
-      item.member.each do |individual|
-        individual_array.push(individual.split(",").first.split("=")[1])
+    search_param = uniqname
+    found = false
+
+    search_filter = Net::LDAP::Filter.eq('uid', search_param)
+
+    perform_search(ldap, filter: search_filter, label: "uid_exist", options: { size: 1 }).each do |item|
+      if item['uid'].first == search_param
+        found = true
+        break
+      end
+    end
+
+    # Check response - Code 19 may occur even when user is found
+    response = ldap.get_operation_result
+    if (response.code == 19 || response.code == 4) && !found
+      # Constraint violation and user not found - may need admin access
+      return false
+    elsif response.code != 0 && !found
+      # Other error and user not found
+      raise "Response Code: #{response.code}, Message: #{response.message}"
+    end
+
+    found
+  end
+
+  def self.get_simple_name(uniqname)
+    get_user_attribute(uniqname, 'displayname', 'not available')
+  end
+
+  def self.get_email(uniqname)
+    get_user_attribute(uniqname, 'mail', nil)
+  end
+
+  def self.get_dept(uniqname)
+    dept = get_nested_attribute(uniqname, 'umichpostaladdressdata.addr1')
+    return dept if dept
+
+    # Fallback to raw attribute if nested parsing fails or attribute is restricted
+    raw_attr = dept_attribute || 'umichPostalAddressData'
+    get_user_attribute(uniqname, raw_attr, nil)
+  end
+
+  def self.is_member_of_group?(uid, group_name)
+    ldap = ldap_connection
+    search_param = group_name
+    result_attrs = ['member']
+    found = false
+
+    search_filter = Net::LDAP::Filter.join(
+      Net::LDAP::Filter.eq('cn', search_param),
+      Net::LDAP::Filter.eq('objectClass', 'group')
+    )
+
+    perform_search(ldap, filter: search_filter, attributes: result_attrs, label: "is_member_of_group").each do |item|
+      members = item['member']
+      if members && members.any? { |entry| entry.split(',').first.split('=')[1] == uid }
+        found = true
+        break
       end
-      result_hash["members"] = individual_array.sort
     end
-    return result_hash
-    get_ldap_response(ldap)
+
+    # Check response - Code 19 may occur for group operations (requires admin access)
+    response = ldap.get_operation_result
+    if response.code == 19
+      # Constraint violation - group operations may require admin access
+      # Return false if not found, true if found (even with Code 19)
+      return found
+    elsif response.code != 0 && !found
+      # Other error and not found
+      raise "Response Code: #{response.code}, Message: #{response.message}"
+    end
+
+    found
   end
 
-  # ---------------------------------------------------------------------------
-  #  Get the groups a user is a member of
-  def self.all_groups_for_user(uid = nil)
+  def self.get_email_distribution_list(group_name)
+    ldap = ldap_connection
+    result_hash = {}
+    found_data = false
+
+    search_param = group_name
+    result_attrs = %w[cn umichGroupEmail member]
+
+    search_filter = Net::LDAP::Filter.join(
+      Net::LDAP::Filter.eq('cn', search_param),
+      Net::LDAP::Filter.eq('objectClass', 'group')
+    )
+
+    perform_search(ldap, filter: search_filter, attributes: result_attrs, label: "get_email_distribution_list").each do |item|
+      found_data = true
+      result_hash['group_name'] = item['cn']&.first
+      result_hash['group_email'] = item['umichGroupEmail']&.first
+      members = item['member']&.map { |individual| individual.split(',').first.split('=')[1] }
+      result_hash['members'] = members&.sort || []
+    end
+
+    # Check response - Code 19 may occur for group operations (requires admin access)
+    response = ldap.get_operation_result
+    if response.code == 19 && !found_data
+      # Constraint violation and no data found - group operations may require admin access
+      return {}
+    elsif response.code != 0 && !found_data
+      # Other error and no data found
+      raise "Response Code: #{response.code}, Message: #{response.message}"
+    end
+
+    result_hash
+  end
+
+  def self.all_groups_for_user(uid)
     ldap = ldap_connection
     result_array = []
-    result_attrs = ["dn"]
-    ldap.search(filter: "member=uid=#{uid},ou=People,dc=umich,dc=edu", attributes: result_attrs) do |item|
-      item.each { |key, value| result_array << value.first.split("=")[1].split(",")[0] }
+
+    result_attrs = ['dn']
+
+    # Use configured base instead of hardcoded dc=umich,dc=edu
+    member_dn = "uid=#{uid},ou=People,#{base}"
+    perform_search(ldap, filter: "member=#{member_dn}", attributes: result_attrs, label: "all_groups_for_user").each do |item|
+      item.each { |key, value| result_array << value.first.split('=')[1].split(',')[0] }
     end
-    return result_array.sort
-    get_ldap_response(ldap)
+
+    # Check response - may raise Constraint Violation for regular users
+    response = ldap.get_operation_result
+    if response.code == 19  # Constraint Violation
+      # Regular authenticated users may not have permission to search groups by member
+      # Return empty array instead of raising error
+      return []
+    elsif response.code != 0
+      raise "Response Code: #{response.code}, Message: #{response.message}"
+    end
+
+    result_array.sort
   end
 end