How do I set up two-factor authentication on TinyPilot?

Overview

TinyPilot supports two-factor authentication (2FA) with a TOTP authenticator app, such as Google Authenticator, Authy, or 1Password.

When 2FA is enabled for your account, signing in requires your password and a six-digit code from your authenticator app.

TinyPilot does not issue recovery codes. If you lose access to your authenticator, an administrator must reset your 2FA, or you must recover access from the device itself.

Before you begin

1. Enable user authentication and create at least one administrator account under System > Security > Users.
2. Install an authenticator app on your phone or computer.

If user authentication is off, opening System > Security > 2FA prompts you to enable authentication first.

Enable 2FA for your account

1. Sign in to TinyPilot.
2. Open the username menu in the top right and choose "Manage Account."

3. Under Two-Factor Authentication, turn on "Enable two-factor authentication."

4. Add TinyPilot to your authenticator app:
   • Click the setup key to copy it, then paste it into your authenticator app, or
   • Click "Show QR Code" and scan the QR code.

5. Enter the six-digit code from your authenticator app.
6. Click "Verify and Enable."

2FA is now enabled for your account. The next time you sign in, TinyPilot will ask for an authentication code after your password.

Sign in with 2FA

1. Enter your username and password, then continue.
2. On the Two-Factor Authentication step, enter the Authentication Code from your authenticator app.
3. Click "Verify."

To return to the password form, click "Back."

Require 2FA for all users

Administrators can require two-factor authentication for every account.

1. Open System > Security > 2FA.

   You can also open System > Security > Users, then click 2FA Settings.

2. Turn on "Require two-factor authentication for all users."

Reset another user’s 2FA

Use this when a user loses their authenticator or needs to set up 2FA again.

1. Open System > Security > 2FA.
2. Find the user in the list.
3. Click "Reset," then confirm.

That user’s 2FA enrollment is cleared. They can sign in with their password and enroll again from "Manage Account."

Disable 2FA on your account

1. Open the username menu and choose "Manage Account."
2. Click "Disable Two-Factor Authentication."

If an administrator has required 2FA for all users, this button is unavailable, and TinyPilot shows that two-factor authentication is required and cannot be disabled. Ask an administrator to turn off the requirement or reset your 2FA.

If you lose access to your authenticator

Option 1: Ask an administrator to reset your 2FA

If another administrator can still sign in, ask them to reset your 2FA using the steps above. Then enroll again from "Manage Account."

Option 2: Recover from the device (sole administrator)

If you are the only administrator and cannot complete the 2FA step, recover over SSH by resetting TinyPilot's database.

Warning: These commands change TinyPilot’s authentication database. Use them only when you cannot regain access through the web interface.

sudo service tinypilot stop && \
sudo mv /home/tinypilot/tinypilot.db /home/tinypilot/tinypilot.db.bak && \
sudo service tinypilot start

After recovery, reload the web interface. You will find that the password prompt has been removed. You can then re-enable user authentication and set up two-factor authentication again.

If you cannot use SSH and no other recovery option works, factory reset the device.

If your authentication code is always rejected

TOTP codes depend on accurate time on both TinyPilot and your authenticator device. If TinyPilot’s clock is wrong, codes can fail even when the app looks correct.

1. Confirm the code in your authenticator app is for TinyPilot and has not expired. Codes refresh about every 30 seconds enter a fresh code promptly.
2. Confirm the clock on your phone or computer is set automatically (network time).
3. Over SSH, check TinyPilot’s time sync:

timedatectl

Look for System clock synchronized: yes    (some versions say NTP synchronized: yes   ). The reported time should match your authenticator device within about a minute.

If TinyPilot’s clock is wrong, restore network time sync:

sudo timedatectl set-ntp true

Wait a few seconds, run timedatectl    again to confirm the clock is synchronized, then try signing in with a fresh code.

If TinyPilot cannot reach an NTP server (for example, on an air-gapped network), set the time manually to match your authenticator device, then try again:

sudo timedatectl set-time 'YYYY-MM-DD HH:MM:SS'