omniauth-ldap 2.3.1 → 2.3.3

data/lib/omniauth-ldap/adaptor.rb

@@ -10,12 +10,36 @@ require "sasl"
 
 module OmniAuth
   module LDAP
+    # Adaptor encapsulates the behavior required to connect to an LDAP server
+    # and perform searches and binds. It maps user-provided configuration into
+    # a Net::LDAP connection and provides compatibility helpers for different
+    # net-ldap and SASL versions. The adaptor is intentionally defensive and
+    # provides a small, stable API used by the OmniAuth strategy.
+    #
+    # @example Initialize with minimal config
+    #   adaptor = OmniAuth::LDAP::Adaptor.new(base: 'dc=example,dc=com', host: 'ldap.example.com')
+    #
+    # @note Public API: {validate}, {initialize}, {bind_as}, and attr readers such as {connection}, {uid}
     class Adaptor
+      # Generic adaptor error super-class
+      # @see Error classes that inherit from this class
       class LdapError < StandardError; end
+
+      # Raised when configuration is invalid
+      # @example
+      #   raise ConfigurationError, 'missing base'
       class ConfigurationError < StandardError; end
+
+      # Raised when authentication fails
       class AuthenticationError < StandardError; end
+
+      # Raised on connection-related failures
       class ConnectionError < StandardError; end
 
+      # Valid configuration keys accepted by the adaptor. These correspond to
+      # the options supported by the gem and are used during initialization.
+      #
+      # @return [Array<Symbol>]
       VALID_ADAPTER_CONFIGURATION_KEYS = [
         :hosts,
         :host,
@@ -31,6 +55,10 @@ module OmniAuth
         :allow_anonymous,
         :filter,
         :tls_options,
+        :password_policy,
+        # Timeouts
+        :connect_timeout,
+        :read_timeout,
 
         # Deprecated
         :method,
@@ -38,7 +66,9 @@ module OmniAuth
         :ssl_version,
       ]
 
-      # A list of needed keys. Possible alternatives are specified using sub-lists.
+      # Required configuration keys. This may include alternatives as sub-lists
+      # (e.g., [:hosts, :host] means either key is acceptable).
+      # @return [Array]
       MUST_HAVE_KEYS = [
         :base,
         [:encryption, :method], # :method is deprecated
@@ -47,6 +77,8 @@ module OmniAuth
         [:uid, :filter],
       ]
 
+      # Supported encryption method mapping for configuration readability.
+      # @return [Hash<Symbol,Symbol,nil>]
       ENCRYPTION_METHOD = {
         simple_tls: :simple_tls,
         start_tls: :start_tls,
@@ -58,9 +90,47 @@ module OmniAuth
         tls: :start_tls,
       }
 
+      # @!attribute [rw] bind_dn
+      #   The distinguished name used for binding when provided in configuration.
+      #   @return [String, nil]
+      # @!attribute [rw] password
+      #   The bind password (may be nil for anonymous binds)
+      #   @return [String, nil]
       attr_accessor :bind_dn, :password
-      attr_reader :connection, :uid, :base, :auth, :filter
 
+      # Read-only attributes exposing connection and configuration state.
+      # @!attribute [r] connection
+      #   The underlying Net::LDAP connection object.
+      #   @return [Net::LDAP]
+      # @!attribute [r] uid
+      #   The user id attribute used for lookups (e.g., 'sAMAccountName')
+      #   @return [String]
+      # @!attribute [r] base
+      #   The base DN for searches.
+      #   @return [String]
+      # @!attribute [r] auth
+      #   The final auth structure used by net-ldap.
+      #   @return [Hash]
+      # @!attribute [r] filter
+      #   Custom filter pattern when provided in configuration.
+      #   @return [String, nil]
+      # @!attribute [r] password_policy
+      #   Whether to request LDAP Password Policy controls.
+      #   @return [Boolean]
+      # @!attribute [r] last_operation_result
+      #   Last operation result object returned by the ldap library (if any)
+      #   @return [Object, nil]
+      # @!attribute [r] last_password_policy_response
+      #   Last extracted password policy response control (if any)
+      #   @return [Object, nil]
+      attr_reader :connection, :uid, :base, :auth, :filter, :password_policy, :last_operation_result, :last_password_policy_response
+
+      # Validate that a minimal configuration is present. Raises ArgumentError when required
+      # keys are missing. This is a convenience to provide early feedback to callers.
+      #
+      # @param configuration [Hash] configuration hash passed to the adaptor
+      # @raise [ArgumentError] when required keys are missing
+      # @return [void]
       def self.validate(configuration = {})
         message = []
         MUST_HAVE_KEYS.each do |names|
