Two-Factor Authentication

dockmesh supports TOTP (RFC 6238) two-factor authentication for local accounts. Compatible with any authenticator app — 1Password, Bitwarden, Authy, Google Authenticator, Aegis, Ente Auth.

Enabling 2FA on your account

Click your avatar (top right) → Profile & security
In the Two-factor authentication section, click Enable
Scan the QR code with your authenticator app
Enter a 6-digit code to verify
Save the 10 recovery codes — each works once, use them if you lose your device

On the next login, dockmesh asks for the 6-digit TOTP code after username+password.

Recovery codes are hashed in the database (argon2id) and cannot be read back — only validated.

Enforcement

Authentication → Sessions & sign-in flow → Require 2FA for admin role flips on org-wide enforcement for any user holding the admin role: until they enrol TOTP they can sign in to view, but the server refuses sensitive actions, and the UI nudges them to Profile & security to complete enrolment. The setting is stored as auth.require_tfa_for_admin in the settings table and applies from the next sign-in. Non-admin roles are not gated by this toggle today — if you need enforcement on operator / deployer / a custom role too, delegate MFA to an SSO provider (which can apply policy regardless of role).

There is no per-role-list enforcement (e.g. “require for admin AND deployer”) in the same toggle yet; for stricter coverage, push everyone through SSO and enforce MFA at the IdP.

SSO and 2FA

If you log in via SSO, dockmesh does not ask for a TOTP code — the identity provider is responsible for MFA. Enforce MFA in Azure AD, Okta, Keycloak, or your IdP of choice, and it applies to every login that goes through that provider.

Local break-glass admins always go through dockmesh’s own 2FA flow when enabled on their account.

Recovery codes

Each user gets 10 single-use recovery codes when enabling 2FA. If you lose your authenticator:

Enter a recovery code on the login screen instead of the TOTP code
Log in, then re-enrol 2FA (new QR code, new recovery codes) from Profile & security

Admin reset

If a user loses both their authenticator and their recovery codes, an admin can force a reset:

Users & Roles → Users tab → Reset 2FA (the key-icon button in the Actions column)

The user’s 2FA secret and recovery codes are wiped; they will be prompted to re-enrol on next login. The reset is written to the audit log with the admin’s identity.