Google Authenticator
Warning: You are browsing the documentation for version 5.x which is not maintained anymore. If some of your projects are still using this version, consider upgrading.
Google Authenticator
Google Authenticator is a popular implementation of a TOTP algorithm to generate authentication codes. Compared to the TOTP two-factor provider, the implementation has a fixed configuration, which is necessary to be compatible with the Google Authenticator app:
- it generates 6-digit codes
- the code changes every 30 seconds
- It uses the sha1 hashing algorithm
If you need different settings, please use the TOTP two-factor provider. Be warned that custom TOTP configurations likely won't be compatible with the Google Authenticator app.
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
. 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(name="googleAuthenticatorSecret", type="string", nullable=true)
*/
private $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
window: 1 # How many codes before/after the current one would be accepted as valid
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
:
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
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);
To render the QR code as an image, install scheb/2fa-qr-code
:
1
composer require scheb/2fa-qr-code
Use service scheb_two_factor.qr_code_generator
to get the QR code image. Auto-wiring of
Scheb
is also possible. You need to implement a small
controller to display the image in your application.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23
<?php
namespace App\Controller;
use Scheb\TwoFactorBundle\Security\TwoFactor\QrCode\QrCodeGenerator;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Annotation\Route;
class QrCodeController extends AbstractController
{
/**
* @Route("/qr-code", name="qr_code")
*/
public function displayGoogleAuthenticatorQrCode(QrCodeGenerator $qrCodeGenerator)
{
// $qrCode is provided by the endroid/qr-code library. See the docs how to customize the look of the QR code:
// https://github.com/endroid/qr-code
$qrCode = $qrCodeGenerator->getGoogleAuthenticatorQrCode($this->getUser());
return new Response($qrCode->writeString(), 200, ['Content-Type' => 'image/png']);
}
}
Caution
Security note: Keep the QR code content within your application. Render the image yourself. Do not pass the content to an external service, because this is exposing the secret code to that service.