@@ -73,6 +143,15 @@ module OmniAuth
         raise ArgumentError.new(message.join(",") + " MUST be provided") unless message.empty?
       end
 
+      # Create a new adaptor instance backed by a Net::LDAP connection.
+      #
+      # The constructor does not immediately open a network connection but
+      # prepares the Net::LDAP instance according to the provided configuration.
+      # It also applies timeout settings where supported by the installed net-ldap version.
+      #
+      # @param configuration [Hash] user-provided configuration options
+      # @raise [ArgumentError, ConfigurationError] on invalid configuration
+      # @return [OmniAuth::LDAP::Adaptor]
       def initialize(configuration = {})
         Adaptor.validate(configuration)
         @configuration = configuration.dup
@@ -88,6 +167,8 @@ module OmniAuth
           port: @port,
           encryption: encryption_options,
         }
+        # Remove passing timeouts here to avoid issues on older net-ldap versions.
+        # We'll set them after initialization if the connection responds to writers.
         @bind_method = if @try_sasl
           :sasl
         else
@@ -102,27 +183,79 @@ module OmniAuth
         }
         config[:auth] = @auth
         @connection = Net::LDAP.new(config)
+        # Apply optional timeout settings if supported by the installed net-ldap version
+        if !@connect_timeout.nil?
+          if @connection.respond_to?(:connect_timeout=)
+            @connection.connect_timeout = @connect_timeout
+          else
+            @connection.instance_variable_set(:@connect_timeout, @connect_timeout)
+          end
+        end
+        if !@read_timeout.nil?
+          if @connection.respond_to?(:read_timeout=)
+            @connection.read_timeout = @read_timeout
+          else
+            @connection.instance_variable_set(:@read_timeout, @read_timeout)
+          end
+        end
       end
 
       #:base => "dc=yourcompany, dc=com",
       # :filter => "(mail=#{user})",
       # :password => psw
+      #
+      # Attempt to locate a user entry and bind as that entry using the supplied
+      # password. Returns the entry on success, or false/nil on failure.
+      #
+      # @param args [Hash] search and bind options forwarded to net-ldap's search
+      # @option args [Net::LDAP::Filter,String] :filter LDAP filter to use
+      # @option args [Integer] :size maximum number of results to fetch
+      # @option args [String,Proc] :password a password string or callable returning a password
+      # @return [Net::LDAP::Entry, false, nil] the found entry on successful bind, otherwise false/nil
+      # @raise [ConnectionError] if the underlying LDAP search fails
       def bind_as(args = {})
         result = false
+        @last_operation_result = nil
+        @last_password_policy_response = nil
         @connection.open do |me|
           rs = me.search(args)
-          if rs and rs.first and dn = rs.first.dn
-            password = args[:password]
-            method = args[:method] || @method
-            password = password.call if password.respond_to?(:call)
-            if method == "sasl"
-              result = rs.first if me.bind(sasl_auths({username: dn, password: password}).first)
-            elsif me.bind(
-              method: :simple,
-              username: dn,
-              password: password,
-            )
-              result = rs.first
+          raise ConnectionError.new("LDAP search operation failed") unless rs
+
+          if rs && rs.first
+            dn = rs.first.dn
+            if dn
+              password = args[:password]
+              password = password.call if password.respond_to?(:call)
+
+              bind_args = if @bind_method == :sasl
+                sasl_auths({username: dn, password: password}).first
+              else
+                {
+                  method: :simple,
+                  username: dn,
+                  password: password,
+                }
+              end
+
+              # Optionally request LDAP Password Policy control (RFC Draft - de facto standard)
+              if @password_policy
+                # Always request by OID using a simple hash; avoids depending on gem-specific control classes
+                control = {oid: "1.3.6.1.4.1.42.2.27.8.5.1", criticality: true, value: nil}
+                if bind_args.is_a?(Hash)
+                  bind_args = bind_args.merge({controls: [control]})
+                else
+                  # Some Net::LDAP versions allow passing a block for SASL only; ensure we still can add controls if hash
+                  # When not a Hash, we can't merge; rely on server default behavior.
+                end
+              end
+
+              begin
+                success = bind_args ? me.bind(bind_args) : me.bind
+              ensure
+                capture_password_policy(me)
+              end
+
+              result = rs.first if success
             end
           end
         end
