Two-factor Authentication (TFA)
Pluggable provider of second factor authentication for Drupal that enhances account security by requiring an additional verification step during login.
tfa
Install
composer require 'drupal/tfa:8.x-1.12'
Overview
The Two-factor Authentication (TFA) module is a comprehensive security enhancement for Drupal that adds an extra layer of protection to user accounts. It provides flexible and well-tested interfaces to enable seamless integration of various two-factor authentication solutions.
The module supports multiple authentication methods including Time-based One-Time Passwords (TOTP), HMAC-based One-Time Passwords (HOTP), recovery codes, and trusted browser functionality. TFA uses a plugin-based architecture allowing easy extension through additional modules.
All sensitive data is encrypted using the Encrypt module, ensuring secure storage of authentication secrets. The module includes flood control protection against brute-force attacks, email notifications when TFA is enabled/disabled, and Views integration for administrators to see which users have TFA enabled.
Features
- TOTP (Time-based One-Time Password) validation supporting apps like Google Authenticator, Microsoft Authenticator, Authy, and FreeOTP
- HOTP (HMAC-based One-Time Password) validation using counter-based codes
- Recovery codes generation for account recovery when primary authentication device is unavailable
- Trusted browser functionality to skip TFA verification on trusted devices for a configurable period
- Plugin-based architecture allowing custom TFA methods through contributed or custom modules
- Flood control protection limiting failed validation attempts to prevent brute-force attacks
- Email notifications sent when users enable or disable TFA on their accounts
- Views field integration showing TFA status for users in administrative listings
- Per-role TFA requirements forcing specific user roles to configure TFA
- Skip validation feature allowing users a limited number of logins before requiring TFA setup
- QR code generation for easy authenticator app setup
- Drush commands for resetting user TFA data and database sanitization
- REST API support for TFA validation in headless applications
Use Cases
Securing administrator accounts
Require all users with the Administrator role to set up TFA before accessing the site. Configure TFA at /admin/config/people/tfa, select the Administrator role under 'Roles required to set up TFA', and ensure administrators have the 'setup own tfa' permission. Administrators will be prompted to configure TFA on their next login.
Optional TFA for regular users
Allow users to optionally enable TFA without requiring it. Grant the 'setup own tfa' permission to the Authenticated role. Users can then access their account's TFA tab (/user/{uid}/security/tfa) to set up TOTP authentication or recovery codes at their discretion.
Headless/decoupled authentication with TFA
Use TFA with REST API authentication in decoupled Drupal architectures. The module supports authentication through REST by allowing validation plugins to implement the validateRequest() method. Configure exempt authentication providers in tfa.services.yml parameters if needed.
Recovery from lost authentication device
Users who lose access to their authenticator app can use recovery codes to log in. Ensure the Recovery Code validation plugin is enabled in TFA settings. Users should generate and securely store recovery codes from their TFA overview page before losing device access.
Trusted devices for frequent users
Reduce friction for users who log in frequently from the same device. Enable the Trusted Browser login plugin in TFA settings. Users can mark their browser as trusted during TFA verification, skipping subsequent TFA checks for the configured period (default 30 days).
Managing TFA for other users
Allow help desk staff to reset TFA for users who are locked out. Grant the 'administer tfa for other users' permission to appropriate roles. Staff can then access any user's TFA page to reset skip validation attempts or disable TFA entirely.
Tips
- Always generate and securely store recovery codes as a backup before relying solely on an authenticator app
- Use the 'validation_skip' setting wisely - too low forces immediate TFA setup, too high reduces security benefits
- Consider enabling the Trusted Browser plugin to reduce friction for users on personal devices while maintaining security on shared computers
- Test TFA configuration thoroughly before enabling it for administrator roles to avoid lockout scenarios
- Keep the encryption key secure and backed up - losing it will make all stored TFA secrets unrecoverable
- Use the Views integration to add a TFA status column to user administration pages for easy monitoring of TFA adoption
Technical Details
Admin Pages 5
/admin/config/people/tfa
Main configuration page for Two-factor Authentication. Configure which validation methods are available, select the default validation plugin, set up encryption, configure flood control, and customize email notifications.
/user/{user}/security/tfa
User account TFA overview page showing current TFA status, configured validation methods, login plugins, and skip validation counter. Users can manage their TFA settings from this page.
/user/{user}/security/tfa/{method}
Setup form for configuring a specific TFA validation method. Form content varies by plugin - TOTP/HOTP shows QR code and seed, Recovery Codes shows generated codes, Trusted Browser shows browser management.
/user/{user}/security/tfa/disable
Confirmation form to disable TFA for a user account. Requires password confirmation for security.
/tfa/{uid}/{hash}
TFA entry form displayed after username/password authentication. Users enter their verification code from their authenticator app or recovery code.
Permissions 4
Hooks 1
hook_tfa_info_alter
Alter TFA plugin definitions. Allows modules to modify the plugin definitions discovered by the TFA plugin manager.
Drush Commands 2
drush tfa:reset-user
Resets a single user's TFA data, removing all configured validation methods and allowing them to set up TFA again.
drush sql-sanitize
TFA integrates with Drush's sql-sanitize command to remove all TFA user data during database sanitization.
Troubleshooting 6
An administrator with 'administer tfa for other users' permission can either reset the user's skip validation attempts from their TFA overview page, or completely disable TFA for the user. Alternatively, use Drush: drush tfa:reset-user --name=username
Users can manually enter the displayed seed/secret key into their authenticator app instead of scanning. Ensure the QR code is displayed at sufficient size and contrast. The seed is shown as a text field above the QR code.
TOTP codes are time-sensitive. Ensure the server time is accurate and synced with NTP. Check that the time_skew setting allows sufficient tolerance. Verify the user's device time is also accurate. Consider increasing the 'Number of Accepted Codes' setting.
You must configure an encryption profile in the Encrypt module before TFA can be configured. Install and configure the Key module with an encryption key, then create an encryption profile at /admin/config/system/encryption.
Disable TFA during testing by setting the enabled configuration to false: drush config-set tfa.settings enabled 0. Re-enable after testing with: drush config-set tfa.settings enabled 1
Verify that Drupal's mail system is properly configured. Check that the mail templates in TFA settings have valid subject and body content. Review the recent log messages for mail sending errors.
Security Notes 7
- TFA secrets are encrypted using the configured Encrypt profile - ensure your encryption key is properly secured and not accessible via web requests
- Flood control protects against brute-force attacks on TFA codes - do not disable or significantly increase thresholds without understanding the security implications
- The Trusted Browser feature uses cookies that could be stolen in XSS attacks - ensure your site has proper XSS protections
- Recovery codes are one-time use and should be treated with the same security as passwords
- Consider using UID-only flood control (more secure) unless you have specific concerns about denial-of-service attacks
- Regular rotation of encryption keys is recommended - note that this requires resetting TFA for all users
- Log TFA events are recorded and should be monitored for unusual activity patterns