PHP Two-Factor Auth: Implementation Guide

PHP Two-Factor Authentication: A Practical Implementation Guide

PHP applications handling sensitive data need more than a strong password to protect user accounts. Credential stuffing attacks use leaked password databases to compromise accounts across thousands of services automatically. If your users reuse passwords, their credentials from a breach somewhere else will work on your application. Two-factor authentication breaks this pattern by requiring a second proof of identity that attackers typically cannot obtain remotely. This guide walks through implementing TOTP-based 2FA in PHP, from secret generation through to secure storage and recovery options.

Why Two-Factor Authentication Matters for PHP Applications

Most account compromises succeed because of weak or reused passwords, not because of sophisticated attacks on the authentication system itself. Credential stuffing works at scale because people reuse the same password across multiple services. When one service suffers a data breach, those credentials become valuable for attacking other platforms.

Two-factor authentication disrupts this workflow. Even with a correct password, an attacker cannot log in without also controlling the user's second factor, typically a mobile device running an authenticator app. For admin accounts and high-value user accounts, 2FA dramatically reduces the risk of unauthorised access. It will not stop every possible attack vector, but it removes the most common path attackers use to take over accounts.

From a security perspective, PHP applications handling user data, payment information, or administrative functions should treat two-factor authentication as a baseline requirement. The implementation effort is reasonable, and the protection it provides justifies the investment.

How TOTP Works

Time-based One-Time Passwords generate a short numeric code using a shared secret and the current time. Both the server and the user's authenticator app know the secret, and both know the current time. They independently generate the same code at the same moment.

The algorithm uses HMAC-SHA1 to combine the secret with a time counter, producing a hash that gets processed into a 6-digit number. The code changes every 30 seconds, giving a brief window for entry while remaining long enough for users to type it comfortably. If the codes matched every 30 seconds for even one cycle, the user has likely entered it correctly.

The code generation happens entirely on the user's device. Nothing travels over the network that would let an attacker generate a valid code themselves. This makes TOTP resistant to interception in ways that SMS-based alternatives are not.

Comparing Second-Factor Methods

Different authentication methods offer different trade-offs between security, usability, and implementation complexity. Understanding these trade-offs helps you choose the right approach for your application.

Time-based One-Time Passwords (TOTP)

TOTP is the most widely supported second-factor method. Users install an authenticator application such as Google Authenticator, Authy, or 1Password on their phone. The app generates a 6-digit code that changes every 30 seconds. The code is created locally on the device, so there is no risk of interception during delivery. Most password managers and dedicated authenticator apps support this standard.

This is the recommended method for most PHP applications because it balances strong security with straightforward implementation and good user experience. The TOTP two-factor authentication PHP setup guide covers the underlying protocol in more detail if you want to understand how the code generation works.

SMS-Based Codes

SMS-based verification sends a one-time code to the user's mobile phone number. While familiar to users, this method has significant weaknesses. SIM swapping attacks let an attacker convince a mobile carrier to transfer the target's phone number to a SIM card they control. Once they have the number, they receive all SMS messages, including authentication codes.

Phone number portability, carrier security inconsistencies, and interception vulnerabilities make SMS 2FA a poor choice where better options exist. Avoid SMS-based authentication unless your user base has no alternative.

Email-Based Codes

Email verification sends a one-time code to the user's registered address. This is less secure than TOTP because email accounts are often protected with weaker security measures than dedicated authenticator apps. Many people access email through less secure connections, and email accounts are common targets for attackers.

That said, email-based 2FA is better than nothing when TOTP is not available. It adds friction for attackers even if the protection is not as strong. For PHP applications where you need a fallback option, email codes are reasonable to implement.

Hardware Security Keys

FIDO2/WebAuthn security keys provide the strongest authentication available for most use cases. The user registers a physical key with your service, and authentication requires the key to be present and activated. These keys are resistant to phishing because the authentication challenge is cryptographically bound to the specific domain. An attacker cannot forward authentication requests from a fake site to the real one.

Implementing WebAuthn in PHP requires more work than TOTP, but for applications handling high-value accounts or sensitive operations, the additional security justifies the effort. Hardware keys also work well for API authentication without requiring shared secrets.

Setting Up Your PHP Environment for TOTP

Before implementing 2FA, ensure your PHP environment has the necessary extensions and tools. You need PHP 7.4 or later, the OpenSSL extension for encryption, and Composer for managing dependencies.

Check your PHP version and available extensions:

php -v
php -m | grep -E "openssl|json|gmp"

The GMP extension improves performance for certain cryptographic operations but is not strictly required for basic TOTP implementation. OpenSSL is essential for encrypting secrets at rest, which you should do regardless of other security measures.

Installing the TOTP Library

The PHPGangsta/GoogleAuthenticator library provides a reliable, tested implementation of TOTP for PHP applications. Install it through Composer:

composer require phpgangsta/googleauthenticator

This library handles secret generation, QR code URL creation, and code verification. It implements the standard RFC 6238 TOTP algorithm, which means it works with any authenticator app that supports the standard, including Google Authenticator, Authy, Microsoft Authenticator, and 1Password.

