From 6b521c1eda5bb59c24445db24bcaf43a3081dab8 Mon Sep 17 00:00:00 2001
From: Olav Morken <olav.morken@uninett.no>
Date: Wed, 5 Aug 2009 07:30:43 +0000
Subject: [PATCH] core_Auth_UserPassBase: Improve comments.
git-svn-id: https://simplesamlphp.googlecode.com/svn/trunk@1631 44740490-163a-0410-bde0-09ae8108e29a
---
modules/core/lib/Auth/UserPassBase.php | 39 ++++++++++++++++++++++----
1 file changed, 33 insertions(+), 6 deletions(-)
diff --git a/modules/core/lib/Auth/UserPassBase.php b/modules/core/lib/Auth/UserPassBase.php
index d2cc4dada..14d809ec2 100644
--- a/modules/core/lib/Auth/UserPassBase.php
+++ b/modules/core/lib/Auth/UserPassBase.php
@@ -74,19 +74,35 @@ abstract class sspmod_core_Auth_UserPassBase extends SimpleSAML_Auth_Source {
public function authenticate(&$state) {
assert('is_array($state)');
- /* We are going to need the authId in order to retrieve this authentication source later. */
+ /*
+ * Save the identifier of this authentication source, so that we can
+ * retrieve it later. This allows us to call the login()-function on
+ * the current object.
+ */
$state[self::AUTHID] = $this->authId;
/* What username we should force, if any. */
if ($this->forcedUsername !== NULL) {
+ /*
+ * This is accessed by the login form, to determine if the user
+ * is allowed to change the username.
+ */
$state['forcedUsername'] = $this->forcedUsername;
}
+ /* Save the $state-array, so that we can restore it after a redirect. */
$id = SimpleSAML_Auth_State::saveState($state, self::STAGEID);
+ /*
+ * Redirect to the login form. We include the identifier of the saved
+ * state array as a parameter to the login form.
+ */
$url = SimpleSAML_Module::getModuleURL('core/loginuserpass.php');
$params = array('AuthState' => $id);
SimpleSAML_Utilities::redirect($url, $params);
+
+ /* The previous function never returns, so this code is never executed. */
+ assert('FALSE');
}
@@ -110,9 +126,8 @@ abstract class sspmod_core_Auth_UserPassBase extends SimpleSAML_Auth_Source {
* Handle login request.
*
* This function is used by the login form (core/www/loginuserpass.php) when the user
- * enters a username and password. On success, it will not return. On wrong
- * username/password failure, it will return the error code. Other failures will throw an
- * exception.
+ * enters a username and password. On success, it will not return. If an error occurs,
+ * it will return the error code.
*
* @param string $authStateId The identifier of the authentication state.
* @param string $username The username the user wrote.
@@ -124,25 +139,37 @@ abstract class sspmod_core_Auth_UserPassBase extends SimpleSAML_Auth_Source {
assert('is_string($username)');
assert('is_string($password)');
- /* Retrieve the authentication state. */
+ /* Here we retrieve the state array we saved in the authenticate-function. */
$state = SimpleSAML_Auth_State::loadState($authStateId, self::STAGEID);
- /* Find authentication source. */
+ /* Retrieve the authentication source we are executing. */
assert('array_key_exists(self::AUTHID, $state)');
$source = SimpleSAML_Auth_Source::getById($state[self::AUTHID]);
if ($source === NULL) {
throw new Exception('Could not find authentication source with id ' . $state[self::AUTHID]);
}
+ /*
+ * $source now contains the authentication source on which authenticate()
+ * was called. We should call login() on the same authentication source.
+ */
try {
/* Attempt to log in. */
$attributes = $source->login($username, $password);
} catch (SimpleSAML_Error_Error $e) {
+ /*
+ * Login failed. Return the error code to the login form, so that it
+ * can display an error message to the user.
+ */
return $e->getErrorCode();
}
+ /* Save the attributes we received from the login-function in the $state-array. */
+ assert('is_array($attributes)');
$state['Attributes'] = $attributes;
+
+ /* Return control to simpleSAMLphp after successful authentication. */
SimpleSAML_Auth_Source::completeAuth($state);
}
--
GitLab