✨ Password Policy for LDAP Directories

- https://datatracker.ietf.org/doc/html/draft-behera-ldap-password-policy-11

Author: pboling

README.md

@@ -191,6 +191,25 @@ The following options are available for configuring the OmniAuth LDAP strategy:
 - `:sasl_mechanisms` - Array of SASL mechanisms to use (e.g., ["DIGEST-MD5", "GSS-SPNEGO"]).
 - `:allow_anonymous` - Whether to allow anonymous binding (default: false).
 - `:logger` - A logger instance for debugging (optional, for internal use).
+- `:password_policy` - When true, the strategy will request the LDAP Password Policy response control (OID `1.3.6.1.4.1.42.2.27.8.5.1`) during the user bind. If the server supports it, the adaptor exposes:
+  - `adaptor.last_operation_result` — the last Net::LDAP operation result object.
+  - `adaptor.last_password_policy_response` — the matching password policy response control (implementation-specific object). This can indicate conditions such as password expired, account locked, reset required, or grace logins remaining (per the draft RFC).
+
+Example enabling password policy:
+
+```ruby
+use OmniAuth::Builder do
+  provider :ldap,
+    host: "ldap.example.com",
+    base: "dc=example,dc=com",
+    uid: "uid",
+    bind_dn: "cn=search,dc=example,dc=com",
+    password: ENV["LDAP_SEARCH_PASSWORD"],
+    password_policy: true
+end
+```
+
+Note: This is best-effort and compatible with a range of net-ldap versions. If your server supports the control, you can inspect the response via the `adaptor` instance during/after authentication (for example in a failure handler) to tailor error messages.
 
 ### Auth Hash UID vs LDAP :uid (search attribute)
 
@@ -453,7 +472,10 @@ Rails.application.config.middleware.use(OmniAuth::Builder) do
     title: "Acme LDAP",
     host: "ldap.acme.internal",
     base: "dc=acme,dc=corp",
