TWO-FACTOR-AUTHENTICATION.md

Two factor authentication

You can use Controller that provides two factor authentication. You need to pass Token\Repository and Wearesho\Token\Generator in addition to base controller settings

Configuration

<?php

use Wearesho\Yii2\Authentication;
use Wearesho\Yii2\Authorization;
use Wearesho\Yii2\Token;
use Wearesho\Token\Generator;

return [
    'controllerMap' => [
        'auth' => [
            'class' => Authentication\TwoFactor\Controller::class, 
            'identityClass' => YourIdentityClass::class,
            'repository' => Authorization\Repository::class,
            'tokenRepository' => Token\Repository::class,
            'tokenGenerator' => new Generator\Numeric($length = 6), // Your Generator definition 
        ],
    ],
];

After confirmation token is being created, an event EVENT_AFTER_CREATE will be triggered in LoginForm. You can add listeners to this event to implement custom logic of token delivery.

<?php

// bootstrap.php

\yii\base\Event::on(\Wearesho\Yii2\Authentication\TwoFactor\LoginForm::EVENT_AFTER_CREATE, function ($event) {
    $tokenValue = $event->getValue();
    // custom logic
});

API

Two-factor controller API extends base controller API with override of POST method and additional PATCH method.

POST

This action is used to check passed credentials and generate confirmation token for two factor authentication

• Body params

{
  "LoginForm": {
    "login": "login value",
    "password": "password value"
  }
}

• Response 202 - When first factor is completed. You will receive hash, that should be passed into the second step request

{
  "hash": "hash to identify created token in second step"
}

• Response 400 - When something went wrong

PATCH

This action is used to confirm authentication with token value

• Body params

{
  "ConfirmForm": {
    "hash": "hash value that has been returned in first stage",
    "value": "filled token value"
  }
}

• Response 202 - When authentication is completed

{
  "id": "returned user id, integer value",
  "access": "access token",
  "refresh": "refresh token"
}

• Response 400 - Required params are missing or invalid

• Response 409 - When hash and token were correct, but token owner was not found by system