04.02 Multi-Factor Authentication

Why this matters

A password alone is one credential. Even with strong policy enforcement (length, complexity, expiration, lockout), credential theft via phishing, malware, or breach-data reuse stays the single most common path to account compromise. MFA mitigates that path: an attacker with the password still can't authenticate without the second factor (the time-based one-time password from the user's authenticator app). For an application that holds risk register, audit findings, and compliance evidence, the cost of activating MFA is minutes; the cost of not activating it shows up the day a credential gets reused from a breach corpus.

The honest scope to know up front: SimpleRisk Core ships TOTP only. There's no support for WebAuthn/FIDO2 hardware tokens, no SMS-based codes (which is fine — NIST SP 800-63B has deprecated SMS as a second factor), no push-based authenticator integration. TOTP via an authenticator app is the only second-factor option. For most programs this is sufficient (it satisfies NIST SP 800-63B AAL2 when combined with a memorized secret); for programs that require AAL3, the TOTP-only posture isn't enough on its own.

The other thing worth knowing: Core has no built-in recovery code mechanism. If a user loses their authenticator device (phone replaced, app deleted, device wiped), there's no "recovery code from when you enrolled" path to log them back in. The recovery is admin-initiated: an admin clears the user's MFA secret, the user re-enrolls on next login. Plan for this; without an admin-managed recovery path, lost-device events become "reset the user via the database" operations.

The third thing: MFA applies to the local-auth login path. Users authenticated via SAML or LDAP/AD have their MFA posture determined by the IdP; the SimpleRisk MFA toggle doesn't insert a TOTP step into the SSO flow. If your IdP doesn't enforce MFA, SimpleRisk won't either for SSO users; configure MFA at the IdP layer for SSO-authenticated users.

Before you start

Have these in hand:

• Admin access to the Settings Hub (Settings cog, top-right of any page) → User Management tile. The page is tabbed: the mfa_required toggle sits on the User Settings tab with the rest of the password policy, and the per-user MFA reset used for lost-device recovery sits on the Manage Users tab.
• Your own authenticator app, if you have MFA enabled on your admin account. The MFA reset form asks the acting admin for a current token before it will clear another user's secret.
• A communication plan for users if you're enabling mfa_required. The toggle forces every user through enrollment on their next login; users who don't have an authenticator app installed can't proceed until they do. A 24–48-hour heads-up reduces the day-of help-desk volume.
• An authenticator app standard for the organization, if you have one (1Password, Authy, Microsoft Authenticator, Google Authenticator are all compatible). The Core flow renders a QR code that any RFC 6238 / TOTP-compatible app can read; you don't have to standardize, but having a recommendation in the user-facing announcement reduces "which app should I use?" questions.
• A recovery process documented for "user lost their device." Without this, the first lost-device event becomes an unplanned database operation. The process is straightforward; just write it down.

Step-by-step

1. Decide whether to require MFA system-wide or leave it per-user

Two postures:

• Voluntary per-user MFA — mfa_required is off. Users can opt into MFA themselves at My Account → Multi-Factor Authentication. The bar to entry is on the user; some will enroll, most won't. Appropriate only for low-risk programs or as a stepping stone to forced-MFA.
• System-wide required MFA — mfa_required is on. Every user is forced through enrollment on their next login (or immediately, if currently logged in). This is the right posture for any production program; the security delta from "voluntary" to "required" is meaningful and the operational cost is small (the enrollment flow takes 60 seconds).

Default to required. Voluntary MFA is a configuration that audits keep flagging.

2. Enable MFA system-wide

Settings cog → Settings Hub → User Management tile → User Settings tab. On the password-policy form, tick Require MFA for all users (the underlying setting is mfa_required in your instance settings), then save.

What happens immediately:

1. Every user without user.multi_factor = 1 (the per-user enrollment flag) is forced through the enrollment flow on their next login.
2. Currently-logged-in users without MFA enrolled keep their session until it expires; they'll hit the enrollment flow on the next login.
3. The next login attempt for an unenrolled user lands on the QR-code enrollment page; they can't proceed to the application until they scan the code and verify a token.

There's also an administrator action that force-enrolls every existing user immediately rather than waiting for each to hit the prompt at next login. It's less commonly used, but it's there when you need enrollment to land on a deadline.

3. The user enrollment flow

What the user sees on first MFA-enforced login:

1. Username + password as normal.
2. Enrollment page: a QR code, plus the same secret as a text string for users who can't scan a QR code and need to type it in.
3. The user opens their authenticator app, scans the QR code (or types the secret).
4. The app starts producing 6-digit codes that rotate every 30 seconds.
5. The user enters the current code into the Verify Token field.
6. The page validates the token. On success the user is marked as enrolled, their secret is stored, and they proceed into the application.
7. On every subsequent login: username + password + token from the authenticator app.

The QR-code image is rendered inline (no external service called). SimpleRisk stores the secret against the user and records the last token accepted, so the same code can't be replayed twice.

4. Per-user voluntary enrollment (when mfa_required is off)

Users open their profile page (My Profile) and click Enable MFA on the MFA row. The flow is the same QR-code-then-verify enrollment described above. Once enrolled, the row shows Enabled and every subsequent login requires a token. A Disable MFA button appears alongside it; using it turns MFA off for the account and discards the enrolment, so the next enrollment starts from a fresh secret.

When MFA is required system-wide, the Disable MFA button isn't shown at all — and the operation is refused server-side even if a request for it arrives some other way. Users can't opt out of a system-wide requirement.

5. Test the enrollment with a non-admin account

Verify the configuration end-to-end before enforcing it across the organization:

1. Create a test non-admin user.
2. Log in as that user; confirm the enrollment flow appears.
3. Enroll an authenticator app, complete the verification.
4. Log out and log back in; confirm the token prompt appears and an entered token is accepted.
5. Log out, attempt to log in with a wrong token; confirm the rejection.
6. Log out, attempt to log in with the previously-used token (replay); confirm rejection (the last_mfa_token check prevents reuse).

If the enrollment flow doesn't appear when expected, check the stored setting directly: SELECT value FROM settings WHERE name = 'mfa_required'; should return 1. The password-policy form writes this one as an integer, not the 'true'/'false' strings some other settings use.

6. Recovery: user lost their authenticator device

When a user's authenticator app is gone (new phone, deleted app, factory reset), the recovery path is admin-initiated:

1. Verify the user's identity out-of-band (phone call, in-person, badge check — whatever your program requires).
2. Open Settings cog → Settings Hub → User Management → Manage Users tab.
3. Scroll to the Multifactor Authentication (MFA) Reset card. Pick the account from the Perform a MFA reset for user dropdown.
4. If your own admin account has MFA enabled, an MFA Token field appears above the button. Enter a current code from your authenticator. A wrong or stale code aborts the reset with "MFA Verification Failed" and nothing changes.
5. Click Reset MFA.
6. The user logs in next and is walked back through enrollment with a fresh QR code, which they scan with their replacement authenticator.

The reset clears the user's enrolment and nothing else. Their MFA-required flag stays on, which is what forces the re-enrollment prompt instead of dropping them to password-only access. That distinction matters: a reset is not a bypass, and it doesn't briefly weaken the account while the user gets around to re-enrolling.

Two behaviors worth knowing before you're doing this under pressure. The reset refuses to run against an account that doesn't have MFA enabled, returning "MFA is Not Enabled for the Selected User" — so it's a recovery tool, not a way to pre-clear someone. And the acting admin's own token is only demanded when that admin has MFA on; an admin without MFA can reset another user's MFA with no second factor at all, which is one more argument for enrolling every admin account.

Document the identity-verification step. Without it, "I lost my phone" becomes a social-engineering vector for credential theft. A phone call to a number on the user's HR record, plus a question or two only the real user would know, is the minimum bar; programs with stricter requirements use video verification or in-person.

7. Turning MFA off for a single user

Reset and disable are different operations on different pages, and mixing them up is the most common MFA support mistake.

To take a user off MFA entirely, open Settings cog → Settings Hub → User Management → Manage Users tab, pick the account under Details for User, and click Select. On the user's detail page, clear the Multi-Factor Authentication checkbox and save. That writes user.multi_factor = 0 and the account goes back to password-only.

When MFA is required system-wide, the checkbox is pre-ticked and read-only on both the add-user and edit-user forms, and the requirement is re-applied server-side no matter what the browser sends. There's no per-user exemption from a system-wide requirement; if you need one account exempt, what you have isn't a system-wide requirement.

Use disable sparingly. Reset is almost always the operation you actually want — it gets the user back in without leaving an account standing on a password alone.

8. Handle org-wide events that affect MFA