@@ -131,6 +264,9 @@ module OmniAuth
 
       private
 
+      # Build encryption options for Net::LDAP given the configured method
+      #
+      # @return [Hash, nil] encryption options or nil for plain (no encryption)
       def encryption_options
         translated_method = translate_method
         return unless translated_method
@@ -141,6 +277,10 @@ module OmniAuth
         }
       end
 
+      # Normalize the user-provided encryption/method option and map to known values.
+      #
+      # @raise [ConfigurationError] when an unknown method is provided
+      # @return [Symbol, nil]
       def translate_method
         method = @encryption || @method
         method ||= "plain"
@@ -155,6 +295,10 @@ module OmniAuth
         ENCRYPTION_METHOD[normalized_method]
       end
 
+      # Build TLS options including backward-compatibility for deprecated keys.
+      #
+      # @param translated_method [Symbol] the normalized encryption method
+      # @return [Hash] a hash suitable for passing as :tls_options
       def tls_options(translated_method)
         return {} if translated_method.nil? # (plain)
 
@@ -175,6 +319,10 @@ module OmniAuth
         options
       end
 
+      # Build a list of SASL auth structures for each requested mechanism.
+      #
+      # @param options [Hash] options such as :username and :password
+      # @return [Array<Hash>] list of auth structures
       def sasl_auths(options = {})
         auths = []
         sasl_mechanisms = options[:sasl_mechanisms] || @sasl_mechanisms
@@ -193,6 +341,9 @@ module OmniAuth
         auths
       end
 
+      # Prepare SASL DIGEST-MD5 bind details
+      # @param options [Hash]
+      # @return [Array] initial_credential and a challenge response proc
       def sasl_bind_setup_digest_md5(options)
         bind_dn = options[:username]
         initial_credential = ""
@@ -205,6 +356,9 @@ module OmniAuth
         [initial_credential, challenge_response]
       end
 
+      # Prepare SASL GSS-SPNEGO bind details
+      # @param options [Hash]
+      # @return [Array] initial Type1 message and a nego proc
       def sasl_bind_setup_gss_spnego(options)
         bind_dn = options[:username]
         psw = options[:password]
@@ -220,8 +374,9 @@ module OmniAuth
         [Net::NTLM::Message::Type1.new.serialize, nego]
       end
 
-      private
-
+      # Default TLS/OpenSSL options used when not explicitly configured.
+      #
+      # @return [Hash]
       def default_options
         if @disable_verify_certificates
           # It is important to explicitly set verify_mode for two reasons:
@@ -238,6 +393,9 @@ module OmniAuth
       #
       # This gem may not always be in the context of Rails so we
       # do this rather than `.blank?`.
+      #
+      # @param hash [Hash]
+      # @return [Hash] sanitized hash with blank values removed
       def sanitize_hash_values(hash)
         hash.delete_if do |_, value|
           value.nil? ||
@@ -245,11 +403,47 @@ module OmniAuth
         end
       end
 
+      # Convert string keys to symbol keys for options hashes.
+      #
+      # @param hash [Hash]
+      # @return [Hash<Symbol, Object>]
       def symbolize_hash_keys(hash)
         hash.each_with_object({}) do |(key, value), result|
           result[key.to_sym] = value
         end
       end
+
+      # Capture the operation result and extract any Password Policy response control if present.
+      #
+      # This method is defensive: if the server or the installed net-ldap gem doesn't
+      # support controls, the method will swallow errors and leave policy fields nil.
+      #
+      # @param conn [Net::LDAP]
+      # @return [void]
+      def capture_password_policy(conn)
+        return unless @password_policy
+        return unless conn.respond_to?(:get_operation_result)
+
+        begin
+          @last_operation_result = conn.get_operation_result
+          controls = if @last_operation_result && @last_operation_result.respond_to?(:controls)
+            @last_operation_result.controls || []
+          else
+            []
+          end
+          if controls.any?
+            # Find Password Policy response control by OID
+            ppolicy_oid = "1.3.6.1.4.1.42.2.27.8.5.1"
+            ctrl = controls.find do |c|
+              (c.respond_to?(:oid) && c.oid == ppolicy_oid) || (c.is_a?(Hash) && c[:oid] == ppolicy_oid)
+            end
+            @last_password_policy_response = ctrl if ctrl
+          end
+        rescue StandardError
+          # Swallow errors to keep authentication flow unaffected when server or gem doesn't support controls
+          @last_password_policy_response = nil
+        end
+      end
     end
   end
 end

