Alt Google 2Fa Laravel Package

Getting Started

This is a Statamic addon (alt-design/alt-google-2fa-addon) that layers Google Authenticator (TOTP) two-factor auth onto the Statamic Control Panel login — it is not a general Laravel 2FA package. If you're on plain Laravel without Statamic, look elsewhere (e.g. pragmarx/google2fa-laravel); the day-to-day value here is specifically protecting CP/front-end-adjacent Statamic users.

Minimum path to a working install:

1. composer require alt-design/alt-google-2fa-addon
2. Publish config/assets: php artisan vendor:publish (pick the addon's provider) — check whether the published config lands as config/google2fa.php or an alt-google-2fa-prefixed file; it has changed naming conventions across addon generations.
3. Clear caches: php artisan config:clear && php artisan cache:clear && php artisan view:clear (Statamic addons register heavily through the addon manifest — stale caches are the #1 "it doesn't show up" cause).
4. Log into the CP as a super user, open your own user profile, and enrol a device before enforcing it site-wide.
5. Only then roll out: enable the requirement per-role/per-user or globally via config/env once you have a recovery path.

v1.1.3 is a maintenance release — it only bumps the Statamic version constraint (PR #9). Nothing to migrate, but it is the release that tells you which Statamic majors the addon currently claims to support. Check the composer.json constraint on the tag before upgrading Statamic, and run composer update alt-design/alt-google-2fa-addon --with-dependencies rather than a bare composer update.

First real use case: lock down a client's Statamic CP so a leaked password alone isn't enough, without touching the front-end auth flow.

Implementation Patterns

Enrolment lives on the user, not in your app code. The addon stores the TOTP secret + recovery state against the Statamic user. Treat that as user data: it must survive user imports/exports. If you seed or migrate users programmatically, don't mass-assign or wipe those fields — check the addon's blueprint/field or column names first and exclude them from any User::update() loop.

Staged enforcement rollout. Don't flip the config to "required" on day one. The workable sequence:

1. Ship with 2FA available but optional.
2. Communicate a deadline; use the CP to show who hasn't enrolled (query users missing the secret field).
3. Flip to enforced, then watch login failures for a week.

Testing without locking yourself out. In local/CI, either disable the addon entirely via env or ensure your seeded test user has a known TOTP secret and generate codes with a library (pragmarx/google2fa or otphp) in the test. For Dusk/browser tests, injecting a fixed secret + computing the code in the test is far more reliable than trying to mock the middleware.

Recovery is your problem. The addon gives users a second factor; it does not give you a support runbook. Build one:

• A php artisan tinker / custom command that clears a user's 2FA fields (an "unlock user" admin action) — this is the single most valuable thing you'll write alongside the addon.
• A documented process for validating identity before you clear it.

Pair it with session/remember-me policy. 2FA at login is undermined by long-lived "remember me" cookies or shared CP accounts. Consider shortening session lifetime for CP users and disabling remember-me for roles that have 2FA enforced.

Guard the CP in non-production. Local dev, staging behind basic-auth, and CI login flows all interact with this addon. Most teams end up gating it on app()->environment('production') or an env flag so devs aren't juggling authenticator codes on a throwaway database.

Upgrade integration tip: because the addon pins Statamic constraints, add it to your upgrade checklist. When bumping Statamic majors, update Statamic and this addon together, then smoke-test the CP login (enrol, verify, recovery code) in staging — the CP auth pipeline is exactly the area third-party addons break on.

Gotchas and Tips

• Cache is the top failure mode. Addon not appearing in the CP nav or not blocking logins? php artisan config:clear, cache:clear, view:clear, and if you use the static cache/stache, clear that too. Re-run php artisan statamic:install-style steps if the addon's publish tags changed.
• Constraint pinning. v1.1.3 is only a Statamic version bump — read it as a compatibility signal. If your composer.json has a caret-locked addon version and you're upgrading Statamic, resolve conflicts deliberately; don't --ignore-platform-reqs your way past a 2FA middleware into a broken CP.
• Clock skew. TOTP is time-based. Containers/VM hosts with drifting clocks cause "invalid code" reports that look like bugs. Ensure NTP is running on app servers; be aware codes are typically valid for one 30s window (addon may allow ±1).
• Recovery codes are shown once. They're hashed or stored-once; if a user loses them and their device, only an admin reset gets them back. Make this explicit in user comms and log admin resets.
• Super users are not exempt by default in most 2FA addons — check whether the addon exempts super users or not. If it does, decide whether that's acceptable (it's a real bypass). If it doesn't, make sure at least two people hold recovery access to the CP.
• Middleware ordering. If you have custom CP middleware, an SSO package, or a custom login controller, verify it composes with the addon's 2FA step. Conflicts typically show up as a redirect loop between /cp and the 2FA challenge route.
• Don't test against production. The failure mode of a misconfigured 2FA addon is "nobody can get in." Keep a break-glass path: a CLI command or .env flag that disables enforcement, documented and tested before you need it.
• Extension points to look at first: the addon's config (enforcement mode, issuer/label shown in the authenticator app — set issuer to your app name so codes are distinguishable), its publishable views (to brand the challenge screen), and its event/listener hooks if you want to audit enrolments. Publishing the views is usually the cleanest way to customise the challenge page without forking.
• Audit value: log successful and failed 2FA attempts. The addon may not do this for you, but a listener here gives you real signal for both security reviews and "I can't log in" support tickets.

Caveat: this assessment is based on the v1.1.3 release notes (a Statamic version bump only) plus the package's general shape. Config file names, field names, and exemption behaviour should be confirmed against the addon's README and published config on the specific tag you install.