search

Arno0x / TwoFactorAuth

Two Factor Authentication web portal written in PHP
130 stars 43 forks source link

readme

TwoFactorAuth

Author: Arno0x0x - @Arno0x0x

TwoFactorAuth is a web authentication portal providing two factor authentication (2FA). The first factor is a password, the second factor is an OTP (One Time Password) generated by an application like Google Authenticator or anything compatible.

TwoFactorAuth is written in PHP and should be pretty easy to integrate with an existing PHP application. It also features a Nginx auth_request module compatible script that integrates easily. See below for Nginx integration.

The aim of TwoFactorAuth is to provide a secure (2FA) authentication of users and, once authentication is passed, let your application handle everything else such as user's authorisations, profile etc...

The app is distributed under the terms of the GPLv3 licence.

Dependencies

TwoFactorAuth requires PHP5. The following required libraries are included with TwoFactorAuth :

Both these libraries are included in the TwoFactorAuth package so you don't have to install them :-)

TwoFactorAuth also relies on some PHP5 libraries that you'll have to install on your own:

Features

TwoFactorAuth uses a SQLite3 database for its users database. The database type can be easily changed by overiding the /twofactorauth/lib/DBManager.php class to use any other database.

Main features are :

Screenshots

The login page :

login page

The home page after login :

home page

The user management page :

user page

The QRCode display :

qrcode page

The administration page :

admin page

Adding a user :

addUser page

How does it work ?

After a user is created, a QRCode is displayed representing the random GAuth secret generated for this user. This QRCode must be scanned with the Google Authenticator application. This should be done only once for each user, unless the user lost/changed his phone and needs to re-enter his QRCode. Once a QRCode has been scanned with the Google Authenticator application, a OTP token is being generated every 30s:

qrcode

This token must be entered on the login page along with the user's password:

Once a user has logged in, a PHP session is created, which name can be configured (optionnal) to match the one of your own PHP application if required. This session holds the following variables:

Installation

  1. Unzip the TwoFactorAuth package in your web server's directory and ensure all files and folders have appropriate user:group ownership, depending on your installation (might be something like www-data:www-data).

  2. Edit the configuration file config.php at the root path of TwoFactorAuth directory, and make it match your needs and personnal settings. See the configuration section below.

  3. Next, open a browser and simply navigate the TwoFactorAuth base url (exact path will vary depending on where you installed the TwoFactorAuth application) : http://www.example.com/twofactorauth/ . This page will finalize the installation process by creating the SQLite3 user database, and the user table schema and allow you to define the first default user with administration rights.

From that point, main features are available on the home page :

Configuration

Edit the /twofactorauth/config.php file to match your needs. Most settings can be kept to their default values. However, pay attention to the following settings :

Security aspects

The user database must be protected against remote access. To achieve this, you can either :

[OPTIONNAL] NGINX auth_request integration

The Nginx auth_request module allows authentication of each request against an internal subrequest specified as a URL. The subrequest must answer with the proper HTTP status code:

This mechanism is a perfect replacement for the auth_basic authentication and allows for custom made mechanism, written in any language. It also allows a whole website (not per application) authentication mechanism.

WARNING: Whenever you save changes to TwoFactorAuth's config.php, always check for error messages at /twofactorauth/login/login.php to ensure you did not make typos in the file. If PHP cannot parse the file, Nginx will consider all users to be authenticated!

TwoFactorAuth provides such a script: /twofactorauth/nginx/auth.php.

You'll have to edit your Nginx configuration file. Assuming the TwoFactorAuth application was deployed in a location named /twofactorauth/ on your webserver, add the following line under the "server" directive:

auth_request /twofactorauth/nginx/auth.php;

error_page 401 = @error401;

location @error401 {
    return 302 $scheme://$host/twofactorauth/login/login.php?from=$uri;
}

location = /twofactorauth/nginx/auth.php {
            fastcgi_pass unix:/var/run/php5-fpm.sock;
            include fastcgi.conf;
            fastcgi_param  CONTENT_LENGTH "";
}

location /twofactorauth/db/ {
    deny all;
}

location /twofactorauth/login/ {
    auth_request off;

    location ~ \.php$ {
            fastcgi_pass unix:/var/run/php5-fpm.sock;
            include fastcgi.conf;
    }
}

Credits

Many thanks to Dominique Climenti (kyos.ch) for his help fixing few bugs (installation procedure, cookie setting when server is run on a non-standard port, login form security improvement) as well as discovering an XSS vulnerability (!). Many thanks to David Carliez (Toreon) too for discovering and help fixing a stored XSS. This is now all fixed.

Todo

Although I already had some useful feedback and fixed some bugs, there might still be some bugs or security concerns to fix. If you have a feature request, feel free to contact me on my twitter page.

bitcoin Like this tool ? Tip me with bitcoins ! address