Recommended releases

Download Released

Intent is to provide basic functionality of TFA Backdrop module and to be an
example of TFA plugin development.

Please use the public issue queue for all feature and support requests:


  • TOTP
    A Time-based One Time Password plugin using PHP_Gansta\GoogleAuthenticator
    PHP library.

  • Trusted Browsers
    A TFA login plugin allowing browsers to be marked "trusted" so that subsequent
    logins will not require TFA for a 30 day window.

  • Recovery Codes
    Pre-generated one-time-use codes.

  • Twilio SMS
    Optional plugin for sending TFA codes via SMS messages. See SMS section below.


  • tfa_basic_secret_key
    Secret key to to use as encryption key for TOTP seed encryption. Should be set
    in settings file. For example:

    $settings['tfa_basic_secret_key'] = '1234567890';

  • tfa_basic_time_skew
    Number of 30 second chunks to allow TOTP keys between.

  • tfa_basic_name_prefix
    Prefix for TOTP QR code names. Suffix is account username.

  • tfa_basic_cookie_name
    Cookie name of TFA trusted browser cookie. Default is "TB". Rarely needs to be
    changed but can set in settings file:

$settings['tfa_basic_cookie_name'] = 'mycookie';

  • tfa_basic_cookie_domain
    Cookie domain for TFA trusted browser cookie.

  • tfa_basic_trust_cookie_expiration
    How long before TFA cookies expire. Default is 30 days.

  • tfa_basic_accepted_code_expiration
    How long before accepted TOTP codes expire. Default is 1 day.

Using qrcode.js library instead of Google images

By default the module uses Google's Chart API to create a QR code. That request
will leak the seed to google in the URL of an HTTP GET request which reduces
the security of the seed. The module also supports the qrcode.js project which
will create the QR code image without leaking information to third-party sites.

To enable qrcode.js you simply have to place the library in the
tfa_basic/includes directory. From the command line:

cd tfa_basic/includes/
git clone

The qrcode.min.js file should be at tfa_basic/includes/qrcodejs/qrcode.min.js

No additional setup is necessary, if the file exists in the right location then
it will be used.

Using SMS for TFA codes

Currently disabled until
is resolved.


  1. Set up a Twilio account and credit at
  2. Install Twilio PHP library.
  3. Provide account mobile phone number by:
    a. Creating an account textfield and configuring it for TFA use, or
    b. Implementing hook_tfa_basic_get_mobile_number_alter()

Installing Twilio PHP library

TFA SMS plugin requires the Twilio PHP library for sending SMS codes. You can
install the Twilio PHP library manually or via the Backdrop Libraries API.

Option 1, install Twilio PHP manually:

cd tfa_basic/includes/
git clone

Such that the file tfa_basic/includes/twilio-php/Services/Twilio.php exists.

Option 2, install via Backdrop Libraries API:

  1. Install Backdrop Libraries API:
  2. Download the Twilio PHP library from (
  3. Extract the library in your /libraries folder and rename the
    directory to 'twilio'.

Account mobile phone numbers

Accounts using SMS for TFA code delivery must have a mobile phone number able
set. By default, TFA Basic's SMS plugin has support for storing mobile numbers
in user account fields. Create a text field on an account and you can set its
use by the plugin on the TFA administration configuration page.

If you want to store the mobile number somewhere else you'll need to write a bit
of code to integrate with TFA Basic.

First, set the variable tfa_basic_phone_field to FALSE. This will inform TFA
Basic that you are using custom storage.

drush vset tfa_basic_phone_field FALSE

Finally, implement hook_tfa_basic_get_mobile_number_alter() in a custom module.
The sole argument is an array with elements 'account' and 'number'. 'account' is
the Backdrop user account object you can use in finding the mobile number.
'number' will be an empty string if there's no account field in use. You should
set the 'number' property to the mobile number you have stored.

When an account is enabling SMS delivery they have the option to change the
mobile number receiving SMS codes. If the number is changed you can implement
hook_tfa_basic_set_mobile_number_alter() in a custom module to update your

Handling numbers that are not NANP

  • Implement hook_tfa_basic_valid_number_alter() for number validation
  • Implement hook_tfa_basic_format_number_alter() for formatting number output


This project is GPL v2 software. See the LICENSE.txt file in this directory for complete text.

Current Maintainers

Herb v/d Dool (

This module is currently seeking co-maintainers.


Ported to Backdrop by Herb v/d Dool (

This module was originally written for Drupal ( Drupal maintainers are: coltrane.