Magento 2 Admin Two Factor Authentication: Setup and Fixes

Since Magento 2.4.0, every admin login requires a second factor. The Magento_TwoFactorAuth module ships enabled in both Magento Open Source and Adobe Commerce, and an admin user cannot reach the dashboard until they configure a provider. It is one of the most useful security features in the platform, and also one of the most common sources of support requests: lost phones, emails that never arrive, local environments where nobody can log in.

This article covers how the module works, how to configure it for a team, the CLI commands that solve most problems, and what to do in local development without weakening production.

How the first login works

When an admin user without a configured provider logs in with a valid password, Magento does not open the dashboard. It sends an email to that user with a link to configure two factor authentication. The user opens the link, chooses a provider (or gets the one the store forces), and completes the setup. From then on, each login asks for the password and then the second factor.

The email step is intentional. It proves the person logging in also controls the mailbox of the account. It also means that if the store cannot send email, new admin users cannot finish the setup. That is the first thing to check when someone says they are stuck on the "you need to configure two factor authentication" screen.

Available providers

The module includes several providers. Which ones you see depends on your version, so check the configuration screen or list them from the CLI:

bin/magento security:tfa:providers

• Google Authenticator. Standard time based one time passwords. Despite the name, it works with any TOTP app, such as Microsoft Authenticator, 1Password or Bitwarden. This is the simplest choice for most teams.
• Duo Security. Push notifications through Duo. It needs a Duo account and the integration keys from the Duo admin panel, entered in the Magento configuration.
• U2F security keys. Hardware keys such as YubiKey, using WebAuthn in the browser. The strongest option against phishing. Security keys need HTTPS, and the key is tied to the admin domain it was registered on.

Forcing a provider

By default users can choose among the enabled providers. For a team it is easier to support one. Set the forced providers under Stores, Configuration, Security, 2FA, or from the CLI:

bin/magento config:set twofactorauth/general/force_providers google

To allow more than one, separate the codes with commas, for example google,u2fkey. Use the codes printed by security:tfa:providers. Lock the value in app/etc/env.php with --lock-env if you do not want it changed through the admin.

CLI commands that solve most problems

A user lost their phone

Reset the provider for that user. On the next login they go through the setup again:

bin/magento security:tfa:reset john.smith google

The arguments are the admin username and the provider code. An administrator can also do this in the admin, on the user edit page, where the two factor configuration can be reset per provider.

Before resetting, confirm the request really comes from that person through a channel other than email. Resetting 2FA for whoever asks is how social engineering gets around it.

Email does not work and someone must log in now

You can set the Google Authenticator secret for a user directly, skipping the email link. Generate a base32 secret, set it, and add it to the authenticator app manually:

SECRET=$(head -c 20 /dev/urandom | base32 | tr -d '=')
bin/magento security:tfa:google:set-secret john.smith "$SECRET"
echo "$SECRET"

Most authenticator apps have an option to enter a setup key instead of scanning a QR code. Use a time based key. This is a recovery tool for someone with server access, so treat the secret like a password and do not paste it in chat tools.

The code is always rejected

Time based codes depend on the clock. If the server clock drifts, every code fails. Check that the server time is synchronized with NTP, and that the phone uses automatic time. This causes more failed logins than any bug in the module.

Local development

On a local environment, typing a code at every login is annoying, and email often goes to a catcher like Mailpit, so the first setup is awkward. There are two clean options.

Use the CLI secret. Set a Google Authenticator secret for your local admin user with the command above and add it to your authenticator app once. This keeps the local environment closer to production.

Disable the modules locally only. Since 2.4.6, the Adobe IMS two factor module depends on the main module, so both have to be disabled together:

bin/magento module:disable Magento_AdminAdobeImsTwoFactorAuth Magento_TwoFactorAuth
bin/magento cache:flush

This writes to app/etc/config.php, which is committed to the repository. That is the risk: one careless commit and production has no second factor. If you disable it locally, keep config.php changes out of your commits, or add a check in your deploy pipeline that fails when Magento_TwoFactorAuth is disabled. Some teams use a small development only module that turns 2FA off through configuration instead of disabling the module, installed as a dev dependency so it never reaches production.

The local environment setup I recommend is in the Docker and Warden guide.

API access with 2FA enabled

With the module enabled, the standard admin token endpoint is no longer enough on its own, because a token would let a client skip the second factor. Integrations are not affected, since they use their own tokens and are not tied to an admin login. For scripts that need an admin token, the module provides provider specific endpoints that take the username, password and a current code. For Google Authenticator:

curl -X POST "https://example.com/rest/V1/tfa/provider/google/authenticate" \
    -H "Content-Type: application/json" \
    -d '{"username":"api.user","password":"...","otp":"123456"}'

For unattended scripts this is impractical, because nobody is there to type a code. Use an integration with limited resources instead. The tradeoffs are covered in the web API authentication article.

Operational advice

• Never disable 2FA in production to solve a support problem. Reset the user instead.
• Make sure transactional email works, and test it by creating a new admin user after every major change to mail settings.
• Keep at least two people with full admin access and working 2FA, so one lost phone does not lock the business out. Someone with server access can always reset through the CLI, but that should be the last resort.
• Remove admin users who no longer need access. 2FA protects accounts, it does not decide who should have one. The rest of the checklist is in the admin hardening guide.

FAQ

Can I disable two factor authentication in Magento 2?

You can disable the Magento_TwoFactorAuth module, and since 2.4.6 also Magento_AdminAdobeImsTwoFactorAuth. Do it only in local development, never in production.

How do I reset 2FA for a Magento admin user?

Run bin/magento security:tfa:reset with the username and provider code, for example google. The user configures the provider again at the next login.

Why are my Google Authenticator codes rejected?

Usually the server or phone clock is out of sync. Time based codes only work when both clocks are correct, so check NTP on the server.

Do Magento integrations need two factor authentication?

No. Integrations use their own tokens and are not tied to an admin login, so they keep working. Give them only the resources they need.

I am available for freelance Magento and Adobe Commerce work, including admin security setup. If you need help with this, get in touch.