Two-Factor Authentication

Last updated

Two-factor authentication (2FA) adds a 6-digit code from an authenticator app (Google Authenticator, Microsoft Authenticator, 1Password and similar) to sign-in. It works with no internet: the code is computed from a shared secret and the clock. It is opt-in per user and available to every role.

Turn it on

Before anyone can enroll, the appliance must have at least two active Admin accounts. With one admin, enrollment is refused: Create a second administrator account before turning on two-factor authentication… This exists so a lost phone can be cleared by a colleague rather than only at the appliance.

1. Click your name in the top bar → My Account.
2. In Two-Factor Authentication, click Set up two-factor authentication.
3. Scan the QR code with the app, or type the key shown under Scan with your authenticator app, or enter this key by hand:. The account appears as Scada.Ink:your-email. (Accounts enrolled with older software show Scada.INK:your-email; they keep working, and there is no need to enroll again.)
4. Save the 10 recovery codes now (Copy all copies them). They are shown once and cannot be retrieved later. Each looks like A1B2-C3D4-E5F6-A7B8 and works once.
5. Enter a current code under Enter a code from the app to finish and click Enable.

From the next sign-in, after the password the login screen asks Enter the 6-digit code from your authenticator app. Use a recovery code instead switches to a recovery code. The step must be completed within 5 minutes of entering the password (That sign-in attempt expired. Please sign in again.).

While it is on

The card shows Enabled on … and N recovery codes remaining.

• Regenerate recovery codes: enter a current code; the previous set stops working.
• Turn off: enter your account password.
• If codes verify more than a step away from the appliance clock, the card warns: Codes are verifying Ns away from this appliance's clock… The appliance accepts codes up to two 30-second steps early or late. Keep the appliance on NTP (see Appliance System).

Lost authenticator

In order of preference:

1. Use a recovery code, sign in, turn 2FA off and enroll again.
2. Ask another admin: Users → shield-with-slash icon (Reset two-factor authentication (for a lost authenticator)) on your row. You then sign in with the password alone until you enroll again.
3. At the appliance itself: on the screen attached to the appliance (the kiosk browser at https://localhost), sign in with your email and password; the second-factor screen offers Lost your authenticator? → Turn off two-factor. This is refused from anywhere else on the network (Two-factor authentication can only be reset from the screen attached to the appliance itself.). It is written to the audit log as mfa_console_reset.

Warning: The 2FA secret is encrypted with a key derived from the appliance's JWT_SECRET. If that secret changes (for example, a restore onto a different appliance), codes fail with The stored authentication secret could not be read. Sign in with a recovery code and re-enrol.

Method	Endpoint	Purpose
GET	/api/auth/mfa/status	Your 2FA status
POST	/api/auth/mfa/enroll	Start enrollment; returns the secret and recovery codes once
POST	/api/auth/mfa/confirm	{ "code": "123456" } — finish enrollment
POST	/api/auth/mfa/backup-codes	{ "code": "123456" } — new recovery codes
POST	/api/auth/mfa/disable	{ "password": "…" }
POST	/api/auth/mfa/verify	{ "challenge", "code" } — second sign-in step
POST	/api/admin/users/:id/mfa/reset	Admin clears another user's 2FA
POST	/api/auth/mfa/console-reset	Local console only, { "email", "password" }

Troubleshooting

Message	Cause	Fix
Create a second administrator account before turning on two-factor authentication.	Fewer than two active admins	Create or enable a second admin
That code is not valid. Check the appliance clock if it keeps failing.	Wrong code, or the appliance clock is off	Check Date & Time on the Appliance page; turn on NTP
That sign-in attempt expired.	More than 5 minutes between password and code	Sign in again
Enter a current code to regenerate recovery codes.	Regenerating needs a valid code	Enter the code from the app
Your password is required to turn off two-factor authentication.	Wrong or empty password	Enter the account password

See also

• Users and Roles
• Appliance System: Hostname, Time, Power and Services
• Audit Log