Second-factor authentication for Backdrop sites. Backdrop provides authentication via something you know -- a username and password while TFA module adds a second step of authentication with a check for something you have -- such as a code sent to (or generated by) your mobile phone.
TFA is a base module for providing two-factor authentication for your Backdrop site. As a base module, TFA handles all of the Backdrop integration work, providing flexible and well tested interfaces to enable seamless, and configurable, choice of various two-factor authentication solutions like Time-based One Time Passwords, SMS-delivered codes, fallback codes, or integrations with third-party suppliers like Authy, Duo and others.
Read more about the features and use of TFA at its Backdrop.org project page at https://backdropcms.org/project/tfa.
TFA module can be installed like other Backdrop modules by placing this directory in the Backdrop file system (for example, under sites/all/modules) and enabling on the Backdrop modules page.
TFA module does not come with any plugins of its own so refer to the project page for contributed plugins or read the section on Plugin development.
TFA can be configured on your Backdrop site at Administration - Configuration - People - Two-factor Authentication. Available plugins will be listed along with their type and configured use, if set.
Additionally, a permission is exposed to Backdrop roles allowing them to skip the TFA process -- regardless of plugins and the "require TFA" setting.
The plugin that will be used by default during user authentication. The plugin must be ready for use by the authenticating account. If "Require TFA" is marked then an account that has not setup TFA with the validation plugin will be unable to log in.
With multiple validation plugins installed, TFA can be setup to handle fallback options for a user going through the TFA process. For example, let's say a user has setup SMS code delivery and TOTP via Google Authenticator app on their phone. In the situation that the user has deleted the Authenticator app they could fallback to SMS code delivery and still authenticate to the site.
TFA plugins provide the form and validation handling for 2nd factor authentication of a user. The TFA module will interrupt a successful username and password authentication and begin the TFA process (see Configuration for exceptions to this statement), passing off the form control and validation to the active plugin.
- Implement
hook_tfa_api()in a .module file - Create a class extending
TfaBasePluginand implementing one of the TFA interfaces. - Optionally create a second class for plugin setup implementing
TfaSetupPluginInterface. For starter or example code see the test classes at./tests/includes/.
TFA plugins should implement one of the following interfaces.
- Validation (
TfaValidationPluginInterface) - Validation plugins are the main TFA plugin and are used during the authentication process to accept the 2nd authenticating element. - Login (
TfaLoginPluginInterface) - Login plugins are used to limit what accounts must carry out TFA before final authentication. - Send (
TfaSendPluginInterface) - Send plugins are used for carrying out an action at the beginning of the TFA process. For example, a plugin that sends a code to a user over SMS could implement this interface to generate and text the code. - Setup (
TfaSetupPluginInterface) - A setup plugin is used by the TfaSetup class for configuring a TFA plugin for an account.
A plugin is instantiated with an array of data about the occurring TFA process. This context array must contain the following elements that should not be modified.
uid- Backdrop UID of user carrying out the TFA process.plugins- Array of active plugins in the process, must include element 'validate' and may also include 'login' and 'fallback'.
The context array may also include any plugin-specifc elements so long as there is no conflict with the above keys. Context can be used for temporal storage of plugin data like codes or state but do be aware that this context may be written to the Backdrop session or form cache database tables.
Plugins can implement the ready() method to determine if its ready for use with
the authenticating account. For example, if authenticating user has not setup of
a phone number for SMS delivery a SMS TFA plugin would not want to begin the TFA
process for that account and should return FALSE.
The finalize() method can be used to carry-out actions after confirming the TFA
process. For example, a SMS plugin might mark a code as having been used to
prevent a repeated attempt.
The base TFA plugin class provides encryption and decryption methods using PHP Mcrypt. While you can use these methods for simple encryption it is recommended that you utilize more advanced cryptography libraries with your own plugins.
Use one of the following libraries and override the TfaBasePlugin encrypt and
decrypt methods.
- Zend Framework's Zend\Crypt
- phpseclib
Create a plugin that implements the TfaSendPluginInterface interface and
implement the begin() method to generate a code (or use parent generate()) and
send it to the user. Use the SMS Framework or Twilio modules (for example) to
actually deliver the code over SMS.
Implement the TfaSetupPluginInterface to allow the user to
set the phone number for delivery. Separately implement hook_schema() to create
a database table for storing TFA phone numbers or use a account profile field.
How to allow web services to authenticate while requiring TFA for regular users
A services authentication scheme will be affected by TFA's implementation during
hook_user_login() so create a login plugin that checks the services user and
returns TRUE for loginAllowed(). See TfaTestLogin in ./tests/includes for an
example.
Available plugins for install as separate modules:
- TFA Basic - includes plugins: Time-based One Time Password, Trusted Browser, Recovery Codes, and Twilio SMS.
This project is GPL v2 software. See the LICENSE.txt file in this directory for complete text.
This module is currently seeking co-maintainers.
Ported to Backdrop by Herb v/d Dool.
This module was originally written for Drupal (https://drupal.org/project/tfa). Drupal maintainers are: coltrane, nerdstein, daggerhart.