Update the documentation to include information on Duo.

README.md

@@ -8,8 +8,9 @@
   [![Gitter](https://img.shields.io/gitter/room/badges/shields.svg)](https://gitter.im/authelia/general?utm_source=share-link&utm_medium=link&utm_campaign=share-link)
   [![Donate](https://img.shields.io/badge/Donate-PayPal-orange.svg)](https://www.paypal.com/cgi-bin/webscr?cmd=_donations&business=clement%2emichaud34%40gmail%2ecom&lc=FR&item_name=Authelia&currency_code=EUR&bn=PP%2dDonationsBF%3abtn_donate_SM%2egif%3aNonHosted)
 
-**Authelia** is an open-source authentication and authorization providing
+**Authelia** is an open-source authentication and authorization server
- 2-factor authentication and single sign-on (SSO) for your applications.
+providing 2-factor authentication and single sign-on (SSO) for your
+applications.
 It acts as a companion of reverse proxies by handling authentication and
 authorization requests.
 
@@ -20,15 +21,17 @@ for specific services in only few seconds.
 
 <p align="center">
   <img src="images/first_factor.png" width="400" />
-  <img src="images/second_factor.png" width="400" />
+  <img src="images/use-another-method.png" width="400" />
 </p>
 
 ## Features summary
 
 Here is the list of the main available features:
 
-* **[U2F] - Universal 2-Factor -** support with [Yubikey].
+* Several kind of second factor:
-* **[TOTP] - Time-Base One Time password -** support with [Google Authenticator].
+  * **[Security Key (U2F)](./docs/2factor/security-key.md)** support with [Yubikey].
+  * **[Time-based One-Time password](./docs/2factor/time-based-one-time-password.md)** support with [Google Authenticator].
+  * **[Mobile Push Notifications](./docs/2factor/duo-push-notifications.md)** with [Duo](https://duo.com/).
 * Password reset with identity verification using email.
 * Single-factor only authentication method available.
 * Access restriction after too many authentication attempts.
@@ -43,6 +46,7 @@ For more details about the features, follow [Features](./docs/features.md).
 
 You can start off with
 
+    git clone https://github.com/clems4ever/authelia.git
     source bootstrap.sh
 
 If you want to go further, please read [Getting Started](./docs/getting-started.md).
@@ -113,8 +117,8 @@ Wanna see more features? Then fuel us with a few beers!
 
 [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/
+[Security Key]: https://www.yubico.com/about/background/fido/
 [Yubikey]: https://www.yubico.com/products/yubikey-hardware/yubikey4/
 [auth_request]: http://nginx.org/en/docs/http/ngx_http_auth_request_module.html
 [Google Authenticator]: https://play.google.com/store/apps/details?id=com.google.android.apps.authenticator2&hl=en
-[config.template.yml]: https://github.com/clems4ever/authelia/blob/master/config.template.yml
+[config.template.yml]: https://github.com/clems4ever/authelia/blob/master/config.template.yml

config.template.yml

@@ -34,7 +34,7 @@ totp:
 # Parameters used to contact the Duo API. Those are generated when you protect an application
 # of type "Partner Auth API" in the management panel.
 duo_api:
-  hostname: api-123456789.duosecurity.com
+  hostname: api-123456789.example.com
   integration_key: ABCDEF
   secret_key: 1234567890abcdefghifjkl
 

docs/2factor/duo-push-notifications.md

@@ -0,0 +1,47 @@
+# Duo Push Notification
+
+Using mobile push notifications is becoming the new trendy way to validate
+the second factor of a 2FA authentication process. [Duo](https://duo.com/) is offering an API
+to integrate this kind validation and **Authelia** leverages this mechanism
+so that you can simply push a button on your smartphone to be securely granted
+access to your services.
+
+<p align="center">
+  <img src="../../images/2factor_duo.png" width="400">
+</p>
+
+In order to use this feature, you should first create a free account on Duo
+(up to 10 users), create a user account and attach it a mobile device. The name
+of the user must match the name of the user in your internal database.
+Then, click on *Applications* and *Protect an Application*. Then select the option
+called *Partner Auth API*. This will generate an integration key, a secret key and
+a hostname. You can set the name of the application to **Authelia** and then you
+must add the generated information to your configuration as:
+
+    duo_api:
+      hostname: api-123456789.example.com
+      integration_key: ABCDEF
+      secret_key: 1234567890abcdefghifjkl
+
+This can be seen in [config.template.yml](../../config.template.yml) file.
+
+When selecting *Duo Push Notification* at the second factor stage, you will
+automatically receive a push notification on your phone to grant or deny access.
+
+<p align="center">
+  <img src="../../images/duo-push-1.jpg" width="400">
+  <img src="../../images/duo-push-2.png" width="400">
+</p>
+
+## Limitations
+
+Users must be enrolled via the Duo Admin panel, they cannot enroll a device from
+**Authelia** yet.
+
+
+## FAQ
+
+### Why don't I have access to the *Duo Push Notification* option?
+
+It's likely that you have not configured **Authelia** correctly. Please read this
+documentation again and be sure you had a look at [config.template.yml](../../config.template.yml).

docs/2factor/security-key.md

@@ -0,0 +1,40 @@
+# Security Keys (U2F)
+
+**Authelia** also offers authentication using Security Keys supporting U2F
+like [Yubikey](Yubikey) USB devices. U2F is one of the most secure
+authentication protocol and is already available for Google, Facebook, Github
+accounts and more.
+
+The protocol requires your security key being enrolled before authenticating.
+
+<p align="center">
+  <img src="../../images/2factor_u2f.png" width="400">
+</p>
+
+To do so, select the *Security Key* method in the second factor page and click
+on the *register new device* link. This will send a link to the 
+user email address. This e-mail will likely be sent to https://mail.example.com:8080/
+if you're testing Authelia and you've not configured anything.
+
+Confirm your identity by clicking on **Continue** and you'll be asked to
+touch the token of your security key to enroll.
+
+<p align="center">
+  <img src="../../images/u2f.png" width="400">
+</p>
+
+Upon successful registration, you can authenticate using your security key by simply
+touching the token again.
+
+Easy, right?!
+
+## FAQ
+
+### Why don't I have access to the *Security Key* option?
+
+U2F protocol is a new protocol that is only supported by recent browser
+and must even be enabled on some of them like Firefox. Please be sure
+your browser supports U2F and that the feature is enabled to make the
+option available in **Authelia**.
+
+[Yubikey]: https://www.yubico.com/products/yubikey-hardware/yubikey4/

docs/2factor/time-based-one-time-password.md

@@ -0,0 +1,29 @@
+# One-Time Passwords
+
+In **Authelia**, your users can use [Google Authenticator] for generating unique
+tokens that they can use to pass the second factor.
+
+<p align="center">
+  <img src="../../images/2factor_totp.png" width="400">
+</p>
+
+Select the *One-Time Password method* and click on the *register new device* link.
+Then, check the email sent by **Authelia** to your email address
+to validate your identity. If you're testing **Authelia**, it's likely
+that this e-mail has been sent to https://mail.example.com:8080/
+
+Confirm your identity by clicking on **Continue** and you'll get redirected
+on a page where your secret will be displayed as QRCode and in Base32 formats.
+
+<p align="center">
+  <img src="../../images/totp.png" width="400">
+</p>
+
+You can use [Google Authenticator] to store it.
+
+From now on, you'll get generated
+tokens from your phone that you can use to validate the second factor in **Authelia**.
+
+
+
+[Google Authenticator]: https://play.google.com/store/apps/details?id=com.google.android.apps.authenticator2&hl=en

docs/features.md

@@ -15,39 +15,16 @@ You can find an example of the configuration of the LDAP backend in
 </p>
 
 
-## Second factor with TOTP
+## Second factor
 
-In **Authelia**, you can register a per user TOTP (Time-Based One Time
+**Authelia** comes with three kind of second factor.
-Password) secret before being being able to authenticate. Click on the
-register button and check the email **Authelia** sent to your email address
-to validate your identity.
 
-Confirm your identity by clicking on **Continue** and you'll get redirected
+* Security keys like [Yubikey]. More info [here](./2factor/security-key.md).
-on a page where your secret will be displayed  in QRCode and Base32 formats.
+* One-Time Passwords generated by [Google Authenticator]. More info [here](./2factor/time-based-one-time-password.md).
-You can use [Google Authenticator] to store it and get the generated tokens.
+* Duo Push Notifications to use with [Duo mobile application](https://play.google.com/store/apps/details?id=com.duosecurity.duomobile&hl=en) available on Android, iOS and Windows. More info [here](./2factor/duo-push-notifications.md).
 
 <p align="center">
-  <img src="../images/totp.png" width="400">
+  <img src="../images/use-another-method.png" width="400">
-</p>
-
-## Second factor with U2F security keys
-
-**Authelia** also offers authentication using U2F (Universal 2-Factor) devices
-like [Yubikey](Yubikey) USB security keys. U2F is one of the most secure
-authentication protocol and is already available for Google, Facebook, Github
-accounts and more.
-
-Like TOTP, U2F requires you register your security key before authenticating. 
-To do so, click on the register button. This will send a link to the 
-user email address. 
-Confirm your identity by clicking on **Continue** and you'll be asked to
-touch the token of your device to register. Upon successful registration,
-you can authenticate using your U2F device by simply touching the token.
-
-Easy, right?!
-
-<p align="center">
-  <img src="../images/u2f.png" width="400">
 </p>
 
 ## Password reset
@@ -96,5 +73,5 @@ Redis key/value store. You can specify your own Redis instance in
 
 [basic authentication]: https://en.wikipedia.org/wiki/Basic_access_authentication
 [config.template.yml]: https://github.com/clems4ever/authelia/blob/master/config.template.yml
-[Google Authenticator]: https://play.google.com/store/apps/details?id=com.google.android.apps.authenticator2&hl=en
 [Yubikey]: https://www.yubico.com/products/yubikey-hardware/yubikey4/
+[Google Authenticator]: https://play.google.com/store/apps/details?id=com.google.android.apps.authenticator2&hl=en

test/suites/.gitignore

@@ -1 +1,3 @@
-users_database.test.yml
+users_database.test.yml
+
+private-*/