Two-factor sign-in
On this page
The Two-factor plugin adds a second step after the password: a 6-digit code that only the member can get. A stolen or guessed password alone no longer opens the account. Members choose to use it; you can ask your admins to.
It needs the PHP extension openssl, which every ordinary host has.
Two ways to get the code
- Authenticator app: Google Authenticator, Microsoft Authenticator, 2FAS or any app that reads a QR code. The app makes a new code every 30 seconds and works without signal. This is the safer way and is marked Best.
- Codes by e-mail: a 6-digit code is e-mailed at each sign-in. It works for 10 minutes and allows five tries. This needs working e-mail on the site (Admin → Settings → E-mail).
What members do
Settings → Two-factor (next to Security & sessions), or Set up on the Two-factor sign-in card of the Security & sessions tab. That card also tells the member at a glance whether it is on, which way they use and how many backup codes are left.
With an app
- Press Set up beside Authenticator app.
- Scan the QR code with the app. If the camera cannot read it, Copy key and type the key into the app as a time-based account.
- Type the 6-digit code the app shows and press Turn on.
By e-mail
- Press Set up beside Codes by e-mail. A code goes to the member's address.
- Type it and press Turn on. Send a new code helps when it does not arrive.
Backup codes
Right after two-factor is switched on, the member sees ten backup codes of 8 digits, with Copy and Download. Each works once, for the day the phone is lost or the e-mail cannot be read. This is the only time they are shown, so they should be saved somewhere safe. When three or fewer are left the settings say Make new ones; Make new codes gives ten new ones and cancels the old ones, and asks for the password.
Signing in
After the password the site asks for the code. A backup code can be typed in the same box. Codes from an app work once only, so a code someone watched being typed is worthless a moment later.
Trust this browser for 30 days under the code box (the number of days is yours to set) skips the question on that browser until the time runs out. The Trusted browsers list in the member's settings shows each one with its device and when it was last used, with Remove and Remove all.
Turn off two-factor sign-in asks for the password. The trusted browsers and backup codes go with it.
Two-factor also applies after Continue with Google and the other buttons of Social login.
Settings
Admin → Plugin pages → Two-factor sign-in.
| Setting | What it does |
|---|---|
| Authenticator apps (QR code) | Offers the app way. |
| Codes by e-mail | Offers the e-mail way. |
| "Trust this browser" lasts (days, 0 = off) | 30 by default, at most 365. 0 asks for a code at every sign-in. |
| Admins must use two-factor sign-in | Admins without it see a reminder at the top of the admin panel until they switch it on. |
Turning a way off only hides it for new set-ups. Members who already use it keep it until they change it.
The e-mail with the code is the template Sign-in code on Admin → E-mail templates, where you can change its wording.
Numbers
The same page shows how many members use two-factor (and what share of all members), split by app and e-mail, how many used it in the last 30 days, how many set-ups were started but not finished, and how many browsers are trusted right now. Admins without two-factor lists the admins who still have to switch it on.
Members using two-factor lists each of them with the way they use, since when, when they last used it, how many backup codes are left and how many browsers they trust. Admin → Members also shows Two-factor: On / Off on each member's page.
When a member is locked out
A member who lost their phone and their backup codes cannot get in alone. Reset for a member takes a username, an e-mail address or a member number; Reset in the members list does the same. After the reset the password alone opens the account again, and the member can set two-factor up anew.
Make sure it is really them first, for example by a message from the e-mail address of the account. Every reset is written to the admin log.
Clean-up
The daily cron job Two-factor: remove expired trusted browsers removes trusted browsers whose time is up and set-ups that were started more than a day ago and never finished.
Good to know
- That code is not right with an app nearly always means the clock of the phone is off. Setting the phone's time to automatic fixes it.
- The app secrets are stored encrypted with the site's secret key in
config.php, and the backup codes only as fingerprints. Keepconfig.phpwhen you move the site, or every member's app stops matching and needs a reset. - On a site without HTTPS the codes and the trusted-browser cookie travel unprotected; the admin page warns about it.