hiqdev/yii2-mfa

Multi-factor authentication for Yii2 projects

Yii2 MFA

Multi-factor authentication for Yii2 projects, _(*1)

, _(*2)

This package provides:, _(*3)

• TOTP - Time-based One-time Password Algorithm used for two factor authentication
• checking for user allowed IPs
• generation and checking recovery codes (PLANNED)

Uses:, _(*4)

• robthree/twofactorauth for TOTP
• hiqdev/php-confirmator for confirmation tokens

Can be plugged into any exising Yii2 project. See how it is used in hiqdev/hiam., _(*5)

Installation

The preferred way to install this yii2-extension is through composer., _(*6)

Either run, _(*7)

php composer.phar require "hiqdev/yii2-mfa"

or add, _(*8)

"hiqdev/yii2-mfa": "*"

to the require section of your composer.json., _(*9)

Configuration

This extension provides pluggable configuration to be used with composer-config-plugin., _(*10)

Also you can use it usual way by copy-pasting config. See src/config/web.php for configuration example., _(*11)

Available configuration parameters:, _(*12)

• organization.name

For more details please see src/config/params.php., _(*13)

Usage

This plugin provides behavior and configuration attaches it to user component on beforeLogin event. And then the behavior validates IPs and TOTP on every login., _(*14)

To use this plugin you have to instantiate your \Yii->app->user->identity class from hiqdev\yii2\mfa\base\MfaIdentityInterface and implement all of the methods, which will return or set MFA properties. For example:, _(*15)

use hiqdev\yii2\mfa\base\MfaIdentityInterface;

class Identity implements MfaIdentityInterface
{
    ...

    /**
     * @inheritDoc
     */
    public function getUsername(): string
    {
        return $this->username;
    }

    /**
     * @inheritDoc
     */
    public function getTotpSecret(): string
    {
        return $this->totp_secret ?? '';
    }

    ...

IPs and TOTP functions are independent and you can provide just one of properties to have only corresponding functionality., _(*16)

Usage with OAuth2

Also there is a configuration to provide MFA for OAuth2., _(*17)

• Require suggested "bshaffer/oauth2-server-php": '~1.7' package, _(*18)

• Use hiqdev\yii2\mfa\GrantType\UserCredentials for configuring /oauth/token command via totp code. For example:, _(*19)

  'modules' => [ 'oauth2' => [ 'grantTypes' => [ 'user_credentials' => [ 'class' => \hiqdev\yii2\mfa\GrantType\UserCredentials::class, ], ], ], ], _(*20)

• Extend you Identity class from ApiMfaIdentityInterface., _(*21)

• Use actions:, _(*22)

  POST /mfa/totp/api-temporary-secret - Proviedes temporary secret to generate QR-code POST /mfa/totp/api-enable - Enables totp POST /mfa/totp/api-disable - Disables totp, _(*23)

Back redirection

For any MFA route, you can add a GET param ?back=https://some.site.com. It will redirect the user after a successful operation to the needed site. To avoid open redirect vulnerability, you need to validate the back param., _(*24)

It should be done with \hiqdev\yii2\mfa\validator\BackUrlValidatorInterface which has a default implementation. You have to create your own and reinitialize it with the container definition:, _(*25)

config/web.php:, _(*26)

'container' => [
   'singletons' => [
       \hiqdev\yii2\mfa\validator\BackUrlValidatorInterface::class => \your\own\validator::class,
    ],
],

License

This project is released under the terms of the BSD-3-Clause license. Read more here., _(*27)

Copyright © 2016-2018, HiQDev (http://hiqdev.com/), _(*28)