TFA

TFA is a base module for setting up two-factor authentication for a Drupal website. It handles the work of integrating actual providers of TFA with Drupal. This tutorial also shows how to add the TFA Basic plugins helper module, along with Auto Assign Role, to allow new users to register and set up SMS-based TFA.

Table of contents

• Introduction
• Final word

Drupal modules discussed in this chapter: Auto Assign Role, Libraries API, TFA, TFA Basic plugins.

Introduction

TFA is a base module for providing two-factor authentication for a Drupal site. As a base module, TFA handles all of the Drupal integration work, providing flexible and well tested interfaces to enable configurable choices of various two-factor authentication solutions.

Please note that TFA does not do anything by itself. It provides a framework that lets you integate various two-factor authentication solutions like Time-based One Time Passwords (TOTP), SMS-delivered codes, pre-generated codes, or integrations with third-party services like Authy, Duo, Twilio and others.

At least one plugin is required to make two-factor authenication operational. A plugin provides the form and validation handling for 2nd factor authentication of a user. When enabled for a user, the TFA module will interrupt a successful username and password authentication and begin the TFA process, passing off the form control and validation to the active plugin.

In this chapter, TFA Basic plugins will be used to set up SMS delivered login codes using Twilio.

See also the TFA community documentation at Drupal.org.

Installing and enabling the module

Install Auto Assign Role, TFA and TFA Basic plugins as you would normally install contributed Drupal modules. See: Installing modules for further information.

To use Twilio for sending SMS, you need to install version 4 the Twilio PHP library. You can install the Twilio PHP library manually or via the Drupal Libraries API.

Option 1, install Twilio PHP manually:

$ cd tfa_basic/includes/
$ git clone https://github.com/twilio/twilio-php.git
$ cd twilio-php
$ git checkout 4.9.2

After doing this. make sure that the file tfa_basic/includes/twilio-php/Services/Twilio.php exists.

Option 2, install using the Drupal Libraries API:

1. Install and enable Libraries API.
2. Download version 4 of the Twilio PHP Helper Library using composer:
3. Move the folder named sdk from the vendor/twilio-folder and place it in the sites/all/libraries-folder as twilio.
4. Remove the vendor-folder and the composer-files..

Here are the commands to use:

$ composer require 'twilio/sdk:^4'
$ mv vendor/twilio/sdk/ ../../libraries/twilio/
$ rm -rf vendor
$ rm composer*

After doing this. make sure that the file libraries/twilio/Services/Twilio.php exists.

The version can be located in twilio/CHANGES.md. It is version 4.9.2.

The produces this message since PHP 7.2: "Deprecated function: Function create_function() is deprecated in Services_Twilio_Resource::camelize() (line 93 of …/Services/Twilio/Resource.php)." SO: PHP 7.2 Function create_function() is deprecated.

Setting up

First, add a new field to user's profile to store the user's SMS mobile number. Navigate to Configuration » Account settings » Manage fields and add a new text field for the mobile number.

For some reason, this number is not used when the user first set up SMS delivery. Instead, the user is prompted for what phone number to use. This is not logical.

To set up TFA, navigate to Configuration » People » Two-factor Authentication.

Check “Enable TFA”. This will expose additional controls. Then select default validation plugin: “Twilio SMS”. This will expose more additional controls.

You will need a Twilio account to use the company's SMS message service. The two main credentials are under Console / Twilio dashboard » Project info. The phone number is under # Phone numbers » Manage » Active numbers in the left sidebar.

