omniauth-ldap 2.3.2 → 2.3.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 64fced98d7ab577e6c9abc446ace5678b829670e9d241f0a759c61efc47ecf5e
-  data.tar.gz: 7fda93687c96509833b9d72f277995f53eb2368ebe44740180ceadd3afac6ebe
+  metadata.gz: 8bcc01a9129d0db019b5530a9bf5f7b5241f9eacba974d5c5585b4620a8d140b
+  data.tar.gz: 5eb2878ad0b0d471d60dfb4596baddb077cde9c26499ad1d2c3f661a96f1b242
 SHA512:
-  metadata.gz: 8750eeed19ed13d89d041b14123b68cc459e7f5595d04d6d0fe67227c06c312f7952264f6fdd19a8f57957ce98c9ea3620d125fd01c445446c8848400a668e12
-  data.tar.gz: ed9dc416b2eba5c6e9d9cc5e889f50bd70347ff4a6ce9261cb8703e77d010c7834a5a566ef8ed7f93f5fbaf4baba0afa9965191decebdf84ed8ffd8b79590a8d
+  metadata.gz: f3d489556fa774b9865a3138dcce9f9eef4d2afedbeff2d0bdb5ce239a3b18dd430bcdf2438b77135434e511750a50236fb0e6902ad00ce16e60d1021058fb41
+  data.tar.gz: 4d544ca2868b9c0eb8d283dbc996b305bd1ca3d8070c9b5d342dc3de6d8d98206f197926da1bfd9f9b57e03728f8d96932a824b540fce3f4c66efd7e8ae08630

data/CHANGELOG.md

@@ -32,6 +32,22 @@ Please file a bug if you notice a violation of semantic versioning.
 
 ### Security
 
+## [2.3.3] - 2025-11-10
+
+- TAG: [v2.3.3][2.3.3t]
+- COVERAGE: 97.61% -- 286/293 lines in 4 files
+- BRANCH COVERAGE: 79.69% -- 102/128 branches in 4 files
+- 94.44% documented
+
+### Added
+
+- Documentation cleanup & updates
+- YARD documentation covering 94% of the code
+
+### Changed
+
+- kettle-dev v1.1.54
+
 ## [2.3.2] - 2025-11-06
 
 - TAG: [v2.3.2][2.3.2t]
@@ -50,14 +66,14 @@ Please file a bug if you notice a violation of semantic versioning.
   - https://datatracker.ietf.org/doc/html/draft-behera-ldap-password-policy-11
 - Support for JSON bodies
 - Support custom LDAP attributes mapping
-- Raise a distinct error when LDAP server is unreachable
-  - Previously raised an invalid credentials authentication failure error, which is technically incorrect
 - Documentation of TLS verification options
 
 ### Changed
 
 - Make support for OmniAuth v1.2+ explicit
   - Versions < 1.2 do not support SCRIPT_NAME properly, and may cause other issues
+- Raise a distinct error when LDAP server is unreachable
+    - Previously raised an invalid credentials authentication failure error, which is technically incorrect
 
 ## [2.3.1] - 2025-11-05
 
@@ -224,7 +240,9 @@ Please file a bug if you notice a violation of semantic versioning.
 [1.0.0]: https://github.com/omniauth/omniauth-ldap/compare/5656da80d4193e0d0584f44bac493a87695e580f...v1.0.0
 [1.0.0t]: https://github.com/omniauth/omniauth-ldap/releases/tag/v1.0.0
 
-[Unreleased]: https://github.com/omniauth/omniauth-ldap/compare/v2.3.2...HEAD
+[Unreleased]: https://github.com/omniauth/omniauth-ldap/compare/v2.3.3...HEAD
+[2.3.3]: https://github.com/omniauth/omniauth-ldap/compare/v2.3.2...v2.3.3
+[2.3.3t]: https://github.com/omniauth/omniauth-ldap/releases/tag/v2.3.3
 [2.3.2]: https://github.com/omniauth/omniauth-ldap/compare/v2.3.1...v2.3.2
 [2.3.2t]: https://github.com/omniauth/omniauth-ldap/releases/tag/v2.3.2
 [2.3.1]: https://github.com/omniauth/omniauth-ldap/compare/v2.0.0...v2.3.1

