MFA Enforcement

Zonitix supports two kinds of second factor at sign-in, passkeys and authenticator-app codes, with single-use recovery codes and an administrator reset for someone who is locked out.

What It Does

Standard passwords are vulnerable to phishing, keyloggers, and reuse leaks. By enabling global MFA enforcement, you require everyone who signs in with a Zonitix password to link an authenticator application or device-level passkey. This maps directly to the SOC 2 Trust Services Criteria for logical access controls.

The switch is under Security & Compliance → Security Settings → MFA: Mandatory MFA for local accounts, in the ORG-WIDE DEFAULT panel. A new instance starts with it on. Each group can follow that default, require MFA, or be exempt; the PER-GROUP ENFORCEMENT panel on the same screen summarises those choices. Administrators, and anyone holding the permission to manage security, to manage users or to mark approved invoices as paid, always need a second factor at sign-in. No group exemption lifts that, and neither does ticking Trust this device for 30 days. Someone who loses their device signs in with a recovery code; if they have none left, an administrator uses Reset MFA on the Users page and the person enrols again at their next sign-in.

If something here is not working as you expect, start with When something goes wrong.

The MFA Endpoint Map

All routes below are exposed through the API gateway under /api/v1/auth and proxied to the identity-service, which owns every gate. Where the identity service answers 401 on these routes, the gateway returns 400 to the caller with the same code, so the statuses below are the ones a client receives. Enrollment and login sit under /mfa; the two operator escape hatches sit under /security and are the only privileged ones. The Auth column is the session type or permission the identity service actually checks.

TOTP Enrollment: Init → Confirm

Enrollment is a two-step handshake so that rendering a QR never half-commits an account. setup/init stages the secret in mfaPendingSecret and returns it; setup/confirm checks a live code against that pending secret and only then promotes it to the live mfaSecret, sets mfaEnabled = true, and returns a full session token. Both steps authenticate with the enrollment token (in the mfaToken body field or the Authorization bearer) and both reject a magic-link or password-change token, and refuse to re-enroll an account that already has MFA unless the session is itself MFA-verified.

Login Step-Up: Verify & Consume A Recovery Code

At login, after the password check, the identity service hands back a short-lived MFA-challenge token (isMfaSession). The client completes step-up by posting either a TOTP code to /mfa/verify or a recovery code to /mfa/verify-recovery. Both require that challenge token — a full session or password-change token is rejected with 403. A recovery code is matched by bcrypt against the stored hashes and the first unused match is flagged used: true before the session is issued, so every code works exactly once.

Attempt Limits And Replay Protection

Guessing a second factor is capped at three levels, and the same counters cover both the authenticator-code and the recovery-code endpoints:

• Per sign-in: 5 wrong codes. The fifth wrong code on one MFA-challenge token burns that token and returns 400 MFA_SESSION_EXPIRED. The person has to enter their password again to get a new challenge.
• Per account: 10 wrong codes in 15 minutes. Counted across any number of sign-ins and addresses, and not reset by re-entering the password — only by a successful second factor. Reaching it locks the account for 15 minutes (the same lock a run of wrong passwords applies) and returns 423 MFA_LOCKED; it is audited as LOGIN_MFA_LOCKED_OUT.
• Per client IP: 20 failed attempts in 5 minutes at the gateway, across the MFA and passkey endpoints. Successful verifications are not counted. Exceeding it returns 429.

Authenticator Code Parameters

• Standard TOTP (RFC 6238). The server passes no digit count, period or hash to its TOTP library, so the library’s defaults apply: 6 digits, a new code every 30 seconds, HMAC-SHA1. The secret is handed to the authenticator app in base32, as text and inside an otpauth:// address with the issuer Zonitix. Any authenticator app that follows the standard works.
• Accepted window: one step either side. Verification is called with window: 1, at enrolment and at sign-in alike. The server accepts the code for the current 30 seconds, the one before and the one after, which allows for a clock that is up to about 30 seconds out and means a code can be accepted for up to about 90 seconds.
• Used codes are remembered for 90 seconds, per account, which covers that whole window; this is what makes a code single-use (next card).
• None of these values is a setting. They cannot be changed from the app.

Rotating Recovery Codes

/mfa/recovery-codes/regenerate is the only way to get a replacement set. The first set is minted by whichever factor is enrolled first — confirming an authenticator app or registering a passkey — whenever the account has no codes. It replaces the caller’s entire set and returns the fresh raw codes exactly once. Because it invalidates the old set, it demands a full, already-MFA-verified session: the token must not be an MFA-challenge, magic-link or password-change token, must carry a username, and must have mfaVerified === true — otherwise 403 MFA_VERIFICATION_REQUIRED.

Operator Lockout Recovery

Two privileged endpoints handle the cases a user cannot fix themselves. Both are gated at the identity route on manage_security and requireSudo (a fresh step-up), take the target as a path parameter, and are audited. The gateway forwards the caller’s x-user, internal service token and Authorization bearer — requireSudo reads sudoGrantedAt from that bearer.

Forcing MFA By Group

Whether a user is challenged for MFA at login is decided in one place — the resolver resolveMfaRequirement that every session-issuing path calls — from a three-state per-group policy: Group.mfaPolicy is inherit, require, or exempt (the legacy requiresMfa boolean is kept as a mirror of require). The decision is precedence-ordered, highest first:

• Privileged floor — always on, never exemptable. The administrator role, and anyone holding a floor permission (manage_security, manage_users, pay_invoice), always requires MFA — even inside an exempt group. This is what lets an admin hand out exemptions without opening a hole on the accounts that change policy, create accounts or mark invoices as paid.
• An active group exemption wins next. A group set to exempt lifts MFA for its non-privileged members. Exemptions are break-glass: each carries an optional expiry (mfaExemptUntil) and a reason (mfaExemptReason), and a lapsed window re-arms enforcement on its own — there is no sweep to run.
• Any require group forces it.
• Otherwise the org-wide default applies — the mfaEnabled setting, read live at login, which every inherit group follows.

WebAuthn Assertion Protocol

The identity service (identity-service) exposes WebAuthn challenge endpoints. Passkey credentials map to user records in the database:

Passkey Parameters

The values the server uses in every passkey (WebAuthn) ceremony. None of them can be changed from the app. The first three are fixed for your instance when it is provisioned; the rest are the same on every instance.

The endpoints are GET /api/v1/auth/webauthn/register/generate and POST /api/v1/auth/webauthn/register/verify to register, GET /api/v1/auth/webauthn/authenticate/generate and POST /api/v1/auth/webauthn/authenticate/verify for the second factor.