After installation, include the autoloader in your authentication code:

require_once 'vendor/autoload.php';

use PHPGangsta\GoogleAuthenticator;

$ga = new GoogleAuthenticator();

Generating User Secrets

Each user who enables 2FA needs a unique secret. Generate this cryptographically secure secret when the user activates two-factor authentication:

$secret = $ga->createSecret();

$qrCodeUrl = $ga->getQRCodeGoogleUrl(
    'YourAppName',     // Issuer name shown in the authenticator app
    $secret,
    '[email protected]' // Account name, usually their email
);

The issuer name should identify your application clearly in the authenticator app. Users often have multiple accounts in their authenticator, so "My Business App" is better than a vague name or abbreviation.

The secret is a base32-encoded string of 80 bits by default, which provides adequate security for this use case. Store this secret immediately after generating it, because you will need it to verify codes from this point forward.

Displaying the QR Code

Users need a convenient way to add your application to their authenticator app. The library generates a URL that works with most QR code readers, which you can convert to an actual QR code image using a library like endroid/qr-code:

use Endroid\QrCode\QrCode;
use Endroid\QrCode\Writer\PngWriter;

$qrCode = new QrCode($qrCodeUrl);
$writer = new PngWriter();
$pngData = $writer->write($qrCode)->getString();

// Output as inline image
header('Content-Type: image/png');
echo $pngData;

Alternatively, you can generate the QR code client-side using a JavaScript library, which keeps the heavy lifting away from your server and simplifies the flow. Libraries like qrcode.js take the same otpauth:// URL and render it in the browser.

Show the QR code on a page where the user can scan it with their authenticator app. Include a backup option to show the secret as typed characters for users who cannot scan the QR code.

Verifying TOTP Codes

When a user logs in with their password, your application also validates the TOTP code they enter from their authenticator app. This verification step happens after the password check succeeds:

// Retrieve the encrypted secret for this user from the database
$storedSecret = getDecryptedTotpSecret($user->id);

$code = $_POST['two_factor_code'];

$ga = new GoogleAuthenticator();

// Allow a 1-step tolerance (30 seconds) for clock skew between server and device
$checkResult = $ga->verifyCode($storedSecret, $code, 1);

if ($checkResult) {
    // 2FA code is valid, complete the login
    $_SESSION['user_id'] = $user->id;
    $_SESSION['2fa_verified'] = true;
    
    // Continue with session creation
} else {
    // Invalid code, reject the login attempt
    echo 'Invalid two-factor authentication code';
}

The tolerance parameter of 1 allows the code to match one step before or after the current time. This accommodates minor clock drift between the server and the user's device without creating a security problem. Each 30-second window still produces a distinct code, so allowing one step either direction does not meaningfully reduce security.

You should also track failed verification attempts and consider temporarily locking the 2FA verification after several failures, while still allowing the user to attempt password authentication again after a cooldown period.

Encrypting Secret Storage

The TOTP secret is a critical piece of security data. If an attacker obtains the secret, they can generate valid 2FA codes without needing access to the user's device. Storing secrets in plain text is not acceptable. Encrypt them at rest using a strong algorithm.

Use AES-256-GCM for authenticated encryption. This provides both confidentiality and integrity verification, alerting you if the encrypted data has been tampered with:

// Encrypting the secret for database storage
$encryptionKey = $_ENV['TOTP_ENCRYPTION_KEY'];
$plainSecret = $userSecret;

$iv = random_bytes(16);
$tag = '';

$encryptedSecret = openssl_encrypt(
    $plainSecret,
    'aes-256-gcm',
    $encryptionKey,
    OPENSSL_RAW_DATA,
    $iv,
    $tag
);

// Store iv, tag, and encryptedSecret together
storeEncryptedSecret($userId, $iv, $tag, $encryptedSecret);

Retrieve and decrypt the secret when needed for verification:

// Retrieve and decrypt the secret
list($iv, $tag, $encryptedSecret) = getStoredSecretParts($userId);

$decryptedSecret = openssl_decrypt(
    $encryptedSecret,
    'aes-256-gcm',
    $encryptionKey,
    OPENSSL_RAW_DATA,
    $iv,
    $tag
);

Keep the encryption key separate from your database credentials. Store it in an environment variable, a secrets manager, or a configuration file outside your web root. The key should never appear in your application code or version control. If your database is compromised but the key is not, the secrets remain protected.

Strong password storage and secret encryption share similar principles. The BCrypt password hashing guide covers hashing considerations that apply to storing sensitive data securely.

Generating and Storing Recovery Codes

Users who lose access to their authenticator app need a way to recover their account. Generate a set of one-time recovery codes when 2FA is enabled. Each code should be used only once, so store hashes of the codes, not the plain codes:

$recoveryCodes = [];
$hashedCodes = [];

for ($i = 0; $i < 10; $i++) {
    $code = bin2hex(random_bytes(8));
    $recoveryCodes[] = $code;
    $hashedCodes[] = password_hash($code, PASSWORD_BCRYPT);
}

// Display all codes to the user ONCE for them to save
displayRecoveryCodes($recoveryCodes);

