Skip to main content

Two-factor authentication

Two-factor adds a second step to password sign-in: after your password, you enter a short code from an authenticator app. It protects local accounts. People who sign in with Microsoft are covered by your identity provider and are not asked for a second factor here.

Set it up​

  1. Go to My account, then Two-factor authentication.
  2. Choose Set up two-factor and confirm your password.
  3. Scan the QR code with an authenticator app (Microsoft Authenticator, Google Authenticator, 1Password and so on).
  4. Save the backup codes somewhere safe. Each one works once if you lose your device.
  5. Enter the 6-digit code from the app to confirm and turn it on.

To turn it off, confirm your password on the same page.

Signing in​

After your password, you are asked for a code. You can:

  • enter the code from your authenticator app,
  • choose "Email me a code instead" to receive a one-time code by email (needs the organisation's email to be set up), or
  • use one of your backup codes.

Requiring it​

An install owner (SuperAdmin) sets the policy under Application, then Security:

  • Off: people opt in from My account.
  • Admins only: admins and the owner must have two-factor.
  • Everyone: every password account must have two-factor.

When it is required, a person with a password but no two-factor is sent to set it up before they can continue. Single sign-on accounts are never forced to enrol here, since they authenticate with Microsoft.

If you are locked out​

Lost your device: use a backup code to sign in, then set up two-factor again from My account.

Lost your device and your backup codes: an install owner recovers the account from the server (see below). This is the reason to keep at least one owner's credentials safe.

Server-side reset (break-glass)​

With access to the server, reset a user's two-factor from the app container:

docker compose exec app node scripts/reset-2fa.mjs someone@example.com

This removes their two-factor so they can sign in with their password and set it up again. It requires shell access to the host, so it is only available to whoever runs the install.

Notes​

  • Emailed codes need the organisation's email transport configured (Settings then Email). Authenticator codes and backup codes work without email.
  • Two-factor applies to password sign-in only. It does not change single sign-on.