PHPackages pragmarx/google2fa - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Authentication & Authorization](/categories/authentication) 4. / 5. pragmarx/google2fa ActiveLibrary[Authentication & Authorization](/categories/authentication) pragmarx/google2fa ================== A One Time Password Authentication package, compatible with Google Authenticator. v9.0.0(8mo ago)2.0k82.4M—7.5%207[3 issues](https://github.com/antonioribeiro/google2fa/issues)[3 PRs](https://github.com/antonioribeiro/google2fa/pulls)20MITPHPPHP ^7.1|^8.0CI passing Since Sep 22Pushed 2mo ago50 watchersCompare [ Source](https://github.com/antonioribeiro/google2fa)[ Packagist](https://packagist.org/packages/pragmarx/google2fa)[ RSS](/packages/pragmarx-google2fa/feed)WikiDiscussions 9.x Synced 1mo ago READMEChangelog (3)Dependencies (3)Versions (50)Used By (20) Google2FA ========= [](#google2fa) Google Two-Factor Authentication for PHP ---------------------------------------- [](#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](https://tools.ietf.org/html/rfc4226) and the Time-based One-time Password (TOTP) algorithm specified in [RFC 6238](https://tools.ietf.org/html/rfc6238). --- [![Latest Stable Version](https://camo.githubusercontent.com/026fa6fff8672d0759d72c5883944b6aff46225e061208e7de1376d0942a3125/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f707261676d6172782f676f6f676c653266612e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/pragmarx/google2fa) [![License](https://camo.githubusercontent.com/55c0218c8f8009f06ad4ddae837ddd05301481fcf0dff8e0ed9dadda8780713e/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d627269676874677265656e2e7376673f7374796c653d666c61742d737175617265)](LICENSE.md) [![Build](https://camo.githubusercontent.com/e61f5a51aa76b20775d635efd28b998b8237152167a81cf7ca90fea013f02a2d/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f616e746f6e696f7269626569726f2f676f6f676c653266612f706870756e69742e796d6c3f7374796c653d666c61742d737175617265)](https://github.com/antonioribeiro/google2fa/actions) [![Static Analysis](https://camo.githubusercontent.com/6c113c6a71c105d301e02a04e6e19c3c9afea16c63105da27768357b1b30a70b/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f616e746f6e696f7269626569726f2f676f6f676c653266612f7374617469632d616e616c797369732e796d6c3f7374796c653d666c61742d737175617265266c6162656c3d7374617469632d616e616c79736973)](https://github.com/antonioribeiro/google2fa/actions) [![Coverage](https://camo.githubusercontent.com/5558aeddeea55c2e813e6d6837a492f64a4fa3a776150ac985263e098e44af7e/68747470733a2f2f696d672e736869656c64732e696f2f636f6465636f762f632f6769746875622f616e746f6e696f7269626569726f2f676f6f676c653266612f392e783f7374796c653d666c61742d737175617265)](https://codecov.io/gh/antonioribeiro/google2fa) [![PHP](https://camo.githubusercontent.com/00cc5eb3efadbda7875f6e7f4730c51f1cd93b32219fa43990361c13a991e8b6/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d372e34253230253743253230382e30253230253743253230382e31253230253743253230382e32253230253743253230382e33253230253743253230382e34253230253743253230382e352d677265656e2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/pragmarx/google2fa) [![Downloads](https://camo.githubusercontent.com/7f5b50da2bd7c035860696bde34af4029ea93ce3bb414b9222134815a75fce5a/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f707261676d6172782f676f6f676c653266612e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/pragmarx/google2fa) --- Menu ---- [](#menu) - [Version Compatibility](#version-compatibility) - [Google Two-Factor Authentication for PHP](#google-two-factor-authentication-for-php) - [Laravel bridge](#laravel-bridge) - [Demos, Example & Playground](#demos-example--playground) - [Requirements](#requirements) - [Installing](#installing) - [Usage](#usage) - [How To Generate And Use Two Factor Authentication](#how-to-generate-and-use-two-factor-authentication) - [Generating QRCodes](#generating-qrcodes) - [QR Code Packages](#qr-code-packages) - [Examples of Usage](#examples-of-usage) - [HMAC Algorithms](#hmac-algorithms) - [Server Time](#server-time) - [Validation Window](#validation-window) - [Using a Bigger and Prefixing the Secret Key](#using-a-bigger-and-prefixing-the-secret-key) - [Google Authenticator secret key compatibility](#google-authenticator-secret-key-compatibility) - [Google Authenticator Apps](#google-authenticator-apps) - [Deprecation Warning](#deprecation-warning) - [Testing](#testing) - [Authors](#authors) - [License](#license) - [Contributing](#contributing) Version Compatibility --------------------- [](#version-compatibility) PHPGoogle2FA7.48.x & 9.x8.08.x & 9.x8.18.x & 9.x8.28.x & 9.x8.38.x & 9.x8.48.x & 9.x8.5 (beta)8.x & 9.x⚠️ Version 9.0.0 Breaking Change -------------------------------- [](#️-version-900-breaking-change) ### Default Secret Key Length Increased [](#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? [](#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 [](#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 [](#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? [](#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 -------------- [](#laravel-bridge) This package is agnostic, but there's a [Laravel bridge](https://github.com/antonioribeiro/google2fa-laravel). About QRCode generation ----------------------- [](#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](https://github.com/antonioribeiro/google2fa-qrcode), 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](#qr-code-packages). Demos, Example & Playground ------------------------------- [](#demos-example--playground) Please check the [Google2FA Package Playground](http://pragmarx.com/playground/google2fa). [![playground](docs/playground.jpg)](docs/playground.jpg) Here's a demo app showing how to use Google2FA: [google2fa-example](https://github.com/antonioribeiro/google2fa-example). You can scan the QR code on [this (old) demo page](https://antoniocarlosribeiro.com/technology/google2fa) with a Google Authenticator app and view the code changing (almost) in real time. Requirements ------------ [](#requirements) - PHP 7.1 or greater Installing ---------- [](#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](https://github.com/Bacon/BaconQrCode): ``` composer require bacon/bacon-qr-code ``` Usage ----- [](#usage) ### Instantiate it directly [](#instantiate-it-directly) ``` use PragmaRX\Google2FA\Google2FA; $google2fa = new Google2FA(); return $google2fa->generateSecretKey(); ``` How To Generate And Use Two Factor Authentication ------------------------------------------------- [](#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 ------------------ [](#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: ``` And to verify, you just have to: ``` $secret = $request->input('secret'); $valid = $google2fa->verifyKey($user->google2fa_secret, $secret); ``` QR Code Packages ---------------- [](#qr-code-packages) This package suggests the use of [Bacon/QRCode](https://github.com/Bacon/BaconQrCode) because it is known as a good QR Code package, but you can use it with any other package, for instance [Google2FA QRCode](https://github.com/antonioribeiro/google2fa-qrcode), [Simple QrCode](https://www.simplesoftware.io/docs/simple-qrcode)or [Endroid QR Code](https://github.com/endroid/qr-code), all of them use [Bacon/QRCode](https://github.com/Bacon/BaconQrCode) 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 ----------------- [](#examples-of-usage) ### [Google2FA QRCode](https://github.com/antonioribeiro/google2fa-qrcode) [](#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: ``` ``` ### [Simple QrCode](https://www.simplesoftware.io/docs/simple-qrcode) [](#simple-qrcode) ``` {!! QrCode::size(100)->generate($google2fa->getQRCodeUrl($companyName, $companyEmail, $secretKey)); !!} Scan me to return to the original page. ``` ### [Endroid QR Code Generator](https://github.com/endroid/qr-code) [](#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 ``` {!! $google2fa_url !!} Scan me to return to the original page. ``` ### [Bacon/QRCode](https://github.com/Bacon/BaconQrCode) [](#baconqrcode) ```