Google2FA

Google Two-Factor Authentication for PHP

Google2FA is a PHP implementation of the Google Two-Factor Authentication Module, supporting the HMAC-Based One-time Password (HOTP) algorithm specified in RFC 4226 and the Time-based One-time Password (TOTP) algorithm specified in RFC 6238.

---

<p align="center"> <a href="https://packagist.org/packages/pragmarx/google2fa"><img alt="Latest Stable Version" src="https://img.shields.io/packagist/v/pragmarx/google2fa.svg?style=flat-square"></a> <a href="LICENSE.md"><img alt="License" src="https://img.shields.io/badge/license-MIT-brightgreen.svg?style=flat-square"></a> <a href="https://github.com/antonioribeiro/google2fa/actions"><img alt="Build" src="https://img.shields.io/github/actions/workflow/status/antonioribeiro/google2fa/phpunit.yml?style=flat-square"></a> <a href="https://github.com/antonioribeiro/google2fa/actions"><img alt="Static Analysis" src="https://img.shields.io/github/actions/workflow/status/antonioribeiro/google2fa/static-analysis.yml?style=flat-square&label=static-analysis"></a> </p> <p align="center"> <a href="https://codecov.io/gh/antonioribeiro/google2fa"><img alt="Coverage" src="https://img.shields.io/codecov/c/github/antonioribeiro/google2fa/9.x?style=flat-square"></a> <a href="https://packagist.org/packages/pragmarx/google2fa"><img alt="PHP" src="https://img.shields.io/badge/PHP-7.4%20%7C%208.0%20%7C%208.1%20%7C%208.2%20%7C%208.3%20%7C%208.4%20%7C%208.5-green.svg?style=flat-square"></a> <a href="https://packagist.org/packages/pragmarx/google2fa"><img alt="Downloads" src="https://img.shields.io/packagist/dt/pragmarx/google2fa.svg?style=flat-square"></a> </p>

---

Menu

• Version Compatibility
• Google Two-Factor Authentication for PHP
• Laravel bridge
• Demos, Example & Playground
• Requirements
• Installing
• Usage
• How To Generate And Use Two Factor Authentication
• Generating QRCodes
• QR Code Packages
• Examples of Usage
• HMAC Algorithms
• Server Time
• Validation Window
• Using a Bigger and Prefixing the Secret Key
• Google Authenticator secret key compatibility
• Google Authenticator Apps
• Deprecation Warning
• Testing
• Authors
• License
• Contributing

Version Compatibility

PHP | Google2FA :--------|:---------- 7.4 | 8.x & 9.x 8.0 | 8.x & 9.x 8.1 | 8.x & 9.x 8.2 | 8.x & 9.x 8.3 | 8.x & 9.x 8.4 | 8.x & 9.x 8.5 (beta) | 8.x & 9.x

⚠️ Version 9.0.0 Breaking Change

Default Secret Key Length Increased

Version 9.0.0 introduces a breaking change: The default secret key length has been increased from 16 to 32 characters for enhanced security.

What Changed?

• generateSecretKey() now generates 32-character secrets by default (previously 16)
• This increases cryptographic entropy from 80 bits to 160 bits
• Maintains full compatibility with Google Authenticator and other TOTP apps

Migration Guide

If you want to keep the previous behavior (16-character secrets):

// Old default behavior (v8.x and below)
$secret = $google2fa->generateSecretKey();

// New way to get 16-character secrets (v9.0+)
$secret = $google2fa->generateSecretKey(16);

If you want to use the new default (32-character secrets):

// This now generates 32-character secrets by default
$secret = $google2fa->generateSecretKey();

Potential Impact Areas

• Database schemas: Check if your google2fa_secret columns can handle 32 characters
• Validation rules: Update any length validations that expect exactly 16 characters
• Tests: Update test assertions expecting 16-character secrets
• UI components: Ensure QR code displays and secret key fields accommodate longer secrets

Important: Existing 16-character secrets remain fully functional. Database updates are only needed if you want to use the new 32-character default behavior.

Why This Change?

While 16-character secrets meet RFC 6238 minimum requirements, 32-character secrets provide significantly better security:

• 16 chars: 80 bits of entropy (adequate but minimal)
• 32 chars: 160 bits of entropy (much stronger against brute force)

This change aligns with modern security best practices for cryptographic applications.