data/lib/omniauth-ldap/version.rb

@@ -1,8 +1,17 @@
 module OmniAuth
   module LDAP
+    # Version namespace for the omniauth-ldap gem
+    #
+    # This module contains the version constant used by rubygems and in code
+    # consumers. It intentionally exposes VERSION both inside the Version
+    # namespace and as OmniAuth::LDAP::VERSION for compatibility.
     module Version
-      VERSION = "2.3.1"
+      # Public semantic version for the gem
+      # @return [String]
+      VERSION = "2.3.3"
     end
+    # Convenience constant for consumers that expect OmniAuth::LDAP::VERSION
+    # @return [String]
     VERSION = Version::VERSION # Make VERSION available in traditional way
   end
 end

data/lib/omniauth-ldap.rb

@@ -1,3 +1,11 @@
+# Integrate the VersionGem helper into the OmniAuth::LDAP::Version module
+# to expose common version-related helper methods. This file is the public
+# entry point required by consumers of the gem.
+#
+# @example
+#   require 'omniauth-ldap'
+#   OmniAuth::LDAP::VERSION # => "2.3.2"
+
 require "version_gem"
 
 require "omniauth-ldap/version"

data/sig/omniauth/ldap/adaptor.rbs

@@ -15,7 +15,7 @@ module OmniAuth
 
       VALID_ADAPTER_CONFIGURATION_KEYS: Array[Symbol]
       MUST_HAVE_KEYS: Array[untyped]
-      METHOD: Hash[Symbol, Symbol?]
+      ENCRYPTION_METHOD: Hash[Symbol, Symbol?]
 
       attr_accessor bind_dn: String?
       attr_accessor password: String?
@@ -28,6 +28,10 @@ module OmniAuth
       attr_reader auth: Hash[Symbol, untyped]
       # filter is an LDAP filter string when configured
       attr_reader filter: String?
+      # optional: request password policy control and capture response
+      attr_reader password_policy: bool?
+      attr_reader last_operation_result: untyped
+      attr_reader last_password_policy_response: untyped
 
       # Validate that required keys exist in the configuration
       def self.validate: (?Hash[Symbol, untyped]) -> void
@@ -38,17 +42,31 @@ module OmniAuth
 
       private
 
-      # Returns a Net::LDAP encryption symbol (e.g. :simple_tls, :start_tls) or nil
-      def ensure_method: (untyped) -> Symbol?
+      # Returns encryption settings hash or nil
+      def encryption_options: () -> Hash[Symbol, untyped]?
+      # Translate configured method/encryption into Net::LDAP symbol
+      def translate_method: () -> Symbol?
+      # Returns a Net::LDAP encryption default options hash
+      def default_options: () -> Hash[Symbol, untyped]
+      # Sanitize provided TLS options
+      def sanitize_hash_values: (Hash[untyped, untyped]) -> Hash[untyped, untyped]
+      # Symbolize option keys
+      def symbolize_hash_keys: (Hash[untyped, untyped]) -> Hash[Symbol, untyped]
+      # Capture password policy control from last operation
+      def capture_password_policy: (Net::LDAP) -> void
 
       # Returns an array of SASL auth hashes
       def sasl_auths: (?Hash[Symbol, untyped]) -> Array[Hash[Symbol, untyped]]
 
-      # Returns initial credential (string) and a proc that accepts a challenge and returns the response
-      # Use Array[untyped] here to avoid tuple syntax issues in some linters; the runtime value
-      # is commonly a two-element array [initial_credential, proc].
+      # Returns initial credential and a proc that accepts a challenge and returns the response
       def sasl_bind_setup_digest_md5: (?Hash[Symbol, untyped]) -> Array[untyped]
       def sasl_bind_setup_gss_spnego: (?Hash[Symbol, untyped]) -> Array[untyped]
+
+      @try_sasl: bool?
+      @allow_anonymous: bool?
+      @tls_options: Hash[untyped, untyped]?
+      @sasl_mechanisms: Array[String]?
+      @disable_verify_certificates: bool?
     end
   end
 end

data/sig/omniauth/strategies/ldap.rbs

@@ -3,9 +3,6 @@ module OmniAuth
     class LDAP
       OMNIAUTH_GTE_V2: bool
 
