Skip to content

Two-Factor Authentication (MFA)

Local accounts can add a second factor: a 6-digit code from an authenticator app. AD/LDAP and SSO accounts get their second factor from the directory or identity provider instead, so none of this applies to them.

Which authenticator apps work

Any app that supports standard time-based codes (TOTP, RFC 6238): Google Authenticator, Microsoft Authenticator, Authy, 1Password, Bitwarden and others. The console uses the usual settings every one of them expects: 6 digits, a new code every 30 seconds, SHA-1. A phone clock that is up to 30 seconds off still works.

Turn on MFA for your own account

  1. Open the account menu (your name, top right) → Security — MFA.
  2. Scan the QR code with your authenticator app. If you can't scan it, type the secret shown under it into the app instead.
  3. Click Next, enter the 6-digit code the app shows, and click Next again.
  4. Save the 10 recovery codes somewhere safe, outside the console. Each one signs you in once if you lose your phone. They are not shown again.

From then on, signing in asks for a code after your password. A recovery code goes in the same box.

Sign in with a security key or passkey

Once your authenticator app is set up, you can add hardware security keys (such as a YubiKey) or passkeys (Windows Hello, Touch ID, a phone) and sign in with a touch instead of typing a code.

  1. Open the console by its host name over HTTPS, for example https://console.example.com. Browsers don't allow security keys on an IP address.
  2. Account menu → 🔑 Security keys.
  3. Give the key a name (for example YubiKey 5C) → Add security key, and follow your browser's prompt.

At the next sign-in, the code prompt has a 🔑 Use security key button. Codes and recovery codes still work, so keep your authenticator app.

  • A key only works on the address you added it from. If you sign in through another host name, add the key again from there.
  • Without an authenticator app set up, the dialog offers to set that up first.
  • Adding, using and removing a key is recorded in the cluster log. An admin's Reset MFA removes a user's keys too.

Require MFA for everyone

Settings → Multi-Factor Authentication → Require MFA for all local accounts → Save.

Nobody is locked out by this. A user who hasn't enrolled yet is walked through enrollment at their next sign-in (scan, enter a code, save the recovery codes) and signed in at the end of it. That includes the account that turned the setting on.

To keep one account out of the requirement, such as a break-glass admin kept in a safe, tick MFA-exempt on its row under Identity → IAM Users. The exemption only skips forced enrollment: an exempt account that enrolls anyway is still asked for its code.

Someone lost their phone

Another admin can reset it. Under Identity → IAM Users, click Reset MFA on that user's row and confirm. Their authenticator, recovery codes and any security keys are removed. They sign in next time with their password alone, or, if MFA is required, they're walked through enrollment again with a new secret and new codes. You can't reset your own MFA this way; use a recovery code, or ask another admin.

If the only admin has lost both the phone and the recovery codes, clear that account's MFA from the host the console runs on. Find the app container with docker ps (or podman ps); Compose v2 names it <project>-app-1-1, podman-compose <project>_app-1_1, where <project> is your install directory, for example mfconsole. Then:

docker exec <app-container> python3 -c "
from core.database import get_db
from core import mfa
with get_db() as conn:
    mfa.admin_reset(conn, 'admin')
    print(mfa.get_mfa_state(conn, 'admin'))
"

It prints {'enabled': False, 'enrolled_at': None} when it has worked. Replace admin with the account's username if it's a different one. Anyone with root on the console host can do this, which is why that host needs the same protection as the console itself.

1.3.0-rc6.3 and earlier: the code prompt opens behind the sign-in screen

In these releases the box that asks for your code opens underneath the sign-in form, so after Sign in nothing seems to happen. The box is there and already has the cursor: type your 6-digit code (or a recovery code) and press Enter. Forced enrollment can't be done blind like that, because the secret to scan is hidden too, so on these releases leave Require MFA off until everyone has enrolled from the account menu. Fixed in the next release.