Two-factor authentication

Starting from version 7.6, WebMail Lite 7 offers support for two-factor authentication, also known as 2-step verification. The idea behind this approach allows users to increase their account security by having to enter PIN code obtained via authentication application installed on their mobile device.

The approach is currently available in two different versions, both are implemented as plugins which need to be installed by system administrator.

Generic two-factor authentication

This implementation of two-factor auth can be used with any 2-step authentication app, such as Google Authenticator or Authy.

You can download the plugin here.

Upon downloading and extracting plugin package content, you'll need to deploy the plugin so that its index file is available at the following location:

data/plugins/two-factor-authentication/index.php

To enable the plugin, add the following to array defined in data/settings/config.php file:

'plugins.two-factor-authentication' => true,

Plugin supports a number of optional parameters supplied as follows:

'plugins.two-factor-authentication.config' => array(
        'logs' => true,
        'discrepancy' => 2
),

If logs set to true, logging is enabled for the plugin. The discrepancy value sets number of tokens generated, which equals discrepancy * 3. Increasing this value may help resolving auth issues caused by inexact time sync.

Also, be sure to purge data/cache/ directory content to avoid translation issues.

Once the plugin is installed, a new tab "2-Step Verification" is added to user accounts' settings area. In there, user can enable authentication for their account, and proceed by scanning QR code from that page or by manually entering secret key into their authentication app.

Assuming user has enabled and set up 2-step verification for their account, they will get additional popup upon next login to WebMail Lite 7, where they're required to enter PIN code obtained from authentication app installed on their mobile device.

NB: if your users encounter authentication issues, those may be caused by outdated timezone database of PHP install, and upgrading PHP to 5.4 or newer version may help. Also, switching to FreeOTP Authenticator is known to be a working solution for those who had issues with Google Authenticator.

Authy support

In addition to generic 2-step verification approach, we offer a different method designed specifically for use with Authy.

You can download the plugin here.

Upon downloading and extracting plugin package content, you'll need to deploy the plugin so that its index file is available at the following location:

data/plugins/two-factor-authentication-authy/index.php

To enable the plugin, add the following to array defined in data/settings/config.php file:

'plugins.two-factor-authentication-authy' => true,

You will also need to sign up to get API key, and enter that key in the same configuration file as follows:

'plugins.two-factor-authentication-authy.config' => array(
        'key' => 'api-key-here',
        'force_send_sms' => 'true',
        'logs' => true,
        'force_2f_auth' => false
),

Only the 1st array item is mandatory there, the rest of the items are optional:

• force_send_sms - if set to 'true', application will request Authy to send SMS to the user when they attempt to log in; if set to 'false', no request to send SMS will be made. Regardless of force_send_sms value, the user will still be able to use Authy application to log in;
• logs - if set to true, logging is enabled for the plugin;
• force_2f_auth - if set to true, two-factor authentication is enforced even if user doesn't have their record in two-factor auth database.

The important part of this approach is that administrator needs to assign Authy IDs to WebMail Lite 7 users. Currently, that can only be done programmatically by utilizing API call of the following kind:

include_once '/var/www/webmail/libraries/afterlogic/api.php';
$oPlugin = \CApi::Plugin()->getPluginByName('two-factor-authentication-authy');
$oPlugin->createDataValue($oAccount, $iDataType, $sDataValue, $bAllowUpdate);

• $oAccount represents the account object obtained via GetAccountOnLogin method for example;
• $iDataType should be set to ETwofaType::AUTH_TYPE_AUTHY
• $sDataValue is the ID to be assigned
• $bAllowUpdate - true means "create or update existing", false means "create only" (if the user with such Authy ID already exists, the method will return an error.)

Once this is set up, users will be able to utilize 2-step verification using Authy app.

Deleting Authy record from the database for the particular account is done using the following method:

$oPlugin = \CApi::Plugin()->getPluginByName('two-factor-authentication-authy');
$oPlugin->removeDataValue($oAccount);