ldap_query 0.0.1

data/Rakefile

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[test rubocop]

data/bin/console

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "ldap_query"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/ldap_query.gemspec

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+lib = File.expand_path('lib', __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'ldap_query/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'ldap_query'
+  spec.version       = LdapQuery::VERSION
+  spec.authors       = ['Brandon Hicks']
+  spec.email         = ['tarellel@gmail.com']
+
+  spec.summary       = 'To easily connect and query ldap'
+  spec.description   = 'Easily generate LDAP connections and queries without having to learn how to build an LDAP connection with ruby.'
+  spec.homepage      = "https://github.com/tarellel/ldap_query"
+  spec.license       = 'MIT'
+  spec.required_ruby_version = Gem::Requirement.new('>= 2.4.0')
+
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['source_code_uri'] = spec.homepage
+  spec.metadata['changelog_uri'] = "#{spec.homepage}/blob/master/CHANGELOG.md"
+
+  # spec.files         = Dir.glob('lib/**/*')
+  spec.files = `git ls-files | grep -Ev '^(test|myapp|examples)'`.split("\n")
+  spec.bindir        = 'exe'
+  spec.executables   = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  spec.add_dependency('activesupport', '>= 5.0')
+  spec.add_dependency('net-ldap', '~> 0.16')
+  spec.add_development_dependency('bundler', '>= 1.17', '< 3.0')
+  spec.add_development_dependency('rake', '~> 13')
+  spec.add_development_dependency('rspec', '~> 3.9')
+end

data/lib/ldap_query.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require_relative 'ldap_query/version'
+require 'active_support'
+require 'active_support/core_ext/object/blank' # Used so methods like .blank? will be available
+require_relative 'ldap_query/ldap_query'
+require_relative 'ldap_query/authenticate'
+require_relative 'ldap_query/config'
+require_relative 'ldap_query/connection'
+require_relative 'ldap_query/error'
+require_relative 'ldap_query/filter'
+require_relative 'ldap_query/ldap_helper'
+require_relative 'ldap_query/rails_credentials'
+require_relative 'ldap_query/query'
+
+require_relative 'ldap_query/railtie' if defined?(::Rails) || defined?(Rails)

data/lib/ldap_query/authenticate.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module LdapQuery
+  # Used to authenticate a users LDAP credentials to a user in LDAP
+  class Authenticate
+    attr_accessor :config, :connection
+
+    REQUIRED_CONNECTION_KEYS = %i[host username password base].freeze
+
+    # Initialzile an ldap connection for authenticating a user
+    #
+    # @params credentials [Hash]
+    def initialize(credentials = {})
+      establish_connection(credentials)
+    end
+
+    # Authenticate the user again ldap with the supplied username/password
+    #
+    # @param username [String]
+    # @param password [String]
+    # @return [Boolean, Hash, Net::Ldap]
+    def auth_user(username, password)
+      return false if username.nil? || password.nil?
+
+      response = @connection.link.bind_as(base: @config.base,
+                                          size: 1,
+                                          filter: LdapQuery::Filter.auth(username),
+                                          password: password)
+      # if no user was found return false, otherwise return the user
+      (response && response[0]) ? response : false
+    end
+
+    private
+
+    # Establish an ldap connection without fulling binding a connection yet
+    #
+    # @params credentials [Hash]
+    def establish_connection(credentials = {})
+      raise_keys_error if credentials.blank? || !required_credentials_supplied?(credentials)
+
+      @config = LdapQuery::Config.new(credentials)
+      @connection = LdapQuery::Connection.new(@config.auth_hash, type: :auth)
+      @connection.link.auth(@config.username, @config.password)
+    rescue
+      raise(ConnectionError, 'Failure connecting to LDAP host')
+    end
+
+    # Verify if the required encryption keys have been supplied
+    #
+    # @return [Boolean]
+    def required_credentials_supplied?(credentials = {})
+      # Verify all reqiured credentail values have been supplied for the LDAP connection
+      REQUIRED_CONNECTION_KEYS.all? { |req_key| credentials.key?(req_key) }
+    end
+
+    # Raise an exception if any of the credentials are missing any key/value for authenticating a user
+    def raise_keys_error
+      raise(CredentialsError, "The following credentials attributes are required: #{REQUIRED_CONNECTION_KEYS}")
+    end
+  end
+end

data/lib/ldap_query/config.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+require 'active_support/core_ext/hash'
+
+module LdapQuery
+  # Used to validate and filter credentials for establishing an LDAP connection
+  class Config
+    DEFAULT_CONFIG = { port: 389,       # Usually 389 && 636
+                       encryption: nil,
+                       base: nil,       # 'dc=company,dc=tld'
+                       username: nil,
+                       password: nil,
+                       method: :simple }.freeze
+    ALLOWED_KEYS = %i[base encryption host method port username password].freeze
+    ALLOWED_KEYS.each { |attr| attr_accessor attr }
+
+    # Required to be assigned and not have nil valuess
+    REQUIRED_KEYS = %i[base username password host port].freeze
+
+    # Attributes whos values are required to by symbols for the LDAP gem
+    VALS_REQUIRED_TO_BE_SYMBOLS = %i[encryption method].freeze
+
+    # Build and validate the configuration hash supplied for creating an LDAP connection
+    #
+    # @param config [Hash]
+    # @return [Hash]
+    def initialize(config = {})
+      raise(ArgumentError, "the following attributes are required for an ldap connection #{REQUIRED_KEYS}") unless config.is_a?(Hash) && !config.blank?
+
+      map_variables(validate_keys(cleanup_hash(defaults(config))))
+    end
+
+    # Build a hash out of the provided config to establish an LDAP connection
+    #
+    # @return [Hash]
+    def hash
+      @hash ||= { host: @host, port: @port, base: @base, encryption: @encryption }.merge(credentials_hash).freeze
+    end
+
+    # Build a hash of required config for authenticating a user against ldap
+    #
+    # @return [Hash]
+    def auth_hash
+      @auth_hash ||= { host: @host, port: @port, encryption: @encryption }.freeze
+    end
+
+    private
+
+    # Build a hash with the connections username, password, and method for the LDAP connection
+    #
+    # @return [Hash]
+    def credentials_hash
+      raise(ConfigError, 'config username or password are nil') unless @username && @password
+
+      credentials_hash = { username: @username, password: @password }.freeze
+      credentials_hash = credentials_hash.merge({ method: @method }) if @method
+      { auth: credentials_hash }.freeze
+    end
+
+    # Associate all the config hash key/values as instance variables for easy reference
+    #
+    # @param config_hash [Hash]
+    def map_variables(config_hash = {})
+      ALLOWED_KEYS.each do |attr|
+        instance_variable_set("@#{attr}", config_hash[attr])
+      end
+    end
+
+    # Set default keys/values if not supplied in the config hash
+    #
+    # @param config [Hash]
+    # @return [Hash]
+    def defaults(config = {})
+      config.reverse_merge(DEFAULT_CONFIG).freeze
+    end
+
+    # Loop through the supplied config hash, make all keys unique and symbolzied, and symbolize the specified values
+    #
+    # @param config_hash [Hash]
+    # @return [Hash]
+    def cleanup_hash(config_hash = {})
+      # ensure keys like :key and 'key' are considered the same
+      # this is similar to running .uniq on an array
+      config_hash.with_indifferent_access.symbolize_keys.tap do |config|
+        VALS_REQUIRED_TO_BE_SYMBOLS.each do |key|
+          config[key] = config[key].to_sym if config[key]
+        end
+      end
+    end
+
+    # Validate all required keys have been included
+    #
+    # @param config_hash [Hash]
+    # @return [Boolean]
+    def required_keys_included?(config_hash = {})
+      REQUIRED_KEYS.all? do |key|
+        raise(ConfigError, "config key #{key} is required to be set.") unless config_hash.key?(key)
+      end
+    end
+
+    # Ensure that a handful of parameters have actual values and not just nil or ''
+    #
+    # @param config_hash [Hash]
+    # @return [Boolean]
+    def required_vals_given?(config_hash)
+      raise(ConfigError, "required config values (#{REQUIRED_KEYS}) can not be nil") unless REQUIRED_KEYS.all? { |k| !config_hash[k].nil? }
+    end
+
+    # Filter out and remove unneeded configuration hash keys
+    #
+    # @param config_hash [Hash]
+    # @return [Hash]
+    def remove_unknown_keys(config_hash)
+      config_hash.select { |key, _v| ALLOWED_KEYS.include?(key) }.freeze
+    end
+
+    # Validate and cleanup all supplied configuration key/values
+    #
+    # @param config_hash [Hash]
+    def validate_keys(config_hash = {})
+      required_keys_included?(config_hash)
+      required_vals_given?(config_hash)
+      remove_unknown_keys(config_hash)
+    end
+  end
+end

data/lib/ldap_query/connection.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require 'net/ldap'
+
+module LdapQuery
+  # For establishing an LDAP connection (binding LDAP connection)
+  class Connection
+    attr_accessor :link
+
+    REQUIRED_KEYS = %i[host port base auth].freeze
+
+    # Used for creating the initial Ldap connection for querying with supplied parameters
+    #
+    # @param credentials [Hash]
+    # @return [Interface <Net::Ldap>]
+    def initialize(credentials, type: :basic)
+      if type == :auth
+        credentials = filter_auth_credentials(credentials)
+      else
+        valid_credentials?(credentials)
+      end
+      @link = bind_connection(credentials)
+    end
+
+    private
+
+    # Filter out all parameter keyus/values and only keep the required auth keys
+    #
+    # @param credentials [Hash]
+    # @return [Hash]
+    def filter_auth_credentials(credentials)
+      auth_keys = %i[host port encryption].freeze
+      credentials.select { |key, _v| auth_keys.include?(key) }.freeze
+    end
+
+    # Validate all required keys have been included
+    #
+    # @param credentials [Hash]
+    # @return [Hash]
+    def valid_credentials?(credentials)
+      credentials_error if !credentials.is_a?(Hash) || credentials.empty?
+      required_credentials?(credentials)
+    end
+
+    # Validate all required auth credentials have been supplied
+    #
+    # @param credentials [Hash]
+    # @return [Hash]
+    def required_credentials?(credentials = {})
+      credentials_error unless REQUIRED_KEYS.all? { |k| credentials[k] }
+    end
+
+    # Raise an exception error if not all LDAP credentials have been included
+    def credentials_error
+      raise(CredentialsError, 'valid ldap credentials must be passed in order to establish a connection')
+    end
+
+    # Create LDAP connection string
+    #
+    # @params credentials [Hash]
+    # @return [Interface <Net::Ldap>]
+    def bind_connection(credentials)
+      Net::LDAP.new(credentials)
+    rescue
+      raise(ConnectionError, 'Failure connecting to LDAP host')
+    end
+  end
+end

data/lib/ldap_query/error.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+# Used for creating exceptions with the Ldap connections and configuration
+module LdapQuery
+  class Error < StandardError; end
+
+  class AttributeError < Error; end
+  class ConnectionError < Error; end
+  class CredentialsError < Error; end
+  class ConfigError < Error; end
+end

data/lib/ldap_query/filter.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require 'net-ldap'
+
+module LdapQuery
+  # Used to create return LDAP query stings depending on what attribute you want to filter
+  class Filter
+    # Used to create an LDAP filter for the specified LDAP attribute
+    #
+    # @param str [String]
+    # @attr wildcard [Boolean] used to determine if the filter should be wildcard match
+    # @example:
+    #   LdapQuery::Filter.cn('mscott')
+    # @example:
+    #   LdapQuery::Filter.memberof('CN=somegroup,OU=OrganizationalUnit,DC=company.tld)
+    %w[cn displayname mail memberof samaccountname].each do |attr|
+      define_singleton_method(attr) do |str, wildcard: false|
+        Net::LDAP::Filter.eq(attr, clean_str(str, wildcard: wildcard))
+      end
+    end
+
+    # Generally most ldap queries are again person, sometimes other types will be used for service accounts
+    #
+    # @param str [String]
+    # @attr wildcard [Boolean] used to determine if the filter should be wildcard match
+    def self.object_class(str = 'person', wildcard: false)
+      Net::LDAP::Filter.eq('objectClass', clean_str(str, wildcard: wildcard))
+    end
+
+    # Used to filter LDAP accounts against a custom attribute and valuess
+    #
+    # @param attr [String] a custom attribute to query again
+    # @param val [String] a user specified value to filter against
+    # @attr wildcard [Boolean] used to determine if the filter should be wildcard match
+    def self.other(attr, val, wildcard: false)
+      Net::LDAP::Filter.eq(attr, clean_str(val, wildcard: wildcard))
+    end
+
+    # Filter user based on CN attribute (CN is a required attribute)
+    #
+    # @param username [String]
+    # @attr wildcard [Boolean] used to determine if the filter should be wildcard match
+    def self.person(username, wildcard: false)
+      cn_filter = LdapQuery::Filter.cn(username, wildcard: wildcard)
+      user_filter = LdapQuery::Filter.object_class
+      Net::LDAP::Filter.join(cn_filter, user_filter)
+    end
+
+    # Filter used to authenticate a validate CN & Person entry
+    #
+    # @param username [String]
+    def self.auth(username)
+      Net::LDAP::Filter.join(cn(username), object_class)
+    end
+
+    # If you want to wildcard it this turns all spaces into '*' and adds '*' at the beginning and end of the str as well
+    #
+    # @param str [String] the query str
+    # @attr wildcard [Boolean] used to determine if the filter should be wildcard match
+    # @return [String] either the original str, or a value prepared to wildcard when hitting ldap
+    def self.clean_str(str, wildcard: false)
+      str = str&.strip
+      return str unless wildcard && str.is_a?(String)
+
+      str = str.split(/\s/).compact.join('*').squeeze('*')
+      "*#{str}*"
+    end
+  end
+end

data/lib/ldap_query/ldap_helper.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module LdapQuery
+  # Methods to be included as helpers in the rails application
+  module LdapHelper
+    def self.included(base); end
+    def self.extended(base); end
+
+    # Search ldap based on users samaccountname attribute
+    #
+    # @param str [String] the attributes string value you want to query against
+    # @param credentials [Hash]
+    def search_ldap_by_username(str, credentials = {}, wildcard: false, limit: 20)
+      credentials = determine_credentials(credentials)
+      LdapQuery::Query.perform(credentials, attr: :cn, val: str, wildcard: wildcard, limit: limit)
+    end
+
+    # Query LDAP based on all users displayname attribute
+    #
+    # @param str [String] the attributes string value you want to query against
+    # @params wildcard [Boolean] used to determine if the filter should be wildcard match
+    def search_ldap_by_name(str, credentials = {}, wildcard: false, limit: 20)
+      credentials = determine_credentials(credentials)
+      LdapQuery::Query.perform(credentials, attr: :displayname, val: str, wildcard: wildcard, limit: limit)
+    end
+
+    # Query ldap based on memberof attribute
+    #
+    # @param str [String] the attributes string value you want to query against
+    # @param credentials [Hash]
+    # @params wildcard [Boolean] used to determine if the filter should be wildcard match
+    def search_ldap_by_group(str, credentials = {}, wildcard: false, limit: 20)
+      credentials = determine_credentials(credentials)
+      LdapQuery::Query.perform(credentials, attr: :memberof, val: str, wildcard: wildcard, limit: limit)
+    end
+
+    # Query LDAP against a custome attribute and value
+    #
+    # @param credentials [Hash]
+    # @params attr [String, Symbol] to attribute you want to query against
+    # @params val [String, Symbol] the attribute vale you want to query with when filtering against ldap results
+    # @params wildcard [Boolean] used to determine if the filter should be wildcard match
+    def search_ldap_by_other(credentials = {}, attr: nil, val: nil, wildcard: false, limit: 20)
+      raise(AttributeError, 'a valid attribute name and value must be supplied to query against') if attr.nil? || val.nil?
+
+      credentials = determine_credentials(credentials)
+      LdapQuery::Query.perform(credentials, attr: attr, val: val, wildcard: wildcard, limit: limit)
+    end
+
+    # Query ldap based on mail attribute
+    #
+    # @param str [String] the attributes string value you want to query against
+    # @param credentials [Hash]
+    # @params wildcard [Boolean] used to determine if the filter should be wildcard match
+    def search_ldap_by_mail(str, credentials = {}, wildcard: false, limit: 20)
+      credentials = determine_credentials(credentials)
+      LdapQuery::Query.perform(credentials, attr: :mail, val: str, wildcard: wildcard, limit: limit)
+    end
+
+    # Used to authenticate a user against ldap
+    #
+    # @param credentials [Hash]
+    # @param username [String]
+    # @params password [String]
+    def authenticate_user(credentials, username: nil, password: '')
+      username, password = username.to_s, password.to_s
+      credentials = determine_credentials(credentials)
+      raise(AttributeError, 'an ldap username is required in order to authenticate.') if username.nil?
+
+      LdapQuery::Authenticate.new(credentials).auth_user(username, password)
+    end
+
+    private
+
+    # Determine if the helpers have had ldap credentials passed to it
+    #   If not, it will attempt to grab ldap credentials from the applications encrypted credentials
+    #
+    # @param credentials [Hash]
+    # @return [Hash]
+    def determine_credentials(credentials = {})
+      return credentials if credentials.is_a?(Hash) && !credentials.empty?
+
+      rails_credentials
+    end
+
+    # Grab the applications Rails.application.credentials[:ldap]
+    #
+    # @return [Hash]
+    def rails_credentials
+      @_rails_credentials ||= LdapQuery::RailsCredentials.credentials
+    end
+  end
+end