email.md

Email Authentication

A two-factor provider to generate a random numeric code and send it to the user via email.

How authentication works

On successful authentication it generates a random number and persist it in the user entity. The number is sent to the user via email. Then the user must enter that number to gain access.

The number of digits can be configured:

# config/packages/scheb_two_factor.yaml
scheb_two_factor:
    email:
        digits: 6

Prerequisites

Install the mailer component:

composer require symfony/swiftmailer-bundle

Alternatively, you can use symfony/mailer, but then you have to implement a custom mailer class (see below), since the default mailer coming with the bundle only works with Swiftmailer.

You may want to upgrade to bundle version 5 (available from scheb/2fa) as it supports symfony/mailer out-of-the-box.

Basic Configuration

To enable this authentication method add this to your configuration:

# config/packages/scheb_two_factor.yaml
scheb_two_factor:
    email:
        enabled: true
        sender_email: [email protected]
        sender_name: John Doe  # Optional

Your user entity has to implement Scheb\TwoFactorBundle\Model\Email\TwoFactorInterface. The authentication code must be persisted, so make sure that it is stored in a persisted field.

<?php

namespace Acme\DemoBundle\Entity;

use Doctrine\ORM\Mapping as ORM;
use Scheb\TwoFactorBundle\Model\Email\TwoFactorInterface;
use Symfony\Component\Security\Core\User\UserInterface;

class User implements UserInterface, TwoFactorInterface
{
    /**
     * @ORM\Column(type="string")
     */
    private $email;

    /**
     * @ORM\Column(type="integer", nullable=true)
     */
    private $authCode;

    // [...]

    public function isEmailAuthEnabled(): bool
    {
        return true; // This can be a persisted field to switch email code authentication on/off
    }

    public function getEmailAuthRecipient(): string
    {
        return $this->email;
    }

    public function getEmailAuthCode(): string
    {
        return $this->authCode;
    }

    public function setEmailAuthCode(string $authCode): void
    {
        $this->authCode = $authCode;
    }
}

Configuration Reference

# config/packages/scheb_two_factor.yaml
scheb_two_factor:
    email:
        enabled: true                  # If email authentication should be enabled, default false
        mailer: acme.custom_mailer_service  # Use alternative service to send the authentication code
        code_generator: acme.custom_code_generator_service  # Use alternative service to generate authentication code
        sender_email: [email protected]   # Sender email address
        sender_name: John Doe          # Sender name
        digits: 4                      # Number of digits in authentication code
        template: security/2fa_form.html.twig   # Template used to render the authentication form

Custom Mailer

By default the email is plain text and very simple. If you want a different style (e.g. HTML) you have to create your own mailer service. It must implement Scheb\TwoFactorBundle\Mailer\AuthCodeMailerInterface.

<?php

namespace Acme\DemoBundle\Mailer;

use Scheb\TwoFactorBundle\Model\Email\TwoFactorInterface;
use Scheb\TwoFactorBundle\Mailer\AuthCodeMailerInterface;

class MyAuthCodeMailer implements AuthCodeMailerInterface
{
    // [...]

    public function sendAuthCode(TwoFactorInterface $user): void
    {
        $authCode = $user->getEmailAuthCode();

        // Send email
    }
}

Then register it as a service and update your configuration:

# config/packages/scheb_two_factor.yaml
scheb_two_factor:
    email:
        mailer: acme.custom_mailer_service

Re-send Authentication Code

When you're using the default authentication code generator that is coming with the bundle, there's an easy way to re-send the email with the authentication code. Get/inject service scheb_two_factor.security.email.code_generator and call method reSend(\Scheb\TwoFactorBundle\Model\Email\TwoFactorInterface $user).

Custom Code Generator

If you want to have the code generated differently, you can have your own code generator. Create a service implementing Scheb\TwoFactorBundle\Security\TwoFactor\Provider\Email\Generator\CodeGeneratorInterface and register it in the configuration:

# config/packages/scheb_two_factor.yaml
scheb_two_factor:
    email:
        code_generator: acme.custom_code_generator_service

Custom Authentication Form Template

The bundle uses Resources/views/Authentication/form.html.twig to render the authentication form. If you want to use a different template you can simply register it in configuration:

# config/packages/scheb_two_factor.yaml
scheb_two_factor:
    email:
        template: security/2fa_form.html.twig