Troubleshooting Guide

Common questions and resolution steps for Magento 2 Two Factor Authentication.

Issue 1: SMS OTP is Not Delivered to Customers

Invalid Twilio Credentials: Verify Auth ID (Account SID) and Token (Auth Token) under Stores > Configuration > Webkul > Two Factor Auth.
Invalid Sender Number: Ensure your Sender Number in Magento matches your active Twilio phone number in E.164 international format (e.g. +1234567890).
Twilio Trial Account Limitations: If using a Twilio trial account, SMS messages can only be sent to pre-verified caller IDs in your Twilio Console.
Missing Twilio Composer SDK: Ensure twilio/sdk:^8.6 is installed via Composer:
```
composer require twilio/sdk:^8.6
```

In Magento Admin, go to Customers > All Customers and edit the locked customer.
Select the Two Factor Auth tab.
Click Unlock 2FA Account to reset failure counters and lift the lockout immediately.
Or wait for the Account Lockout Duration timer to expire automatically.

Server Clock Drift: The TOTP algorithm (RFC 6238) depends on synchronized system clocks between the server and the customer's smartphone. If your server clock drifts by more than 30–60 seconds, generated codes will be rejected.
- Sync your server clock using NTP:
```
sudo timedatectl set-ntp on
sudo systemctl restart systemd-timesyncd
```
Device Clock Drift: The customer's smartphone must have "Set time automatically" enabled in date & time settings.
Expired Time Window: TOTP codes refresh every 30 seconds. Ensure the customer submits the current rolling code before the timer elapses.

Non-HTTPS Connection: Push notifications require a secure origin (https://). Service workers will not register on insecure HTTP domains.
Browser Permission Blocked: If the user previously clicked "Block" on the browser notification prompt, they must go to browser site settings and change the notification permission to "Allow".
Invalid Firebase Credentials: Verify your Web API Key, Project ID, App ID, and ensure your Firebase Service Account JSON file is correctly uploaded.

The customer can click Sign In another way on the 2FA prompt and enter one of their 12 unused single-use Backup Recovery Codes.
If the customer does not have any remaining backup codes, the store administrator can generate fresh backup codes from Customers > All Customers > Edit Customer > Two Factor Auth > Generate.