data/CONTRIBUTING.md

@@ -24,13 +24,13 @@ Follow these instructions:
 
 ## Executables vs Rake tasks
 
-Executables shipped by dependencies, such as omniauth-ldap, and stone_checksums, are available
+Executables shipped by dependencies, such as kettle-dev, and stone_checksums, are available
 after running `bin/setup`. These include:
 
 - gem_checksums
 - kettle-changelog
 - kettle-commit-msg
-- omniauth-ldap-setup
+- kettle-dev-setup
 - kettle-dvcs
 - kettle-pre-release
 - kettle-readme-backers
@@ -68,7 +68,9 @@ GitHub API and CI helpers
 Releasing and signing
 - SKIP_GEM_SIGNING: If set, skip gem signing during build/release
 - GEM_CERT_USER: Username for selecting your public cert in `certs/<USER>.pem` (defaults to $USER)
-- SOURCE_DATE_EPOCH: Reproducible build timestamp. `kettle-release` will set this automatically for the session.
+- SOURCE_DATE_EPOCH: Reproducible build timestamp.
+  - `kettle-release` will set this automatically for the session.
+  - Not needed on bundler >= 2.7.0, as reproducible builds have become the default.
 
 Git hooks and commit message helpers (exe/kettle-commit-msg)
 - GIT_HOOK_BRANCH_VALIDATE: Branch name validation mode (e.g., `jira`) or `false` to disable
@@ -166,6 +168,7 @@ NOTE: To build without signing the gem set `SKIP_GEM_SIGNING` to any value in th
 1. Update version.rb to contain the correct version-to-be-released.
 2. Run `bundle exec kettle-changelog`.
 3. Run `bundle exec kettle-release`.
+4. Stay awake and monitor the release process for any errors, and answer any prompts.
 
 #### Manual process
 

data/FUNDING.md

@@ -6,7 +6,7 @@ Many paths lead to being a sponsor or a backer of this project. Are you on such
 
 [![Sponsor Me on Github][🖇sponsor-img]][🖇sponsor] [![Liberapay Goal Progress][⛳liberapay-img]][⛳liberapay] [![Donate on PayPal][🖇paypal-img]][🖇paypal]
 
-[![Buy me a coffee][🖇buyme-small-img]][🖇buyme] [![Donate on Polar][🖇polar-img]][🖇polar] [![Donate to my FLOSS or refugee efforts at ko-fi.com][🖇kofi-img]][🖇kofi] [![Donate to my FLOSS or refugee efforts using Patreon][🖇patreon-img]][🖇patreon]
+[![Buy me a coffee][🖇buyme-small-img]][🖇buyme] [![Donate on Polar][🖇polar-img]][🖇polar] [![Donate to my FLOSS efforts at ko-fi.com][🖇kofi-img]][🖇kofi] [![Donate to my FLOSS efforts using Patreon][🖇patreon-img]][🖇patreon]
 
 [⛳liberapay-img]: https://img.shields.io/liberapay/goal/pboling.svg?logo=liberapay&color=a51611&style=flat
 [⛳liberapay]: https://liberapay.com/pboling/donate
@@ -27,11 +27,11 @@ Many paths lead to being a sponsor or a backer of this project. Are you on such
 
 <!-- RELEASE-NOTES-FOOTER-END -->
 
-# 🤑 Request for Help
+# 🤑 A request for help
 
 Maintainers have teeth and need to pay their dentists.
-After getting laid off in an RIF in March and filled with many dozens of rejections,
-I'm now spending ~60+ hours a week building open source tools.
+After getting laid off in an RIF in March, and encountering difficulty finding a new one,
+I began spending most of my time building open source tools.
 I'm hoping to be able to pay for my kids' health insurance this month,
 so if you value the work I am doing, I need your support.
 Please consider sponsoring me or the project.