Laravel bridge

This package is agnostic, but there's a Laravel bridge.

About QRCode generation

This package does not generate QRCodes for 2FA.

If you are looking for Google Two-Factor Authentication, but also need to generate QRCode for it, you can use the Google2FA QRCode package, which integrates this package and also generates QRCodes using the BaconQRCode library, or check options on how to do it yourself here in the docs.

Demos, Example & Playground

Please check the Google2FA Package Playground.

Here's a demo app showing how to use Google2FA: google2fa-example.

You can scan the QR code on this (old) demo page with a Google Authenticator app and view the code changing (almost) in real time.

Requirements

• PHP 7.1 or greater

Installing

Use Composer to install it:

composer require pragmarx/google2fa

To generate inline QRCodes, you'll need to install a QR code generator, e.g. BaconQrCode:

composer require bacon/bacon-qr-code

Usage

Instantiate it directly

use PragmaRX\Google2FA\Google2FA;

$google2fa = new Google2FA();

return $google2fa->generateSecretKey();

How To Generate And Use Two Factor Authentication

Generate a secret key for your user and save it:

// Generates a 32-character secret key (v9.0.0+ default)
$user->google2fa_secret = $google2fa->generateSecretKey();

// Or explicitly specify 16 characters for compatibility
$user->google2fa_secret = $google2fa->generateSecretKey(16);

Generating QRCodes

The more secure way of creating QRCode is to do it yourself or using a library. First you have to install a QR code generator e.g. BaconQrCode, as stated above, then you just have to generate the QR code url using:

$qrCodeUrl = $google2fa->getQRCodeUrl(
    $companyName,
    $companyEmail,
    $secretKey
);

Once you have the QR code url, you can feed it to your preferred QR code generator.

// Use your own QR Code generator to generate a data URL:
$google2fa_url = custom_generate_qrcode_url($qrCodeUrl);

/// and in your view:

<img src="{{ $google2fa_url }}" alt="">

And to verify, you just have to:

$secret = $request->input('secret');

$valid = $google2fa->verifyKey($user->google2fa_secret, $secret);

QR Code Packages

This package suggests the use of Bacon/QRCode because it is known as a good QR Code package, but you can use it with any other package, for instance Google2FA QRCode, Simple QrCode or Endroid QR Code, all of them use Bacon/QRCode to produce QR Codes.

Usually you'll need a 2FA URL, so you just have to use the URL generator:

$google2fa->getQRCodeUrl($companyName, $companyEmail, $secretKey)

Examples of Usage

Google2FA QRCode

Get a QRCode to be used inline:

$google2fa = (new \PragmaRX\Google2FAQRCode\Google2FA());

$inlineUrl = $google2fa->getQRCodeInline(
    'Company Name',
    'company@email.com',
    $google2fa->generateSecretKey()
);

And use in your template:

<img src="{{ $inlineUrl }}">

Simple QrCode

<div class="visible-print text-center">
    {!! QrCode::size(100)->generate($google2fa->getQRCodeUrl($companyName, $companyEmail, $secretKey)); !!}
    <p>Scan me to return to the original page.</p>
</div>

Endroid QR Code Generator

Generate the data URL

$qrCode = new \Endroid\QrCode\QrCode($value);
$qrCode->setSize(100);
$google2fa_url = $qrCode->writeDataUri();

And in your view

<div class="visible-print text-center">
    {!! $google2fa_url !!}
    <p>Scan me to return to the original page.</p>
</div>

Bacon/QRCode

<?php

use PragmaRX\Google2FA\Google2FA;
use BaconQrCode\Renderer\ImageRenderer;
use BaconQrCode\Renderer\Image\ImagickImageBackEnd;
use BaconQrCode\Renderer\RendererStyle\RendererStyle;
use BaconQrCode\Writer;

$google2fa = app(Google2FA::class);

$g2faUrl = $google2fa->getQRCodeUrl(
    'pragmarx',
    'google2fa@pragmarx.com',
    $google2fa->generateSecretKey()
);

$writer = new Writer(
    new ImageRenderer(
        new RendererStyle(400),
        new ImagickImageBackEnd()
    )
);

$qrcode_image = base64_encode($writer->writeString($g2faUrl));

And show it as an image:

<img src="data:image/png;base64, <?php echo $qrcode_image; ?> "/>