release 1.013

[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..8742ae8 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 = '1.013';
 
 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' => {
@@ -54,6 +52,7 @@ Catalyst::Authentication::Store::LDAP
                role_scope          => "one",
                role_search_options => { deref => "always" },
                role_value          => "dn",
+               role_search_as_user => 0,
                start_tls           => 1,
                start_tls_options   => { verify => "none" },
                entry_class         => "MyApp::LDAP::Entry",
@@ -61,8 +60,9 @@ Catalyst::Authentication::Store::LDAP
                user_basedn         => "ou=people,dc=yourcompany,dc=com",
                user_field          => "uid",
                user_filter         => "(&(objectClass=posixAccount)(uid=%s))",
-               user_scope          => "one",
+               user_scope          => "one", # or "sub" for Active Directory
                user_search_options => { deref => "always" },
+               user_results_filter => sub { return shift->pop_entry },
              },
            },
          },
@@ -156,6 +156,7 @@ tweeks to the example configuration will work:
     user_basedn: ou=Domain Users,ou=Accounts,dc=mycompany,dc=com
     user_field:  samaccountname
     user_filter: (sAMAccountName=%s) 
+    user_scope: sub
 
 He also notes: "I found the case in the value of user_field to be significant: 
 it didn't seem to work when I had the mixed case value there."
@@ -234,6 +235,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 
@@ -281,6 +303,23 @@ Be careful not to specify:
 
 As they are already taken care of by other configuration options.
 
+=head2 role_search_as_user
+
+By default this setting is false, and the role search will be performed
+by binding to the directory with the details in the I<binddn> and I<bindpw>
+fields. If this is set to false, then the role search will instead be
+performed when bound as the user you authenticated as.
+
+=head2 entry_class
+
+The name of the class of LDAP entries returned. This class should
+exist and is expected to be a subclass of Net::LDAP::Entry
+
+=head2 user_class
+
+The name of the class of user object returned. By default, this is
+L<Catalyst::Authentication::Store::LDAP::User>.
+
 =head1 METHODS
 
 =head2 new