Google Authenticator

How authentication works

The user has to link their account to the Google Authenticator app first. This is done by generating a shared secret code, which is stored in the user entity. Users add the code to the Google Authenticator app either by manually typing it in, or scanning a QR which automatically transfers the information.

On successful authentication the bundle checks if there is a secret stored in the user entity. If that's the case, it will ask for the authentication code. The user must enter the code currently shown in the Google Authenticator app to gain access.

For more information see the Google Authenticator website.

Installation

To make use of this feature, you have to install scheb/2fa-google-authenticator.

1

composer require scheb/2fa-google-authenticator

Basic Configuration

To enable this authentication method add this to your configuration:

1
2
3
4

# config/packages/scheb_2fa.yaml
scheb_two_factor:
    google:
        enabled: true

Your user entity has to implement Scheb\TwoFactorBundle\Model\Google\TwoFactorInterface. To activate Google Authenticator for a user, generate a secret code and persist it with the user entity.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

<?php

namespace Acme\Demo\Entity;

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

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

    // [...]

    public function isGoogleAuthenticatorEnabled(): bool
    {
        return null !== $this->googleAuthenticatorSecret;
    }

    public function getGoogleAuthenticatorUsername(): string
    {
        return $this->username;
    }

    public function getGoogleAuthenticatorSecret(): ?string
    {
        return $this->googleAuthenticatorSecret;
    }

    public function setGoogleAuthenticatorSecret(?string $googleAuthenticatorSecret): void
    {
        $this->googleAuthenticatorSecret = $googleAuthenticatorSecret;
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

<?php

namespace Acme\Demo\Entity;

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

class User implements UserInterface, TwoFactorInterface
{
   #[ORM\Column(type: 'string', nullable: true)]
   private ?string $googleAuthenticatorSecret;

   // [...]

   public function isGoogleAuthenticatorEnabled(): bool
   {
       return null !== $this->googleAuthenticatorSecret;
   }

   public function getGoogleAuthenticatorUsername(): string
   {
       return $this->username;
   }

   public function getGoogleAuthenticatorSecret(): ?string
   {
       return $this->googleAuthenticatorSecret;
   }

   public function setGoogleAuthenticatorSecret(?string $googleAuthenticatorSecret): void
   {
       $this->googleAuthenticatorSecret = $googleAuthenticatorSecret;
   }
}

Configuration Reference

1
2
3
4
5
6
7
8
9

# config/packages/scheb_2fa.yaml
scheb_two_factor:
    google:
        enabled: true                  # If Google Authenticator should be enabled, default false
        server_name: Server Name       # Server name used in QR code
        issuer: Issuer Name            # Issuer name used in QR code
        digits: 6                      # Number of digits in authentication code
        leeway: 0                      # Acceptable time drift in seconds, must be less or equal than 30 seconds
        template: security/2fa_form.html.twig   # Template used to render the authentication form

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:

1
2
3
4

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

Custom Form Rendering

There are certain cases when it's not enough to just change the template. For example, you're using two-factor authentication on multiple firewalls and you need to render the form differently for each firewall. In such a case you can implement a form renderer to fully customize the rendering logic.

Create a class implementing Scheb\TwoFactorBundle\Security\TwoFactor\Provider\TwoFactorFormRendererInterface:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

<?php

namespace Acme\Demo\FormRenderer;

use Scheb\TwoFactorBundle\Security\TwoFactor\Provider\TwoFactorFormRendererInterface;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;

class MyFormRenderer implements TwoFactorFormRendererInterface
{
    // [...]

    public function renderForm(Request $request, array $templateVars): Response
    {
        // Customize form rendering
    }
}

Then register it as a service and update your configuration:

1
2
3
4

# config/packages/scheb_2fa.yaml
scheb_two_factor:
    google:
        form_renderer: acme.custom_form_renderer_service

Generating a Secret Code

The service scheb_two_factor.security.google_authenticator provides a method to generate new secret for Google Authenticator. Auto-wiring of Scheb\TwoFactorBundle\Security\TwoFactor\Provider\Google\GoogleAuthenticatorInterface is also possible.

1

$secret = $container->get("scheb_two_factor.security.google_authenticator")->generateSecret();

QR Codes

To generate a QR code that can be scanned by the Google Authenticator app, retrieve the QR code's content from Google Authenticator service:

1

$qrCodeContent = $container->get("scheb_two_factor.security.google_authenticator")->getQRContent($user);

Use the QR code rendering library of your choice to render a QR code image.

An example how to render the QR code with endroid/qr-code version 4 can be found in the demo application.