-    uid: "uid"
+    uid: "uid",
+    bind_dn: "cn=search,dc=acme,dc=corp",
+    password: ENV["LDAP_SEARCH_PASSWORD"],
+    name_proc: proc { |n| n.split("@").first }
 end
 ```
 

lib/omniauth-ldap/adaptor.rb

@@ -31,6 +31,7 @@ class ConnectionError < StandardError; end
         :allow_anonymous,
         :filter,
         :tls_options,
+        :password_policy,
 
         # Deprecated
         :method,
@@ -59,7 +60,7 @@ class ConnectionError < StandardError; end
       }
 
       attr_accessor :bind_dn, :password
-      attr_reader :connection, :uid, :base, :auth, :filter
+      attr_reader :connection, :uid, :base, :auth, :filter, :password_policy, :last_operation_result, :last_password_policy_response
 
       def self.validate(configuration = {})
         message = []
@@ -109,20 +110,60 @@ def initialize(configuration = {})
       # :password => psw
       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
+          if rs && rs.first
+            dn = rs.first.dn
+            if dn
+              password = args[:password]
+              method = args[:method] || @method
+              password = password.call if password.respond_to?(:call)
+
+              bind_args = if 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
+                # Best-effort: if specific control class is available use it; otherwise request by OID
+                control = begin
+                  if defined?(Net::LDAP::Control::PasswordPolicy)
+                    Net::LDAP::Control::PasswordPolicy.new
+                  elsif defined?(Net::LDAP::Controls) && defined?(Net::LDAP::Controls::PasswordPolicy)
+                    Net::LDAP::Controls::PasswordPolicy.new
+                  elsif defined?(Net::LDAP::Control) && Net::LDAP::Control.respond_to?(:new)
+                    # Arguments: oid, critical, value
+                    Net::LDAP::Control.new("1.3.6.1.4.1.42.2.27.8.5.1", true, nil)
+                  else
+                    # Fallback to a simple hash - useful for testing with stubs
+                    {oid: "1.3.6.1.4.1.42.2.27.8.5.1", criticality: true, value: nil}
+                  end
+                rescue StandardError
+                  {oid: "1.3.6.1.4.1.42.2.27.8.5.1", criticality: true, value: nil}
+                end
+                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
+                  # If 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
@@ -250,6 +291,32 @@ def symbolize_hash_keys(hash)
           result[key.to_sym] = value
         end
       end
+
+      # Capture the operation result and extract any Password Policy response control if present.
+      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

lib/omniauth/strategies/ldap.rb

@@ -100,9 +100,14 @@ def callback_phase
           @ldap_user_info = @adaptor.bind_as(filter: filter(@adaptor), size: 1, password: request.params["password"])
 
           unless @ldap_user_info
+            # Attach password policy info to env if available (best-effort)
+            attach_password_policy_env(@adaptor)
             return fail!(:invalid_credentials, InvalidCredentialsError.new("Invalid credentials for #{request.params["username"]}"))
           end
 
+          # Optionally attach policy info even on success (e.g., timeBeforeExpiration)
+          attach_password_policy_env(@adaptor)
+
           @user_info = self.class.map_user(CONFIG, @ldap_user_info)
           super
         rescue => e
@@ -197,10 +202,51 @@ def directory_lookup(adaptor, username)
         search_filter = filter(adaptor, username)
         adaptor.connection.open do |conn|
           rs = conn.search(filter: search_filter, size: 1)
-          entry = rs.first if rs && rs.first
+          entry = rs && rs.first
         end
         entry
       end
+
+      # If the adaptor captured a Password Policy response control, expose a minimal, stable hash
+      # in the Rack env for applications to inspect.
+      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
+        op = adaptor.respond_to?(:last_operation_result) ? adaptor.last_operation_result : nil
+        return unless ctrl || op
+
+        request.env["omniauth.ldap.password_policy"] = extract_password_policy(ctrl, op)
+      end
+
+      # Best-effort extraction across net-ldap versions; if fields are not available, returns a raw payload.
+      def extract_password_policy(control, operation)
+        data = {raw: control}
+        if control
+          # Prefer named readers if present
+          if control.respond_to?(:error)
+            data[:error] = control.public_send(:error)
+          elsif control.respond_to?(:ppolicy_error)
+            data[:error] = control.public_send(:ppolicy_error)
+          end
+          if control.respond_to?(:time_before_expiration)
+            data[:time_before_expiration] = control.public_send(:time_before_expiration)
+          end
+          if control.respond_to?(:grace_authns_remaining)
+            data[:grace_authns_remaining] = control.public_send(:grace_authns_remaining)
+          elsif control.respond_to?(:grace_logins_remaining)
+            data[:grace_authns_remaining] = control.public_send(:grace_logins_remaining)
+          end
+          if control.respond_to?(:oid)
+            data[:oid] = control.public_send(:oid)
+          end
+        end
+        if operation
+          code = operation.respond_to?(:code) ? operation.code : nil
+          message = operation.respond_to?(:message) ? operation.message : nil
+          data[:operation] = {code: code, message: message}
+        end
+        data
+      end
     end
   end
 end

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

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

sig/omniauth/strategies/ldap.rbs

@@ -27,6 +27,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

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

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
-

spec/omniauth-ldap/adaptor_spec.rb

@@ -216,5 +216,30 @@
       expect(adaptor.connection).to receive(:bind).and_return(true)
       expect(adaptor.bind_as(args)).to eq rs
     end
+
+    context "when password policy is enabled" do
+      let(:ppolicy_oid) { "1.3.6.1.4.1.42.2.27.8.5.1" }
+
+      it "adds a Password Policy request control to the bind" do
+        adaptor = described_class.new({host: "127.0.0.1", encryption: "plain", base: "dc=example, dc=com", port: 389, uid: "sAMAccountName", bind_dn: "bind_dn", password: "password", password_policy: true})
+        expect(adaptor.connection).to receive(:open).and_yield(adaptor.connection)
+        expect(adaptor.connection).to receive(:search).with(args).and_return([rs])
+        expect(adaptor.connection).to receive(:bind) do |bind_args|
+          expect(bind_args).to be_a(Hash)
+          expect(bind_args[:controls]).to be_a(Array)
+          ctrl = bind_args[:controls].first
+          oid = ctrl.respond_to?(:oid) ? ctrl.oid : ctrl[:oid]
+          expect(oid).to eq(ppolicy_oid)
+          true
+        end.and_return(true)
+        # Stub operation result with a ppolicy response control
+        ctrl = Struct.new(:oid).new(ppolicy_oid)
+        op_result = Struct.new(:controls).new([ctrl])
+        allow(adaptor.connection).to receive(:get_operation_result).and_return(op_result)
+
+        expect(adaptor.bind_as(args)).to eq rs
+        expect(adaptor.last_password_policy_response).not_to be_nil
+      end
+    end
   end
 end