finished porting one time password feature after moving some UsrModule properties to behaviors; reverted adding a getter for user component; cleaned up

Author: Jan Was

README.md

@@ -86,6 +86,8 @@ Remember to invalidate the email if it changes in the save() method from the Edi
 
 This interface allows password reset with optional tracking of used passwords. This allows to detect expired passwords and avoid reusing old passwords by users.
 
+See the ExpiredPasswordBehavior description below.
+
 ## Hybridauth
 
 This interface allows finding local identity associated with a remote one (from an external social site) and creating such associations.
@@ -94,71 +96,70 @@ This interface allows finding local identity associated with a remote one (from
 
 This interface allow saving and retrieving a secret used to generate one time passwords. Also, last used password and counter used to generate last password are saved and retrieve to protect against reply attacks.
 
+See the OneTimePasswordFormBehavior description below.
+
 ## Profile Pictures
 
 Allows users to upload a profile picture. The example identity uses [Gravatar](http://gravatar.com/) to provide a default picture.
 
-# Custom behaviors
+## Managable
+
+Allows to manage users:
+
+* update their profiles (and pictures)
+* change passwords
+* assign authorization roles
+* activate/disable and mark email as verified
+* see details as timestamps of account creation, last profile update and last visit
+
+# Custom login behaviors
+
+The login action can be extended by attaching custom behaviors to the LoginForm. This is done by configuring the UsrModule.loginFormBehaviors property.
 
-Do akcji logowania można podpinać dodatkowe Behaviory za pomocą zdefiniowania właściwości loginFormBehaviors w konfiguracji modułu. Pozwalają one na dodanie własnej logiki do operacji logowania uzytkowników.
+There are two such behaviors provided by yii-usr module:
 
-## Moduł dostarcza 2 wbudowane behaviory:
 * ExpiredPasswordBehavior
 * OneTimePasswordFormBehavior
 
 ### ExpiredPasswordBehavior
 
-Obsługuje zachowanie pozwalające na wymuszenie na użytkownikach zmiany hasła co pewien czas.
+Validates if current password has expired and forces the users to change it before logging in.
 
-Dodatkowe parametry:
+Options:
 
-* passwordTimeout - pozwala na zdefiniowanie czasu co jaki powinno zostać zmienione hasło
+* passwordTimeout - number of days after which user is requred to reset his password after logging in
 
 ### OneTimePasswordFormBehavior
 
-Obsługuję obsługe jednorazowych haseł.
+Two step authentication using one time passwords.
 
-Dodatkowe parametry:
+Options:
 
-* authenticator - 
-* required - boolean Should the user be allowed to log in even if a secret hasn't been generated yet. This only makes sense when mode is 'counter', secrets are generated when registering users and a code is sent via email.
-* timeout - int DEFAULT: -1 Number of seconds for how long is the last verified code valid
-* mode - one of otp mode values: 'otp', 'time', 'counter', 'none' DEFAULT: 'none'. If set to 'time' or 'counter' two step authentication is enabled using one time passwords
+* authenticator - if null, set to a new instance of GoogleAuthenticator class.
+* mode - if set to OneTimePasswordFormBehavior::OTP_TIME or OneTimePasswordFormBehavior::OTP_COUNTER, two step authentication is enabled using one time passwords. Time mode uses codes generated using current time and requires the user to use an external application, like Google Authenticator on Android. Counter mode uses codes generated using a sequence and sends them to user's email.
+* required - should the user be allowed to log in even if a secret hasn't been generated yet (is null). This only makes sense when mode is 'counter', secrets are generated when registering users and a code is sent via email.
+* timeout - Number of seconds for how long is the last verified code valid.
+
+## Example usage
 
-## Przykładowa instalacja behaviorów
 ~~~php
 'loginFormBehaviors' => array(
     'expiredPasswordBehavior' => array(
-        'class' => 'usr.components.ExpiredPasswordBehavior',
+        'class' => 'ExpiredPasswordBehavior',
         'passwordTimeout' => 10,
     ),
     'oneTimePasswordBehavior' => array(
         'class' => 'OneTimePasswordFormBehavior',
         'oneTimePasswordConfig' => array(
-            'authenticator' => $this->googleAuthenticator,
-            'mode' => 'time',
+            'mode' => OneTimePasswordFormBehavior::OTP_TIME,
             'required' => true,
             'timeout' => 123,
         ),
-        'controller' => Yii::app()->controller,
-    ),
-    'myCustomBehavior' => array(
-        'class' => 'application.components.MyCustomBehavior',
-        'customBehaviorConf' => 'some value',
     ),
+    // ... other behaviors
 ),
 ~~~
 
-## Managable
-
-Allows to manage users:
-
-* update their profiles (and pictures)
-* change passwords
-* assign authorization roles
-* activate/disable and mark email as verified
-* see details as timestamps of account creation, last profile update and last visit
-
 # User model example
 
 A sample ExampleUserIdentity and corresponding ExampleUser and ExampleUserUsedPassword models along with database migrations are provided respectively in the 'components', 'models' and 'migrations' folders.
@@ -201,7 +202,7 @@ Feel free to send new and updated translations to the author.
 
 # Usage scenarios
 
-Varios scenarios can be created by enabling or disabling following features:
+Various scenarios can be created by enabling or disabling following features:
 
 * registration
 * email verification

UsrModule.php

@@ -35,7 +35,7 @@
  *
  * # Usage scenarios
  *
- * Varios scenarios can be created by enabling or disabling following features:
+ * Various scenarios can be created by enabling or disabling following features:
  *
  * * registration
  * * email verification
@@ -82,12 +82,6 @@
  */
 class UsrModule extends CWebModule
 {
-	const OTP_SECRET_PREFIX = 'UsrModule.oneTimePassword.';
-	const OTP_COOKIE = 'otp';
-	const OTP_NONE = 'none';
-	const OTP_TIME = 'time';
-	const OTP_COUNTER = 'counter';
-
 	/**
 	 * @var boolean Is new user registration enabled.
 	 */
@@ -104,11 +98,6 @@ class UsrModule extends CWebModule
 	 * @var integer For how long the user will be logged in without any activity, in seconds. Defaults to 3600*24*30 seconds (30 days).
 	 */
 	public $rememberMeDuration = 2592000;
-	/**
-	 * @var integer Timeout in days after which user is requred to reset his password after logging in.
-	 * If not null, the user identity class must implement IPasswordHistoryIdentity interface.
-	 */
-	public $passwordTimeout;
 	/**
 	 * @var array Set of rules to measure the password strength when choosing new password in the registration or recovery forms.
 	 * Rules should NOT include attribute name, it will be added when they are used.
@@ -128,7 +117,6 @@ class UsrModule extends CWebModule
 	public $pictureUploadRules;
 	/**
 	 * @var string Class name of user identity object used to authenticate user.
-	 * Must implement the IPasswordHistoryIdentity interface if passwordTimeout is set.
 	 */
 	public $userIdentityClass = 'CUserIdentity';
 	/**
@@ -156,7 +144,8 @@ class UsrModule extends CWebModule
 	 */
 	public $submitButtonCssClass = '';
 	/**
-	 * @var array configuration for PHPMailer, values which are arrays will trigger methods for each value instead of setting properties.
+     * @var array configuration for PHPMailer, values which are arrays will trigger methods
+     * for each value instead of setting properties.
 	 * For a full reference, please resolve to PHPMailer documentation.
 	 */
 	public $mailerConfig = array(
@@ -191,20 +180,29 @@ class UsrModule extends CWebModule
 	 */
 	public $dicewareExtraChar = false;
 	/**
-	 * @var array Available Hybridauth providers, indexed by name, defined as array('enabled'=>true|false, 'keys'=>array('id'=>string, 'key'=>string, 'secret'=>string), 'scope'=>string)
+     * @var array Available Hybridauth providers, indexed by name, defined as
+     * array(
+     *   'enabled'=>true|false,
+     *   'keys'=>array('id'=>string, 'key'=>string, 'secret'=>string),
+     *   'scope'=>string,
+     * )
 	 * @see http://hybridauth.sourceforge.net/userguide.html
 	 */
 	public $hybridauthProviders = array();
     /**
-     * @var array list of identity attribute names that should be passed to UserIdentity::find() to find a local identity matching a remote one.
-     * If one is found, user must authorize to associate it. If none has been found, a new local identity is automatically registered.
+     * @var array list of identity attribute names that should be passed to UserIdentity::find()
+     * to find a local identity matching a remote one.
+     * If one is found, user must authorize to associate it. If none has been found,
+     * a new local identity is automatically registered.
      * If the attribute list is empty a full pre-filled registration and login forms are displayed.
      */
     public $associateByAttributes = array('email');
 
 	/**
-	 * @var array If not null, CAPTCHA will be enabled on the registration and recovery form and this will be passed as arguments to the CCaptcha widget.
-	 * Remember to include the 'captchaAction'=>'/usr/default/captcha' property. Adjust the module id.
+     * @var array If not null, CAPTCHA will be enabled on the registration and recovery form
+     * and this will be passed as arguments to the CCaptcha widget.
+     * Remember to include the 'captchaAction'=>'/usr/default/captcha' property.
+     * Adjust the module id.
 	 */
 	public $captcha;
     /**
@@ -220,12 +218,8 @@ class UsrModule extends CWebModule
     public $loginFormBehaviors;
 
     /**
-     * @var string Name of the user application component
-     */
-    public $userComponent = 'user';
-
-    /**
-     * @var array Scenarios configuration
+     * @var array View params used in different LoginForm model scenarios.
+     * View name can be changed by setting the 'view' key.
      */
     public $scenarios;
 	/**
@@ -339,7 +333,7 @@ public function createFormModel($class, $scenario='')
 	{
 		/** @var CFormModel */
 		$form = new $class($scenario);
-        $form->webUser = $this->getUser();
+        $form->webUser = Yii::app()->user;
 		$form->userIdentityClass = $this->userIdentityClass;
 		if ($form instanceof BasePasswordForm) {
 			$form->passwordStrengthRules = $this->passwordStrengthRules;
@@ -376,9 +370,4 @@ public function createFormModel($class, $scenario='')
 		}
 		return $form;
 	}
-
-    public function getUser()
-    {
-        return Yii::app()->{$this->userComponent};
-    }
 }

components/ExpiredPasswordBehavior.php

@@ -9,19 +9,28 @@
  * ExpiredPasswordBehavior adds captcha validation to a form model component.
  * The model should extend from {@link CFormModel} or its child classes.
  *
+ * The user identity class must implement IPasswordHistoryIdentity interface.
+ *
  * @property CFormModel $owner The owner model that this behavior is attached to.
+ * @property integer $passwordTimeout Number of days after which user is requred to reset his password after logging in.
  *
  * @author Jan Was <[email protected]>
  */
 class ExpiredPasswordBehavior extends FormModelBehavior
 {
 	private $_passwordTimeout;
 
+	/**
+	 * @return integer Number of days after which user is requred to reset his password after logging in.
+	 */
 	public function getPasswordTimeout()
 	{
 		return $this->_passwordTimeout;
 	}
 
+	/**
+	 * @param $value integer Number of days after which user is requred to reset his password after logging in.
+	 */
 	public function setPasswordTimeout($value)
 	{
 		$this->_passwordTimeout = $value;

components/OneTimePasswordAction.php

@@ -6,12 +6,21 @@
  */
 class OneTimePasswordAction extends CAction
 {
+    /**
+     * @var array Same configuration as set for @see OneTimePasswordFormBehavior.
+     */
+    public $configuration = array(
+        'authenticator' => null,
+        'mode'          => null,
+        'required'      => null,
+        'timeout'       => null,
+    );
+
 	public function run() {
-		if ($this->controller->module->getUser()->isGuest)
+		if (Yii::app()->user->isGuest)
 			$this->controller->redirect(array('login'));
 		/** @var UsrModule */
-		$module = $this->controller->module;
-		if ($module->oneTimePasswordRequired)
+		if ($this->configuration['required'])
 			$this->controller->redirect(array('profile'));
 
 		$model = new OneTimePasswordForm;
@@ -22,22 +31,22 @@ public function run() {
 		 */
 		if ($identity->getOneTimePasswordSecret() !== null) {
 			$identity->setOneTimePasswordSecret(null);
-			Yii::app()->request->cookies->remove(UsrModule::OTP_COOKIE);
+			Yii::app()->request->cookies->remove(OneTimePasswordFormBehavior::OTP_COOKIE);
 			$this->controller->redirect('profile');
 			return;
 		}
 
-		$model->setMode($module->oneTimePasswordMode)->setAuthenticator($module->googleAuthenticator);
+		$model->setMode($this->configuration['mode'])->setAuthenticator($this->configuration['authenticator']);
 
 		/**
 		 * When no secret has been set yet, generate a new secret and save it in session.
 		 * Do it if it hasn't been done yet.
 		 */
-		if (($secret=Yii::app()->session[UsrModule::OTP_SECRET_PREFIX.'newSecret']) === null) {
-			$secret = Yii::app()->session[UsrModule::OTP_SECRET_PREFIX.'newSecret'] = $module->googleAuthenticator->generateSecret();
+		if (($secret=Yii::app()->session[OneTimePasswordFormBehavior::OTP_SECRET_PREFIX.'newSecret']) === null) {
+			$secret = Yii::app()->session[OneTimePasswordFormBehavior::OTP_SECRET_PREFIX.'newSecret'] = $this->configuration['authenticator']->generateSecret();
 
 			$model->setSecret($secret);
-			if ($module->oneTimePasswordMode === UsrModule::OTP_COUNTER) {
+			if ($this->configuration['mode'] === OneTimePasswordFormBehavior::OTP_COUNTER) {
 				$this->controller->sendEmail($model, 'oneTimePassword');
 			}
 		}
@@ -48,23 +57,27 @@ public function run() {
 			if ($model->validate()) {
 				// save secret
 				$identity->setOneTimePasswordSecret($secret);
-				Yii::app()->session[UsrModule::OTP_SECRET_PREFIX.'newSecret'] = null;
+				Yii::app()->session[OneTimePasswordFormBehavior::OTP_SECRET_PREFIX.'newSecret'] = null;
 				// save current code as used
-				$identity->setOneTimePassword($model->oneTimePassword, $module->oneTimePasswordMode === UsrModule::OTP_TIME ? floor(time() / 30) : $model->getPreviousCounter() + 1);
+				$identity->setOneTimePassword($model->oneTimePassword, $this->configuration['mode'] === OneTimePasswordFormBehavior::OTP_TIME ? floor(time() / 30) : $model->getPreviousCounter() + 1);
 				$this->controller->redirect('profile');
 			}
 		}
 		if (YII_DEBUG) {
-			$model->oneTimePassword = $module->googleAuthenticator->getCode($secret, $module->oneTimePasswordMode === UsrModule::OTP_TIME ? null : $model->getPreviousCounter());
+			$model->oneTimePassword = $this->configuration['authenticator']->getCode($secret, $this->configuration['mode'] === OneTimePasswordFormBehavior::OTP_TIME ? null : $model->getPreviousCounter());
 		}
 
-		if ($module->oneTimePasswordMode === UsrModule::OTP_TIME) {
+		if ($this->configuration['mode'] === OneTimePasswordFormBehavior::OTP_TIME) {
 			$hostInfo = Yii::app()->request->hostInfo;
 			$url = $model->getUrl($identity->username, parse_url($hostInfo, PHP_URL_HOST), $secret);
 		} else {
 			$url = '';
 		}
 
-		$this->controller->render('generateOTPSecret', array('model'=>$model, 'url'=>$url));
+        $this->controller->render('generateOTPSecret', array(
+            'model' => $model,
+            'url'   => $url,
+            'mode'  => $this->configuration['mode'],
+        ));
 	}
 }