release 0.1001

[catagits/Catalyst-Authentication-Store-LDAP.git] / lib / Catalyst / Authentication / Store / LDAP.pm

diff --git a/lib/Catalyst/Authentication/Store/LDAP.pm b/lib/Catalyst/Authentication/Store/LDAP.pm
index 5311af9..06b5b21 100644 (file)
--- a/lib/Catalyst/Authentication/Store/LDAP.pm
+++ b/lib/Catalyst/Authentication/Store/LDAP.pm
@@ -3,7 +3,7 @@ package Catalyst::Authentication::Store::LDAP;
 use strict;
 use warnings;
 
-our $VERSION = '0.1000';
+our $VERSION = '0.1001';
 
 use Catalyst::Authentication::Store::LDAP::Backend;
 
@@ -26,11 +26,9 @@ Catalyst::Authentication::Store::LDAP
 
 =head1 SYNOPSIS
 
-    use Catalyst qw/
+    use Catalyst qw(
       Authentication
-      Authentication::Store::LDAP
-      Authentication::Credential::Password
-      /;
+      );
 
     __PACKAGE__->config(
       'authentication' => {
@@ -63,6 +61,7 @@ Catalyst::Authentication::Store::LDAP
                user_filter         => "(&(objectClass=posixAccount)(uid=%s))",
                user_scope          => "one",
                user_search_options => { deref => "always" },
+               user_results_filter => sub { return shift->pop_entry },
              },
            },
          },
@@ -234,6 +233,27 @@ Be careful not to specify:
 
 As they are already taken care of by other configuration options.
 
+=head2 user_results_filter
+
+This is a Perl CODE ref that can be used to filter out multiple results
+from your LDAP query. In theory, your LDAP query should only return one result
+and find_user() will throw an exception if it encounters more than one result.
+However, if you have, for whatever reason, a legitimate reason for returning
+multiple search results from your LDAP query, use C<user_results_filter> to filter
+out the LDAP entries you do not want considered. Your CODE ref should expect
+a single argument, a Net::LDAP::Search object, and it should return exactly one
+value, a Net::LDAP::Entry object.
+
+Example:
+
+ user_results_filter => sub {
+                          my $search_obj = shift;
+                          foreach my $entry ($search_obj->entries) {
+                              return $entry if my_match_logic( $entry );
+                          }
+                          return undef; # i.e., no match
+                        }
+ 
 =head2 use_roles
 
 Whether or not to enable role lookups.  It defaults to true; set it to 0 if