From a6ce3121fda7e1ad089f8737dc8705e8c8d1f73e Mon Sep 17 00:00:00 2001
From: Chris <chris@starforge.co.uk>
Date: Thu, 12 Jun 2014 13:13:54 +0100
Subject: [PATCH] AuthMethods can return extra data to pass to the
 post_authenticate.

---
 Webperl/AppUser.pm    | 4 +++-
 Webperl/Auth.pm       | 7 ++++---
 Webperl/AuthMethod.pm | 8 ++++++--
 3 files changed, 13 insertions(+), 6 deletions(-)

diff --git a/Webperl/AppUser.pm b/Webperl/AppUser.pm
index 9cd0230..dd792a5 100644
--- a/Webperl/AppUser.pm
+++ b/Webperl/AppUser.pm
@@ -294,7 +294,7 @@ sub pre_authenticate {
 }
 
 
-## @method $ post_authenticate($username, $password, $auth, $authmethod)
+## @method $ post_authenticate($username, $password, $auth, $authmethod, $extradata)
 # Perform any system-specific post-authentication tasks on the specified
 # user's data. This function allows each system to tailor post-auth tasks
 # to the requirements of the system. This function is only called if
@@ -313,6 +313,7 @@ sub pre_authenticate {
 # @param password   The password the user authenticated with.
 # @param auth       A reference to the auth object calling this.
 # @param authmethod The id of the authmethod to set for the user.
+# @param extradata  An optional reference to a hash containin extra data to set.
 # @return A reference to a hash containing the user's data on success,
 #         undef otherwise. If this returns undef, an error message will be
 #         set in the specified auth's errstr field.
@@ -322,6 +323,7 @@ sub post_authenticate {
     my $password   = shift;
     my $auth       = shift;
     my $authmethod = shift;
+    my $extradata  = shift;
 
     $self -> clear_error();
 
diff --git a/Webperl/Auth.pm b/Webperl/Auth.pm
index 7a9edce..5ddc451 100644
--- a/Webperl/Auth.pm
+++ b/Webperl/Auth.pm
@@ -210,6 +210,7 @@ sub valid_user {
     my $username   = shift;
     my $password   = shift;
     my $valid      = 0;
+    my $extradata;
     my $methodimpl;
 
     # clean up the password
@@ -235,7 +236,7 @@ sub valid_user {
             or return undef;
 
         # Check whether the user can authenticate if the implementation was found
-        $valid = $methodimpl -> authenticate($username, $password, $self);
+        ($valid, $extradata) = $methodimpl -> authenticate($username, $password, $self);
 
         # errors should halt auth attempts
         return undef if(!defined($valid));
@@ -248,7 +249,7 @@ sub valid_user {
             my $methodimpl = $self -> get_authmethod_module($trymethod)
                 or return undef;
 
-            $valid = $methodimpl -> authenticate($username, $password, $self);
+            ($valid, $extradata) = $methodimpl -> authenticate($username, $password, $self);
 
             # If this method worked, record it.
             $authmethod = $trymethod if($valid);
@@ -261,7 +262,7 @@ sub valid_user {
     # If one of the auth methods succeeded in validating the user, record it
     # invoke the app standard post-auth for the user, and return the user's
     # database record.
-    return $self -> {"app"} -> post_authenticate($username, $password, $self, $authmethod)
+    return $self -> {"app"} -> post_authenticate($username, $password, $self, $authmethod, $extradata)
         if($valid);
 
     # Authentication failed.
diff --git a/Webperl/AuthMethod.pm b/Webperl/AuthMethod.pm
index 672cd2d..87e307a 100644
--- a/Webperl/AuthMethod.pm
+++ b/Webperl/AuthMethod.pm
@@ -122,7 +122,7 @@ sub create_user {
 }
 
 
-## @method $ authenticate($username, $password, $auth)
+## @method @ authenticate($username, $password, $auth)
 # Authenticate a user based on the credentials supplied. This will attempt
 # to determine whether the user's credentials are valid, and will return
 # true if they are, or false if they are not or a problem occured while
@@ -133,7 +133,11 @@ sub create_user {
 # @param auth     A reference to the Auth object calling this function,
 #                 if any errors are encountered while performing the
 #                 authentication, they will be set in $auth -> {"errstr"}.
-# @return true if the user's credentials are valid, false otherwise.
+# @return true if the user's credentials are valid, false otherwise. Some
+#         AuthMethods may also return an additional value: a reference to a
+#         hash containing values to set for the user. Keys may be system-specific,
+#         and may require a custom AppUser implementation to use properly, but
+#         recommended keys are "email" and "realname", but other fields may be included.
 sub authenticate {
     my $self     = shift;
     my $username = shift;