Two-Factor Authentication Troubleshooting

Symptom-by-symptom resolutions for the most common 2FA issues. If your symptom isn't here, double-check the 2FA settings (master toggle on, at least one method enabled), the user's enrollment status on the User Management tab, and any SMS provider or email configuration in use.

A User Says They're Not Being Prompted for 2FA

Symptom: 2FA is enabled but a specific user signs in without ever being prompted for a second factor.

Causes and resolutions:

1. Enforcement is Risk-Based and the user is on a recognized device. Risk-based mode evaluates cookies and IP address against the user's sign-in history; if either matches, 2FA is bypassed. This is by design. To force prompting on every login regardless of device, switch the enforcement mode to Enforce for every login.
2. The user's existing session is still valid. 2FA prompts on sign-in, not on every page navigation. Have the user sign out and back in.
3. The master toggle is off. Confirm Enable Two-Factor Authentication is on.

The QR Code Doesn't Scan

Symptom: The user opens the enrollment screen but the authenticator app can't scan the QR code.

Causes and resolutions:

1. Screen brightness or contrast. Raise screen brightness and reduce glare. QR scanning needs good contrast.
2. App permissions. The authenticator app needs camera permission. Check device settings.
3. QR code too small or too large. Zoom the browser to roughly 100% and re-load the enrollment screen.
4. Use manual entry as fallback. The enrollment screen shows a text key alongside the QR code. The user can type this key into the authenticator app manually instead of scanning.

The Code From the Authenticator App Is Always Rejected

Symptom: The user enrolls successfully but every code they enter from the authenticator is rejected.

Cause: TOTP relies on the device clock matching the server clock. A clock skew of more than about 30 seconds will cause codes to be rejected.

Resolution:

1. Have the user check the time settings on the device running the authenticator app. Enable automatic time synchronization.
2. Some authenticator apps (Google Authenticator) have a built-in "time correction for codes" option in Settings > Time correction. Have the user re-sync.
3. If the issue persists, reset the user's enrollment and re-enroll. See Managing User MFA Enrollments.

SMS Codes Aren't Arriving

Symptom: A user selects SMS verification but never receives the code.

Causes and resolutions:

1. SMS provider Integration is not configured. Open the 2FA settings page and confirm an SMS provider Integration is selected. If none, SMS verification cannot send codes.
2. SMS provider Integration is unhealthy. Open the Integration record and confirm the credentials are valid. Send a test message from the provider's console.
3. The user's phone number is missing or malformed. Open the user's profile and confirm the phone number is in international format with country code.
4. Carrier delivery delay. SMS can take 30 seconds to several minutes depending on the carrier. Confirm the timeout window in the Security Code Timeout setting is long enough.
5. SMS provider rate limits. Heavy 2FA usage can hit the provider's rate limit; check the provider's console for throttle errors.

Email Codes Aren't Arriving

Symptom: A user selects Email verification, but does not receive the code.

Causes and resolutions:

1. Email Delivery Issues. Check the Email logs and Company Preferences for sender configuration, and ask the user to check their spam folder.
2. The user's email address is wrong or bounced. Confirm the email on the user's profile and check spam folders.
3. Code already expired. Email codes obey the Security Code Timeout setting. If the user takes too long to find the email, ask them to request a new code.

A User Is Locked Out by Too Many Invalid Attempts

Symptom: The user entered an incorrect verification code more times than the Maximum Invalid Attempts setting allows, and the platform stopped accepting further attempts in that verification session.

Resolution:

1. Verify the user's identity through an out-of-band channel.
2. Have the user start a new sign-in. The lockout counter is per verification session, so a fresh login automatically starts with a clean count — no admin action is required in most cases.
3. If the user is enrolled in the Authenticator App and you suspect their device or backup codes are compromised, open Security → Two-Factor Authentication → Reset Enrollment tab, select the user, and click Reset. This deletes their TOTP secret and backup codes; they will re-enroll on the next sign-in.
4. If many users are hitting the limit, consider raising Maximum Invalid Attempts from 3 to 5, 10, or No Limit under the Settings tab → Security Controls.

A User Lost Their Authenticator Device and Has No Backup Codes

Symptom: The user can't sign in because they lost their phone and exhausted all backup codes.

Resolution:

1. Verify the user's identity out-of-band.
2. Reset the user's enrollment in the Two-Factor Authentication settings page.
3. On next sign-in, the user is prompted to re-enroll with a fresh QR code and receives new backup codes.

To prevent future occurrences, encourage users to:

• Save their backup codes in a secure place (password manager, sealed envelope).
• Use an authenticator app with cloud backup (Authy, Microsoft Authenticator) so the TOTP secret survives a device change.
• Regenerate backup codes proactively from their profile after using a few.

Allow Fallback Methods Is Off and a User Lost Their Default Method

Symptom: A user's default method (e.g., Authenticator App) is unavailable, but the sign-in screen doesn't offer an alternate.

Cause: Allow Fallback Methods is turned off on the settings page. When off, users are locked to their default method.

Resolution:

1. If the policy is intentional, reset the user's enrollment and have them re-enroll with the default method.
2. If the policy is unintentional, enable Allow Fallback Methods on the settings page so users can pick an alternate from the allowed methods.

Authenticator Enrollment Is Required, But Users Aren't Being Forced

Symptom: Authenticator Enrollment is set to Required, but some users are signing in with Email or SMS without being prompted to enroll an authenticator.

Causes and resolutions:

1. Allow the Authenticator App is off. The Required policy only triggers when the Authenticator App method is allowed in the first place.
2. The user has an active session. Have the user sign out and back in to trigger the policy.
3. The user's Role is exempt. Some Roles may be excluded via the Security Roles configuration. Confirm the Role's 2FA setting.

The Overview Tab Shows Many Users in "Pending" Status

Symptom: A large number of users started enrollment but never completed it.

Causes and resolutions:

1. Users got stuck on the QR scan. Send a reminder email with the manual-entry instructions (the text key alongside the QR code).
2. Users abandoned the flow. If Authenticator Enrollment is Optional, they may have skipped intentionally. Consider switching to Required if 2FA adoption is mandatory.
3. Reset the Pending users. In the Two-Factor Authentication Settings, reset the enrollment for users in the Pending state, and the platform clears any partial state.

SMS Costs Are Too High

Symptom: The SMS provider bill is higher than expected after enabling 2FA.

Causes and resolutions:

1. Default Method is SMS. SMS sends a message on every prompt. Switching the default method to Authenticator App (which uses no provider) or Email (typically cheaper) reduces volume.
2. Resend Limit is No Limit. Lower the Resend Limit to 3 or 5 to cap per-session resends.
3. Risk-Based mode would reduce volume. If you're running Enforce for every login, but security needs allow it, switch to Enforce only for unrecognized devices.

<< Managing User MFA Enrollments