Two-factor sign-in
How two-factor authentication works for staff and customers, how to require it for staff, and what to do when someone loses their phone.
Staff and customers can protect their logins with a code from an authenticator app. After the password, the person enters a 6-digit code that changes every 30 seconds. This article covers how it works, how to require it for your staff and how to recover a locked-out account.
What people see#
Setting up is the same for staff and customers, on their own Security page:
- Staff: open the account menu in the admin and choose Security.
- Customers: open the account menu in the client portal and choose Security.
- Select Set up two-factor.
- Scan the QR code with an authenticator app. If you cannot scan it, type in the key or the setup link instead.
- Enter the 6-digit code from the app and select Confirm and turn on. It only turns on once a valid code is confirmed. Select Cancel setup to back out.
- Save the ten recovery codes. They are shown once. Store them somewhere safe, such as a password manager.
At the next sign-in, after the password, a Two-factor check page asks for the code. A recovery code works too: choose Use a recovery code. Each recovery code works once. The sign-in step expires after five minutes, and after five wrong codes in a row the person has to wait before trying again.
Remember this device#
The check page has Remember this device for 30 days. Ticking it skips the code on that browser for 30 days.
On the Security page, Trusted devices lists every remembered browser with a description such as "Firefox on Windows", its IP address, when it was added, when it was last used and when it expires. The one you are using is marked This device.
- Revoke removes one device. It asks for a code at its next sign-in.
- Revoke all removes every device.
A device also stops being trusted when it expires, when the password changes, and when two-factor is reset or turned off. Revocations are written to the activity log.
Recovery codes and turning it off#
Once it is on, the Security page shows how many recovery codes are left and warns when two or fewer remain.
- Make new codes needs the current password. The new set replaces the old one, and the old codes stop working.
- Turn off two-factor needs the current password and a current code (or a recovery code). It is hidden for staff while two-factor is required (see below).
Require it for staff#
An administrator can make two-factor mandatory for the team. Go to Settings → Security and turn on Require two-factor authentication for staff.
While it is on:
- Staff and administrators without two-factor are sent to their Security page to set it up before they can use the admin area.
- The Turn off option on the Security page is replaced by a note saying two-factor is required.
- The requirement covers the API too. Every call made with the token of a staff user who has not enrolled is refused with
403and the codetwo_factor_enrolment_required. This includes tokens that existed before you turned the setting on, and creating new tokens. The token works again as soon as its owner has turned on two-factor. The one exception is revoking the token itself. - Customers are not affected.
Staff in the admin menu lists each person's role, last sign-in and whether two-factor is On or Off. Use the No 2FA tab to see who has not set it up yet. People without it show a warning colour while the requirement is on.
When someone loses their phone#
Someone who has lost their phone can still sign in with a recovery code. If they have lost both, an administrator or staff member can reset their two-factor. A reset turns two-factor off, removes remembered devices and lets the person sign in with their password and set it up again.
| Who is locked out | Who can reset it | Where |
|---|---|---|
| A customer | Any staff member | The client's Contacts tab. See Managing clients. |
| A staff member | Administrators only | Staff, then Reset 2FA… on the person's row. |
| Yourself | Nobody in the app | Use a recovery code, or ask another administrator. |
Nobody can reset their own two-factor from these screens, and only administrators can reset staff.
API tokens and resets#
A reset only removes the second factor. It does not sign the person out elsewhere or stop their API tokens. What happens to tokens depends on how it ended:
| Action | API tokens |
|---|---|
| The person turns two-factor off themselves | Kept. |
| An administrator or staff member resets it | Kept, unless Revoke API tokens is ticked. |
| The command line reset (below) | Kept, unless --revoke-tokens is given. |
| A staff user is deactivated | Always revoked. Any signed-in browser session ends on its next request. |
Tick the option whenever the account may be compromised. Resets are written to the activity log with the number of tokens revoked.
If the only administrator is locked out#
If the only administrator has lost their phone and recovery codes, no one in the app can reset them. Run this on the server instead:
php artisan billing:reset-2fa [email protected]
Add --revoke-tokens to also revoke that account's API tokens. The account's two-factor is turned off and the reset is logged. The person signs in with their password and sets it up again.
Anyone who can run this command has shell access to your server, so it is as trusted as editing the database.
Staff viewing as a customer#
When a staff member uses View as client, they never need the customer's code, and they cannot set up, change or turn off the customer's two-factor while doing so.