Hyva Compatibility Add-On
Customer TFA uses a separate package for storefronts based on Hyva. The add-on supplies Hyva and Alpine-compatible templates for enrollment, login verification, recovery codes and account management. The base package still owns the security rules, customer data, routes and Admin configuration.
- Composer package:
mageb2b/customer-tfa-hyva - Magento module:
MageB2B_CustomerTFAHyva - Required base package:
mageb2b/customer-tfa - Required storefront: Hyva Default Theme
You do not need this package for Luma, Blank or a theme that inherits Magento's standard frontend templates.
Install the add-on
Install and configure the base package first. Then add the Hyva bridge:
composer config bearer.repo.softwaresilo.io <token>
composer config repositories.softwaresilo composer https://repo.softwaresilo.io/
composer require mageb2b/customer-tfa-hyva:*
php bin/magento module:enable MageB2B_CustomerTFAHyva
php bin/magento setup:upgrade
php bin/magento setup:di:compile
php bin/magento cache:flush
php bin/magento hyva:config:generate
Rebuild the Tailwind CSS for every active Hyva theme after installation. Use the normal static-content deployment steps required by the Magento mode and storefront locales.
Storefront coverage
The add-on provides Hyva templates for the complete customer flow:
| Area | What the customer can do |
|---|---|
| Account dashboard | See whether TFA is active and start enrollment |
| Enrollment | Scan the QR code, enter the secret manually and verify the first authenticator code |
| Recovery-code handoff | Save the newly generated one-time codes after enrollment or regeneration |
| Login verification | Submit an authenticator code or switch to a recovery code |
| Account management | Regenerate recovery codes or disable optional TFA when the store configuration permits it |
The same settings apply to Luma and Hyva. For example, disabling customer recovery-code regeneration removes that block from the Hyva account dashboard as well. Mandatory TFA also prevents customer deactivation in both storefronts.
What remains in the base package
The add-on does not store a second secret or create a separate login session. It replaces storefront presentation only. These functions remain in MageB2B_CustomerTFA:
- TOTP secret creation and verification;
- recovery-code generation, hashing and one-time use;
- pending-login and attempt limits;
- website and store-view configuration;
- Login as Customer handling;
- Admin status display and reset action.
Keep both modules enabled. Disabling the base module leaves the Hyva templates without the services and routes they call.
Verify the integration
Test with a fictional customer on the actual Hyva store view:
- enable TFA from the customer account and scan the QR code;
- save the recovery codes and complete a fresh password login;
- submit a valid authenticator code, then repeat the login with one recovery code;
- regenerate recovery codes and confirm that an old code no longer works;
- disable optional TFA when the action is allowed;
- enable mandatory TFA and confirm that an unenrolled account is sent to setup;
- check the same pages at a mobile viewport.
Also test the configured Login as Customer policy. The Hyva templates do not change whether an impersonated session must complete TFA.
Troubleshooting
The standard Magento template is still displayed
Confirm that the active store view uses a Hyva theme and that MageB2B_CustomerTFAHyva is enabled. Regenerate the Hyva configuration, rebuild Tailwind CSS and clear Magento caches.
The page has no styling
Check that the module's view/frontend/tailwind/module.css is included in the active theme build. Rebuilding Magento static content alone does not replace the Hyva Tailwind build.
An account action is missing
Check the base Customer TFA configuration at the active scope. Recovery-code regeneration and customer deactivation have independent settings. Deactivation is also hidden while TFA is mandatory.
Verification returns to the login page
Treat this as a base authentication issue rather than a theme setting. Check the pending-login lifetime, verification attempt limit, session and form key, then follow Common Issues.