@@ -40,16 +40,13 @@ To join the community or get help 👇️ Join the Discord.
 
 [![Live Chat on Discord][✉️discord-invite-img-ftb]][✉️discord-invite]
 
-To say "thanks for maintaining such a great tool" ☝️ Join the Discord or 👇️ send money.
+To say "thanks!" ☝️ Join the Discord or 👇️ send money.
 
-[![Sponsor me on GitHub Sponsors][🖇sponsor-bottom-img]][🖇sponsor] 💌 [![Sponsor me on Liberapay][⛳liberapay-bottom-img]][⛳liberapay-img] 💌 [![Donate on PayPal][🖇paypal-bottom-img]][🖇paypal-img]
+[![Sponsor me on GitHub Sponsors][🖇sponsor-bottom-img]][🖇sponsor] 💌 [![Sponsor me on Liberapay][⛳liberapay-bottom-img]][⛳liberapay] 💌 [![Donate on PayPal][🖇paypal-bottom-img]][🖇paypal]
 
 # Another Way to Support Open Source Software
 
-> How wonderful it is that nobody need wait a single moment before starting to improve the world.<br/>
->—Anne Frank
-
-I’m driven by a passion to foster a thriving open-source community – a space where people can tackle complex problems, no matter how small.  Revitalizing libraries that have fallen into disrepair, and building new libraries focused on solving real-world challenges, are my passions — totaling 79 hours of FLOSS coding over just the past seven days, a pretty regular week for me.  I was recently affected by layoffs, and the tech jobs market is unwelcoming. I’m reaching out here because your support would significantly aid my efforts to provide for my family, and my farm (11 🐔 chickens, 2 🐶 dogs, 3 🐰 rabbits, 8 🐈‍ cats).
+I’m driven by a passion to foster a thriving open-source community – a space where people can tackle complex problems, no matter how small.  Revitalizing libraries that have fallen into disrepair, and building new libraries focused on solving real-world challenges, are my passions.  I was recently affected by layoffs, and the tech jobs market is unwelcoming. I’m reaching out here because your support would significantly aid my efforts to provide for my family, and my farm (11 🐔 chickens, 2 🐶 dogs, 3 🐰 rabbits, 8 🐈‍ cats).
 
 If you work at a company that uses my work, please encourage them to support me as a corporate sponsor. My work on gems you use might show up in `bundle fund`.
 

data/README.md

@@ -81,7 +81,7 @@ use OmniAuth::Strategies::LDAP,
 
 All of the listed options are required, with the exception of `:title`, `:name_proc`, `:bind_dn`, and `:password`.
 
-## TLS certificate verification
+### TLS certificate verification
 
 This gem enables TLS certificate verification by default when you use `encryption: "ssl"` (LDAPS / simple TLS) or `encryption: "tls"` (STARTTLS). We always pass `tls_options` to Net::LDAP based on `OpenSSL::SSL::SSLContext::DEFAULT_PARAMS`, which includes `verify_mode: OpenSSL::SSL::VERIFY_PEER` and sane defaults.
 
@@ -153,7 +153,7 @@ Compatible with MRI Ruby 2.0+, and concordant releases of JRuby, and TruffleRuby
 
 Available as part of the Tidelift Subscription.
 
-<details>
+<details markdown="1">
   <summary>Need enterprise-level guarantees?</summary>
 
 The maintainers of this and thousands of other packages are working with Tidelift to deliver commercial support and maintenance for the open source packages you use to build your applications. Save time, reduce risk, and improve code health, while paying the maintainers of the exact packages you use.
@@ -188,7 +188,7 @@ gem install omniauth-ldap
 
 ### 🔒 Secure Installation
 
-<details>
+<details markdown="1">
   <summary>For Medium or High Security Installations</summary>
 
 This gem is cryptographically signed, and has verifiable [SHA-256 and SHA-512][💎SHA_checksums] checksums by
@@ -668,7 +668,7 @@ Security checklist:
 
 ## 🦷 FLOSS Funding
 
