diff --git a/README.md b/README.md index c369be8d..8b4c362f 100644 --- a/README.md +++ b/README.md @@ -1,61 +1,116 @@ -# two-factor-auth-server +# Authelia [![license](https://img.shields.io/github/license/mashape/apistatus.svg?maxAge=2592000)][MIT License] - [![Build](https://travis-ci.org/clems4ever/two-factor-auth-server.svg?branch=master)](https://travis-ci.org/clems4ever/two-factor-auth-server) + [![Build](https://travis-ci.org/clems4ever/authelia.svg?branch=master)](https://travis-ci.org/clems4ever/authelia) -**two-factor-auth-server** is the simplest to set up HTTP 2-factor authentication server. It is compatible with NGINX auth_request module and is used in production to secure internal services in a swarm cluster. +**Authelia** is a complete HTTP 2-factor authentication server for proxies like +nginx. It has been made to work with NGINX auth_request module and is currently +used in production to secure internal services in a small docker swarm cluster. + +## Features +* Two-factor authentication using either +**[TOTP] - Time-Base One Time password -** or **[U2F] - Universal 2-Factor -** +as 2nd factor. +* Password reset with identity verification by sending links to user email +address. +* Access restriction after too many authentication attempts. + +## Deployment + +If you don't have any LDAP and nginx setup yet, I advise you to follow the +Getting Started. That way, you will not require anything to start. + +Otherwise here are the available steps to deploy on your machine. + +### With NPM + + npm install -g authelia + +### With Docker + + docker pull clems4ever/authelia ## Getting started -This project is docker-enabled so that you can deploy and test it very quickly. -Before starting, make sure you don't have anything listening on port 8080. Then, type the following command to build and deploy the services: +The provided example is docker-based so that you can deploy and test it very +quickly. First clone the repo make sure you don't have anything listening on +port 8080 before starting. +Then, type the following command to build and deploy the services: docker-compose build docker-compose up -d -After few seconds the services should be running and you should be able to visit [http://localhost:8080/](http://localhost:8080/) and access the login page: +After few seconds the services should be running and you should be able to visit +[https://localhost:8080/](https://localhost:8080/). -![login-page](https://raw.githubusercontent.com/clems4ever/two-factor-auth-server/master/images/login.png) +Normally, a self-signed certificate exception should appear, it has to be +accepted before getting to the login page: -### LDAP authentication -An LDAP server has been deployed with the following credentials: **admin/password**. +![first-factor-page](https://raw.githubusercontent.com/clems4ever/authelia/master/images/first_factor.png) -### TOTP verification -You can use Google Authenticator for the verification of the TOTP token. You can either enter the base32 secret key or scan the QR code in Google Authenticator and the application should start generating verification tokens. +### 1st factor: LDAP +An LDAP server has been deployed for you with the following credentials: **user/password**. -Test secret key: GRWGIJS6IRHVEODVNRCXCOBMJ5AGC6ZE +Type them in the login page and validate. Then, the second factor page should +have appeared as shown below. -![secret-key](https://raw.githubusercontent.com/clems4ever/two-factor-auth-server/master/images/secret-key.png) +![second-factor-page](https://raw.githubusercontent.com/clems4ever/authelia/master/images/second_factor.png) + + +### 2nd factor: TOTP (Time-Base One Time Password) +In **Authelia**, you need to register a per user TOTP secret before +authenticating. To do that, you need to click on the register button. It will +send a link to the user email address. Since this is an example, no email will +be sent, the link is rather delivered in the file +./notifications/notification.txt. Paste the link in your browser and you'll get +your secret in QRCode and Base32 formats. You can use +[Google Authenticator](https://play.google.com/store/apps/details?id=com.google.android.apps.authenticator2&hl=en) +to store them and get the generated tokens required during authentication. + +![totp-secret](https://raw.githubusercontent.com/clems4ever/authelia/master/images/totp.png) + +### 2nd factor: U2F (Universal 2-Factor) with security keys +**Authelia** also offers authentication using U2F devices like [Yubikey](Yubikey) +USB security keys. U2F is one of the most secure authentication protocol and is +already available for accounts on Google, Facebook, Github and more. + +Like TOTP, U2F requires you register your security key before authenticating +with it. To do so, click on the register button. This will send a link to the +user email address. Since this is an example, no email will be sent, the +link is rather delivered in the file ./notifications/notification.txt. Paste +the link in your browser and you'll be asking to touch the token of your device +to register it. You can now authenticate using your U2F device by simply +touching the token. + +![u2f-validation](https://raw.githubusercontent.com/clems4ever/authelia/master/images/u2f.png) + +### Password reset +With **Authelia**, you can also reset your password in no time. Click on the +according button in the login page, provide the username of the user requiring +a password reset and **Authelia** will send an email with an link to the user +email address. For the sake of the example, the email is delivered in the file +./notifications/notification.txt. +Paste the link in your browser and you should be able to reset the password. ## Documentation -two-factor-auth-server provides a way to log in using LDAP credentials and TOTP tokens. When the user is logged in, -the server generates a JSON web token with an expiry date that the user must keep in the *access_token* cookie. +### Configuration +The configuration of the server is defined in the file +**configuration.template.yml**. All the details are documented there. +You can specify another configuration file by giving it as first argument of +**Authelia**. -### Endpoints -Here are the available endpoints: + authelia config.custom.yml -| Endpoint | Method | Description | -|-----------------|-----------|-------------------------------------------------------------------| -| /login | GET | Serve a static webpage for login | -| /logout | GET | Logout the current session if logged in | -| /_auth | GET | Verify whether the user is logged in | -| /_auth | POST | Generate an access token to store in *access_token* cookie | +### API documentation +There is a complete API documentation generated with +[apiDoc](http://apidocjs.com/) and embedded in the repo under the **doc/** +directory. Simply open index.html locally to watch it. -### Parameters -And the parameters: - -| Endpoint | Parameters | Returns | -|--------------------|-----------------------------------------------------------|----------------------------------| -| /login | None | Login static page | -| /logout | None | Redirect to *redirect* parameter | -| /_auth (GET) | *access_token* cookie containing the JSON web token | @204 or @401 | -| /_auth (POST) | { password: 'abc', username: 'user', token: '0982'} | @200 with access_token or @401 | - -## Contributing to two-factor-auth-server +## Contributing to Authelia Follow [contributing](CONTRIBUTORS.md) file. ## License -two-factor-auth-server is **licensed** under the **[MIT License]**. The terms of the license are as follows: +**Authelia** is **licensed** under the **[MIT License]**. The terms of the license are as follows: The MIT License (MIT) @@ -80,4 +135,7 @@ two-factor-auth-server is **licensed** under the **[MIT License]**. The terms of [MIT License]: https://opensource.org/licenses/MIT - +[TOTP]: https://en.wikipedia.org/wiki/Time-based_One-time_Password_Algorithm +[U2F]: https://www.yubico.com/about/background/fido/ +[Yubikey]: https://www.yubico.com/products/yubikey-hardware/yubikey4/ + diff --git a/images/first_factor.png b/images/first_factor.png new file mode 100644 index 00000000..9f388325 Binary files /dev/null and b/images/first_factor.png differ diff --git a/images/login.png b/images/login.png deleted file mode 100644 index 93d8c228..00000000 Binary files a/images/login.png and /dev/null differ diff --git a/images/second_factor.png b/images/second_factor.png new file mode 100644 index 00000000..e98452fb Binary files /dev/null and b/images/second_factor.png differ diff --git a/images/totp.png b/images/totp.png new file mode 100644 index 00000000..30f84a7b Binary files /dev/null and b/images/totp.png differ diff --git a/images/u2f.png b/images/u2f.png new file mode 100644 index 00000000..6ca0beef Binary files /dev/null and b/images/u2f.png differ diff --git a/package.json b/package.json index dc72d2a3..dd715cfe 100644 --- a/package.json +++ b/package.json @@ -3,6 +3,9 @@ "version": "1.0.11", "description": "2-factor authentication server using LDAP as 1st factor and TOTP or U2F as 2nd factor", "main": "src/index.js", + "bin": { + "authelia": "src/index.js" + }, "scripts": { "test": "./node_modules/.bin/mocha --recursive test/unitary", "unit-test": "./node_modules/.bin/mocha --recursive test/unitary", diff --git a/src/index.js b/src/index.js old mode 100644 new mode 100755 index 3b641d7b..cb452f66 --- a/src/index.js +++ b/src/index.js @@ -1,3 +1,4 @@ +#! /usr/bin/env node process.env.NODE_TLS_REJECT_UNAUTHORIZED = "0"; @@ -10,6 +11,12 @@ var nedb = require('nedb'); var YAML = require('yamljs'); var config_path = process.argv[2]; +if(!config_path) { + console.log('No config file has been provided.'); + console.log('Usage: authelia '); + process.exit(0); +} + console.log('Parse configuration file: %s', config_path); var yaml_config = YAML.load(config_path);