Introduction

Starting from version 8.2.4, WebMail Pro 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. It can be used with any 2-step authentication app, such as Google Authenticator or Authy. If you'd like to learn more about this security approach, check the following guide: Two-Factor Authentication: What Is It and Why You Should Use It

Enabling 2FA

Two-factor auth is implemented as TwoFactorAuth module which is included in the package by default. To enable it, set Disabled to false in data/settings/modules/TwoFactorAuth.config.json file.

Once the module is enabled, a new "Security" tab is added to user account 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.

If you set ShowRecommendationToConfigure in data/settings/modules/TwoFactorAuth.config.json file to true, users will be getting notifications that it's recommended to enable 2FA protection for their account.

ClockTolerance parameter is by default set to 2 and means that codes starting from ClockTolerance * 30sec ago to ClockTolerance * 30sec from now are accepted. Increasing this value may help resolving auth issues caused by inexact time sync.

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

NB: With 2FA protection enabled, it will not be possible to access backends which don't support 2FA such as DAV. In the future, we're going to implement app passwords to work around that.

Additional 2FA methods

As another 2FA method, user can configure security key. Support for FIDO2 U2F keys (such as YubiKey) is implemented, and while other types of keys might work we cannot guarantee that.

If security app or security key was configured, user will be able to use backup codes. Technically they're another 2FA method but are only to be used as a last resort should the primary 2nd factor (app or key) become unavailable.

As of v8.5.3, it's possible to disable 2nd factor for the particular user from within admin interface.

Trusted devices

The concept of a trusted device means that every device used for access is added to the list; different browsers on the same computer are considered different devices, that also applies to different apps on the same mobile device.

User can mark their device as trusted when going logging in with 2FA enabled. Later on, user can remove the device from the trusted list in web interface.

Adding device to trusted list effectively means that 2FA will not be requested for that device within amount of time set by the system administrator. In turn, it means authentication should expire from time to time, and that time interval should be less than time interval set for trusted devices.

Server configuration

The above functionality in web interface and in Aurora Mail for iOS is enabled using the following configuration options in data/settings/modules/TwoFactorAuth.config.json file:

• AllowSecurityKeys
• AllowAuthenticatorApp
• AllowBackupCodes
• AllowUsedDevices
• TrustDevicesForDays

All these settings are boolean (true/false), except for TrustDevicesForDays - it should be set to a number of days; if it's set to 0, adding devices to trusted list is disabled.

To enable authentication token expiration, lifetime needs to be set in AuthTokenExpirationLifetimeDays parameter found in data/settings/config.json file (and if you set TrustDevicesForDays to non-zero value, it needs to be bigger than AuthTokenExpirationLifetimeDays for the approach to work). In the same file, enable StoreAuthTokenInDB option to ensure that logging out off a particular device will work as expected.

Removing expired tokens require setting up a cronjob, system/crons/CleanUpAuthTokens.php script needs to be run daily. For example, the following crontab entry should work on Linux:

0 1 * * * php /var/www/html/system/crons/CleanUpAuthTokens.php

To allow for using security keys in Android mobile app, .well-known feature needs to be configured on the server. And if you use customized version of mobile apps, make sure 2FA setup holds the correct facet IDs for the apps. Details on both the items can be found at:
https://github.com/afterlogic/aurora-module-two-factor-auth