-While these tools are free software and will always be, the project would benefit immensely from some funding.
+While omniauth tools are free software and will always be, the project would benefit immensely from some funding.
 Raising a monthly budget of... "dollars" would make the project more sustainable.
 
 We welcome both individual and corporate sponsors! We also offer a
@@ -678,7 +678,7 @@ Currently, [GitHub Sponsors][🖇sponsor], and [Liberapay][⛳liberapay] are our
 **If you're working in a company that's making significant use of omniauth tools we'd
 appreciate it if you suggest to your company to become a omniauth sponsor.**
 
-You can support me in development of OmniAuth tools via
+You can support the development of omniauth tools via
 [GitHub Sponsors][🖇sponsor],
 [Liberapay][⛳liberapay],
 [PayPal][🖇paypal],
@@ -698,7 +698,7 @@ I’m developing a new library, [floss_funding][🖇floss-funding-gem], designed
 
 **[Floss-Funding.dev][🖇floss-funding.dev]: 👉️ No network calls. 👉️ No tracking. 👉️ No oversight. 👉️ Minimal crypto hashing. 💡 Easily disabled nags**
 
-[![Sponsor Me on Github][🖇sponsor-img]][🖇sponsor] [![Liberapay Goal Progress][⛳liberapay-img]][⛳liberapay] [![Donate on PayPal][🖇paypal-img]][🖇paypal] [![Buy me a coffee][🖇buyme-small-img]][🖇buyme] [![Donate on Polar][🖇polar-img]][🖇polar] [![Donate to my FLOSS or refugee efforts at ko-fi.com][🖇kofi-img]][🖇kofi] [![Donate to my FLOSS or refugee efforts using Patreon][🖇patreon-img]][🖇patreon]
+[![Sponsor Me on Github][🖇sponsor-img]][🖇sponsor] [![Liberapay Goal Progress][⛳liberapay-img]][⛳liberapay] [![Donate on PayPal][🖇paypal-img]][🖇paypal] [![Buy me a coffee][🖇buyme-small-img]][🖇buyme] [![Donate on Polar][🖇polar-img]][🖇polar] [![Donate to my FLOSS efforts at ko-fi.com][🖇kofi-img]][🖇kofi] [![Donate to my FLOSS efforts using Patreon][🖇patreon-img]][🖇patreon]
 
 ## 🔐 Security
 
