Refactor Login controller and auth to be more modular and easier to extend/override. Added extra method to Auth interface and documented Auth interface completely. Created new PasswordResetter class to contain password reset logic.

1 files changed, 54 insertions, 16 deletions

diff --git a/core/Auth.php b/core/Auth.php
index 6ae99687b3..5243290a81 100644
--- a/core/Auth.php
+++ b/core/Auth.php
@@ -9,49 +9,87 @@
 
 namespace Piwik;
 
+use Exception;
+
 /**
- * Base for authentication modules
+ * Base for authentication implementations. Plugins that provide Auth implementations
+ * must provide a class that implements this interface. Additionally, an instance
+ * of that class must be set in the {@link \Piwik\Registry} class with the 'auth'
+ * key during the {@link Request.initAuthenticationObject} event.
+ *
+ * Authentication implementations must support authentication via username and
+ * clear-text password and authentication via username and token auth. They can
+ * additionally support authentication via username and an MD5 hash of a password. If
+ * they don't support it, then formless authentication will fail.
+ *
+ * Derived implementations should favor authenticating by password over authenticating
+ * by token auth. That is to say, if a token auth and a password are set, password
+ * authentication should be used.
+ *
+ * @api
  */
 interface Auth
 {
     /**
-     * Authentication module's name, e.g., "Login"
+     * Must return the Authentication module's name, e.g., `"Login"`.
      *
      * @return string
      */
     public function getName();
 
     /**
-     * Authenticates user
+     * Sets the authentication token to authenticate with.
      *
-     * @return AuthResult
+     * @param string $token_auth authentication token
      */
-    public function authenticate();
+    public function setTokenAuth($token_auth);
 
     /**
-     * Authenticates the user and initializes the session.
+     * Sets the login name to authenticate with.
+     *
+     * @param string $login The username.
      */
-    public function initSession($login, $md5Password, $rememberMe);
+    public function setLogin($login);
 
     /**
-     * Accessor to set authentication token. If set, you can authenticate the tokenAuth by calling the authenticate()
-     * method afterwards.
+     * Sets the password to authenticate with.
      *
-     * @param string $token_auth authentication token
+     * @param string $password Password (not hashed).
      */
-    public function setTokenAuth($token_auth);
+    public function setPassword($password);
 
     /**
-     * Accessor to set login name
+     * Sets the hash of the password to authenticate with. The hash will be an MD5 hash.
      *
-     * @param string $login user login
+     * @param string $passwordHash The hashed password.
+     * @throws Exception if authentication by hashed password is not supported.
      */
-    public function setLogin($login);
+    public function setPasswordHash($passwordHash);
+
+    /**
+     * Authenticates a user using the login and password set using the setters. Can also authenticate
+     * via token auth if one is set and no password is set.
+     *
+     * @return AuthResult
+     */
+    public function authenticate();
+
+    /**
+     * Authenticates the user using login and password and initializes an authenticated session.
+     *
+     * @param bool $rememberMe Whether the user should be remembered by setting a client side cookie
+     *                         or not.
+     *
+     *                         TODO: maybe this logic should be handled by Login\Controller?
+     */
+    public function initSession($rememberMe);
 }
 
 /**
- * Authentication result
+ * Authentication result. This is what is returned by authentication attempts using {@link Auth}
+ * implementations.
  *
+ * @api
  */
 class AuthResult
 {
@@ -144,4 +182,4 @@ class AuthResult
     {
         return $this->code > self::FAILURE;
     }
-}
+}
\ No newline at end of file