Two factor authentication plugin – FAQs

Two Factor Authentication

What are the shortcodes available in the two factor authentication plugin?

The following short-codes are available:

twofactor_user_settings : This short-code will display the whole user configuration. Use this to allow your users to get/set their TFA settings. Alternatively, to design the page yourself, you can use the individual short-codes, following:

twofactor_user_settings_enabled : Display the option to turn TFA on or off. If you supply the parameter style=”require_current” then the user will have to enter the current code correctly to be allowed to activate TFA.

twofactor_user_qrcode : Display the user’s QR code for scanning.

twofactor_user_emergencycodes : Display the user’s emergency codes.

twofactor_user_advancedsettings : Display the user’s advanced settings (e.g. selecting TOTP or HOTP).

twofactor_user_privatekeys : Display the user’s private keys. Use the ‘type’ parameter, with values ‘full’ (default), ‘plain’, ‘base32’ or ‘base64’ to control exactly what is displayed.

twofactor_user_privatekeys_reset : Display a link for the user to reset (change) their private key.

twofactor_user_currentcode : Display the current TFA code.

twofactor_user_presstorefresh : Wrap this shortcode around any HTML that you want to cause the current TFA code (displayed by the twofactor_user_currentcode shortcode) to refresh when clicked. i.e. Use both an opening and closing shortcode tag; and whatever you put inside will cause an update if the user clicks on it. Example:

Example short-code usage

twofactor_conditional : Wrap this shortcode around any content that you wish to be displayed only if the condition is met. The condition is specified by the “onlyif” parameter, with valid values: active, inactive, available, unavailable. The content will be shown depending on whether the user has TFA available (i.e. the administrator has allowed it for their user level)/activated. You can use this, for example, to display notices to your users to suggest that they activate TFA, or to remind them that it is available, etc.

Here are a couple of screenshots of examples of using these shortcodes. In the first, the site owner is using the WordPress page editor to design his own TFA-setup page for users, using short-codes:

Designing your own page for users, using short-codes

In the second is an example of the twofactor_conditional shortcode (make sure that you do not have anything cacheing a page it is used on):

Conditional shortcode example

What is two factor authentication?

Basically, it’s to do with securing your logins, so that there’s more than one link in the chain needing to be broken before an unwanted intruder can get in your website.

By default, your WordPress accounts are protected by only one thing: your password. If that’s broken, then everything’s wide open.

“Two factor” means adding a second requirement. Usually, this is a code that comes to a device you own (e.g. phone, tablet) – so, someone can’t get into your website without getting hold of your device. You can get a longer answer from Wikipedia.

Sometimes it is also called multi-factor authentication instead of two-factor – because someone could secure their systems with as many factors as they like.

How does two factor authentication work?

Since “two factor authentication” just means “a second something is necessary to get in”, this answer depends upon the particular set-up. In the most common case, a numeric code is shown on your phone, tablet or other device. This code could be sent via an SMS, but this depends on the mobile phone network working, and is technically easy to hijack (and so is not recommended by security professionals). So, this plugin does not uses that method. Instead, it uses a standard mathematical algorithm to generate codes that are only valid once each, or for only for 30 seconds (depending on which algorithm you choose). Your phone or tablet can know the code after it has been set up once (often, by just scanning a bar-code off the screen).

What do I need to set up on my phone/tablet (etc.) in order to generate the codes?

This depends on your particular make of phone, and your preferences. Google have produced a popular app called “Google Authenticator”, which is a preferred option for many people because it is easy to use and can be set up via just scanning a bar code off your screen – follow this link, and ignore the first paragraph that is talking about 2FA on your Google account (rather than being relevant to this plugin).

What if I do not have a phone or tablet?

Many and various devices and programs can generate the codes. One option is an add-on for your web browser; for example, here are some apps and add-ons for Google Chrome. Wikipedia lists various programs for different computers.

I lost my device that has pass-codes – or, they don’t work. What to do?

If your pass-code used to work, but no longer does, then check that the time on your device that generates them is accurate (it needs to agree with the webserver within around 30 seconds; note that time zones are irrelevant to this – what they need to agree on is how many seconds have passed since it became the year 1970 in London).

If you cannot get in and need to disable two-factor authentication, then add this to your wp-config.php file, using FTP, SFTP, shell access or the file manager in your hosting control panel:

define('TWO_FACTOR_DISABLE', true);

Add it next to where any other line beginning with “define” is.

Alternatively, if you have FTP, SFTP, shell access or cPanel access to your web hosting space, you can de-activate the plugin; see this article:

What are HOTP and TOTP?

These are the names of the two mathematical algorithms that are used to create the special codes. These are industry-standard algorithms, devised by expert cryptographers. HOTP is less popular, but the device that generates the codes does not need to know the correct time (instead, the codes are generated in a precise sequence). TOTP is much more popular, and generates codes that are only valid for 30 seconds (and so your device needs to know the time). I’d recommend TOTP, as HOTP can be annoying if something causes the sequences to get out of sync.

How can I trigger an action when the user saves their TFA settings on the front-end?

When settings are successfully saved, the plugin triggers a jQuery event upon the document:

jQuery(document).trigger('tfa_settings_saved', resp);

So, you just need to add some JavaScript to your site (e.g. using one of the popular plugins for doing this, or using your own hand-coding) to hook that event.

For example, to reload the page after the settings are saved:

jQuery(document).on('tfa_settings_saved', function() {

Can the two-factor code be sent by email?

Our two-factor authentication plugin does not support sending codes by email, because this is not secure. This is because WordPress also sends password reset links by email (via the link on the login form for people who have forgotten their password). Thus, the email account would have access to both the ability to set passwords and read two-factor codes, meaning that it was not truly a second factor. This would be mitigated somewhat if the email itself was protected by two-factor authentication via another mechanism – but in this case a) users are already being expected to use something other than email, so that shouldn’t be a problem for WordPress either, and b) it is outside of the control of the administrator of the WordPress website, which would nullify the plugin’s features for handing them this control.

Email delivery is also unreliable and often unencrypted, which makes it an unsuitable communications channel to rely upon for time-dependent (two factor codes are time-limited) and security-related functions.

Is any user personal information processed (for GDPR etc.) purposes by the plugin?

No. Logging in, setting up TFA, and all other operations of plugin functionality do not send any data to any remote service.

If you connect the plugin to receive plugin updates using the WordPress plugin update mechanism, then it will periodically request information on update availability from our servers. The information contained in this update check (e.g. the identifier for your account with us, the WordPress and PHP version the plugin is running on) is not processed by us for any further purpose. It does not contain any information on how or by whom the plugin is used (i.e. “telemetrics”) beyond the URL of the website it is installed upon. The HTTP request as logged by our webserver may remain in our webserver logs until they are periodically and automatically rotated, up to 6 months later.

I deliberately entered a wrong password, and the Two Factor Authentication plugin let me log in

You have a password manager extension installed in your web browser, with the correct password entered in it. It has automatically replaced your wrong password with the right one from its saved store. This behaviour has been observed and confirmed by several users. You can verify it by using the web developer tools in your browser to look at the HTTP data sent to WordPress, and observe which password is actually in it. You can also open a fresh web browser with no such extension in it to re-test.

Note that the two factor authentication plugin has no mechanism to compare or approve passwords; this is done by WordPress core. If the wrong password is sent, then this is handled by WordPress, and the login will not proceed.