Multi-Factor Authentication

Rackvio supports time-based one-time passwords (TOTP, RFC 6238) as a second factor on password logins. You scan a QR code with an authenticator app, and from then on signing in needs your password and a six-digit code from your phone. A stolen password is no longer enough on its own.

This is free in every edition, including the fully air-gapped self-hosted Community Edition. There is no tier gate, no capability flag and no licence check on it — a security baseline should not be an upsell.

Availability by edition

SSO is the only row that is paid, and it is a different thing: it hands authentication to your identity provider entirely. The second factor on a Rackvio password is not withheld from anyone.

1. Turning it on for your account

The setting lives on your own account page — avatar menu -> Change Password, or /account/change-password, listed as Security in the account navigation. Look for the Two-factor authentication card.

1. Click Set up two-factor authentication. Rackvio generates a secret and shows it as a QR code.
2. Scan the QR with an authenticator app — Google Authenticator, Microsoft Authenticator, 1Password, Bitwarden, Aegis, or anything else implementing RFC 6238. Nothing is sent to us and nothing is sent to the app vendor.
3. No camera? The same secret is printed underneath the QR, grouped in fours, as selectable text. Type or paste it into your authenticator’s “enter a setup key” field. This is the path that works on a desktop-only console, on an air-gapped workstation with no phone camera, and in a password manager’s TOTP field.
4. Enter the six-digit code your app is showing and confirm.

Enrolment is not active until you confirm. If you scan the QR and close the dialog, nothing is protecting your account yet — the card says so, and you start again from step 1.

The code you confirm with is a used code. Rackvio refuses to accept the same code twice, which is what stops an intercepted code being replayed. So if you finish setup and immediately sign in somewhere else within the same 30-second window, that sign-in is refused with “That code did not match.” Wait for your app to roll to the next code and it works. This is correct behaviour, not a fault.

2. Recovery codes

Confirming enrolment produces ten recovery codes. Each looks like 3F7K-9QRT — eight characters and a dash. They are drawn from an alphabet with no 0, O, 1, I or L in it, so there is nothing to misread when you write them down.

• They are shown exactly once. Rackvio stores only a bcrypt hash of each one and cannot show them to you again. Copy or download them before you close the dialog; the dialog will not let you past until you say you have.
• Each code works once. Using one marks it spent for good.
• Regenerating replaces the set. The old ten stop working the moment the new ten appear.
• Store them somewhere your phone is not. A password manager on a different device, a printed copy in a safe, or your team’s break-glass procedure. Recovery codes kept as a screenshot on the phone that holds the authenticator protect you against nothing.

On a self-hosted install — especially an air-gapped one with a single administrator — there may be nobody who can help you. An admin reset needs a second administrator with a working login. If you are the only one, your recovery codes are the whole of your safety net.

3. Signing in

Enter your email and password as usual. Rackvio then asks for a code:

• The default field takes the six-digit code from your authenticator app.
• “Use a recovery code” switches the field to the nine-character recovery shape, dash included. Type it exactly as it was shown to you; case, spacing and the dash are all normalised, so 3f7k9qrt and 3F7K-9QRT are the same code.

Codes are accepted within plus or minus 30 seconds of your phone’s clock, so a slightly fast or slow device still works. A code that has already been used is never accepted again, even inside that window.

Wrong codes count toward the same lockout counter as wrong passwords. There is deliberately not a second, separate MFA lockout — one counter, one lockout, one thing for an administrator to clear.

4. If you lose your phone

1. Sign in with your password and a recovery code in place of the six-digit code.
2. Go to Change Password -> Two-factor authentication and turn it off. Turning it off needs a code or an unused recovery code, which you have just proved you hold.
3. Turn it back on with your replacement device. This produces a fresh set of ten recovery codes and invalidates the old set.

If the recovery codes are gone too, another administrator in your organization can reset your enrolment from Administration -> Users -> Reset MFA. That clears your authenticator and every one of your recovery codes, and it is recorded in the audit log with who did it, to whom, and when. Enrol a new authenticator immediately afterwards — until you do, your account is protected by a password only.

