Two-Factor Authentication for Customers

Two-factor authentication (2FA) adds a second verification step to the login process, after entering a username and password, users must also confirm their identity with a time-based code from an authenticator app. Storefront supports app-based 2FA (TOTP) for your customers.

2FA is optional for customers. They set it up and manage it from their own account settings. As the reseller, you can see whether each customer has 2FA enabled, and you can disable it on their behalf if they lose access to their authenticator device.

How 2FA works in Storefront

Storefront uses TOTP (Time-based One-Time Password), the same standard used by Google Authenticator, Authy, 1Password, and similar apps. Customers scan a QR code in their account settings, and the app generates a fresh 6-digit code every 30 seconds.

SMS-based 2FA is not supported. Customers who don't have an authenticator app will need to install one before setting up 2FA.

When 2FA is enabled on an account, an attacker with the customer's username and password still cannot log in without also having the authenticator device. This protects domains and account settings from unauthorized access if credentials are compromised.

What your customers experience

Setting up 2FA

Customers set up 2FA from their account settings page.

1. The customer navigates to Account → Settings in the Storefront customer portal.
2. They click Set up two-factor authentication.
3. A QR code is displayed. The customer opens their authenticator app and scans the code.
4. If they cannot scan the QR code, a text key is also displayed in a copyable format for manual entry into the app.
5. The customer enters the 6-digit code shown in their authenticator app to confirm the setup is working.
6. Storefront displays 10 recovery codes. The customer should save these immediately in a secure location. Each recovery code can only be used once and cannot be retrieved later.
7. 2FA is now active on the account. The customer remains logged in.

Important: Recovery codes are the only way a customer can access their account if they lose their authenticator device. Emphasize this when customers ask about setup.

Logging in with 2FA

After a customer has 2FA enabled, the login flow has two steps.

1. The customer enters their username and password as usual.
2. A 2FA prompt appears asking for their current authenticator code.
3. The customer opens their authenticator app, enters the 6-digit code, and submits.

Storefront accepts codes from a small window around the current time to account for slight clock differences between the customer's device and the server. If a customer enters a valid code and still sees an error, their device clock may be significantly out of sync, most authenticator apps have a time sync option in settings.

If a customer enters an invalid code, a clear error message appears and they can try again.

Using a recovery code

If a customer can't access their authenticator app, they can use one of their saved recovery codes to log in.

1. At the 2FA prompt, the customer clicks Use a recovery code.
2. They enter one of their saved recovery codes.
3. Storefront grants access for that session.
4. After logging in, the customer sees a prompt on their domains page recommending they reset their 2FA settings with a link to the settings page.

Each recovery code works only once. Using a recovery code does not disable 2FA, the customer still needs to enter a code on their next login unless they disable 2FA first or set up a new authenticator.

If a customer has used all their recovery codes and lost their authenticator device, they cannot log in on their own. You can disable their 2FA from Storefront Manager — see below.

Disabling 2FA

Customers can turn off 2FA from their account settings.

1. The customer navigates to Account → Settings.
2. They click Disable two-factor authentication.
3. They enter their account password to confirm.
4. 2FA is removed from the account. All recovery codes are invalidated.

The customer can re-enable 2FA at any time by going through the setup flow again.

Reseller tools

This feature won’t be available until it is released as part of the redesign in the May release.

View a customer's 2FA status

The customer details page shows whether each customer has 2FA enabled.

1. Log in to Storefront Manager.
2. Navigate to Customers and open the customer's record.
3. Look for the Two-Factor Authentication field in the account details section.

The status shows as either Enabled or Disabled. This is a read-only display, you cannot enable 2FA on a customer's behalf, only disable it.

Disable a customer's 2FA

Use this when a customer has lost their authenticator device and all their recovery codes and cannot log in.

1. Navigate to Customers and open the customer's record.
2. Confirm the Two-Factor Authentication field shows Enabled. The Disable button only appears when 2FA is active.
3. Click Disable.
4. A confirmation pop-up appears. Click Disable to confirm.
5. A notification confirms that 2FA has been disabled.

After you disable 2FA, the customer's TOTP secret and all remaining recovery codes are permanently invalidated. The customer can log in with their username and password alone. If they want 2FA again, they go through the setup flow from the beginning.

This action is logged in the customer's event log.

Password resets and 2FA

If a customer with 2FA enabled uses the Forgot password link to reset their password via email:

• After clicking the link and setting a new password, the customer is not logged in directly.
• Instead, they are taken to the 2FA prompt and must enter their authenticator code to complete the login.

2FA remains active through a password reset. The only way to bypass this is for you to disable 2FA on their account from Storefront Manager first.

Troubleshooting

A customer says their authenticator code isn't being accepted. 

First, confirm the code is current, TOTP codes refresh every 30 seconds, and entering a code in the last second or two before it refreshes can cause a timing mismatch. Ask them to wait for the next code and try again. If codes continue to fail, their device clock may be out of sync. Most authenticator apps have a Sync time or Fix time sync option in settings, ask them to use it.

A customer is locked out and has no recovery codes. 

The customer cannot log in on their own. Disable their 2FA from Storefront Manager (see above). Once disabled, they can log in with their password and set up 2FA again.

A customer wants to switch to a new authenticator app or phone. 

They should disable 2FA while they still have access to the old app, then set it up again on the new device. If they've already lost access to the old app, use the disable flow in Storefront Manager first.

A customer used a recovery code but still can't get into their account. 

Each recovery code works only once, if the code they entered was already used, it won't work again. If they have remaining unused codes, ask them to try another one. If all codes are exhausted and they've also lost their authenticator, disable their 2FA from Storefront Manager.

I can't see the Disable button on the customer's page. 

The Disable button only appears when the customer has 2FA enabled. If the status shows Disabled, 2FA is already off and no action is needed.

Related articles

• Managing Customer Accounts and Domains
• Using the Event Log

Questions? Contact OpenSRS Support.