Two-factor authentication

HelpingHand admin logins use an authenticator app as a second factor. Shop and customer logins are unchanged.

Who must enrol now

New admin accounts created after this feature shipped are required to finish enrolment before they can use /admin. After email and password they are sent to the setup page and cannot skip it.

Legacy admin accounts that already existed (or any admin whose is_totp_required flag is off) can use the admin after password login without a code. A reminder stays on the admin until they enrol. They can choose Remind me later, which hides the reminder for 24 hours on that browser. After that it comes back. There is no permanent dismiss.

Once any admin has enrolled, later logins ask for a 6-digit code after the password.

Enrolment

Sign in with your email and password.
Open the setup page from the yellow reminder, from the user menu (Two-factor authentication (not set up)), or (for a new account) as the page you land on after login.
Scan the QR code with Google Authenticator, Authy, 1Password or another TOTP app.
If you cannot scan, type the secret shown under the code into the app by hand. Keep a copy of that secret somewhere safe.
Enter the 6-digit code the app shows and submit.

Later logins

After enrolment, each admin login asks for a fresh 6-digit code after your password. The code changes every 30 seconds.

Skipping the code for 2 weeks

The code screen has a Don't ask for a code on this device for 2 weeks tick box. Ticking it stores a signed cookie in that browser, and for the next 14 days that browser goes straight in after your password.

Some things worth knowing:

Your password is still asked for every time. The tick box only skips the code, so a borrowed laptop still needs your password.
It is per browser, not per person. The cookie lives in the browser you ticked it in - a different browser, a different machine, or a private window all ask for a code again.
2 weeks means 2 weeks. The window does not renew itself on each visit; 14 days after you ticked it, you get asked for a code again.
Only tick it on a device you control. Never on a shared or public machine.

Resetting two-factor authentication - from your account page or with the console command below - immediately cancels this on every device you ticked it on. So does changing APP_SECRET.

Manage or reset from your account

Once you are signed in, open the user menu (top right) and choose Two-factor authentication. That page shows that 2FA is enabled. To enrol a new device, enter a current code and choose Reset two-factor authentication. You will be sent through enrolment again.

Lost device

If you cannot produce a code, ask a technical contact to reset your account from the server:

docker compose exec php bin/console app:admin:reset-2fa you@example.com

The next admin login follows the same policy as an unenrolled account (forced setup for required admins, reminder for legacy admins). Shop and customer logins are not affected.