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.
Installation and use
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.
Configuration
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.
Default validation plugin
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.
Fallback plugins
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.
Plugin development
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.
Getting started
- 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/.
Plugin interfaces, or types of plugins
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.
Plugin context
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.
Base methods
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.
Cryptography
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
Example implementation descriptions
How to generate and send a code to a user via SMS
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
Available plugins for install as separate modules:
- TFA Basic - includes plugins: Time-based One Time Password,
Trusted Browser, Recovery Codes, and Twilio SMS.
License
This project is GPL v2 software. See the LICENSE.txt file in this directory for complete text.
Current Maintainers
This module is currently seeking co-maintainers.
Credits
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.