Skip to main content

Multi-Factor Authentication (MFA)

MFA requires users to present a second factor in addition to their password. LumoAuth supports time-based one-time passwords (TOTP) from authenticator apps, SMS codes, email codes, and single-use backup codes. You enable MFA per organization, choose which methods users can enroll in, and set the enforcement policy (off, optional, required, or adaptive).

Supported MFA Methods​

MethodHow It WorksSetup
TOTP (Authenticator App)Time-based one-time passwords via apps like Google Authenticator, Authy, 1PasswordScan a QR code to enroll
SMSOne-time code sent via text messageEnter and verify phone number
EmailOne-time code sent to the user's emailUses verified email address
Backup CodesPre-generated single-use recovery codesDownloaded at enrollment time

How MFA Works​

MFA During Login​

  1. User enters email and password (first factor).
  2. LumoAuth validates the credentials.
  3. If MFA is required → user is redirected to the MFA challenge page.
  4. User provides their second factor (TOTP code, SMS code, etc.).
  5. LumoAuth validates the second factor.
  6. Login is complete — tokens are issued.

MFA Enrollment​

When MFA is enabled but a user hasn't enrolled yet:

  1. After first login, the user is redirected to /auth/mfa-enrollment.
  2. User selects their preferred MFA method.
  3. User completes enrollment:
    • TOTP: scan QR code with an authenticator app, then enter a verification code.
    • SMS: enter phone number, verify with a code sent via SMS.
    • Email: verify with a code sent to their email.
  4. Backup codes are generated and displayed — the user must save them.
  5. Future logins will require the enrolled MFA method.

Configuration​

Enable MFA for an Organization​

Navigate to Configuration → Auth Settings at:

/orgs/{orgId}/portal/configuration/auth-settings

Under the Multi-Factor Authentication section:

SettingOptionsDescription
MFA PolicyOff, Optional, Required, AdaptiveHow MFA is enforced
Allowed MethodsTOTP, SMS, Email, Backup CodesWhich methods users can choose from
Default MethodTOTP (recommended)Pre-selected method during enrollment
Grace Period0–30 daysTime before MFA is required for new users
Remember DeviceOn/OffTrust devices for a configurable period

MFA Policy Options​

PolicyBehavior
OffMFA is completely disabled
OptionalUsers can opt in to MFA from account settings
RequiredAll users must enroll in MFA after their next login
AdaptiveMFA is triggered based on risk assessment — see Adaptive MFA

MFA Enrollment Page​

When MFA enrollment is required, users see the enrollment page at:

/auth/mfa-enrollment

TOTP Enrollment​

  1. A QR code is displayed along with a manual-entry secret.
  2. User scans the QR code with their authenticator app.
  3. User enters the 6-digit code from the app to verify.
  4. Enrollment is confirmed.

SMS Enrollment​

  1. User enters their phone number.
  2. A verification code is sent via SMS.
  3. User enters the code to verify.
  4. The phone number is saved for future MFA challenges.

Email Enrollment​

  1. Users whose email is already verified can use it for MFA.
  2. A verification code is sent to their email during each MFA challenge.
  3. No additional enrollment step is needed.

Backup Codes​

After enrolling in any MFA method:

  1. A set of 10 single-use backup codes is generated.
  2. Codes are displayed once — the user must save them.
  3. Each code can be used once to bypass the primary MFA method.
  4. New codes can be regenerated (invalidating old ones).

MFA Challenge Page​

During login, if MFA is triggered, the challenge page is shown at:

/login/mfa-challenge

The challenge page:

  • Shows the user's enrolled MFA method.
  • Accepts the one-time code input.
  • Offers a link to use backup codes if needed.
  • Handles retry and rate limiting.

MFA Setup Page (Self-Service)​

Users can manage their MFA settings from the account security page:

/account/security

Or the dedicated MFA setup page:

/auth/mfa-setup

From here users can:

  • Enroll in additional MFA methods.
  • Change their primary MFA method.
  • View remaining backup codes.
  • Regenerate backup codes.
  • Disable MFA (if organization policy allows).

MFA for Administrators​

View User MFA Status​

In the organization portal, admins can see MFA enrollment status:

/orgs/{orgId}/portal/access-management/users

Each user listing shows:

  • MFA enrolled: Yes/No
  • MFA method: TOTP, SMS, Email
  • Last MFA challenge timestamp

Reset User MFA​

If a user loses access to their MFA device:

  1. Go to the user's profile in the organization portal.
  2. Click Reset MFA.
  3. The user's MFA enrollment is cleared.
  4. On next login, the user is prompted to re-enroll.

Trusted Devices​

When "Remember Device" is enabled:

  1. After successful MFA, the user can mark the device as trusted.
  2. Future logins from the same device skip MFA.
  3. Trust expires after a configurable period (e.g., 30 days).
  4. Users can revoke trusted devices from account settings.
  5. Admins can clear all trusted devices for a user.

Best Practices​

  1. Use Required or Adaptive for production applications.
  2. Always enable backup codes to prevent lockouts.
  3. Recommend TOTP as the primary method — it is the most secure and reliable.
  4. Enable Remember Device to reduce friction for trusted devices.
  5. Set a reasonable grace period when rolling out mandatory MFA to existing users.
  6. Monitor MFA events in the audit log for suspicious activity.