1. Do not selet any validation fallback plugins.
2. Select login plugins: “Trusted Browsers”.
3. Do require any roles to have set up TFA!
4. Check the cookie domain field (default is usually correct).
5. Fill in “Twilio account SID” (main credential #1).
6. Fill in “Twilio account token” (main cerdential #2).
7. Fill in “Twilio account number” (sender phone number) The number will typicall look like: (443) 296-3334. Enter it as +14432963334.
8. Fill in “Twilio message text” (Placeholder for code is !code).
9. Untick “Validate phone numbers against NANP”.
10. Select the user profile field that stores the SMS mobile number (the field you just created).

If the Twilio librarys has not been correctly installes, you'll be unable to configure or use the module. You'll experience that items 5-10 in the list above are missing. You may also fail to login: "Error: Call to a member function sendMessage() on null in TfaBasicSms->sendCode() (line 145 of …/sites/all/modules/tfa_basic/includes/tfa_sms.inc)."

When done, press “Save configuration”.

For «trusted browsers» to be recognized, the domain set for the trusted browser TFA cookie must match the domain used for the site. Subdomains are recogized, so setting the domain to .example.com will match example.com, www.example.com, foo.example.com, etc.

When setting up, make sure that you do not tick the boxes for authenticated users, the “tfa-access” role, or any other role who has not yet set up TFA under the heading “Roles required to have set up TFA”. If you do, all your users belonging to a role ticked will encounter a Catch-22 when they first try to login: “Login disallowed. You are required to set up two-factor authentication. Please contact a site administrator.” I.e.: This settings prevents the user from setting up TFA herself or himself.

Handling users

To allow users to set up TFA, enable the permission “Set up TFA for account” for a role and assign users to that role. For example, you may create the role tfa-access and enable this permission for it.

The permission “Set up TFA for account” is not correctly named. It should be called “Administer TFA for own account” because allows the user to both set up and disable TFA. I.e.: As long as this permission is enabled, a user can toggle whether TFA should be used via the user profile «Security» tab. If this permission is revoked, the user does not have access to the security tab on his/her profile and can no longer control whether TFA is enabled or not. It is suggested that the super-admin disable this for users that have managed to set up TFA for their account.

To automatically allow new users to set up TFA, use Auto Assign Role to auto-assign new users to the tfa-access role upon registration.

To check whether a user has activated TFA, the super-admin mey visit the «Security» tab in the user's profile. If it says “Status: TFA enabled” with a timestamp, the user has activated TFA.

PVN Hacks

Unfortunately, TFA Basic plugins is not well maintained.

Open issues (numbers refers to numbered changes below):

• Document require TFA and UX challenge (3).
• SMS TFA pretends to be ready when it is not (1-2).
• README (3).
• Hyphen confuses translator (4).

Pending patches being committed, I use a hacked version of the TFA Basic plugins module on the PVN site. The changes are in my sandbox on ifi:

1. tfa_basic.module is changed to only use fallback if it exists.
2. tfa_sms.inc has public function ready is added (to expose Twilio specific fields).
3. README.txt is changed to give download instructions for ver. 4 of the Twilio library.
4. tfa_sms.inc is changed to not use hyphen in token (to allow translation).

I've also added two new fields to the user profile: mob. phone (provided by the user) and Twilio (filled in when the user enables TFA). The twilio-number has the international prefix. In the PVNcustom project, there is hook_user_presave that fills in the twilio-number automatically.

Email to a new user

XXXX,
for å få tilgang til intanettet går du til følgende adresse
   https://intranet.pvn.no/user/register
og fyller inn samtlige felter, inklusive et selvvalgt passord.

Det hemmlige ordet er: «xxxx».

Etter å ha gjort dette trykker du på: «Opprett ny konto» (nederst på
siden).

Du skal nå være pålogget intranettet vårt.

Jeg anbefaler imidlertid at du gjør din egen pålogging sikrere ved å
ta i bruk to-fase autentisering (TFA).

Pass på at du har mobilen tilgjengelig.  Deretter trykker du på «Min
konto» øverst til høyre på skjermen, og deretter på fanen «Sikkerhet».
Nå trykker du på lenken: «Skru på SMS-autentisering».  For å komme
videre må du oppgi ditt selvvalgte passord og trykke på «Bekreft».

Du skal nå komme til en side med overskriften «Oppsett av TFA - SMS».
Sjekk at mobiltelefonnummeret er korrekt og at det foran nummeret står
det internasjonale prefikset for Norge «+47». Trykk deretter på «Send
SMS».  Nå skal du (etter ca. 10 sekunder) motta en SMS med en 6-sifret
verifikasjonskode.  Skriv denne inn i feltet og trykk «Verifiser og
lagre» (den er bare gyldig i ca.  30 sekunder).  Dersom du er på en
sikker PC (på kontoret) kan du krysse av for at den nettleseren du
benytter er «tiltrodd».  Da vil du kunne logge på uten TFA i 30 dager
fra denne nettleseren.  Sitter du på en offentlig PC (bibliotek,
nettkafé) må du ikke krysse av for at nettleseren er «tiltrodd».

Dersom du lurer på noe, eller noe ikke fungerer, kan du nå meg via
epost (gisle@ifi.uio.no) og på telefon +4790553659.

Final word

[TBA]

---

Last update: 2021-12-26 for D7 [gh].