Moodle 4.3 ships with multi-factor authentication (MFA) as a built-in admin tool. This guide covers enabling TOTP-based 2FA, configuring a grace period so users have time to set up the app, replacing the confusing default grace period message with something users can actually act on, and verifying the setup without risking locking yourself out.

Why an authenticator app, not email

Email-based codes are better than nothing, but they shift the second factor to a channel that may itself be compromised. If an attacker already has access to a user’s email account, an emailed code provides no meaningful protection. A TOTP app (Google Authenticator, Aegis, Microsoft Authenticator, or any compatible app) generates time-based codes that never leave the device. That is what makes it a genuine second factor.

This guide therefore disables the email factor entirely. There is no point offering a weaker alternative alongside a strong one, because users will gravitate toward whichever is easiest.

Before you start

  • Moodle 4.3 or later. MFA is built in as tool_mfa; no plugin installation needed.
  • Site administrator access.
  • A second Moodle administrator account that you can use to recover access if something goes wrong. Set up TOTP on that account before enforcing the policy.
  • Keep a non-incognito browser window with an active admin session open throughout. This is your safety net.

Step 1: Enable MFA

Go to Site administration > Plugins > Admin tools > Multi-factor authentication > Manage multi-factor authentication.

At the top of the page, check the box labeled MFA plugin enabled and save.

Step 2: Enable the Authenticator App factor

On the same Manage multi-factor authentication page, find Authenticator app in the factor list and click its Settings link.

  • Enable factor: Yes
  • Factor weight: 100

Save changes.

Step 3: Disable the Email factor

Back on the Manage multi-factor authentication page, find Email in the factor list and click its Settings link.

  • Enable factor: No

Save changes.

Step 4: Configure the Grace Period

The grace period factor allows users to log in for a set number of days without having completed MFA setup. During this window, Moodle prompts them to get the authenticator app configured. Once the grace period expires, they cannot log in until they have done so.

On the Manage multi-factor authentication page, find Grace period in the factor list and click its Settings link.

  • Enable factor: Yes
  • Grace period: this is a duration field. Enter a number and pick a unit from the dropdown. Set it to, for example, 5 with the unit days (a reasonable default). The shipped default is 1 week.

Save changes.

On the factor list page, make sure Grace period appears after Authenticator app in the order. Use the up/down arrow icons next to each factor to move it down if needed. This ensures Moodle checks whether a user already has the app set up before falling back to the grace period.

Step 5: Fix the grace period warning message

The default message users see during the grace period reads:

You are currently in the grace period, and may not have enough factors set up to log in once the grace period expires. Go to {$a->url} to check your authentication status and set up more authentication factors. Your grace period expires in {$a->time}.

This is unhelpful. Users do not know what “factors” are. The message also does not tell them what to actually do. Replace it with something clear and actionable.

Go to Site administration > Language > Language customisation. Select your language (for example, English (en)) and click Open language pack.

In the filter form, enter the following and click Show strings:

  • String identifier: setupfactors
  • Component: factor_grace

One result appears. In the Local customisation field, paste:

To keep your account secure, we require Two-Factor Authentication (2FA). Go to {$a->url} to set up an Authenticator app on your phone. You have {$a->time} left to do this. After this period, you will not be able to log in without it.

Click Apply changes and continue editing, then Save changes to the language pack.

The placeholders {$a->url} and {$a->time} are filled in by Moodle at runtime, so leave them exactly as written.

Step 6: Test without locking yourself out

Keep your admin session active in the regular browser. Then open an incognito or private browser window and log in as a regular user, either a dedicated test account or a colleague’s account with their permission.

Verify the following:

  • The grace period message appears after login and shows your custom text.
  • The link in the message takes the user to their MFA preferences page.
  • The user can scan the QR code with an authenticator app and complete setup.
  • After setup, logging out and back in prompts for the TOTP code and grants access once the correct code is entered.

If anything is misconfigured, your open admin session lets you correct it without getting locked out.

Once the full flow works, set up TOTP on your own admin account if you have not done so already.

Need help with a Moodle or Totara project?

Contact us