-      # CONFIG is a read-only mapping of string keys to mapping definitions
-      CONFIG: Hash[String, untyped]
-
       # The request_phase either returns a Rack-compatible response or the form response.
       def request_phase: () -> (Rack::Response | Array[untyped] | String)
 
@@ -27,6 +24,12 @@ module OmniAuth
 
       # Perform a directory lookup for a given username; returns an Entry or nil
       def directory_lookup: (OmniAuth::LDAP::Adaptor, String) -> untyped
+
+      def uid: () { () -> String } -> void
+
+      def info: () { () -> Hash[untyped, untyped] } -> void
+
+      def extra: () { () -> Hash[Symbol, untyped] } -> void
     end
   end
 end

data/sig/omniauth-ldap.rbs

@@ -3,3 +3,8 @@
 # - sig/omniauth/ldap/adaptor.rbs
 # - sig/omniauth/strategies/ldap.rbs
 # This file is intentionally minimal to avoid duplicating declarations.
+
+module OmniAuth
+  module LDAP
+  end
+end

data/sig/rbs/net-ldap.rbs

@@ -5,6 +5,7 @@ module Net
     def open: () { (self) -> untyped } -> untyped
     def search: (?Hash[Symbol, untyped]) -> Array[Net::LDAP::Entry]
     def bind: (?Hash[Symbol, untyped]) -> bool
+    def get_operation_result: () -> Net::LDAP::PDU
   end
 
   class LDAP::Entry
@@ -15,5 +16,20 @@ module Net
     def self.construct: (String) -> Net::LDAP::Filter
     def self.eq: (String, String) -> Net::LDAP::Filter
   end
-end
 
+  class LDAP::Control
+    def initialize: (String, bool, untyped) -> void
+    def oid: () -> String
+  end
+
+  module LDAP::Controls
+    class PasswordPolicy
+      def initialize: () -> void
+      def oid: () -> String
+    end
+  end
+
+  class LDAP::PDU
+    def controls: () -> Array[untyped]
+  end
+end

data/sig/rbs/net-ntlm.rbs

@@ -4,6 +4,8 @@ module Net
     class Message
       def self.parse: (untyped) -> Net::NTLM::Message
       def response: (?Hash[Symbol, untyped], ?Hash[Symbol, untyped]) -> Net::NTLM::Message
+      # writer used by adaptor to set target name when a domain is present
+      def target_name=: (String) -> String
     end
 
     class Message::Type1
@@ -13,4 +15,3 @@ module Net
     def self.encode_utf16le: (String) -> String
   end
 end
-

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: omniauth-ldap
 version: !ruby/object:Gem::Version
-  version: 2.3.1
+  version: 2.3.3
 platform: ruby
 authors:
 - Peter Boling
@@ -65,7 +65,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '1'
+        version: '1.2'
     - - "<"
       - !ruby/object:Gem::Version
         version: '3'
@@ -75,7 +75,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '1'
+        version: '1.2'
     - - "<"
       - !ruby/object:Gem::Version
         version: '3'
@@ -337,34 +337,6 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 1.0.3
-- !ruby/object:Gem::Dependency
-  name: vcr
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '4'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '4'
-- !ruby/object:Gem::Dependency
-  name: webmock
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '3'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '3'
 description: "\U0001F4C1 LDAP strategy for OmniAuth."
 email:
 - floss@galtzo.com
@@ -408,10 +380,10 @@ licenses:
 - MIT
 metadata:
   homepage_uri: https://omniauth-ldap.galtzo.com/
-  source_code_uri: https://github.com/omniauth/omniauth-ldap/tree/v2.3.1
-  changelog_uri: https://github.com/omniauth/omniauth-ldap/blob/v2.3.1/CHANGELOG.md
+  source_code_uri: https://github.com/omniauth/omniauth-ldap/tree/v2.3.3
+  changelog_uri: https://github.com/omniauth/omniauth-ldap/blob/v2.3.3/CHANGELOG.md
   bug_tracker_uri: https://github.com/omniauth/omniauth-ldap/issues
-  documentation_uri: https://www.rubydoc.info/gems/omniauth-ldap/2.3.1
+  documentation_uri: https://www.rubydoc.info/gems/omniauth-ldap/2.3.3
   funding_uri: https://github.com/sponsors/pboling
   wiki_uri: https://github.com/omniauth/omniauth-ldap/wiki
   news_uri: https://www.railsbling.com/tags/omniauth-ldap