diff --git a/README.md b/README.md index c369be8de..73ba0423d 100644 --- a/README.md +++ b/README.md @@ -1,61 +1,95 @@ -# 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. ## 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. +Before starting, make sure you don't have anything listening on port 8080. +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/readme-update/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/readme-update/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/readme-update/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/readme-update/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 -### Endpoints -Here are the available endpoints: +### 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. -| 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 | - -### 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 +114,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 000000000..9f3883253 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 93d8c2287..000000000 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 000000000..e98452fb5 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 000000000..30f84a7b8 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 000000000..6ca0beefc Binary files /dev/null and b/images/u2f.png differ