A few patterns to plan for:

• Mass device migration (organization moves from BYOD authenticator to managed authenticator app): users will need to re-enroll. Either trigger admin resets en masse or schedule a maintenance window where users are guided through the migration.
• Authenticator app deprecation (Google Authenticator's lack of cloud backup historically led to lost-token events when users switched phones): consider standardizing on an authenticator with cloud backup (Authy, 1Password, Microsoft Authenticator).
• Departing admin with the only admin account on MFA: if the admin can't be recovered, the MFA state can be cleared directly in the database as a break-glass move. Note that the user's identifier column is value, not id:

sql DELETE FROM user_mfa WHERE uid = {admin_id}; UPDATE user SET multi_factor = 0 WHERE value = {admin_id};

Dropping multi_factor to 0 leaves that account password-only, so re-enroll it the moment you're back in. If MFA is required system-wide, skip the second statement — clearing the enrolment alone is enough to trigger re-enrollment on next login, and the flag would be forced back to 1 anyway. The right preventive: have at least two admin accounts, both enrolled in MFA.

9. Combine with SSO (Authentication Extra users)

For users who authenticate via SAML or LDAP (the Authentication Extra), the SimpleRisk MFA flow doesn't apply — their the account's type is not 'simplerisk' and the local-auth path that triggers MFA isn't taken. MFA enforcement for those users belongs to the IdP:

• SAML IdPs (Azure AD, Okta, ADFS, Auth0, etc.) all support MFA configuration at the IdP layer. Configure MFA there.
• LDAP/AD with MFA: the LDAP bind itself doesn't carry MFA. If MFA is required for AD accounts, it has to happen at a layer the LDAP bind sees (e.g., Conditional Access in Azure AD, third-party MFA solutions integrated with on-prem AD).

Don't assume "we have MFA" because SimpleRisk's MFA is on; verify the SSO-side MFA posture independently.

Common pitfalls

A handful of patterns recur with MFA.

• Toggling mfa_required without warning users. Users hit the enrollment flow on next login, can't proceed without an authenticator app installed, and call the help desk. Warn 24–48 hours in advance with a recommended app name.

• Voluntary MFA as the long-term posture. Voluntary MFA produces low enrollment rates and audits keep flagging it. The path of least resistance is usually to flip to required and absorb the one-day support spike.

• No documented lost-device recovery. The first lost-device event becomes an unplanned database operation. Document the recovery and the identity-verification step before you need them.

• Skipping identity verification on MFA reset. "Hi, I lost my phone, please reset my MFA" is a social-engineering script. Always verify out-of-band before clearing the secret.

• Reaching for the disable checkbox when you meant Reset MFA. They're on different pages and they do different things. Reset clears the secret and forces re-enrollment; the checkbox on the user's detail page takes the account back to password-only and leaves it there. Under support pressure the checkbox is the easier one to find, which is exactly why it gets misused.

• Leaving admin accounts off MFA. Beyond the obvious, an admin without MFA can reset any other user's MFA without presenting a second factor of their own. The token prompt on the reset form only appears when the acting admin has MFA enabled, so an unenrolled admin account is also a weaker gate on everyone else's recovery.

• Assuming SSO users have MFA because SimpleRisk's MFA is on. SSO users bypass SimpleRisk's MFA; the SSO IdP's posture is what matters. Confirm separately.

• Confusing the mfa_required system-wide toggle with per-user enrollment. mfa_required is a requirement, not an auto-enrollment. Users still enroll themselves (via the forced flow on next login); the toggle just removes the opt-out. There's no "auto-enroll all users with these specific secrets" path.

• Storing the QR-code secret somewhere recoverable. The QR-code secret is sensitive (anyone with it can produce the user's TOTP codes). Don't paste it into the support ticket, the chat thread, or the helpdesk note. The user scans it; SimpleRisk stores it; nobody else needs it.

• Disabling MFA to "let the user in just this once." A user's MFA being disabled means their account is now password-only; if the password was the compromised credential, the disable just opened the door. Either reset MFA properly (via the enrollment flow) or have the user use a temporary admin-issued password and re-enroll immediately.

• Locking out the only admin account with MFA when the device is gone. Recoverable from the database, but better avoided. Have a second admin account.

Related

• Local Authentication and Password Policies
• The Authentication Extra Overview
• Configuring SAML SSO
• Session Management and Timeout
• Managing Users, Teams, and Roles