@@ -770,12 +770,11 @@ For example:
 spec.add_dependency("omniauth-ldap", "~> 1.0")
 ```
 
-<details>
+<details markdown="1">
 <summary>📌 Is "Platform Support" part of the public API? More details inside.</summary>
 
 SemVer should, IMO, but doesn't explicitly, say that dropping support for specific Platforms
-is a *breaking change* to an API.
-It is obvious to many, but not all, and since the spec is silent, the bike shedding is endless.
+is a *breaking change* to an API, and for that reason the bike shedding is endless.
 
 To get a better understanding of how SemVer is intended to work over a project's lifetime,
 read this article from the creator of SemVer:
@@ -991,7 +990,7 @@ Thanks for RTFM. ☺️
 [📌gitmoji]: https://gitmoji.dev
 [📌gitmoji-img]: https://img.shields.io/badge/gitmoji_commits-%20%F0%9F%98%9C%20%F0%9F%98%8D-34495e.svg?style=flat-square
 [🧮kloc]: https://www.youtube.com/watch?v=dQw4w9WgXcQ
-[🧮kloc-img]: https://img.shields.io/badge/KLOC-0.297-FFDD67.svg?style=for-the-badge&logo=YouTube&logoColor=blue
+[🧮kloc-img]: https://img.shields.io/badge/KLOC-0.293-FFDD67.svg?style=for-the-badge&logo=YouTube&logoColor=blue
 [🔐security]: SECURITY.md
 [🔐security-img]: https://img.shields.io/badge/security-policy-259D6C.svg?style=flat
 [📄copyright-notice-explainer]: https://opensource.stackexchange.com/questions/5778/why-do-licenses-such-as-the-mit-license-specify-a-single-year

data/lib/omniauth/strategies/ldap.rb

@@ -1,14 +1,64 @@
+# frozen_string_literal: true
+
 require "omniauth"
 require "omniauth/version"
 
+# OmniAuth strategies namespace.
+#
+# This file implements an LDAP authentication strategy for OmniAuth.
+# It provides both an interactive request phase (login form) and a
+# callback phase which binds to an LDAP directory to authenticate the
+# user or performs a lookup for header-based SSO.
+#
+# The strategy exposes a number of options (see `option` calls below)
+# that control LDAP connection, mapping of LDAP attributes to the
+# OmniAuth `info` hash, header-based SSO behavior, and SSL/timeouts.
+#
+# @example Minimal Rack mounting
+#   use OmniAuth::Builder do
+#     provider :ldap, {
+#       host: 'ldap.example.com',
+#       base: 'dc=example,dc=com'
+#     }
+#   end
+#
 module OmniAuth
   module Strategies
+    # LDAP OmniAuth strategy
+    #
+    # This class implements the OmniAuth::Strategy interface and performs
+    # LDAP authentication using an `Adaptor` object. It supports three
+    # primary flows:
+    #
+    # - Interactive login form (request_phase) where users POST username/password
+    # - Callback binding where the strategy attempts to bind as the user
+    # - Header-based SSO (trusted upstream) where a header identifies the user
+    #
+    # The mapping from LDAP attributes to resulting `info` fields is
+    # configurable via the `:mapping` option. See `map_user` for the
+    # mapping algorithm.
+    #
+    # @see OmniAuth::Strategy
     class LDAP
+      # Whether the loaded OmniAuth version is >= 2.0.0; used to set default request methods.
+      # @return [Boolean]
       OMNIAUTH_GTE_V2 = Gem::Version.new(OmniAuth::VERSION) >= Gem::Version.new("2.0.0")
+
       include OmniAuth::Strategy
 
+      # Raised when credentials are invalid or the user cannot be authenticated.
+      # @example
+      #   raise InvalidCredentialsError, 'Invalid credentials'
       InvalidCredentialsError = Class.new(StandardError)
 
+      # Default mapping for converting LDAP attributes to OmniAuth `info` keys.
+      # Keys are the resulting `info` hash keys (strings). Values may be:
+      # - String: single LDAP attribute name
+      # - Array: list of attribute names in priority order
+      # - Hash: pattern mapping where pattern keys contain %<n> placeholders
+      #   that are substituted from a list of possible attribute names
+      #
+      # @return [Hash<String, String|Array|Hash>]
       option :mapping, {
         "name" => "cn",
         "first_name" => "givenName",
@@ -24,7 +74,11 @@ module OmniAuth
         "image" => "jpegPhoto",
         "description" => "description",
       }
-      option :title, "LDAP Authentication" # default title for authentication form
+
+      # Default title shown on the login form.
+      # @return [String]
+      option :title, "LDAP Authentication"
+
       # For OmniAuth >= 2.0 the default allowed request method is POST only.
       # Ensure the strategy follows that default so GET /auth/:provider returns 404 as expected in tests.
       if OMNIAUTH_GTE_V2
@@ -32,6 +86,8 @@ module OmniAuth
       else
         option(:request_methods, [:get, :post])
       end
+
+      # Default LDAP connection options / behavior
       option :port, 389
       option :method, :plain
       option :disable_verify_certificates, false
@@ -39,6 +95,7 @@ module OmniAuth
       option :ssl_version, nil # use OpenSSL default if nil
       option :uid, "sAMAccountName"
       option :name_proc, lambda { |n| n }
+
       # Trusted header SSO support (disabled by default)
       # :header_auth - when true and the header is present, the strategy trusts the upstream gateway
       #                 and searches the directory for the user without requiring a user password.
@@ -46,10 +103,20 @@ module OmniAuth
       #                 standard Rack "HTTP_" variant automatically.
       option :header_auth, false
       option :header_name, "REMOTE_USER"
+
       # Optional timeouts (forwarded to Net::LDAP when supported)
       option :connect_timeout, nil
       option :read_timeout, nil
 
+      # Request phase: Render the login form or redirect to callback for header-auth or direct POSTed credentials
+      #
+      # This will behave differently depending on OmniAuth version and request method:
+      # - For OmniAuth >= 2.0 a GET to /auth/:provider should return 404 (so we return a 404 for GET requests).
+      # - If header-based SSO is enabled and a trusted header is present we immediately redirect to the callback.
+      # - If credentials are POSTed directly to /auth/:provider we redirect to the callback so the test helpers
+      #   that populate `env['omniauth.auth']` can operate on the callback request.
+      #
+      # @return [Array] A Rack response triple from the login form or redirect.
       def request_phase
         # OmniAuth >= 2.0 expects the request phase to be POST-only for /auth/:provider.
         # Some test environments (and OmniAuth itself) enforce this by returning 404 on GET.
@@ -78,6 +145,19 @@ module OmniAuth
         f.to_response
       end
 
+      # Callback phase: Authenticate user or perform header-based lookup
+      #
+      # This method executes on the callback URL and implements the main
+      # authentication logic. There are two primary paths:
+      #
+      # - Header-based lookup: when `options[:header_auth]` is enabled and a header value is present,
+      #   we perform a read-only directory lookup for the user and, if found, map attributes and finish.
+      # - Password bind: when username/password are provided we attempt a bind as the user using the adaptor.
+      #
+      # Errors raised by the LDAP adaptor are captured and turned into OmniAuth failures.
+      #
+      # @raise [InvalidCredentialsError] when credentials are invalid
+      # @return [Object] result of calling `super` from the OmniAuth::Strategy chain
       def callback_phase
         @adaptor = OmniAuth::LDAP::Adaptor.new(@options)
 
@@ -118,6 +198,15 @@ module OmniAuth
         end
       end
 
+      # Build an LDAP filter for searching/binding the user.
+      #
+      # If the adaptor has a custom `filter` option set it will be used (with
+      # interpolation of `%{username}`). Otherwise a simple equality filter for
+      # the configured uid attribute is used.
+      #
+      # @param adaptor [OmniAuth::LDAP::Adaptor] the adaptor used to build connection/filters
+      # @param username_override [String, nil] optional username to build the filter for (defaults to request username)
+      # @return [Net::LDAP::Filter] the constructed filter object
       def filter(adaptor, username_override = nil)
         flt = adaptor.filter
         if flt && !flt.to_s.empty?
@@ -128,17 +217,37 @@ module OmniAuth
         end
       end
 
-      uid {
-        @user_info["uid"]
-      }
-      info {
-        @user_info
-      }
-      extra {
-        {raw_info: @ldap_user_info}
-      }
+      # The uid exposed to OmniAuth consumers.
+      #
+      # This block-based DSL is part of OmniAuth::Strategy; document the value
+      # returned by the block.
+      #
+      # @return [String] the user's uid as determined from the mapped info
+      uid { @user_info["uid"] }
+
+      # The `info` hash returned to OmniAuth consumers. Usually contains name, email, etc.
+      # @return [Hash<String, Object>]
+      info { @user_info }
+
+      # Extra information exposed under `extra[:raw_info]` containing the raw LDAP entry.
+      # @return [Hash{Symbol => Object}]
+      extra { {raw_info: @ldap_user_info} }
 
       class << self
+        # Map LDAP attributes from the directory entry into a simple Hash used
+        # for the OmniAuth `info` hash according to the provided `mapper`.
+        #
+        # The mapper supports three types of values:
+        # - String: a single attribute name. The method will call the attribute
+        #   reader (downcased symbol) on the `object` and take the first value.
+        # - Array: iterate values and pick the first attribute that exists on the object.
+        # - Hash: a mapping of a pattern string to an array of attribute-name lists
+        #   where each `%<n>` placeholder in the pattern will be substituted by the
+        #   first available attribute from the corresponding list.
+        #
+        # @param mapper [Hash] mapping configuration (see option :mapping)
+        # @param object [#respond_to?, #[]] directory entry (commonly a Net::LDAP::Entry or similar)
+        # @return [Hash<String, Object>] the mapped user info hash
         def map_user(mapper, object)
           user = {}
           mapper.each do |key, value|
@@ -177,20 +286,38 @@ module OmniAuth
 
       protected
 
+      # Validate that the incoming request method is allowed.
+      #
+      # For OmniAuth >= 2.0 the default is POST only. This method checks the
+      # Rack env REQUEST_METHOD directly so tests and environments that stub
+      # request.HTTP_METHOD are handled deterministically.
+      #
+      # @return [Boolean] true when the request method is POST
       def valid_request_method?
         request.env["REQUEST_METHOD"] == "POST"
       end
 
+      # Determine if the request is missing required credentials.
+      #
+      # @return [Boolean] true when username or password are nil/empty
       def missing_credentials?
         request_data["username"].nil? || request_data["username"].empty? || request_data["password"].nil? || request_data["password"].empty?
       end
 
+      # Extract request parameters in a way compatible with Rails/Rack.
+      #
+      # @return [Hash] parameters hash containing at least "username" and "password" when provided
       def request_data
         @env["action_dispatch.request.request_parameters"] || request.params
       end
 
       # Extract a normalized username from a trusted header when enabled.
       # Returns nil when not configured or not present.
+      #
+      # The method will attempt the raw env key (e.g. "REMOTE_USER") and the Rack
+      # HTTP_ variant (e.g. "HTTP_REMOTE_USER" or "HTTP_X_REMOTE_USER").
+      #
+      # @return [String, nil] normalized username or nil if not present
       def header_username
         return unless options[:header_auth]
 
@@ -204,6 +331,10 @@ module OmniAuth
 
       # Perform a directory lookup for the given username using the strategy configuration
       # (bind_dn/password or anonymous). Does not attempt to bind as the user.
+      #
+      # @param adaptor [OmniAuth::LDAP::Adaptor] initialized adaptor
+      # @param username [String] username to look up
+      # @return [Object, nil] first directory entry found or nil
       def directory_lookup(adaptor, username)
         entry = nil
         search_filter = filter(adaptor, username)
@@ -216,6 +347,11 @@ module OmniAuth
 
       # If the adaptor captured a Password Policy response control, expose a minimal, stable hash
       # in the Rack env for applications to inspect.
+      #
+      # The structure is available at `request.env['omniauth.ldap.password_policy']`.
+      #
+      # @param adaptor [OmniAuth::LDAP::Adaptor]
+      # @return [void]
       def attach_password_policy_env(adaptor)
         return unless adaptor.respond_to?(:password_policy) && adaptor.password_policy
         ctrl = adaptor.respond_to?(:last_password_policy_response) ? adaptor.last_password_policy_response : nil
@@ -226,6 +362,10 @@ module OmniAuth
       end
 
       # Best-effort extraction across net-ldap versions; if fields are not available, returns a raw payload.
+      #
+      # @param control [Object, nil] the password policy response control if available
+      # @param operation [Object, nil] the last operation result if available
+      # @return [Hash] normalized password policy info with keys :raw, :error, :time_before_expiration, :grace_authns_remaining, :oid, :operation
       def extract_password_policy(control, operation)
         data = {raw: control}
         if control

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,
@@ -42,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
@@ -51,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,
@@ -62,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
+
+      # 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|
@@ -77,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
@@ -128,6 +203,16 @@ module OmniAuth
       #: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
@@ -179,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
@@ -189,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"
@@ -203,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)
 
@@ -223,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
@@ -241,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 = ""
@@ -253,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]
@@ -268,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:
@@ -286,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? ||
@@ -293,6 +403,10 @@ 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
@@ -300,6 +414,12 @@ module OmniAuth
       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)

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.2"
+      # 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"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: omniauth-ldap
 version: !ruby/object:Gem::Version
-  version: 2.3.2
+  version: 2.3.3
 platform: ruby
 authors:
 - Peter Boling
@@ -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.2
-  changelog_uri: https://github.com/omniauth/omniauth-ldap/blob/v2.3.2/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.2
+  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