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, and more.

Enabling 2FA on your account

Profile → Security → Two-factor authentication → 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.

Admin enforcement

In Settings → Authentication → 2FA policy admins can choose:

Optional (default) — users enable it if they want
Required for admins — users with the Admin role must enable 2FA on next login
Required for all local accounts — everyone with a local password must enable it

Enforcement kicks in on next login with a forced enrollment flow — no grace period to skip.

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, or Keycloak and it applies to all dockmesh logins via that IdP.

Local break-glass admins always go through dockmesh’s own 2FA flow.

Recovery codes

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

Use a recovery code on the login screen
You’re prompted to re-enroll 2FA (new QR code, new recovery codes)

Recovery codes are hashed in the database (argon2id) — they can’t be read back, only validated.

Admin reset

If a user loses both their device and their recovery codes, an admin can reset their 2FA: Users → select → Reset 2FA. The user is forced to re-enroll on next login. The reset is written to the audit log with the admin’s identity.