Yii2 MFA ¶

1. About it
2. Requirements
3. Installation
4. Usage

About it ¶

An extension support implementing multi factor authenticate base on Spomky-Labs/otphp wrapper for Yii2 user component.

Requirements ¶

• PHP >= 7.1
• yiisoft/yii2 >= 2.0.13

Installation ¶

Require Yii2 MFA using Composer:

composer require vxm/yii2-mfa

Usage ¶

App config ¶

'components' => [
    'user' => [
        'as mfa' => [
            'class' => 'vxm\mfa\Behavior',
            'verifyUrl' => 'site/mfa-verify' // verify action, see bellow for setup it
        ]
    ],
]

Identity implementing ¶

When use it, your identity class must be implementing vxm\mfa\IdentityInterface this interface extends from yii\web\IdentityInterface add getMfaSecretKey(), this method return a mfa key of an identity use for generate and validate otp or return null if mfa disabled on an identity.

use yii\db\ActiveRecord;

use vxm\mfa\IdentityInterface;

/**
* @property string $mfa_secret
*/
class User extends ActiveRecord implements IdentityInterface 
{

    public function getMfaSecretKey()
    {
        return $this->mfa_secret;
    }

}

Verify action config ¶

This action use to redirect user when user login and need to be verify mfa otp. Config it in to actions method of your controller

public function actions()
{
    return [
        'mfa-verify' => [
            'class' => 'vxm\mfa\VerifyAction',
            'viewFile' => 'mfa-verify', // the name of view file use to render view. If not set an action id will be use, in this case is `mfa-verify`
            'formVar' => 'model', // the name of variable use to parse [[\vxm\mfa\OtpForm]] object to view file.
            'retry' => true, // allow user retry when type wrong otp
            'successCallback' => [$this, 'mfaPassed'], // callable call when user type valid otp if not set [[yii\web\Controller::goBack()]] will be call.
            'invalidCallback' => [$this, 'mfaOtpInvalid'], // callable call when user type wrong otp if not set and property `retry` is false [[yii\web\User::loginRequired()]] will be call, it should be use for set flash notice to user.
            'retry' => true, // allow user retry when type wrong otp
        ]
    ];
}

After setup verify action, you need create a view (mfa-verify) in this view have a variable model is instance of vxm\mfa\OtpForm use to create a form submit an otp

/**
* @var \vxm\mfa\OtpForm $model
*/

use yii\helpers\Html;
use yii\widgets\ActiveForm;

$form = ActiveForm::begin();

echo Html::tag('h1', 'Multi factor authenticate');

echo $form->field($model, 'otp');

echo Html::submitButton('Verify');

ActiveForm::end();

QR Code widget for authenticator ¶

After setup all, when user enabled mfa (mfaSecretKey is set) you need to provide a qr code for app like google authenticator to generate an otp. Use vxm\mfa\QrCodeWidget to render a qr code image in view

use vxm\mfa\QrCodeWidget;


echo QrCodeWidget::widget([
    'label' => Yii::$app->user->identity->email,
    'issuer' => Yii::$app->name
]);

Notice: when use this widget ensure user had been logged in, if not an yii\base\InvalidCallException will be throw.