diff --git a/.buildkite/deployment.yml b/.buildkite/deployment.yml
index 355f32892..2d0985569 100644
--- a/.buildkite/deployment.yml
+++ b/.buildkite/deployment.yml
@@ -14,7 +14,7 @@ steps:
DOCKER_CLI_EXPERIMENTAL: "enabled"
- label: ":github: Deploy Artifacts"
- command: ".buildkite/steps/ghartifacts.sh"
+ command: "ghartifacts.sh"
retry:
automatic: true
agents:
@@ -24,4 +24,10 @@ steps:
- label: ":linux: Deploy AUR"
command: ".buildkite/steps/aurpackages.sh | buildkite-agent pipeline upload"
- if: build.tag != null || build.branch == "master"
\ No newline at end of file
+ if: build.tag != null || build.branch == "master"
+
+ - label: ":docs: Deploy documentation"
+ command: "syncdoc.sh"
+ agents:
+ upload: "fast"
+ if: build.branch == "master"
diff --git a/.buildkite/steps/syncdoc.sh b/.buildkite/steps/syncdoc.sh
new file mode 100755
index 000000000..3a13c7fa2
--- /dev/null
+++ b/.buildkite/steps/syncdoc.sh
@@ -0,0 +1,21 @@
+#!/bin/bash
+
+set -e
+
+rm -rf authelia
+git clone git@github.com:authelia/authelia.git --branch gh-pages
+
+pushd docs
+bundle install
+bundle exec jekyll build -d ../authelia
+popd
+
+COMMIT=$(git show -s --format=%h)
+
+pushd authelia
+git add -A
+git commit -m "synchronize docs of commit ${COMMIT}"
+git push
+popd
+
+rm -rf authelia
\ No newline at end of file
diff --git a/docs/.gitignore b/docs/.gitignore
new file mode 100644
index 000000000..fcb2476de
--- /dev/null
+++ b/docs/.gitignore
@@ -0,0 +1,4 @@
+_site
+.sass-cache
+.jekyll-metadata
+.jekyll-cache
diff --git a/docs/2factor/duo-push-notifications.md b/docs/2factor/duo-push-notifications.md
deleted file mode 100644
index 758c93154..000000000
--- a/docs/2factor/duo-push-notifications.md
+++ /dev/null
@@ -1,48 +0,0 @@
-# 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.
-
-
- 
-
-
-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 (LDAP).
-In Duo interface, 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 *Push Notification* at the second factor stage, you will
-automatically receive a push notification on your phone to grant or deny access.
-
-
- 
- 
-
-
-## 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 *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).
\ No newline at end of file
diff --git a/docs/2factor/security-key.md b/docs/2factor/security-key.md
deleted file mode 100644
index aba3898b5..000000000
--- a/docs/2factor/security-key.md
+++ /dev/null
@@ -1,40 +0,0 @@
-# Security Keys (U2F)
-
-**Authelia** offers authentication using Security Keys like [Yubikey](Yubikey)
-which are one of the most secure way to authenticate and get authorized.
-It is already available for Google, Facebook, Github accounts and more.
-
-The protocol requires your security key to enrolled before authenticating.
-
-To do so, select the *Security Key* method at the second factor stage and
-click on the link *Not registered yet?*. This will send a link to your
-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 **Register** and you'll be asked to
-touch the token of your security key to enroll.
-
-
- 
-
-
-Upon successful registration, you can authenticate using your security key
-by simply touching the token again when required:
-
-
- 
-
-
-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 browsers
-and might even be enabled on some of them. 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/
diff --git a/docs/2factor/time-based-one-time-password.md b/docs/2factor/time-based-one-time-password.md
deleted file mode 100644
index ee372ae33..000000000
--- a/docs/2factor/time-based-one-time-password.md
+++ /dev/null
@@ -1,29 +0,0 @@
-# One-Time Passwords
-
-In **Authelia**, your users can use [Google Authenticator] for generating unique
-tokens that they can use to pass the second factor.
-
-
- 
-
-
-Select the *One-Time Password method* and click on the *Not registered yet?* 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 **Register** and you'll get redirected
-on a page where your secret will be displayed as QRCode that you can scan.
-
-
- 
-
-
-You can use [Google Authenticator] to store it.
-
-From now on, you'll get tokens generated every 30 seconds on 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
\ No newline at end of file
diff --git a/docs/Gemfile b/docs/Gemfile
new file mode 100644
index 000000000..bb490aa87
--- /dev/null
+++ b/docs/Gemfile
@@ -0,0 +1,30 @@
+source "https://rubygems.org"
+
+# Hello! This is where you manage which Jekyll version is used to run.
+# When you want to use a different version, change it below, save the
+# file and run `bundle install`. Run Jekyll with `bundle exec`, like so:
+#
+# bundle exec jekyll serve
+#
+# This will help ensure the proper Jekyll version is running.
+# Happy Jekylling!
+# gem "jekyll", "~> 3.8.5"
+
+# This is the default theme for new Jekyll sites. You may change this to anything you like.
+#gem "minima", "~> 2.0"
+gem "just-the-docs"
+
+# If you want to use GitHub Pages, remove the "gem "jekyll"" above and
+# uncomment the line below. To upgrade, run `bundle update github-pages`.
+gem "github-pages", group: :jekyll_plugins
+
+# If you have any plugins, put them here!
+group :jekyll_plugins do
+ # gem "jekyll-feed", "~> 0.6"
+end
+
+# Windows does not include zoneinfo files, so bundle the tzinfo-data gem
+gem "tzinfo-data", platforms: [:mingw, :mswin, :x64_mingw, :jruby]
+
+# Performance-booster for watching directories on Windows
+gem "wdm", "~> 0.1.0" if Gem.win_platform?
diff --git a/docs/Gemfile.lock b/docs/Gemfile.lock
new file mode 100644
index 000000000..67cad73ec
--- /dev/null
+++ b/docs/Gemfile.lock
@@ -0,0 +1,255 @@
+GEM
+ remote: https://rubygems.org/
+ specs:
+ activesupport (6.0.2.1)
+ concurrent-ruby (~> 1.0, >= 1.0.2)
+ i18n (>= 0.7, < 2)
+ minitest (~> 5.1)
+ tzinfo (~> 1.1)
+ zeitwerk (~> 2.2)
+ addressable (2.7.0)
+ public_suffix (>= 2.0.2, < 5.0)
+ coffee-script (2.4.1)
+ coffee-script-source
+ execjs
+ coffee-script-source (1.11.1)
+ colorator (1.1.0)
+ commonmarker (0.17.13)
+ ruby-enum (~> 0.5)
+ concurrent-ruby (1.1.6)
+ dnsruby (1.61.3)
+ addressable (~> 2.5)
+ em-websocket (0.5.1)
+ eventmachine (>= 0.12.9)
+ http_parser.rb (~> 0.6.0)
+ ethon (0.12.0)
+ ffi (>= 1.3.0)
+ eventmachine (1.2.7)
+ execjs (2.7.0)
+ faraday (1.0.0)
+ multipart-post (>= 1.2, < 3)
+ ffi (1.12.2)
+ forwardable-extended (2.6.0)
+ gemoji (3.0.1)
+ github-pages (204)
+ github-pages-health-check (= 1.16.1)
+ jekyll (= 3.8.5)
+ jekyll-avatar (= 0.7.0)
+ jekyll-coffeescript (= 1.1.1)
+ jekyll-commonmark-ghpages (= 0.1.6)
+ jekyll-default-layout (= 0.1.4)
+ jekyll-feed (= 0.13.0)
+ jekyll-gist (= 1.5.0)
+ jekyll-github-metadata (= 2.13.0)
+ jekyll-mentions (= 1.5.1)
+ jekyll-optional-front-matter (= 0.3.2)
+ jekyll-paginate (= 1.1.0)
+ jekyll-readme-index (= 0.3.0)
+ jekyll-redirect-from (= 0.15.0)
+ jekyll-relative-links (= 0.6.1)
+ jekyll-remote-theme (= 0.4.1)
+ jekyll-sass-converter (= 1.5.2)
+ jekyll-seo-tag (= 2.6.1)
+ jekyll-sitemap (= 1.4.0)
+ jekyll-swiss (= 1.0.0)
+ jekyll-theme-architect (= 0.1.1)
+ jekyll-theme-cayman (= 0.1.1)
+ jekyll-theme-dinky (= 0.1.1)
+ jekyll-theme-hacker (= 0.1.1)
+ jekyll-theme-leap-day (= 0.1.1)
+ jekyll-theme-merlot (= 0.1.1)
+ jekyll-theme-midnight (= 0.1.1)
+ jekyll-theme-minimal (= 0.1.1)
+ jekyll-theme-modernist (= 0.1.1)
+ jekyll-theme-primer (= 0.5.4)
+ jekyll-theme-slate (= 0.1.1)
+ jekyll-theme-tactile (= 0.1.1)
+ jekyll-theme-time-machine (= 0.1.1)
+ jekyll-titles-from-headings (= 0.5.3)
+ jemoji (= 0.11.1)
+ kramdown (= 1.17.0)
+ liquid (= 4.0.3)
+ mercenary (~> 0.3)
+ minima (= 2.5.1)
+ nokogiri (>= 1.10.4, < 2.0)
+ rouge (= 3.13.0)
+ terminal-table (~> 1.4)
+ github-pages-health-check (1.16.1)
+ addressable (~> 2.3)
+ dnsruby (~> 1.60)
+ octokit (~> 4.0)
+ public_suffix (~> 3.0)
+ typhoeus (~> 1.3)
+ html-pipeline (2.12.3)
+ activesupport (>= 2)
+ nokogiri (>= 1.4)
+ http_parser.rb (0.6.0)
+ i18n (0.9.5)
+ concurrent-ruby (~> 1.0)
+ jekyll (3.8.5)
+ addressable (~> 2.4)
+ colorator (~> 1.0)
+ em-websocket (~> 0.5)
+ i18n (~> 0.7)
+ jekyll-sass-converter (~> 1.0)
+ jekyll-watch (~> 2.0)
+ kramdown (~> 1.14)
+ liquid (~> 4.0)
+ mercenary (~> 0.3.3)
+ pathutil (~> 0.9)
+ rouge (>= 1.7, < 4)
+ safe_yaml (~> 1.0)
+ jekyll-avatar (0.7.0)
+ jekyll (>= 3.0, < 5.0)
+ jekyll-coffeescript (1.1.1)
+ coffee-script (~> 2.2)
+ coffee-script-source (~> 1.11.1)
+ jekyll-commonmark (1.3.1)
+ commonmarker (~> 0.14)
+ jekyll (>= 3.7, < 5.0)
+ jekyll-commonmark-ghpages (0.1.6)
+ commonmarker (~> 0.17.6)
+ jekyll-commonmark (~> 1.2)
+ rouge (>= 2.0, < 4.0)
+ jekyll-default-layout (0.1.4)
+ jekyll (~> 3.0)
+ jekyll-feed (0.13.0)
+ jekyll (>= 3.7, < 5.0)
+ jekyll-gist (1.5.0)
+ octokit (~> 4.2)
+ jekyll-github-metadata (2.13.0)
+ jekyll (>= 3.4, < 5.0)
+ octokit (~> 4.0, != 4.4.0)
+ jekyll-mentions (1.5.1)
+ html-pipeline (~> 2.3)
+ jekyll (>= 3.7, < 5.0)
+ jekyll-optional-front-matter (0.3.2)
+ jekyll (>= 3.0, < 5.0)
+ jekyll-paginate (1.1.0)
+ jekyll-readme-index (0.3.0)
+ jekyll (>= 3.0, < 5.0)
+ jekyll-redirect-from (0.15.0)
+ jekyll (>= 3.3, < 5.0)
+ jekyll-relative-links (0.6.1)
+ jekyll (>= 3.3, < 5.0)
+ jekyll-remote-theme (0.4.1)
+ addressable (~> 2.0)
+ jekyll (>= 3.5, < 5.0)
+ rubyzip (>= 1.3.0)
+ jekyll-sass-converter (1.5.2)
+ sass (~> 3.4)
+ jekyll-seo-tag (2.6.1)
+ jekyll (>= 3.3, < 5.0)
+ jekyll-sitemap (1.4.0)
+ jekyll (>= 3.7, < 5.0)
+ jekyll-swiss (1.0.0)
+ jekyll-theme-architect (0.1.1)
+ jekyll (~> 3.5)
+ jekyll-seo-tag (~> 2.0)
+ jekyll-theme-cayman (0.1.1)
+ jekyll (~> 3.5)
+ jekyll-seo-tag (~> 2.0)
+ jekyll-theme-dinky (0.1.1)
+ jekyll (~> 3.5)
+ jekyll-seo-tag (~> 2.0)
+ jekyll-theme-hacker (0.1.1)
+ jekyll (~> 3.5)
+ jekyll-seo-tag (~> 2.0)
+ jekyll-theme-leap-day (0.1.1)
+ jekyll (~> 3.5)
+ jekyll-seo-tag (~> 2.0)
+ jekyll-theme-merlot (0.1.1)
+ jekyll (~> 3.5)
+ jekyll-seo-tag (~> 2.0)
+ jekyll-theme-midnight (0.1.1)
+ jekyll (~> 3.5)
+ jekyll-seo-tag (~> 2.0)
+ jekyll-theme-minimal (0.1.1)
+ jekyll (~> 3.5)
+ jekyll-seo-tag (~> 2.0)
+ jekyll-theme-modernist (0.1.1)
+ jekyll (~> 3.5)
+ jekyll-seo-tag (~> 2.0)
+ jekyll-theme-primer (0.5.4)
+ jekyll (> 3.5, < 5.0)
+ jekyll-github-metadata (~> 2.9)
+ jekyll-seo-tag (~> 2.0)
+ jekyll-theme-slate (0.1.1)
+ jekyll (~> 3.5)
+ jekyll-seo-tag (~> 2.0)
+ jekyll-theme-tactile (0.1.1)
+ jekyll (~> 3.5)
+ jekyll-seo-tag (~> 2.0)
+ jekyll-theme-time-machine (0.1.1)
+ jekyll (~> 3.5)
+ jekyll-seo-tag (~> 2.0)
+ jekyll-titles-from-headings (0.5.3)
+ jekyll (>= 3.3, < 5.0)
+ jekyll-watch (2.2.1)
+ listen (~> 3.0)
+ jemoji (0.11.1)
+ gemoji (~> 3.0)
+ html-pipeline (~> 2.2)
+ jekyll (>= 3.0, < 5.0)
+ just-the-docs (0.2.7)
+ jekyll (~> 3.8.5)
+ jekyll-seo-tag (~> 2.0)
+ rake (~> 12.3.1)
+ kramdown (1.17.0)
+ liquid (4.0.3)
+ listen (3.2.1)
+ rb-fsevent (~> 0.10, >= 0.10.3)
+ rb-inotify (~> 0.9, >= 0.9.10)
+ mercenary (0.3.6)
+ mini_portile2 (2.4.0)
+ minima (2.5.1)
+ jekyll (>= 3.5, < 5.0)
+ jekyll-feed (~> 0.9)
+ jekyll-seo-tag (~> 2.1)
+ minitest (5.14.0)
+ multipart-post (2.1.1)
+ nokogiri (1.10.8)
+ mini_portile2 (~> 2.4.0)
+ octokit (4.16.0)
+ faraday (>= 0.9)
+ sawyer (~> 0.8.0, >= 0.5.3)
+ pathutil (0.16.2)
+ forwardable-extended (~> 2.6)
+ public_suffix (3.1.1)
+ rake (12.3.3)
+ rb-fsevent (0.10.3)
+ rb-inotify (0.10.1)
+ ffi (~> 1.0)
+ rouge (3.13.0)
+ ruby-enum (0.7.2)
+ i18n
+ rubyzip (2.2.0)
+ safe_yaml (1.0.5)
+ sass (3.7.4)
+ sass-listen (~> 4.0.0)
+ sass-listen (4.0.0)
+ rb-fsevent (~> 0.9, >= 0.9.4)
+ rb-inotify (~> 0.9, >= 0.9.7)
+ sawyer (0.8.2)
+ addressable (>= 2.3.5)
+ faraday (> 0.8, < 2.0)
+ terminal-table (1.8.0)
+ unicode-display_width (~> 1.1, >= 1.1.1)
+ thread_safe (0.3.6)
+ typhoeus (1.3.1)
+ ethon (>= 0.9.0)
+ tzinfo (1.2.6)
+ thread_safe (~> 0.1)
+ unicode-display_width (1.6.1)
+ zeitwerk (2.2.2)
+
+PLATFORMS
+ ruby
+
+DEPENDENCIES
+ github-pages
+ just-the-docs
+ tzinfo-data
+
+BUNDLED WITH
+ 2.1.4
diff --git a/docs/_config.yml b/docs/_config.yml
new file mode 100644
index 000000000..47281c10a
--- /dev/null
+++ b/docs/_config.yml
@@ -0,0 +1,9 @@
+title: Authelia
+email: clement.michaud34@gmail.com
+description: Authelia is an open source multi-factor single sign-on portal for web applications
+baseurl: "/authelia"
+url: "https://authelia.github.io"
+logo: ./images/authelia-title.png
+footer_content: "Copyright © 2020 Authelia. Distributed by an Apache 2.0 license."
+markdown: kramdown
+theme: just-the-docs
\ No newline at end of file
diff --git a/docs/_sass/overrides.scss b/docs/_sass/overrides.scss
new file mode 100644
index 000000000..cba6cefdc
--- /dev/null
+++ b/docs/_sass/overrides.scss
@@ -0,0 +1,10 @@
+
+img {
+ border: 1px solid #e6e6e6;
+ border-radius: 5px;
+ padding: 10px;
+}
+
+.no-border {
+ border: 0px;
+}
\ No newline at end of file
diff --git a/docs/configuration.md b/docs/configuration.md
deleted file mode 100644
index ae4d43acc..000000000
--- a/docs/configuration.md
+++ /dev/null
@@ -1,33 +0,0 @@
-# Configuration
-
-Authelia is highly configurable thanks to a configuration file.
-There is a documented template configuration, called
-[config.template.yml](../config.template.yml), at the root of the
-repository. All the details are documented there.
-
-When running **Authelia**, you can specify your configuration file by passing
-the file path as the first argument of **Authelia**.
-
- $ authelia --config config.custom.yml
-
-
-## Secrets
-
-Configuration of Authelia requires some secrets or passwords. Please
-note that the recommended way to set secrets in Authelia is to use
-environment variables.
-
-A secret in Authelia configuration could be set by providing the
-environment variable prefixed by AUTHELIA_ and with name equals to
-the capitalized path of the configuration key and with dots replaced
-by underscores.
-
-For instance the LDAP password is identified by the path
-**authentication_backend.ldap.password**, so this password could
-alternatively be set using the environment variable called
-**AUTHELIA_AUTHENTICATION_BACKEND_LDAP_PASSWORD**.
-
-If for some reason you prefer keeping the secrets in the configuration
-file, be sure to apply the right permissions to the file in order to
-prevent secret leaks if an another application gets compromised on your
-server. The UNIX permissions should probably be something like 600.
\ No newline at end of file
diff --git a/docs/configuration/access-control.md b/docs/configuration/access-control.md
new file mode 100644
index 000000000..3c944cc96
--- /dev/null
+++ b/docs/configuration/access-control.md
@@ -0,0 +1,131 @@
+---
+layout: default
+title: Access Control
+parent: Configuration
+nav_order: 2
+---
+
+# Access Control
+{: .no_toc }
+
+## Access Control List
+
+With **Authelia** you can define a list of rules that are going to be evaluated in
+order when authorization is delegated to Authelia.
+
+The first matching rule of the list defines the policy applied to the resource and, if
+no rule matches the resource, a customizable default policy is applied.
+
+
+## Access Control Rule
+
+A rule defines two things:
+
+* the matching criterion of the request presented to the reverse proxy
+* the policy applied when all criterion match.
+
+The criterion are:
+
+* domain: domain targeted by the request.
+* resources: list of patterns that the path should match (one is sufficient).
+* subject: the user or group of users to define the policy for.
+* networks: the network range from where should comes the request.
+
+A rule is matched when all criterion of the rule match
+
+
+## Policies
+
+A policy represents the level of authentication the user needs to pass before
+being authorized to request the resource.
+
+There exist 4 policies:
+
+* bypass: the resource is public as the user does not need any authentication to
+get access to it.
+* one_factor: the user needs to pass at least the first factor to get access to
+the resource.
+* two_factor: the user needs to pass two factors to get access to the resource.
+* deny: the user does not have access to the resource.
+
+## Domains
+
+The domains defined in rules must obviously be either a subdomain of the domain
+protected by Authelia or the protected domain itself. In order to match multiple
+subdomains, the wildcard matcher character `*.` can be used as prefix of the domain.
+For instance, to define a rule for all subdomains of *example.com*, one would use
+`*.example.com` in the rule.
+
+## Resources
+
+A rule can define multiple regular expressions for matching the path of the resource. If
+any one of them matches, the resource criteria of the rule matches.
+
+
+## Subjects
+
+A subject is a representation of a user or a group of user for who the rule should apply.
+
+For a user with unique identifier `john`, the subject should be `user:john` and for a group
+uniquely identified by `developers`, the subject should be `group:developers`. Unlike resources
+there can be only one subject per rule. However, if multiple users or group must be matched by
+a rule, one can just duplicate the rule as many times as there are subjects.
+
+*Note: Any PR to make it a list instead of a single item is welcome.*
+
+## Networks
+
+A list of network ranges can be specified in a rule in order to apply different policies when
+requests come from different networks.
+
+The main use case is when, let say a resource should be exposed both on the Internet and from an
+authenticated VPN for instance. Passing a second factor a first time to get access to the VPN and
+a second time to get access to the application can sometimes be cumbersome if the endpoint is not
+that much sensitive.
+
+Even if Authelia provides that flexbility, you might prefer higher level of security and avoid
+this option entirely. You and only you can define your security policy and it's up to you to
+configure Authelia accordingly.
+
+
+## Complete example
+
+Here is a complete example of complex access control list that can be defined in Authelia.
+
+ access_control:
+ default_policy: deny
+
+ rules:
+ - domain: public.example.com
+ policy: bypass
+
+ - domain: secure.example.com
+ policy: one_factor
+ networks:
+ - 192.168.1.0/24
+
+ - domain: secure.example.com
+ policy: two_factor
+
+ - domain: singlefactor.example.com
+ policy: one_factor
+
+ - domain: "mx2.mail.example.com"
+ subject: "group:admins"
+ policy: deny
+
+ - domain: "*.example.com"
+ subject: "group:admins"
+ policy: two_factor
+
+ - domain: dev.example.com
+ resources:
+ - "^/groups/dev/.*$"
+ subject: "group:dev"
+ policy: two_factor
+
+ - domain: dev.example.com
+ resources:
+ - "^/users/john/.*$"
+ subject: "user:john"
+ policy: two_factor
\ No newline at end of file
diff --git a/docs/configuration/authentication/file.md b/docs/configuration/authentication/file.md
new file mode 100644
index 000000000..c75c887a4
--- /dev/null
+++ b/docs/configuration/authentication/file.md
@@ -0,0 +1,77 @@
+---
+layout: default
+title: File
+parent: Authentication backends
+grand_parent: Configuration
+nav_order: 1
+---
+
+# File
+
+**Authelia** supports a file as a users database.
+
+## Configuration
+
+Configuring Authelia to use a file is done by specifying the path to the
+file in the configuration file.
+
+ authentication_backend:
+ file:
+ path: /var/lib/authelia/users.yml
+
+
+## Format
+
+
+The format of the file is as follows.
+
+ users:
+ john:
+ password: "$6$rounds=500000$jgiCMRyGXzoqpxS3$w2pJeZnnH8bwW3zzvoMWtTRfQYsHbWbD/hquuQ5vUeIyl9gdwBIt6RWk2S6afBA0DPakbeWgD/4SZPiS0hYtU/"
+ email: john.doe@authelia.com
+ groups:
+ - admins
+ - dev
+
+ harry:
+ password: "$6$rounds=500000$jgiCMRyGXzoqpxS3$w2pJeZnnH8bwW3zzvoMWtTRfQYsHbWbD/hquuQ5vUeIyl9gdwBIt6RWk2S6afBA0DPakbeWgD/4SZPiS0hYtU/"
+ email: harry.potter@authelia.com
+ groups: []
+
+ bob:
+ password: "$6$rounds=500000$jgiCMRyGXzoqpxS3$w2pJeZnnH8bwW3zzvoMWtTRfQYsHbWbD/hquuQ5vUeIyl9gdwBIt6RWk2S6afBA0DPakbeWgD/4SZPiS0hYtU/"
+ email: bob.dylan@authelia.com
+ groups:
+ - dev
+
+ james:
+ password: "$6$rounds=500000$jgiCMRyGXzoqpxS3$w2pJeZnnH8bwW3zzvoMWtTRfQYsHbWbD/hquuQ5vUeIyl9gdwBIt6RWk2S6afBA0DPakbeWgD/4SZPiS0hYtU/"
+ email: james.dean@authelia.com
+
+This file should be set with read/write permissions as it could be updated by users
+resetting their passwords.
+
+## Passwords
+
+The file contains hash of passwords instead of plain text passwords for security reasons.
+
+You can use authelia binary or docker image to generate the hash of any password.
+
+For instance, with the docker image, just run
+
+ $ docker run authelia/authelia:latest authelia hash-password yourpassword
+ $6$rounds=50000$BpLnfgDsc2WD8F2q$be7OyobnQ8K09dyDiGjY.cULh4yDePMh6CUMpLwF4WHTJmLcPE2ijM2ZsqZL.hVAANojEfDu3sU9u9uD7AeBJ/
+
+
+## Password Hash Function
+
+The only supported hash function is salted sha512 determined by the prefix `$6$` as described
+in this [wiki](https://en.wikipedia.org/wiki/Crypt_(C)) page.
+
+Although not the best hash function, Salted SHA512 is a decent algorithm given the number of rounds is big
+enough. It's not the best because the difficulty to crack the hash does not on the performance of the machine.
+The best algorithm, [Argon2](https://en.wikipedia.org/wiki/Argon2) does though. It won the
+[Password Hashing Competition](https://en.wikipedia.org/wiki/Password_Hashing_Competition) in 2015 and is now
+considered the best hashing function. There is an open [issue](https://github.com/authelia/authelia/issues/577)
+to add support for this hashing function.
+
diff --git a/docs/configuration/authentication/index.md b/docs/configuration/authentication/index.md
new file mode 100644
index 000000000..8b1fa6b32
--- /dev/null
+++ b/docs/configuration/authentication/index.md
@@ -0,0 +1,15 @@
+---
+layout: default
+title: Authentication backends
+parent: Configuration
+nav_order: 1
+has_children: true
+---
+
+# Authentication Backends
+
+There are two ways to store the users along with their password:
+
+* LDAP: users are stored in remote servers like OpenLDAP, OpenAM or Microsoft Active Directory.
+* File: users are stored in YAML file with a hashed version of their password.
+
\ No newline at end of file
diff --git a/docs/configuration/authentication/ldap.md b/docs/configuration/authentication/ldap.md
new file mode 100644
index 000000000..8c5ea8ef5
--- /dev/null
+++ b/docs/configuration/authentication/ldap.md
@@ -0,0 +1,62 @@
+---
+layout: default
+title: LDAP
+parent: Authentication backends
+grand_parent: Configuration
+nav_order: 2
+---
+
+# LDAP
+
+**Authelia** supports using a LDAP server as the users database.
+
+## Configuration
+
+Configuration of the LDAP backend is done as follows
+
+```yaml
+authentication_backend:
+ ldap:
+ # The url to the ldap server. Scheme can be ldap:// or ldaps://
+ url: ldap://127.0.0.1
+
+ # Skip verifying the server certificate (to allow self-signed certificate).
+ skip_verify: false
+
+ # The base dn for every entries
+ base_dn: dc=example,dc=com
+
+ # An additional dn to define the scope to all users
+ additional_users_dn: ou=users
+
+ # The users filter used to find the user DN
+ # {0} is a matcher replaced by username.
+ # 'cn={0}' by default.
+ users_filter: (cn={0})
+
+ # An additional dn to define the scope of groups
+ additional_groups_dn: ou=groups
+
+ # The groups filter used for retrieving groups of a given user.
+ # {0} is a matcher replaced by username.
+ # {dn} is a matcher replaced by user DN.
+ # {uid} is a matcher replaced by user uid.
+ # 'member={dn}' by default.
+ groups_filter: (&(member={dn})(objectclass=groupOfNames))
+
+ # The attribute holding the name of the group
+ group_name_attribute: cn
+
+ # The attribute holding the mail address of the user
+ mail_attribute: mail
+
+ # The username and password of the admin user.
+ user: cn=admin,dc=example,dc=com
+
+ # This secret can also be set using the env variables AUTHELIA_AUTHENTICATION_BACKEND_LDAP_PASSWORD
+ password: password
+```
+
+The user must have an email address in order for Authelia to perform
+identity verification when password reset request is initiated or
+when a second factor device is registered.
\ No newline at end of file
diff --git a/docs/configuration/duo-push-notifications.md b/docs/configuration/duo-push-notifications.md
new file mode 100644
index 000000000..343f530f0
--- /dev/null
+++ b/docs/configuration/duo-push-notifications.md
@@ -0,0 +1,27 @@
+---
+layout: default
+title: Duo Push Notifications
+parent: Configuration
+nav_order: 3
+---
+
+# Duo Push Notifications
+
+Authelia supports mobile push notifications relying on [Duo].
+
+Follow the instructions in the dedicated [documentation](../features/2fa/push-notifications.md)
+to know how to set up push notifications in Authelia.
+
+## Configuration
+
+The configuration is as follows:
+
+ duo_api:
+ hostname: api-123456789.example.com
+ integration_key: ABCDEF
+ secret_key: 1234567890abcdefghifjkl
+
+The secret key is shown as an example but you'd better set it using an environment
+variable as described [here](./secrets.md).
+
+[Duo]: https://duo.com/
\ No newline at end of file
diff --git a/docs/configuration/google-analytics.md b/docs/configuration/google-analytics.md
new file mode 100644
index 000000000..0e90be71a
--- /dev/null
+++ b/docs/configuration/google-analytics.md
@@ -0,0 +1,13 @@
+---
+layout: default
+title: Google Analytics
+parent: Configuration
+nav_order: 4
+---
+
+# Google Analytics
+
+It is possible to provide a Google Analytics ID to Authelia in order
+to monitor the usage of the Sign-In portal.
+
+ google_analytics: UA-00000-01
\ No newline at end of file
diff --git a/docs/configuration/index.md b/docs/configuration/index.md
new file mode 100644
index 000000000..7f94010fe
--- /dev/null
+++ b/docs/configuration/index.md
@@ -0,0 +1,16 @@
+---
+layout: default
+title: Configuration
+nav_order: 4
+has_children: true
+---
+
+# Configuration
+
+Authelia uses a YAML file as configuration file. A template with all possible
+options can be found [here](../config.template.yml), at the root of the repository.
+
+When running **Authelia**, you can specify your configuration by passing
+the file path as shown below.
+
+ $ authelia --config config.custom.yml
diff --git a/docs/configuration/miscellaneous.md b/docs/configuration/miscellaneous.md
new file mode 100644
index 000000000..178909bf2
--- /dev/null
+++ b/docs/configuration/miscellaneous.md
@@ -0,0 +1,53 @@
+---
+layout: default
+title: Miscellaneous
+parent: Configuration
+nav_order: 5
+---
+
+# Miscellaneous
+
+Here are the main customizable options in Authelia.
+
+## Host & Port
+`optional: true`
+
+Defines the address to listen on.
+
+ host: 0.0.0.0
+ port: 9091
+
+## Logs level
+
+`optional: true`
+
+Defines the level of logs used by Authelia. This level can be set to
+`trace`, `debug`, `info`.
+
+ logs_level: debug
+
+
+## JWT Secret
+
+`optional: false`
+
+Defines the secret used to craft JWT tokens leveraged by the identity
+verification process
+
+ jwt_secret: v3ry_important_s3cr3t
+
+## Default redirection URL
+
+`optional: true`
+
+The default redirection URL is the URL where users are redirected when Authelia
+cannot detect the target URL where the user was heading.
+
+In a normal authentication workflow, a user tries to access a website and she
+gets redirected to the sign-in portal in order to authenticate. Since the user
+initially targeted a website, the portal knows where the user was heading and
+can redirect her after the authentication process.
+However, when a user visits the sign in portal directly, the portal considers
+the targeted website is the portal. In that case and if the default redirection URL
+is configured, the user is redirected to that URL. If not defined, the user is not
+redirected after authentication.
\ No newline at end of file
diff --git a/docs/configuration/notifier/filesystem.md b/docs/configuration/notifier/filesystem.md
new file mode 100644
index 000000000..c1a765062
--- /dev/null
+++ b/docs/configuration/notifier/filesystem.md
@@ -0,0 +1,18 @@
+---
+layout: default
+title: Filesystem
+parent: Notifier
+grand_parent: Configuration
+nav_order: 1
+---
+
+# Filesystem
+
+With this configuration, the message will be sent to a file. This option
+should be used only for testing purpose.
+
+```yaml
+notifier:
+ filesystem:
+ filename: /tmp/authelia/notification.txt
+```
\ No newline at end of file
diff --git a/docs/configuration/notifier/index.md b/docs/configuration/notifier/index.md
new file mode 100644
index 000000000..5d05b6cc7
--- /dev/null
+++ b/docs/configuration/notifier/index.md
@@ -0,0 +1,12 @@
+---
+layout: default
+title: Notifier
+parent: Configuration
+nav_order: 6
+has_children: true
+---
+
+# Notifier
+
+**Authelia** sometimes needs to send messages to users in order to
+verify their identity.
diff --git a/docs/configuration/notifier/smtp.md b/docs/configuration/notifier/smtp.md
new file mode 100644
index 000000000..e44086520
--- /dev/null
+++ b/docs/configuration/notifier/smtp.md
@@ -0,0 +1,53 @@
+---
+layout: default
+title: SMTP
+parent: Notifier
+grand_parent: Configuration
+nav_order: 2
+---
+
+# SMTP
+
+**Authelia** can send emails to users through an SMTP server.
+It can be configured as described below.
+
+```yaml
+notifier:
+ # Use a SMTP server for sending notifications. Authelia uses PLAIN or LOGIN method to authenticate.
+ # [Security] By default Authelia will:
+ # - force all SMTP connections over TLS including unauthenticated connections
+ # - use the disable_require_tls boolean value to disable this requirement (only works for unauthenticated connections)
+ # - validate the SMTP server x509 certificate during the TLS handshake against the hosts trusted certificates
+ # - trusted_cert option:
+ # - this is a string value, that may specify the path of a PEM format cert, it is completely optional
+ # - if it is not set, a blank string, or an invalid path; will still trust the host machine/containers cert store
+ # - defaults to the host machine (or docker container's) trusted certificate chain for validation
+ # - use the trusted_cert string value to specify the path of a PEM format public cert to trust in addition to the hosts trusted certificates
+ # - use the disable_verify_cert boolean value to disable the validation (prefer the trusted_cert option as it's more secure)
+ smtp:
+ username: test
+ # This secret can also be set using the env variables AUTHELIA_NOTIFIER_SMTP_PASSWORD
+ password: password
+ host: 127.0.0.1
+ port: 1025
+ sender: admin@example.com
+ ## disable_require_tls: false
+ ## disable_verify_cert: false
+ ## trusted_cert: ""
+```
+
+## Using Gmail
+
+You need to generate an app password in order to use Gmail SMTP servers. The process is
+described [here](https://support.google.com/accounts/answer/185833?hl=en)
+
+```yaml
+notifier:
+ smtp:
+ username: myaccount@gmail.com
+ # This secret can also be set using the env variables AUTHELIA_NOTIFIER_SMTP_PASSWORD
+ password: yourapppassword
+ sender: admin@example.com
+ host: smtp.gmail.com
+ port: 587
+```
\ No newline at end of file
diff --git a/docs/configuration/one-time-password.md b/docs/configuration/one-time-password.md
new file mode 100644
index 000000000..08c7c5f81
--- /dev/null
+++ b/docs/configuration/one-time-password.md
@@ -0,0 +1,17 @@
+---
+layout: default
+title: One-Time Password
+parent: Configuration
+nav_order: 6
+---
+
+# One-Time Password
+
+Applications generating one-time passwords usually displays an issuer to
+differentiate the various applications registered by the user.
+
+Authelia allows to customize the issuer to differentiate the entry created
+by Authelia from others.
+
+ totp:
+ issuer: authelia.com
\ No newline at end of file
diff --git a/docs/configuration/regulation.md b/docs/configuration/regulation.md
new file mode 100644
index 000000000..26d8fc0a4
--- /dev/null
+++ b/docs/configuration/regulation.md
@@ -0,0 +1,27 @@
+---
+layout: default
+title: Regulation
+parent: Configuration
+nav_order: 7
+---
+
+# Regulation
+
+**Authelia** can temporarily ban accounts when there was too many
+authentication attempts. This helps prevent brute force attacks.
+
+## Configuration
+
+```yaml
+regulation:
+ # The number of failed login attempts before user is banned.
+ # Set it to 0 to disable regulation.
+ max_retries: 3
+
+ # The time range during which the user can attempt login before being banned.
+ # The user is banned if the authentication failed `max_retries` times in a `find_time` seconds window.
+ find_time: 120
+
+ # The length of time before a banned user can sign in again.
+ ban_time: 300
+```
\ No newline at end of file
diff --git a/docs/configuration/secrets.md b/docs/configuration/secrets.md
new file mode 100644
index 000000000..0ed030486
--- /dev/null
+++ b/docs/configuration/secrets.md
@@ -0,0 +1,44 @@
+---
+layout: default
+title: Secrets
+parent: Configuration
+nav_order: 8
+---
+
+# Secrets
+
+Configuration of Authelia requires some secrets and passwords.
+Even if they can be set in the configuration file, the recommended
+way to set secrets is to use environment variables as described
+below.
+
+## Environment variables
+
+A secret can be configured using an environment variable with name
+starting with AUTHELIA_ and followed by the path of the option capitalized
+and with dots replaced by underscores.
+
+For instance the LDAP password is identified by the path
+**authentication_backend.ldap.password**, so this password could
+alternatively be set using the environment variable called
+**AUTHELIA_AUTHENTICATION_BACKEND_LDAP_PASSWORD**.
+
+Here is the list of the environment variables which are considered
+secrets and can be defined. Any other option defined using an
+environment variable will not be replaced.
+
+* AUTHELIA_JWT_SECRET
+* AUTHELIA_DUO_API_SECRET_KEY
+* AUTHELIA_SESSION_SECRET
+* AUTHELIA_AUTHENTICATION_BACKEND_LDAP_PASSWORD
+* AUTHELIA_NOTIFIER_SMTP_PASSWORD
+* AUTHELIA_SESSION_REDIS_PASSWORD
+* AUTHELIA_STORAGE_MYSQL_PASSWORD
+* AUTHELIA_STORAGE_POSTGRES_PASSWORD
+
+## Secrets in configuration file
+
+If for some reason you prefer keeping the secrets in the configuration
+file, be sure to apply the right permissions to the file in order to
+prevent secret leaks if an another application gets compromised on your
+server. The UNIX permissions should probably be something like 600.
diff --git a/docs/configuration/session.md b/docs/configuration/session.md
new file mode 100644
index 000000000..42b4e2cdc
--- /dev/null
+++ b/docs/configuration/session.md
@@ -0,0 +1,46 @@
+---
+layout: default
+title: Session
+parent: Configuration
+nav_order: 9
+---
+
+# Session
+
+**Authelia** relies on session cookies to authenticate users. When the user visits
+a website of the protected domain `example.com` for the first time, Authelia detects
+that there is no cookie for that user. Consequently, Authelia redirects the user
+to the login portal through which the user should authenticate to get a cookie which
+is valid for `*.example.com`, meaning all websites of the domain.
+At the next request, Authelia receives the cookie associated to the authenticated user
+and can then order the reverse proxy to let the request pass through to the application.
+
+## Configuration
+
+```yaml
+session:
+ # The name of the session cookie. (default: authelia_session).
+ name: authelia_session
+
+ # The secret to encrypt the session cookie.
+ # This secret can also be set using the env variables AUTHELIA_SESSION_SECRET
+ secret: unsecure_session_secret
+
+ # The time in seconds before the cookie expires and session is reset.
+ expiration: 3600 # 1 hour
+
+ # The inactivity time in seconds before the session is reset.
+ inactivity: 300 # 5 minutes
+
+ # The domain to protect.
+ # Note: the login portal must also be a subdomain of that domain.
+ domain: example.com
+
+ # The redis connection details (optional)
+ # If not provided, sessions will be stored in memory
+ redis:
+ host: 127.0.0.1
+ port: 6379
+ # This secret can also be set using the env variables AUTHELIA_SESSION_REDIS_PASSWORD
+ password: authelia
+```
\ No newline at end of file
diff --git a/docs/configuration/storage/index.md b/docs/configuration/storage/index.md
new file mode 100644
index 000000000..79224e050
--- /dev/null
+++ b/docs/configuration/storage/index.md
@@ -0,0 +1,20 @@
+---
+layout: default
+title: Storage backends
+parent: Configuration
+nav_order: 10
+has_children: true
+---
+
+# Storage backends
+
+**Authelia** supports multiple storage backends. This backend is used
+to store user preferences, 2FA device handles and secrets, authentication
+logs, etc...
+
+The available options are:
+
+* [SQLite](./sqlite.html)
+* [MariaDB](./mariadb.html)
+* ~~MySQL~~ ([#512](https://github.com/authelia/authelia/issues/512))
+* [Postgres]((./postgres.html))
\ No newline at end of file
diff --git a/docs/configuration/storage/mariadb.md b/docs/configuration/storage/mariadb.md
new file mode 100644
index 000000000..cfa5216c1
--- /dev/null
+++ b/docs/configuration/storage/mariadb.md
@@ -0,0 +1,20 @@
+---
+layout: default
+title: MariaDB
+parent: Storage backends
+grand_parent: Configuration
+nav_order: 1
+---
+
+# MariaDB
+
+```yaml
+storage:
+ mysql:
+ host: 127.0.0.1
+ port: 3306
+ database: authelia
+ username: authelia
+ # This secret can also be set using the env variables AUTHELIA_STORAGE_MYSQL_PASSWORD
+ password: mypassword
+```
diff --git a/docs/configuration/storage/postgres.md b/docs/configuration/storage/postgres.md
new file mode 100644
index 000000000..5554266ee
--- /dev/null
+++ b/docs/configuration/storage/postgres.md
@@ -0,0 +1,20 @@
+---
+layout: default
+title: PostgreSQL
+parent: Storage backends
+grand_parent: Configuration
+nav_order: 2
+---
+
+# PostgreSQL
+
+```yaml
+storage:
+ postgres:
+ host: 127.0.0.1
+ port: 3306
+ database: authelia
+ username: authelia
+ # This secret can also be set using the env variables AUTHELIA_STORAGE_POSTGRES_PASSWORD
+ password: mypassword
+```
diff --git a/docs/configuration/storage/sqlite.md b/docs/configuration/storage/sqlite.md
new file mode 100644
index 000000000..cc961bbf5
--- /dev/null
+++ b/docs/configuration/storage/sqlite.md
@@ -0,0 +1,23 @@
+---
+layout: default
+title: SQLite
+parent: Storage backends
+grand_parent: Configuration
+nav_order: 3
+---
+
+# SQLite
+
+If you don't have a SQL server, you can use [SQLite](https://en.wikipedia.org/wiki/SQLite).
+However please note that this setup will prevent you from running multiple
+instances of Authelia since the database will be a local file.
+
+## Configuration
+
+Just give the path to the sqlite database. It will be created if the file does not exist.
+
+```yaml
+storage:
+ local:
+ path: /var/lib/authelia/db.sqlite3
+```
diff --git a/docs/authelia-scripts.md b/docs/contributing/authelia-scripts.md
similarity index 84%
rename from docs/authelia-scripts.md
rename to docs/contributing/authelia-scripts.md
index 75de7c716..44db9f803 100644
--- a/docs/authelia-scripts.md
+++ b/docs/contributing/authelia-scripts.md
@@ -1,3 +1,9 @@
+---
+layout: default
+title: Authelia Scripts
+parent: Contributing
+---
+
# Authelia Scripts
Authelia comes with a set of dedicated scripts doing a broad range of operations such as
diff --git a/docs/build-and-dev.md b/docs/contributing/build-and-dev.md
similarity index 96%
rename from docs/build-and-dev.md
rename to docs/contributing/build-and-dev.md
index a003f6a27..5184c367f 100644
--- a/docs/build-and-dev.md
+++ b/docs/contributing/build-and-dev.md
@@ -1,4 +1,11 @@
-# Build and dev
+---
+layout: default
+title: Build & Dev
+parent: Contributing
+nav_order: 1
+---
+
+# Build & Dev
**Authelia** is written in Go and comes with a dedicated CLI called
[authelia-scripts](./authelia-scripts.md) which is available after
diff --git a/docs/contributing/index.md b/docs/contributing/index.md
new file mode 100644
index 000000000..0724ed379
--- /dev/null
+++ b/docs/contributing/index.md
@@ -0,0 +1,8 @@
+---
+layout: default
+title: Contributing
+nav_order: 7
+has_children: true
+---
+
+# Contributing
\ No newline at end of file
diff --git a/docs/suites.md b/docs/contributing/suites.md
similarity index 95%
rename from docs/suites.md
rename to docs/contributing/suites.md
index 90db91d15..3058f0e72 100644
--- a/docs/suites.md
+++ b/docs/contributing/suites.md
@@ -1,3 +1,10 @@
+---
+layout: default
+title: Suites
+parent: Contributing
+nav_order: 3
+---
+
# Suites
Authelia is a single component in interaction with many others in a complete
diff --git a/docs/deployment-dev.md b/docs/deployment-dev.md
deleted file mode 100644
index c352e8bc4..000000000
--- a/docs/deployment-dev.md
+++ /dev/null
@@ -1,165 +0,0 @@
-# Deployment for Dev
-
-1. [Deploy With npm](#deploy-with-npm)
-2. [Deploy With Docker](#deploy-with-docker)
-3. [Deploy nginx](#deploy-nginx)
-4. [Discard components](#discard-components)
- 1. [Discard SQL Server](#discard-sql-server)
- 2. [Discard Redis](#discard-redis)
- 3. [Discard LDAP](#discard-ldap)
-5. [FAQ](#faq)
-
-**WARNING:** *the instructions given in this documentation are not meant
-to be used for production environments since it will make **Authelia**
-non resilient to failures.*
-
-**NOTE:** If not done already, we highly recommend you first follow the
-[Getting Started] documentation.
-
-In some cases, like protecting personal projects/websites, it can be fine
-to use **Authelia** in a non highly-available setup. This reduces the number
-of components to only two: a reverse proxy such as nginx or Traefik and
-Authelia as a companion of the proxy.
-
-As for a regular deployment in production, you need to install **Authelia**
-either by pulling the Docker image or building distributable version.
-
-## Build and deploy the distributable version
-
- $ authelia-scripts build
- $ PUBLIC_DIR=./dist/public_html ./dist/authelia --config /path/to/your/configuration.yml
-
-## Deploy with Docker
-
- $ docker pull authelia/authelia
- $ docker run -v /path/to/your/configuration.yml:/etc/authelia/configuration.yml authelia/authelia
-
-## Deploy Nginx
-
-You also need to install nginx and take
-[example/compose/nginx/minimal/nginx.conf](./example/compose/nginx/minimal/nginx.conf)
-as an example for your configuration.
-
-## Deploy Traefik
-
-TODO
-
-## Discard components
-
-### Discard SQL server
-
-There is an option in the configuration file to avoid using an external
-SQL server and use a local sqlite3 database instead. This option will
-therefore prevent you from running multiple instances of **Authelia**
-in parallel.
-Consequently, this option is not meant to be used in production or at
-least not one that should scale out.
-
-Here is the configuration you should use:
-
- storage:
- # The file path of the sqlite3 file where data will be persisted
- local:
- path: /var/lib/authelia/db.sqlite3
-
-### Discard Redis
-
-There is an option in the configuration file to discard Redis and use the
-memory of the server to store the KV data. This option will therefore
-prevent you from running multiple instances of **Authelia** in parallel and
-will make you lose user sessions if the application restarts. This
-concretely means that all your users will need to authenticate again after
-a restart of Authelia. Hence, this option is not meant to be used in production.
-
-To use memory instead of a Redis backend, just comment out the Redis
-connection details in the following block:
-
- session:
- ...
- # # The redis connection details
- # redis:
- # host: redis
- # port: 6379
- # password: authelia
-
-### Discard LDAP
-
-**Authelia** can use a file backend in order to store users instead of a
-LDAP server or an Active Directory. This mode will therefore prevent you
-from running multiple instances of **Authelia** in parallel and is therefore
-discouraged for production environments.
-
-To use a file backend instead of a LDAP server, you should first duplicate
-the file [users_database.yml](../test/suites/basic/users_database.yml) and
-edit it to add the users you want.
-
-The content of this file is as follows:
-
- users:
- ...
- john:
- password: "$6$rounds=500000$jgiCMRyGXzoqpxS3$w2pJeZnnH8bwW3zzvoMWtTRfQYsHbWbD/hquuQ5vUeIyl9gdwBIt6RWk2S6afBA0DPakbeWgD/4SZPiS0hYtU/"
- email: john.doe@authelia.com
- groups:
- - admins
- - dev
-
-The password is hashed and salted as it is in LDAP servers with salted SHA-512
-(more hash algorithms such as Argon2 will be provided in the future).
-Here is a one-liner to generate such hashed password:
-
- $ docker run authelia/authelia authelia hash-password yourpassword
- $6$rounds=50000$BpLnfgDsc2WD8F2q$PumMwig8O0uIe9SgneL8Cm1FvUniOzpqBrH.uQE3aZR4K1dHsQldu5gEjJZsXcO./v3itfz6CXTDTJgeh5e8t.
-
-Copy this newly hashed password into your `users_database.yml` file.
-
-Once the file is created, edit the configuration file with the following
-block (as used in [configuration.yml](../test/suites/basic/configuration.yml)):
-
- authentication_backend:
- file:
- path: /path/to/the/users_database.yml
-
-instead of (used in [config.template.yml](../config.template.yml)):
-
- authentication_backend:
- ldap:
- url: ldap://openldap
- base_dn: dc=example,dc=com
-
- additional_users_dn: ou=users
- users_filter: cn={0}
-
- additional_groups_dn: ou=groups
- groups_filter: (&(member={dn})(objectclass=groupOfNames))
-
- group_name_attribute: cn
-
- mail_attribute: mail
-
- user: cn=admin,dc=example,dc=com
- password: password
-
-## FAQ
-
-### Can you give more details on why this is not suitable for production environments?
-
-This documentation gives instructions that will make **Authelia** non
-highly-available and non scalable by preventing you from running multiple
-instances of the application.
-This means that **Authelia** won't be able to distribute the
-load across multiple servers and it will prevent failover in case of a
-crash or an hardware issue. Moreover, it will also prevent from reliably
-persisting data and consequently fail access to your platform as the devices
-registered by your users will be lost.
-
-### Why aren't all those steps automated?
-
-Well, as stated before those instructions are not meant to be applied for
-a production environment. That being said, in some cases it is just fine and
-writing an Ansible playbook to automate all this process is ok.
-We would really be more than happy to review such a PR.
-In the meantime, you can check the *Standalone* [suite](./suites.md) to see all this
-in a real example.
-
-[Getting Started]: ./getting-started.md
diff --git a/docs/deployment-production.md b/docs/deployment/deployment-ha.md
similarity index 80%
rename from docs/deployment-production.md
rename to docs/deployment/deployment-ha.md
index 82ab9d6cf..f1c2b4395 100644
--- a/docs/deployment-production.md
+++ b/docs/deployment/deployment-ha.md
@@ -1,4 +1,11 @@
-# Deployment for Production
+---
+layout: default
+title: Deployment - Highly-Available
+parent: Deployment
+nav_order: 2
+---
+
+# Highly-Available Deployment
**Authelia** can be deployed on bare metal or on Kubernetes with two
different kind of artifacts: the distributable version (binary and public_html)
@@ -42,16 +49,6 @@ pay attention to the permissions of the configuration file. See
$ docker run -v /path/to/your/configuration.yml:/etc/authelia/configuration.yml -e TZ=Europe/Paris authelia/authelia
-## On top of Kubernetes
-
-
-
-**Authelia** can also be installed on top of [Kubernetes] using
-[nginx ingress controller](https://github.com/kubernetes/ingress-nginx).
-
-Please refer to the following [documentation](../internal/suites/example/kube/README.md)
-for more information.
-
## FAQ
### Why is this not automated?
@@ -59,9 +56,6 @@ for more information.
Ansible would be a very good candidate to automate the installation of such
an infrastructure on bare metal. We would be more than happy to review any PR on that matter.
-Regarding Kubernetes, the right way to go would be to write a Helm recipe.
-Again, we would be glad to review any PR implementing this.
-
[config.template.yml]: ../config.template.yml
diff --git a/docs/deployment/deployment-kubernetes.md b/docs/deployment/deployment-kubernetes.md
new file mode 100644
index 000000000..9a1472ddb
--- /dev/null
+++ b/docs/deployment/deployment-kubernetes.md
@@ -0,0 +1,14 @@
+---
+layout: default
+title: Deployment - Kubernetes
+parent: Deployment
+nav_order: 3
+---
+
+# Deployment on Kubernetes
+
+
+ 
+
+
+UNDER CONSTRUCTION
\ No newline at end of file
diff --git a/docs/deployment/deployment-lite.md b/docs/deployment/deployment-lite.md
new file mode 100644
index 000000000..246e178a8
--- /dev/null
+++ b/docs/deployment/deployment-lite.md
@@ -0,0 +1,61 @@
+---
+layout: default
+title: Deployment - Lite
+parent: Deployment
+---
+
+# Lite Deployment
+
+**Authelia** can be deployed as a lite setup not requiring any SQL server,
+Redis cluster or LDAP server. In some cases, like protecting personal projects/websites,
+it can be fine to use that setup but beware that this setup is non-resilient to failures
+so it should be used at your own risk.
+
+The setup is called lite since it reduces the number of components in the architecture to
+only two: a reverse proxy such as Nginx, Traefik or HAProxy and Authelia.
+
+## Reverse Proxy
+
+Documentation for deploying a reverse proxy collaborating with Authelia is available
+[here](./supported-proxies/index).
+
+## Discard components
+
+### Discard SQL server
+
+It's possible to use a SQLite file instead of a SQL server as documented
+[here](../configuration/storage/sqlite).
+
+### Discard Redis
+
+Connection details to Redis are optional. If not provided, sessions will
+be stored in memory instead. This has the inconvenient of logging out users
+every time Authelia restarts.
+
+The documentation about session management is available
+[here](../configuration/session).
+
+
+### Discard LDAP
+
+**Authelia** can use a file backend in order to store users instead of a
+LDAP server or an Active Directory.
+
+To use a file backend instead of a LDAP server, please follow the related
+documentation [here](../configuration/authentication/file).
+
+## FAQ
+
+### Can you give more details on why this is not suitable for production environments?
+
+This documentation gives instructions that will make **Authelia** non
+resilient to failures and non scalable by preventing you from running multiple
+instances of the application. This means that **Authelia** won't be able to distribute
+the load across multiple servers and it will prevent failover in case of a
+crash or an hardware issue. Moreover, users will be logged out every time
+Authelia restarts.
+
+### Why aren't all those steps automated?
+
+We would really be more than happy to review any contribution with an Ansible playbook,
+a Chef cookbook or whatever else to automate the process.
diff --git a/docs/deployment/index.md b/docs/deployment/index.md
new file mode 100644
index 000000000..197b8c35b
--- /dev/null
+++ b/docs/deployment/index.md
@@ -0,0 +1,8 @@
+---
+layout: default
+title: Deployment
+nav_order: 5
+has_children: true
+---
+
+# Deployment
\ No newline at end of file
diff --git a/docs/deployment/supported-proxies/haproxy.md b/docs/deployment/supported-proxies/haproxy.md
new file mode 100644
index 000000000..2deb924a6
--- /dev/null
+++ b/docs/deployment/supported-proxies/haproxy.md
@@ -0,0 +1,15 @@
+---
+layout: default
+title: HAProxy
+parent: Supported Proxies
+grand_parent: Deployment
+nav_order: 1
+---
+
+# HAProxy
+
+[HAProxy] is a reverse proxy supported by **Authelia**.
+
+UNDER CONSTRUCTION
+
+[HAproxy]: https://www.haproxy.org/
\ No newline at end of file
diff --git a/docs/deployment/supported-proxies/index.md b/docs/deployment/supported-proxies/index.md
new file mode 100644
index 000000000..e6e93f821
--- /dev/null
+++ b/docs/deployment/supported-proxies/index.md
@@ -0,0 +1,12 @@
+---
+layout: default
+title: Supported Proxies
+parent: Deployment
+nav_order: 4
+has_children: true
+---
+
+# Supported Proxies
+
+**Authelia** works in collaboration with reverse proxies. Here you can find
+the documentation of the configuration required for every supported proxies.
\ No newline at end of file
diff --git a/docs/proxies/nginx.md b/docs/deployment/supported-proxies/nginx.md
similarity index 98%
rename from docs/proxies/nginx.md
rename to docs/deployment/supported-proxies/nginx.md
index f1b47eb38..c981a4b86 100644
--- a/docs/proxies/nginx.md
+++ b/docs/deployment/supported-proxies/nginx.md
@@ -1,3 +1,11 @@
+---
+layout: default
+title: Nginx
+parent: Supported Proxies
+grand_parent: Deployment
+nav_order: 2
+---
+
# Nginx
[nginx] is a reverse proxy supported by **Authelia**.
diff --git a/docs/proxies/traefik1.x.md b/docs/deployment/supported-proxies/traefik1.x.md
similarity index 95%
rename from docs/proxies/traefik1.x.md
rename to docs/deployment/supported-proxies/traefik1.x.md
index 41577deec..75a953a3d 100644
--- a/docs/proxies/traefik1.x.md
+++ b/docs/deployment/supported-proxies/traefik1.x.md
@@ -1,3 +1,11 @@
+---
+layout: default
+title: Traefik 1.x
+parent: Supported Proxies
+grand_parent: Deployment
+nav_order: 3
+---
+
# Traefik
[Traefik 1.x] is a reverse proxy supported by **Authelia**.
diff --git a/docs/proxies/traefik2.x.md b/docs/deployment/supported-proxies/traefik2.x.md
similarity index 96%
rename from docs/proxies/traefik2.x.md
rename to docs/deployment/supported-proxies/traefik2.x.md
index b08f78d68..9ed0d1886 100644
--- a/docs/proxies/traefik2.x.md
+++ b/docs/deployment/supported-proxies/traefik2.x.md
@@ -1,3 +1,11 @@
+---
+layout: default
+title: Traefik 2.x
+parent: Supported Proxies
+grand_parent: Deployment
+nav_order: 3
+---
+
# Traefik2
[Traefik 2.x] is a reverse proxy supported by **Authelia**.
diff --git a/docs/favicon.ico b/docs/favicon.ico
new file mode 100644
index 000000000..46d3d0e2a
Binary files /dev/null and b/docs/favicon.ico differ
diff --git a/docs/features.md b/docs/features.md
deleted file mode 100644
index eb91186c3..000000000
--- a/docs/features.md
+++ /dev/null
@@ -1,77 +0,0 @@
-# Features in details
-
-## 1-Factor (1FA) using a LDAP server
-
-**Authelia** uses an LDAP server as the backend for storing credentials.
-When authentication is needed, the user is redirected to the login page which
-corresponds to the first factor. **Authelia** tries to bind the username and
-password against the configured LDAP backend.
-
-You can find an example of the configuration of the LDAP backend in
-[config.template.yml].
-
-
- 
-
-
-
-## 2-Factor (2FA)
-
-**Authelia** comes with three kind of second factor.
-
-* Security keys like [Yubikey]. More info [here](./2factor/security-key.md).
-* One-Time Passwords generated by [Google Authenticator]. More info [here](./2factor/time-based-one-time-password.md).
-* 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).
-
-
- 
-
-
-## Password reset
-
-With **Authelia**, you can also reset your password in no time. Click on the
-**Forgot password?** link in the login page, provide the username of the user
-requiring a password reset and **Authelia** will send an email a confirmation
-email to the user email address.
-
-Proceed with the password reset form and validate to reset your password.
-
-
- 
-
-
-## Access Control
-
-With **Authelia**, you can define your own access control rules for finely
-restricting user access to some resources and subdomains. Those rules are
-defined and fully documented in the configuration file. They can apply to
-users, groups or everyone.
-
-Check out [config.template.yml] to see how they are defined.
-
-## Single factor authentication
-
-**Authelia** allows you to customize the authentication method to use for each
-subdomain. The supported methods are either "single_factor" or "two_factor".
-Please check [config.template.yml] to see an example of configuration.
-
-It is also possible to use [basic authentication] to access a resource
-protected by a single factor.
-
-Please note that Authelia uses the *Proxy-Authorization* header and not
-*Authorization* since one might be willing to authenticate against both
-Authelia and the proxy. For instance you can use the following command to
-access your service:
-
- $ curl -H "Proxy-Authorization: Basic am9objpwYXNzd29yZA==" https://myservice.example.com"
-
-## Session management with Redis
-
-When your users authenticate against Authelia, sessions are stored in a
-Redis key/value store. You can specify your own Redis instance in
-[config.template.yml].
-
-[basic authentication]: https://en.wikipedia.org/wiki/Basic_access_authentication
-[config.template.yml]: https://github.com/authelia/authelia/blob/master/config.template.yml
-[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
\ No newline at end of file
diff --git a/docs/features/2fa/index.md b/docs/features/2fa/index.md
new file mode 100644
index 000000000..f8a820f06
--- /dev/null
+++ b/docs/features/2fa/index.md
@@ -0,0 +1,24 @@
+---
+layout: default
+title: Second Factor
+parent: Features
+nav_order: 1
+has_children: true
+---
+
+# Second Factor
+
+There are multiple supported options for the second factor.
+
+* Time-based One-Time passwords with [Google Authenticator]
+* Security Keys with tokens like [Yubikey].
+* Push notifications on your mobile using [Duo].
+
+
+ 
+
+
+
+[Duo]: https://duo.com/
+[Yubikey]: https://www.yubico.com/products/yubikey-hardware/yubikey4/
+[Google Authenticator]: https://google-authenticator.com/
\ No newline at end of file
diff --git a/docs/features/2fa/one-time-password.md b/docs/features/2fa/one-time-password.md
new file mode 100644
index 000000000..558ca4357
--- /dev/null
+++ b/docs/features/2fa/one-time-password.md
@@ -0,0 +1,38 @@
+---
+layout: default
+title: One-Time Password
+nav_order: 1
+parent: Second Factor
+grand_parent: Features
+---
+
+# Time-based One-Time Password
+
+**Authelia** supports Time-base one-time password generated by apps like [Google Authenticator].
+
+
+ 
+ 
+
+
+
+After having successfully completed the first factor, select **One-Time Password method**
+option and click on **Not registered yet?** link. This will send you an e-mail to confirm
+your identity.
+
+*NOTE: If you're testing **Authelia**, this e-mail has likely been sent to the mailbox available at https://mail.example.com:8080/*
+
+Once this validation step is completed, a QRCode gets displayed.
+
+
+ 
+
+
+You can then use [Google Authenticator] to scan the code in order to register your device.
+
+From now on, you get tokens generated every 30 seconds that
+you can use to validate the second factor in **Authelia**.
+
+
+
+[Google Authenticator]: https://google-authenticator.com/
\ No newline at end of file
diff --git a/docs/features/2fa/push-notifications.md b/docs/features/2fa/push-notifications.md
new file mode 100644
index 000000000..ce7e3ee15
--- /dev/null
+++ b/docs/features/2fa/push-notifications.md
@@ -0,0 +1,61 @@
+---
+layout: default
+title: Push Notification
+parent: Second Factor
+nav_order: 3
+grand_parent: Features
+---
+
+# Mobile Push Notification
+
+Mobile push notifications is the new trendy second factor method. When second factor is requested
+by Authelia, a notification is sent on your phone that you can either accept or deny.
+
+
+ 
+ 
+
+
+
+Authelia leverages [Duo] third party to provide this feature.
+
+First, sign up on their website, log in, create a user account and attach it a mobile device.
+Beware that the name of the user must match the name of the user in Authelia.
+
+Then, in Duo interface, click on *Applications* and *Protect an Application*. Select the option
+*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 Authelia [configuration](../deployment/configuration.md) as shown below:
+
+ duo_api:
+ hostname: api-123456789.example.com
+ integration_key: ABCDEF
+ secret_key: 1234567890abcdefghifjkl
+
+Now that Authelia is configured, pass the first factor and select the Push notification
+option.
+
+
+ 
+
+
+You should now receive a notification on your mobile phone with all the details
+about the authentication request.
+
+
+## Limitation
+
+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 *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).
+
+
+
+[Duo]: https://duo.com/
\ No newline at end of file
diff --git a/docs/features/2fa/security-key.md b/docs/features/2fa/security-key.md
new file mode 100644
index 000000000..a547d12cb
--- /dev/null
+++ b/docs/features/2fa/security-key.md
@@ -0,0 +1,56 @@
+---
+layout: default
+title: Security Keys
+nav_order: 2
+parent: Second Factor
+grand_parent: Features
+---
+
+# Security Keys
+
+**Authelia** supports hardware-based second factors leveraging security keys like
+[Yubikeys](Yubikey).
+
+Security keys are among the most secure second factor. This method is already
+supported by many major applications and platforms like Google, Facebook, Github,
+some banks, and much more...
+
+
+ 
+
+
+Normally, the protocol requires your security key to be enrolled on each site before
+being able to authenticate with it. Since Authelia provides Single Sign-On, your users
+will need to enroll their device only once to get access to all your applications.
+
+
+ 
+
+
+After having successfully passed the first factor, select *Security Key* method and
+click on *Not registered yet?* link. This will send you an email to verify your identity.
+
+*NOTE: This e-mail has likely been sent to the mailbox at https://mail.example.com:8080/ if you're testing Authelia.*
+
+Confirm your identity by clicking on **Register** and you'll be asked to
+touch the token of your security key to complete the enrollment.
+
+Upon successful enrollment, you can authenticate using your security key
+by simply touching the token again when requested:
+
+
+ 
+
+
+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 browsers
+and might even be enabled on some of them. 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/
diff --git a/docs/features/access-control.md b/docs/features/access-control.md
new file mode 100644
index 000000000..2ee4e2e1d
--- /dev/null
+++ b/docs/features/access-control.md
@@ -0,0 +1,29 @@
+---
+layout: default
+title: Access Control
+parent: Features
+nav_order: 5
+---
+
+# Access Control
+
+**Authelia** allows to define a fine-grained rule-based access control policy in
+configuration. This list of rules is tested against any requests protected by
+Authelia and defines the level of authentication the user must pass to get access
+to the resource.
+
+For instance a rule can look like this:
+
+ - domain: dev.example.com
+ resources:
+ - "^/groups/dev/.*$"
+ subject: "group:dev"
+ policy: two_factor
+
+This rule matches when the request targets the domain `dev.example.com` and the path
+matches the regular expression `^/groups/dev/.*$`. In that case, a two-factor policy
+is applied requiring the user to authenticate with two factors.
+
+## Configuration
+
+Please check the dedicated [documentation](./deployment/configuration/access-control.md)
diff --git a/docs/features/first-factor.md b/docs/features/first-factor.md
new file mode 100644
index 000000000..617f21b79
--- /dev/null
+++ b/docs/features/first-factor.md
@@ -0,0 +1,25 @@
+---
+layout: default
+title: First Factor
+parent: Features
+nav_order: 1
+---
+
+# First Factor
+
+2-Factor authentication is a method in which a user is granted access by presenting
+two pieces of evidence that she is who she claims to be.
+
+**Authelia** requires usual username and password as a first factor.
+
+
+ 
+
+
+*IMPORTANT: This is the only method available as first factor.*
+
+Authelia supports several kind of users databases:
+
+* An LDAP server like OpenLDAP or OpenAM.
+* An Active Directory.
+* A YAML file
diff --git a/docs/features/index.md b/docs/features/index.md
new file mode 100644
index 000000000..ebc8196a5
--- /dev/null
+++ b/docs/features/index.md
@@ -0,0 +1,18 @@
+---
+layout: default
+title: Features
+nav_order: 3
+has_children: true
+---
+
+# Features
+
+**Authelia** is a 2FA & SSO authentication server which is dedicated
+to the security of applications and users. It can be considered
+as an extension of reverse proxies by providing features specific
+to authentication. You will find among other features:
+
+* Multiple two-factor methods.
+* Identity verification when registering second factor devices.
+* Reset password.
+* Ban account after too many attempts (known as regulation).
diff --git a/docs/features/password-reset.md b/docs/features/password-reset.md
new file mode 100644
index 000000000..f6872db30
--- /dev/null
+++ b/docs/features/password-reset.md
@@ -0,0 +1,31 @@
+---
+layout: default
+title: Password Reset
+parent: Features
+nav_order: 4
+---
+
+# Password Reset
+
+**Authelia** provides workflow to let users reset their password when they lose it.
+
+A simple click on `Forgot password?` for starting the process. Note that resetting a
+password requires a new identity verification using the e-mail of the user.
+
+
+
+
+
+Give your username and receive an e-mail to verify your identity.
+
+
+ 
+
+
+Once your identity is verified, fill in the form to reset your password.
+
+
+ 
+
+
+Now you can authenticate with your new credentials.
\ No newline at end of file
diff --git a/docs/features/regulation.md b/docs/features/regulation.md
new file mode 100644
index 000000000..e3bb2b02a
--- /dev/null
+++ b/docs/features/regulation.md
@@ -0,0 +1,17 @@
+---
+layout: default
+title: Regulation
+parent: Features
+nav_order: 6
+---
+
+# Regulation
+
+**Authelia** takes the security of users very seriously and comes with
+a way to avoid brute forcing the first factor by regulating the
+authentication attempts and temporarily ban an account when too many
+attempts have been made.
+
+## Configuration
+
+Please check the dedicated [documentation](./deployement/configuration/regulation.md).
\ No newline at end of file
diff --git a/docs/features/single-factor.md b/docs/features/single-factor.md
new file mode 100644
index 000000000..45b4d027a
--- /dev/null
+++ b/docs/features/single-factor.md
@@ -0,0 +1,29 @@
+---
+layout: default
+title: Single Factor
+parent: Features
+nav_order: 3
+---
+
+# Single Factor
+
+**Authelia** supports single factor authentication to let applications
+send authenticated requests to other applications.
+
+Single or two-factor authentication can be configured per resource of an
+application for flexibility.
+
+For instance, you can configure Authelia to grant access to all resources
+matching `app1.example.com/api/(.*)` with only a single factor and all
+resources matching `app1.example.com/admin` with two factors.
+
+To know more about the configuration of the feature, please visit the
+documentation about the [configuration](../deployment/configuration.md).
+
+
+## Proxy-Authorization header
+
+Authelia reads credentials from the header `Proxy-Authorization` instead of
+the usual `Authorization` header. This is because in some circumstances both Authelia
+and the application could require authentication in order to provide specific
+authorizations at the level of the application.
diff --git a/docs/getting-started.md b/docs/getting-started.md
index fe5ac5d40..18f3d8a48 100644
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -1,3 +1,9 @@
+---
+layout: default
+title: Getting Started
+nav_order: 2
+---
+
# Getting Started
**Authelia** can be tested in a matter of seconds with Docker and docker-compose.
@@ -59,15 +65,25 @@ Here are the versions used for testing in Buildkite:
$ docker-compose --version
docker-compose version 1.24.1, build unknown
-### How am I supposed to access the subdomains of example.com?
+### How can I serve my application under example.com?
-In order to test Authelia, Authelia fakes your browser by adding entries
-in /etc/hosts when you first source the bootstrap.sh script.
+Don't worry, you don't need to own the domain *example.com* to test Authelia.
+Copy the following lines in your /etc/hosts.
+
+ 192.168.240.100 home.example.com
+ 192.168.240.100 login.example.com
+ 192.168.240.100 singlefactor.example.com
+ 192.168.240.100 public.example.com
+ 192.168.240.100 secure.example.com
+ 192.168.240.100 mail.example.com
+ 192.168.240.100 mx1.mail.example.com
+
+`192.168.240.100` is the IP attributed by Docker to the reverse proxy. Once done
+you can access the listed sub-domains from your browser and they will target
+the reverse proxy.
### What should I do if I want to contribute?
-You can refer to the dedicated documentation [here](./build-and-dev.md).
+You can refer to the dedicated documentation [here](./contributing/index.md).
-[config.template.yml]: ../config.template.yml
-[DockerHub]: https://hub.docker.com/r/authelia/authelia/
-[suite]: ./suites.md
\ No newline at end of file
+[suite]: ./contributing/suites.md
\ No newline at end of file
diff --git a/docs/home/architecture.md b/docs/home/architecture.md
new file mode 100644
index 000000000..57b2ec0b7
--- /dev/null
+++ b/docs/home/architecture.md
@@ -0,0 +1,48 @@
+---
+layout: default
+title: Architecture
+parent: Home
+nav_order: 1
+---
+
+# Architecture
+
+**Authelia** is a companion of reverse proxies like Nginx, Traefik and HAProxy.
+It can be seen as an extension of those proxies providing authentication functions
+and a login portal.
+
+As shown in the following architecture diagram, Authelia is directly connected to
+the reverse proxy but never directly connected to application backends.
+
+
+ 
+
+
+## Workflow
+
+Reverse proxies are configured so that every incoming requests generates an authentication
+request sent to Authelia and to which Authelia responds to order the reverse
+proxy to let the incoming request pass through or block it because user is not authenticated
+or is not sufficiently authorized.
+
+### Step by step
+
+When the first request of an unauthenticated user hits the reverse proxy, Authelia
+determines the user is not authenticated because no session cookie has been sent along with
+the request. Consequently, Authelia redirects the user to the authentication portal provided
+by Authelia itself. The user can then execute the authentication workflow using that portal
+to obtain a session cookie valid for all subdomains of the domain protected by Authelia.
+
+When the user visits the initial website again, the query is sent along with the
+session cookie which is forwarded in the authentication request to Authelia. This time,
+Authelia can verify the user is authenticated and order the reverse proxy to let the query
+pass through.
+
+### Sequence Diagram
+
+Here is a description of the complete workflow:
+
+
+ 
+
+
diff --git a/docs/images/2FA-METHODS-noborder.png b/docs/images/2FA-METHODS-noborder.png
new file mode 100644
index 000000000..24bf87070
Binary files /dev/null and b/docs/images/2FA-METHODS-noborder.png differ
diff --git a/docs/images/2FA-TOTP.png b/docs/images/2FA-TOTP.png
index b12bbf8e4..9fb637cda 100644
Binary files a/docs/images/2FA-TOTP.png and b/docs/images/2FA-TOTP.png differ
diff --git a/docs/images/RESET-PASSWORD-STEP2.png b/docs/images/RESET-PASSWORD-STEP2.png
new file mode 100644
index 000000000..3cd8f3cd1
Binary files /dev/null and b/docs/images/RESET-PASSWORD-STEP2.png differ
diff --git a/docs/images/google-authenticator.png b/docs/images/google-authenticator.png
new file mode 100644
index 000000000..b299eee21
Binary files /dev/null and b/docs/images/google-authenticator.png differ
diff --git a/docs/images/logos/authelia.logo.png b/docs/images/logos/authelia.logo.png
deleted file mode 100644
index 65747fea1..000000000
Binary files a/docs/images/logos/authelia.logo.png and /dev/null differ
diff --git a/docs/images/sequence-diagram.png b/docs/images/sequence-diagram.png
new file mode 100644
index 000000000..e0ae5269c
Binary files /dev/null and b/docs/images/sequence-diagram.png differ
diff --git a/docs/images/yubikey.jpg b/docs/images/yubikey.jpg
new file mode 100644
index 000000000..d70cd5725
Binary files /dev/null and b/docs/images/yubikey.jpg differ
diff --git a/docs/index.md b/docs/index.md
new file mode 100644
index 000000000..89f5148ed
--- /dev/null
+++ b/docs/index.md
@@ -0,0 +1,63 @@
+---
+layout: default
+title: Home
+nav_order: 1
+has_children: true
+---
+
+# Home
+
+*It has never been so easy to secure your applications with Single Sign-On
+and Two-Factor.*
+
+
+With **Authelia** you can login once and get access to all your web apps
+safely from the Web thanks to two-factor authentication.
+
+
+ 
+
+
+**Authelia** is an open source authentication and authorization server
+protecting modern web applications by collaborating with reverse proxies
+such as NGINX, Traefik and HAProxy. Consequently, no code is required to
+protect your apps.
+
+
+ 
+
+
+Multiple 2-factor methods are available for satisfying every users.
+
+* Time-based One-Time passwords with [Google Authenticator].
+* Security Keys with tokens like [Yubikey].
+* Push notifications on your mobile using [Duo].
+
+**Authelia** is available as Docker images, static binaries and AUR packages
+so that you can test it in minutes. Let's begin with the
+[Getting Started](./getting-started).
+
+
+## Authelia...
+
+* is not an OAuth or OpenID Connect provider yet.
+* is not a SAML provider yet.
+<<<<<<< HEAD
+* does not support support authentication against an OAuth or OpenID Connect provider.
+* does not support using hardware devices as single factor.
+* does not allow provide a PAM module yet.
+=======
+* does not support authentication against an OAuth or OpenID Connect provider.
+* does not support authentication against a SAML provider.
+* does not support using hardware devices as single factor.
+* does not provide a PAM module yet.
+>>>>>>> [WIP] Use 'Just-the-docs' jekyll theme to organize documentation.
+
+
+[Duo]: https://duo.com/
+[Yubikey]: https://www.yubico.com/products/yubikey-hardware/yubikey4/
+<<<<<<< HEAD
+[Google Authenticator]: https://google-authenticator.com/
+=======
+[Google Authenticator]: https://google-authenticator.com/
+>>>>>>> [WIP] Use 'Just-the-docs' jekyll theme to organize documentation.
diff --git a/docs/security/index.md b/docs/security/index.md
new file mode 100644
index 000000000..48671620d
--- /dev/null
+++ b/docs/security/index.md
@@ -0,0 +1,8 @@
+---
+layout: default
+title: Security
+nav_order: 6
+has_children: true
+---
+
+# Security
\ No newline at end of file
diff --git a/docs/security.md b/docs/security/measures.md
similarity index 94%
rename from docs/security.md
rename to docs/security/measures.md
index e2b483a21..baa31182b 100644
--- a/docs/security.md
+++ b/docs/security/measures.md
@@ -1,4 +1,11 @@
-# Security
+---
+layout: default
+title: Security Measures
+parent: Security
+nav_order: 2
+---
+
+# Security Measures
## Protection against cookie theft
@@ -93,10 +100,4 @@ add_header X-Frame-Options "SAMEORIGIN";
add_header X-XSS-Protection "1; mode=block";
```
-## Contributing
-
-If you find possible vulnerabilities or threats, do not hesitate to contribute
-either by writing a test case demonstrating the possible attack and if
-possible some solutions to prevent it or submit a PR.
-
[HSTS]: https://www.nginx.com/blog/http-strict-transport-security-hsts-and-nginx/
diff --git a/docs/security/report.md b/docs/security/report.md
new file mode 100644
index 000000000..299bf4c02
--- /dev/null
+++ b/docs/security/report.md
@@ -0,0 +1,15 @@
+---
+layout: default
+title: Report Vulnerabilities
+parent: Security
+nav_order: 1
+---
+
+# Report Vulnerabilities
+
+Security is taken very seriously here, therefore we follow the rule of
+responsible disclosure and we encourage you to do so.
+
+Would you like to report any vulnerability discovered in Authelia, please
+first contact **clems4ever** on [Matrix](https://riot.im/app/#/room/#authelia:matrix.org)
+or by [email](mailto:clement.michaud34@gmail.com).
diff --git a/go.sum b/go.sum
index a98f1e519..d19222238 100644
--- a/go.sum
+++ b/go.sum
@@ -126,6 +126,7 @@ github.com/konsorten/go-windows-terminal-sequences v1.0.1 h1:mweAR1A6xJ3oS2pRaGi
github.com/konsorten/go-windows-terminal-sequences v1.0.1/go.mod h1:T0+1ngSBFLxvqU3pZ+m/2kptfBszLMUkC4ZK/EgS/cQ=
github.com/kr/logfmt v0.0.0-20140226030751-b84e30acd515/go.mod h1:+0opPa2QZZtGFBFZlji/RkVcI2GknAs/DXo4wKdlNEc=
github.com/kr/pretty v0.1.0/go.mod h1:dAy3ld7l9f0ibDNOQOHHMYYIIbhfbHSm3C4ZsoJORNo=
+github.com/kr/pty v1.1.1 h1:VkoXIwSboBpnk99O/KFauAEILuNHv5DVFKZMBN/gUgw=
github.com/kr/pty v1.1.1/go.mod h1:pFQYn66WHrOpPYNljwOMqo10TkYh1fy3cYio2l3bCsQ=
github.com/kr/pty v1.1.8 h1:AkaSdXYQOWeaO3neb8EM634ahkXXe3jYbVh/F9lq+GI=
github.com/kr/pty v1.1.8/go.mod h1:O1sed60cT9XZ5uDucP5qwvh+TE3NnUj51EiZO/lmSfw=