An administrator cannot use that button on their own row; it is not offered. Changing your own second factor goes through Change Password, which asks you to prove you still hold one.

5. Requiring MFA for the whole organization

Administrators can make MFA mandatory from Administration -> Security.

• You must be enrolled yourself first. Rackvio refuses the switch otherwise, and says why: “the administrator who enables this is the one person an admin reset cannot rescue.”
• Before you confirm, the page tells you how many administrators have not enrolled. SSO-only accounts and service accounts are not counted — they are exempt, so counting them would produce a warning that can never reach zero.
• The grace period is between 1 and 90 days, and defaults to 7. During grace, users who have not enrolled are prompted at their next sign-in. They are not locked out and they can dismiss the prompt and carry on working.
• When grace expires, an un-enrolled user can still sign in, but their session is restricted to exactly what they need to fix it: viewing their own account, enrolling, confirming the enrolment, and changing their password. Everything else answers 403. The moment they confirm an authenticator, the next sign-in is a normal session.
• Turning the requirement back off takes effect immediately — no restart, no cache wait. Users who already enrolled keep their authenticators and their recovery codes; only the organization-wide requirement is removed.

Break-glass: nobody left who can turn it off

If an organization ends up with no enrolled administrator who can sign in, the requirement can be cleared from the backend container:

# One organization
docker compose exec backend rackvio admin mfa-disable-requirement "Default Organization"
 
# Every organization (multi-tenant deployments)
docker compose exec backend rackvio admin mfa-disable-requirement all

This clears the org-wide requirement and its grace clock, and writes an audit row. It removes nobody’s second factor — enrolled users keep their authenticators. To clear one user’s enrolment, use the admin reset in the UI.

6. Users who sign in with SSO

SSO users are never prompted for a Rackvio TOTP code, in grace or after it. Their second factor belongs to their identity provider, which is where it should be configured and enforced. This holds for service accounts too: an integration account cannot produce a TOTP code, so requiring one of it would simply be a scheduled outage.

7. Operators: rotating SECRET_KEY

TOTP secrets are encrypted at rest. By default the encryption key is derived from your existing SECRET_KEY, which is what makes MFA work on a Community install that configures nothing extra.

Before you rotate SECRET_KEY, print and pin the current derived key:

docker compose exec backend rackvio admin mfa-print-key
# -> set MFA_ENCRYPTION_KEY to the printed value in your environment,
#    THEN rotate SECRET_KEY.

MFA_ENCRYPTION_KEY is optional and, once set, takes precedence over the derived key — so existing enrolments keep working across the rotation.

If you rotate without doing this, nobody is permanently locked out. Recovery codes are bcrypt-hashed and do not depend on that key, so every enrolled user can still sign in with one. What it costs is one recovery code and a re-scan per user, and at the login screen they are told “your authenticator can no longer be verified” rather than being sent to a password reset that cannot help.

This belongs in your incident runbook, not only here. Secret rotation is something you do at 3am after a security incident, which is exactly when nobody is thinking about MFA.

8. One limitation, stated plainly

A user who controls the account’s mailbox can clear an MFA lockout by completing a password reset, because POST /auth/reset-password clears failed_login_attempts and locked_until. They still cannot pass the second factor: the reset rewrites password_hash and touches neither totp_secret_enc nor user_mfa_recovery_codes. This is exactly the behaviour password lockouts have always had, and MFA reuses the same two columns by design so that an operator unlocking an account in the UI clears one lockout state rather than leaving a second latch closed.

9. What is not supported yet

Naming these is more useful to you than leaving them to be discovered:

• WebAuthn / passkeys. Not supported. It is the natural next step and is on the roadmap.
• SMS and email one-time codes. Deliberately not offered, and we do not intend to add them. NIST SP 800-63B discourages SMS, and an emailed code is not a second factor at all when password reset targets the same mailbox — one compromised inbox would defeat both.
• Trusted-device suppression (“don’t ask again on this computer”). Not supported; every sign-in asks.
• Per-action step-up. Rackvio asks for a factor at sign-in, and again before you disable MFA or regenerate recovery codes. It does not re-challenge on individual writes.