README

This bundle enables Two-Factor Authentication (TFA/2FA) via TOTP for Contao backend users. Users with 2FA enabled are not allowed to visit any backend page before typing in the correct access code after having logged in.

The bundle is compatible with Contao 4.4 or newer.

Installation

No matter which method you use to install the package, make sure to run the install tool afterwards so that the additional database column can be created.

Composer

With Composer simply type composer require dieschittigs/contao-tfa-bundle in your Contao installation's root folder.

Contao Manager (Contao 4.5+)

Select Packages > Install Packages and search for contao-tfa-bundle. The button Check & Install will then install it for you.

Usage

To enable Two-Factor Authentication for your account, visit your backend profile and open the "Two-Factor Authentication" section. Scan the displayed QR code with a compatible app (we recommend Google Authenticator, which is available for iOS and Android) and verify by typing in the code generated by your app before hitting Save.

Since the generated code is time-based and thus changes periodically, it is important that your server time is set up correctly. By default the used library for code verification is able to correct for a delay of up to 30 seconds. This can be changed in the security section of your application settings.

You can also force all users to set up Two-Factor Authentication by toggling the checkbox for "Force Two-Factor Authentication" in your application's security settings. This will redirect all users (including yourself as an admin) to a 2FA setup page, before they can access any other page.

In case a user doesn't have access to their code anymore, any admin is able to reset the Two-Factor Authentication on a per-user basis in the user settings. There, admins can also force users to set up Two-Factor Authentication when they next log in, similar to how the setting "Password change required" works.

Caveats

This bundle intercepts all backend requests to redirect users that have yet to authenticate themselves to a 2FA authentication page. As such the users can still log in, but they can't access any backend pages.

If you plan to execute code on behalf of the user, make sure to take the two-factor status into account. Although the user can't visit any pages, they are still fully authenticated by the Symfony security layer, so you'll have to add extra checks to make sure two-factor authentication is complete.

Roadmap

Although we haven't yet decided on any further features, the following might be possible:

Additional 2FA methods (e.g. mail)
Backup Codes

dieschittigs / contao-tfa-bundle

Maintainers

Details