// Store only the hashed codes
storeHashedRecoveryCodes($userId, $hashedCodes);

Show the plain codes to the user exactly once, on the screen where they enable 2FA. Require them to confirm they have saved the codes before proceeding. After this point, you should never be able to show the plain codes again.

When a user provides a recovery code during login, verify it against the stored hash and then delete that code from the database:

function verifyRecoveryCode($userId, $providedCode) {
    $hashedCodes = getHashedRecoveryCodes($userId);
    
    foreach ($hashedCodes as $index => $storedHash) {
        if (password_verify($providedCode, $storedHash)) {
            // Code is valid, delete it so it cannot be used again
            deleteRecoveryCode($userId, $index);
            return true;
        }
    }
    
    return false;
}

Each recovery code works exactly once by design. If an attacker obtains a code, it becomes useless after the legitimate user has used it. If the legitimate user uses it first, the attacker loses that code. Either way, the one-time nature of recovery codes limits the damage from leaked codes.

Deciding When to Require 2FA

Not every user on every application needs mandatory 2FA. The right approach depends on your application's risk profile and user base.

These actions and account types should always require two-factor authentication:

• Admin panel access: Privileged accounts have the highest value to attackers and the greatest potential for damage if compromised.
• Password and security changes: Any page that lets users change passwords, update email addresses, or modify security settings should require 2FA.
• Payment and financial pages: Where money moves, attackers follow. Require 2FA for any payment processing, withdrawal, or financial reporting functions.
• Access to personal data: User accounts containing financial information, medical records, personal documents, or other sensitive data warrant additional protection.
• API key management: Interfaces for creating, rotating, or deleting API credentials should require strong authentication.

For most business web applications, enabling mandatory 2FA for admin accounts and privileged functions while offering it as an optional feature for regular users strikes a practical balance. Users who want additional protection can enable it, while those who will not use it are not forced through unnecessary friction.

For applications handling financial transactions, sensitive personal data, or other high-value targets, consider requiring 2FA for all users. The additional security justifies the implementation and maintenance cost.

Security Considerations and Limitations

TOTP provides strong protection against most account takeover attacks, but it is not invulnerable. Understanding its limitations helps you make informed decisions about additional security measures.

Phishing and Man-in-the-Middle Attacks

TOTP codes are time-based and short-lived, making them resistant to replay attacks where an attacker captures and reuses a code. However, they do not inherently protect against sophisticated phishing pages that forward entered credentials and codes to the real site in real time. A user on a fake login page enters their password and TOTP code, and the attacker immediately uses those credentials on the legitimate site.

Hardware security keys using FIDO2/WebAuthn are resistant to this attack because the authentication challenge is cryptographically bound to the specific domain. The fake site cannot forward the challenge because it does not match its own domain.

Device Security

The security of TOTP ultimately depends on the security of the user's device. If an attacker gains access to the user's phone and can unlock it, they can generate valid codes. Encourage users to enable device-level security such as PINs, biometrics, or device encryption on their phones.

Application Security Context

TOTP protects the authentication layer but does not address other security concerns in your application. The OWASP Top 10 guide for business web applications covers other vulnerability categories that affect overall security, including injection risks, broken authentication patterns, and security misconfiguration.

Testing Your Implementation

Before deploying 2FA to production, test the implementation thoroughly with test accounts you control. Verify these scenarios:

• Initial setup: Can you scan the QR code with an authenticator app and see the correct account name and issuer?
• Code verification: Do generated codes verify correctly against the stored secret?
• Clock tolerance: Do codes work when there is minor time drift between server and device?
• Invalid codes: Are incorrect codes reliably rejected?
• Recovery codes: Can you log in with a recovery code, and is it then invalidated?
• Account recovery: Can users who lose their device and recovery codes go through your recovery process?

Test with multiple authenticator apps, as different apps may handle edge cases slightly differently. Google Authenticator, Authy, and 1Password are good starting points.

Maintaining Your 2FA System

2FA implementation is not a one-time task. Ongoing maintenance keeps the system secure and usable. Monitor for failed verification attempts that might indicate brute-force attacks. Regularly review which accounts have 2FA enabled, particularly privileged accounts.

When updating your application's issuer name, users may need to re-register their authenticator apps. Communicate changes clearly and give users time to make the transition. Avoid changing issuer names without good reason, as the disruption to users outweighs any minor benefit.

Keep your TOTP library updated. Security libraries receive updates for good reasons, and newer versions may address vulnerabilities discovered in the protocol or implementation.

Moving Forward with 2FA Implementation

Adding TOTP-based two-factor authentication to your PHP application significantly reduces the risk of account takeover through compromised credentials. The implementation involves generating and securely storing secrets, displaying QR codes for user setup, verifying time-based codes during login, and providing recovery options for users who lose access to their authentication device.

The core components are straightforward to implement using established libraries. The more challenging aspects involve secure secret storage, designing a workable account recovery process, and deciding which accounts should require 2FA based on your application's risk profile.

If you need help reviewing your current authentication setup or implementing two-factor authentication for your PHP application, you can get in touch with details of your platform, the user authentication flow you currently use, and which accounts you are looking to protect.