add documentation for AD; add User methods per RT #60793

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

diff --git a/lib/Catalyst/Authentication/Store/LDAP/User.pm b/lib/Catalyst/Authentication/Store/LDAP/User.pm
index 22f95c5..42e4417 100644 (file)
--- a/lib/Catalyst/Authentication/Store/LDAP/User.pm
+++ b/lib/Catalyst/Authentication/Store/LDAP/User.pm
@@ -8,12 +8,15 @@ Catalyst::Authentication::Store::LDAP::User
 
 =head1 SYNOPSIS
 
-You should be creating these objects through L<Catalyst::Authentication::Store::LDAP::Backend>'s "get_user" method, or just letting $c->login do
+You should be creating these objects through L<Catalyst::Authentication::Store::LDAP::Backend>'s "get_user" method, or just letting $c->authenticate do
 it for you.
 
     sub action : Local {
         my ( $self, $c ) = @_;
-        $c->login($c->req->param(username), $c->req->param(password));
+        $c->authenticate({
+            id => $c->req->param(username),
+            password => $c->req->param(password)
+        );
         $c->log->debug($c->user->username . "is really neat!");
     }
 
@@ -45,27 +48,33 @@ use base qw( Catalyst::Authentication::User Class::Accessor::Fast );
 
 use strict;
 use warnings;
+use Scalar::Util qw/refaddr/;
 
-our $VERSION = '0.1004';
+our $VERSION = '1.012';
 
 BEGIN { __PACKAGE__->mk_accessors(qw/user store/) }
 
 use overload '""' => sub { shift->stringify }, fallback => 1;
 
+my %_ldap_connection_passwords; # Store inside-out so that they don't show up
+                                # in dumps..
+
 =head1 METHODS
 
-=head2 new($store, $user)
+=head2 new($store, $user, $c)
 
 Takes a L<Catalyst::Authentication::Store::LDAP::Backend> object
 as $store, and the data structure returned by that class's "get_user"
-method as $user.
+method as $user.  The final argument is an instance of your application,
+which is passed along for those wanting to subclass User and perhaps use
+models for fetching data.
 
 Returns a L<Catalyst::Authentication::Store::LDAP::User> object.
 
 =cut
 
 sub new {
-    my ( $class, $store, $user ) = @_;
+    my ( $class, $store, $user, $c ) = @_;
 
     return unless $user;
 
@@ -102,8 +111,8 @@ sub stringify {
         return $string;
     }
     else {
-        my ($string) = $self->$userfield;
-        return $string;
+        my $val = $self->$userfield;
+        return ref($val) eq 'ARRAY' ? $val->[0] : $val;
     }
 }
 
@@ -136,10 +145,13 @@ sub check_password {
         'forauth' );
     if ( defined($ldap) ) {
         if ($self->store->role_search_as_user) {
+            # FIXME - This can be removed and made to use the code below..
             # Have to do the role lookup _now_, as this is the only time
             # that we have the user's password/ldap bind..
             $self->roles($ldap);
         }
+        # Stash a closure which can be used to retrieve the connection in the users context later.
+        $_ldap_connection_passwords{refaddr($self)} = $password;
         return 1;
     }
     else {
@@ -216,6 +228,9 @@ sub has_attribute {
     if ( $attribute eq "dn" ) {
         return $self->ldap_entry->dn;
     }
+    elsif ( $attribute eq "username" ) {
+       return $self->user->{'attributes'}->{$self->store->user_field};
+    }
     elsif ( exists( $self->user->{'attributes'}->{$attribute} ) ) {
         return $self->user->{'attributes'}->{$attribute};
     }
@@ -224,6 +239,36 @@ sub has_attribute {
     }
 }
 
+=head2 get
+
+A simple wrapper around has_attribute() to satisfy the Catalyst::Authentication::User API.
+
+=cut
+
+sub get { return shift->has_attribute(@_) }
+
+=head2 get_object
+
+Satisfies the Catalyst::Authentication::User API and returns the contents of the user()
+attribute.
+
+=cut
+
+sub get_object { return shift->user }
+
+=head2 ldap_connection
+
+Re-binds to the auth store with the credentials of the user you logged in
+as, and returns a L<Net::LDAP> object which you can use to do further queries.
+
+=cut
+
+sub ldap_connection {
+    my $self = shift;
+    $self->store->ldap_bind( undef, $self->ldap_entry->dn,
+        $_ldap_connection_passwords{refaddr($self)} );
+}
+
 =head2 AUTOLOADed methods
 
 We automatically map the attributes of the underlying L<Net::LDAP::Entry>
@@ -263,6 +308,12 @@ value of user_field (uid by default.)
 
 =cut
 
+sub DESTROY {
+    my $self = shift;
+    # Don't leak passwords..
+    delete $_ldap_connection_passwords{refaddr($self)};
+}
+
 sub AUTOLOAD {
     my $self = shift;
 
@@ -271,20 +322,9 @@ sub AUTOLOAD {
     if ( $method eq "DESTROY" ) {
         return;
     }
-    if ( exists( $self->user->{'attributes'}->{$method} ) ) {
-        return $self->user->{'attributes'}->{$method};
-    }
-    elsif ( $method eq "username" ) {
-        my $userfield = $self->store->user_field;
-        my $username  = $self->has_attribute($userfield);
-        if ($username) {
-            return $username;
-        }
-        else {
-            Catalyst::Exception->throw( "User is missing the "
-                    . $userfield
-                    . " attribute, which should not be possible!" );
-        }
+
+    if ( my $attribute = $self->has_attribute($method) ) {
+        return $attribute;
     }
     else {
         Catalyst::Exception->throw(