lahthony/otp-auth-bundle

TOTP authentification

1.2.4 2017-12-08 15:30 UTC

Requires

• php: ^5.5.9 || ^7.0
• doctrine/doctrine-bundle: ^1.8
• doctrine/orm: ^2.5
• spomky-labs/otphp: ^9.0
• swiftmailer/swiftmailer: ^5.0 || ^6.0
• symfony/form: ^2.8 || ^3.0
• symfony/framework-bundle: ^2.8 || ^3.0
• symfony/security-bundle: ^2.8 || ^3.0
• symfony/templating: ^2.8 || ^3.0
• symfony/twig-bundle: ^2.8 || ^3.0
• twig/twig: ^1.28 || ^2.0

Requires (Dev)

• php-coveralls/php-coveralls: ^1.0
• phpunit/phpunit: ^6.4

MIT

• Lahcen
• Anthony

README

About :

This bundle permits to easy implements 2 factor authentication in a symfony project.

Users will then get TOTP authentication by using apps like Google Authenticator

Let's get started. Just go through the following steps.

Step 1: Download the Bundle

Open a command console, enter your project directory and execute the following command to download the latest stable version of this bundle:

$ composer require lahthony/otp-auth-bundle

This command requires you to have Composer installed globally, as explained in the installation chapter of the Composer documentation.

Step 2: Enable the Bundle

Then, enable the bundle by adding it to the list of registered bundles in the app/AppKernel.php file of your project:

<?php
// app/AppKernel.php

// ...
class AppKernel extends Kernel
{
    public function registerBundles()
    {
        $bundles = array(
            // ...
            new LahthonyOTPAuthBundle\LahthonyOTPAuthBundle(),
        );

        // ...
    }

    // ...
}

Then you will need to update the service.yml

    YourBundle\:
        resource: '../../src/YourBundle/*'
        #Remove the folder Entity From exclude folder 
        exclude: '../../src/YourBundle/{Repository,Tests}'

Step 3: Implements OTPAuthInterface

You need to implement the OTPAuthInterface on your User Entity commonly present in src/AppBundle/Entity/User.

⚠️ Do not forget to generate getter setter. ⚠️

<?php
//src/AppBundle/Entity/User

use LahthonyOTPAuthBundle\Model\OTPAuthInterface;
//...

class User implements OTPAuthInterface
{
    /**
     * This attribute needs to be stock in Database
     * @var string 
     * @ORM\Column(name="secret_auth_key", type="string", length=255, nullable=true)
     */
    private $secretAuthKey;

    /**
     * This attribute needs to be stocked in Database   
     * @var string
     * @ORM\Column(name="recovery_key", type="string", length=255, nullable=true)
     */
    private $recoveryKey;
    
    
    /**
     * This attribute will permit to do verification on user registration 
     * if he accepts 2Factor Authentication 
     * @var boolean
     */
    private $OTP2Auth;
    
  
    /**
     * !!! DO NOT FORGET TO GENERATE GETTER AND SETTER FOR THESE THREE ATTRIBUTES !!! 
     */
    
    //We'll need email and password for the OTP Authentication reset
    public function getEmail(){}
    public function getPassword(){}
        
}

⚠️ After that DO NOT FORGET to schema update: ⚠️

$ php bin/console doctrine:schema:update --force

Step 4: Add one field to your UserFormType

We've made for you an eventsubscriber that permits you to add the required field easily on yourUserFormType.

You can add it on your UserEditType too if you want to permit your users to enable or disable OTP Authentication after he has registered.

Just do like so:

For User Registration:

<?php
//src/AppBundle/Form/UserType

use LahthonyOTPAuthBundle\Form\EventSubscriber\Add2FactorAuthFieldSubscriber;
//...

class UserType 
{
    public function buildForm(FormBuilderInterface $builder, array $options)
    {
        $builder
            //...
            ->addEventSubscriber(new Add2FactorAuthFieldSubscriber())
        ;
    }
    //...
}

For User Edit:

//src/AppBundle/Form/UserEditType

use LahthonyOTPAuthBundle\Form\EventSubscriber\Add2FactorAuthFieldSubscriber;
//...

class UserType 
{
    public function buildForm(FormBuilderInterface $builder, array $options)
    {
        $builder
            //...
            ->addEventSubscriber(new Add2FactorAuthFieldSubscriber())
        ;
    }
    //...
}

Step 5: Update your Login Form And your homepage

You need now to add one field one your login form and the link to reset the authenticator

<!--login login.html.twig -->
<form>
    <label for="otp">Code OTP(optionnal if you haven't accept 2factorAuth)</label>
    <input type="text" name="otp">
</form>
<a href="{{ path('lahthony_otp_ask_recovery') }}">I've lost my OTP Authenticator.</a>

<!-- homepage index.html.twig -->
    <div class="flash-notice">
        {% for message in app.flashes('2factor') %}
            {{ message|raw }}
        {% endfor %}
        {% for message in app.flashes('reset') %}
            {{ message }}
        {% endfor %}
    </div>

Step 6: Import Routes

In your routing.yml import routes from our bundle :

lahthony_otp_auth_recovery:
    resource: "@LahthonyOTPAuthBundle/Resources/config/routing.xml"

Step 7: Enjoy

• You can now try it. First create a user that accepts the 2Factor Authentication.

• Then a flash message will appears on your homepage with the QRCode and the Recovery Pass.

  ⚠️ Don't forget to wrote it down the Recovery Pass if you want to recover an account that has lost its authenticator. ⚠️

  Scan the QRCode with an otp app like Google Authenticator dowload it here

• Go on the login page and enter the generated code on your app to connect.

• You can now update it from your user edit ask to disable it.

• That's magic right ?! Hope you like it; feel free to give us feed backs and report bugs. We'd like to know your opinion.

Configuration

If you want to redefine default configuration add this to your app/config/config.yml

lahthony_otp_auth:
    digest_algo:
        sha1 #algorithm
    digit:
        6 #the output will generate 6 digit 
    period:
        30 #period for the timer
    issuer:
        'your_website_name'
    image:
         null
    roles: []