scheb/2fa-google-authenticator

scheb/2fa-google-authenticator extends scheb/2fa-bundle with a time-based one-time password (TOTP) provider compatible with Google Authenticator, Authy, and other standard authenticator apps. It validates codes generated from a per-user shared secret using spomky-labs/otphp, without requiring an email or SMS round-trip during login.

As a provider plugin for the core scheb 2FA bundle, it implements the TwoFactorProviderInterface contract and adds a Symfony Validator constraint (UserGoogleTotpCode) for validating a submitted TOTP code during secret setup, giving applications a standards-compliant, offline-capable second factor with minimal integration code.

What You Get

• A GoogleAuthenticatorTwoFactorProvider implementing the core bundle’s TwoFactorProviderInterface
• A GoogleAuthenticator/GoogleAuthenticatorInterface pair wrapping TOTP code generation and verification via spomky-labs/otphp
• A GoogleTotpFactory for building TOTP instances from a user’s stored secret
• A Symfony Validator constraint (UserGoogleTotpCode) for validating a code during secret setup/enrollment
• A TwoFactorInterface contract for marking user entities as Google-Authenticator-enabled and storing their shared secret

Common Use Cases

• Adding authenticator-app-based (TOTP) login verification to a Symfony application’s existing auth flow
• Letting users enroll a new authenticator app and confirming enrollment with a validator constraint
• Offering an offline-capable second factor that doesn’t depend on email/SMS delivery
• Combining with other scheb 2FA providers (email, TOTP) to give users a choice of second factor

Under The Hood

Architecture The package implements a provider plugin against the core scheb/2fa-bundle’s extension points: GoogleAuthenticatorTwoFactorProvider checks whether a user has Google Authenticator enabled and has a stored secret (via the TwoFactorInterface contract), then delegates code verification to GoogleAuthenticator, which builds a TOTP object per-user via GoogleTotpFactory and checks submitted codes using spomky-labs/otphp’s RFC 6238-compliant TOTP implementation. A separate UserGoogleTotpCodeValidator Symfony Validator constraint reuses the same verification logic during the secret-enrollment step, so a user can confirm their authenticator app is correctly configured before 2FA is enforced.

Tech Stack PHP 8.4/8.5 with a hard dependency on scheb/2fa-bundle (version-pinned via self.version) and spomky-labs/otphp (^11.4) for the underlying TOTP/HOTP algorithm implementation; optionally integrates with symfony/validator for the enrollment-time code constraint.

Code Quality The package is small and tightly scoped — eight classes/interfaces split across Model/, Security/TwoFactor/Provider/Google/, Security/TwoFactor/Validator/, and Security/TwoFactor/Event/ namespaces — delegating the cryptographic TOTP algorithm entirely to the well-established spomky-labs/otphp library rather than reimplementing it, which reduces security risk. Test coverage for this provider lives in the parent scheb/2fa monorepo rather than in this subtree-split repo.

API Design Integration requires implementing the TwoFactorInterface on the application’s user entity (storing a secret and enabled flag) and enabling the google provider in bundle configuration, mirroring the pattern used by scheb’s other 2FA providers — a low learning curve for anyone already using scheb/2fa-bundle, with the added enrollment-validator constraint providing an easy way to confirm setup.