Skip to content

🔐 Two-Factor Authentication

← Back to Documentation Index

📋 Overview

Two-factor authentication (2FA) adds a second step to the login process: after your password, Mail Archiver asks for a 6-digit code generated by an authenticator app on your phone. A stolen password alone is then no longer enough to access the archive.

Mail Archiver implements 2FA using TOTP (Time-based One-Time Password, RFC 6238) — the same standard used by Google Authenticator, Microsoft Authenticator, Authy, 1Password, Bitwarden and others. No external service is involved; the secret never leaves your instance.

2FA is opt-in per user. It is configured by each user for their own account, not globally by an administrator.

🛠ī¸ Prerequisites

  • A TOTP-capable authenticator app on your phone or desktop
  • Access to your own account (you must be logged in)
  • A local (password) account — see the note on OIDC below

⚠ī¸ Not available for OIDC users. If you sign in through an external identity provider (Entra ID, Authelia, Keycloak, â€Ļ), 2FA is managed by that provider and the setup page is blocked with the message "OIDC users cannot enable 2FA. Authentication is managed by your OIDC provider." Enable multi-factor authentication in your identity provider instead — see OIDC / SSO.

🚀 Enabling Two-Factor Authentication

Step 1 — Open the setup page

  1. Log in to Mail Archiver
  2. Open your account menu and choose Two-Factor Authentication
  3. You land on Two-Factor Setup

Step 2 — Scan the QR code

The page shows a QR code. Open your authenticator app, choose Add account → Scan QR code, and point the camera at it.

Can't scan the code? Use Manual Entry instead: the page displays the secret as text (If you can't scan the QR code, enter this secret manually in your authenticator app). Type it into your app as a time-based/TOTP account.

ℹī¸ The secret is not saved yet. It is held only for the duration of the setup in your browser session. 2FA becomes active only after step 3 succeeds — if you abandon the setup, nothing changes on your account.

Step 3 — Confirm with a code

Enter the 6-digit code your app now shows and click Enable Two-Factor Authentication.

If the code is rejected, the setup page is shown again with a fresh QR code and the message "Invalid authentication code. Please try again." Check that your phone's clock is set automatically — TOTP depends on accurate time.

Step 4 — Save your backup codes

On success you are taken to the Backup Codes page. It shows 10 codes, each 16 characters long.

⚠ī¸ This is the only time the codes are shown. They are stored hashed — neither you nor an administrator can display them again later. Use Download Backup Codes to save them to a file, or copy them into your password manager before you leave the page.

The download contains this reminder:

Mail Archiver - Two-Factor Authentication Backup Codes. Store these backup codes in a safe place. You can use them to log in if you lose access to your authenticator app. Each backup code can only be used once. After using a code, it will be invalidated. Important: Keep these codes secure and do not share them with anyone.

🔑 Logging In with 2FA

After entering your password you are taken to Two-Factor Verification and asked for a code:

Enter a 6-digit TOTP code from your authenticator app or a 16-character backup code

Both work in the same field — Mail Archiver distinguishes them by length:

Input Length Behaviour
Code from your authenticator app 6 digits Verified against the current time window
Backup code 16 characters Verified against your stored codes, then invalidated

To accept small clock differences, codes from the immediately preceding and following time step are also accepted.

"Remember me" carries over from the login form: if you ticked it, you stay signed in across browser restarts after completing the 2FA step.

Using a backup code

  1. Enter one of your saved 16-character codes in the same field
  2. The code is accepted and immediately invalidated — it cannot be reused
  3. Successful logins with a backup code are recorded in the access log with the note (2FA Backup Code), so you can spot unusual usage later

Rate limiting

To slow down brute-force attempts, 2FA verification is limited to 5 attempts per 15 minutes, counted per IP address and username. After that you see:

Too Many Attempts — You have made too many 2FA verification attempts. Please wait and try again later.

Wait out the window and try again. The limit applies to failed and successful attempts within the window.

đŸšĢ Disabling Two-Factor Authentication

  1. Open Two-Factor Authentication in your account menu
  2. The page asks for confirmation: "Are you sure you want to disable two-factor authentication? This will reduce the security of your account."
  3. Enter your password — this step requires your current password, not a 2FA code
  4. Click Disable Two-Factor Authentication

Disabling removes the secret and invalidates all remaining backup codes. Your next login needs only the password.

🔄 Lost Your Authenticator? Two Ways Back In

If you still have backup codes

Log in with a backup code as described above, then disable and re-enable 2FA with your new device. Remember to save the new backup codes.

If you have no backup codes left

An administrator must reset 2FA for your account:

  1. Administrator opens Users
  2. Edits the affected user
  3. Chooses Reset Two-Factor Authentication and confirms: "Are you sure you want to reset two-factor authentication for this user? They will need to set it up again."
  4. The user can then log in with their password only and set up 2FA again

The reset clears the secret and the backup codes. The confirmation message "Two-factor authentication has been successfully reset for user â€Ļ" appears in the Users list.

ℹī¸ Scope of the reset. The reset covers 2FA only. It is not a password reset — see Emergency Account Recovery if the password is the problem, or the account is locked out entirely.

👁ī¸ What Administrators Can See

The Users overview shows a 2FA column:

  • "Two-factor authentication is currently enabled for this user." — 2FA is active
  • Otherwise 2FA is off for that user

Administrators can reset 2FA (above) but cannot read the secret or the backup codes — both are stored hashed. A user who loses their device without backup codes has no way back in other than the admin reset.

🔍 Audit Trail

2FA activity is written to the log and, for successful logins, to the access log:

Event Where Entry
Login via authenticator app Access log Login with note IP: <address> (2FA)
Login via backup code Access log Login with note IP: <address> (2FA Backup Code)
Failed 2FA attempt Application log Warning with username, IP and masked token
Invalid backup code Application log Warning with username and IP

The access log entry makes backup-code usage visible after the fact — useful to detect a code being used by someone who should not have it. See Access Logging for how to read these entries.

⚙ī¸ How It Works Under the Hood

For administrators and reviewers:

  • Standard: TOTP (RFC 6238), 20-byte random secret, base32-encoded
  • Verification window: Âą1 time step, to tolerate clock drift
  • Backup codes: 10 codes, 16 characters each, generated from a cryptographic RNG, stored hashed, invalidated individually on use
  • Secret storage: in the user record; never returned to the browser after setup
  • Session handling: the session is regenerated before the 2FA identity is stored, so a session cookie planted before login cannot be carried into the authenticated session
  • OIDC accounts: 2FA management is blocked; the provider is authoritative
  • API keys: bypass 2FA by design, as non-interactive tokens cannot answer a challenge — see the security rationale in the REST API guide

❓ Troubleshooting

Symptom Cause Fix
"Invalid authentication code" Phone clock off, or wrong account in the app Enable automatic time synchronisation; check the app shows the Mail Archiver entry
"Two-factor secret is missing. Please restart the setup process." Setup page was open too long, session expired Start the setup again from the account menu
"Your session has expired. Please log in again." Too much time passed on the verification page Log in again
"Two-factor authentication is not enabled for this account." 2FA was reset or never completed Set it up again, or ask an administrator
Backup code rejected Code already used, or a character misread Backup codes work once; use another, or have 2FA reset
"Too Many Attempts" More than 5 verification attempts in 15 minutes Wait out the window
No setup page in the account menu You sign in via OIDC Enable MFA at your identity provider
No 2FA column in the Users list You are not an administrator Ask an administrator