docs: refactor several areas of documentation (#1726)

Updated all links to use https://www.authelia.com/docs/. Removed all comment sections from documented configuration on the documentation site and replaced them with their own sections. Made all documentation inside config.template.yml double hashes, and made all commented configuration sections single quoted. Added .yamllint.yaml to express our desired YAML styles. Added a style guide. Refactored many documentation areas to be 120 char widths where possible. It's by no means exhaustive but is a large start. Added a statelessness guide for the pending Kubernetes chart introduction. Added labels to configuration documentation and made many areas uniform.
2024-09-14 22:47:21 +07:00 · 2021-04-11 21:25:03 +10:00 · 2021-04-11 21:25:03 +10:00 · 08e674b62f
commit 08e674b62f
parent 2a74e8cdcf
55 changed files with 2241 additions and 1242 deletions
--- a/.yamllint.yml
+++ b/.yamllint.yml
@ -4,9 +4,6 @@ extends: default
 ignore: |
  internal/configuration/test_resources/config_bad_quoting.yml
  web/node_modules/
  compose/
  config.template.yml
  internal/configuration/config.template.yml
 rules:
  document-end:
--- a/README.md
+++ b/README.md
@ -15,13 +15,12 @@
  [![Discord](https://img.shields.io/discord/707844280412012608?label=discord&logo=discord&style=flat-square&color=blue)](https://discord.authelia.com)
  [![Matrix](https://img.shields.io/matrix/authelia:matrix.org?label=matrix&logo=matrix&style=flat-square&color=blue)](https://riot.im/app/#/room/#authelia:matrix.org)
-**Authelia** is an open-source authentication and authorization server
+**Authelia** is an open-source authentication and authorization server providing 2-factor authentication and single 
-providing 2-factor authentication and single sign-on (SSO) for your
+sign-on (SSO) for your applications via a web portal. It acts as a companion of reverse proxies like [nginx], [Traefik] 
-applications via a web portal.
+or [HAProxy] to let them know whether queries should pass through. Unauthenticated users are redirected to Authelia 
-It acts as a companion of reverse proxies like [nginx], [Traefik] or [HAProxy] to let them know whether queries should pass through. Unauthenticated users are
+Sign-in portal instead.
 redirected to Authelia Sign-in portal instead.
-Documentation is available at https://docs.authelia.com.
+Documentation is available at https://www.authelia.com/docs.
 The architecture is shown in the diagram below.
@ -29,8 +28,11 @@ The architecture is shown in the diagram below.
  <img src="./docs/images/archi.png"/>
 </p>
-**Authelia** can be installed as a standalone service from the [AUR](https://aur.archlinux.org/packages/authelia/), [FreeBSD Ports](https://svnweb.freebsd.org/ports/head/www/authelia/), or using a [Static binary](https://github.com/authelia/authelia/releases/latest),
+**Authelia** can be installed as a standalone service from the [AUR](https://aur.archlinux.org/packages/authelia/), 
-[Docker] or [Kubernetes] leveraging ingress controllers and ingress configurations. Assistance to publish a [debian package](https://github.com/authelia/authelia/issues/573) would be greatly appreciated.
+[FreeBSD Ports](https://svnweb.freebsd.org/ports/head/www/authelia/), or using a 
 [Static binary](https://github.com/authelia/authelia/releases/latest), [Docker] or [Kubernetes] leveraging ingress 
 controllers and ingress configurations. Assistance to publish a 
 [Debian package](https://github.com/authelia/authelia/issues/573) would be greatly appreciated.
 <p align="center">
  <img src="./docs/images/logos/kubernetes.logo.png" height="100"/>
@ -49,9 +51,11 @@ Here is what Authelia's portal looks like
 Here is the list of the main available features:
 * Several kind of second factor:
-  * **[Security Key (U2F)](https://docs.authelia.com/features/2fa/security-key)** with [Yubikey].
+  * **[Security Key (U2F)](https://www.authelia.com/docs/features/2fa/security-key)** with [Yubikey].
-  * **[Time-based One-Time password](https://docs.authelia.com/features/2fa/one-time-password)** with [Google Authenticator].
+  * **[Time-based One-Time password](https://www.authelia.com/docs/features/2fa/one-time-password)** 
-  * **[Mobile Push Notifications](https://docs.authelia.com/features/2fa/push-notifications)** with [Duo](https://duo.com/).
+    with [Google Authenticator].
  * **[Mobile Push Notifications](https://www.authelia.com/docs/features/2fa/push-notifications)** 
    with [Duo](https://duo.com/).
 * Password reset with identity verification using email confirmation.
 * Single-factor only authentication method available.
 * Access restriction after too many authentication attempts.
@ -60,9 +64,9 @@ Here is the list of the main available features:
 * Highly available using a remote database and Redis as a highly available KV store.
 * Compatible with Kubernetes [ingress-nginx](https://github.com/kubernetes/ingress-nginx) controller out of the box.
-For more details about the features, follow [Features](https://docs.authelia.com/features/).
+For more details about the features, follow [Features](https://www.authelia.com/docs/features/).
-If you want to know more about the roadmap, follow [Roadmap](https://docs.authelia.com/roadmap).
+If you want to know more about the roadmap, follow [Roadmap](https://www.authelia.com/docs/roadmap).
 ## Proxy support
@ -80,23 +84,27 @@ Docker or on top of [Kubernetes].
 You can start utilising Authelia with the provided `docker-compose` bundles:
-#### [Local](https://docs.authelia.com/getting-started)
+#### [Local](https://www.authelia.com/docs/getting-started)
 The Local compose bundle is intended to test Authelia without worrying about configuration.
 It's meant to be used for scenarios where the server is not be exposed to the internet.
 Domains will be defined in the local hosts file and self-signed certificates will be utilised.
-#### [Lite](https://docs.authelia.com/deployment/deployment-lite)
+#### [Lite](https://www.authelia.com/docs/deployment/deployment-lite)
-The Lite compose bundle is intended for scenarios where the server will be exposed to the internet, domains and DNS will need to be setup accordingly and certificates will be generated through LetsEncrypt.
+The Lite compose bundle is intended for scenarios where the server will be exposed to the internet, domains and DNS will 
-The Lite element refers to minimal external dependencies; File based user storage, SQLite based configuration storage. In this configuration, the service will not scale well.
+need to be setup accordingly and certificates will be generated through LetsEncrypt. The Lite element refers to minimal 
 external dependencies; File based user storage, SQLite based configuration storage. In this configuration, the service 
 will not scale well.
-#### [Full](https://docs.authelia.com/deployment/deployment-ha)
+#### [Full](https://www.authelia.com/docs/deployment/deployment-ha)
-The Full compose bundle is intended for scenarios where the server will be exposed to the internet, domains and DNS will need to be setup accordingly and certificates will be generated through LetsEncrypt.
+The Full compose bundle is intended for scenarios where the server will be exposed to the internet, domains and DNS will 
-The Full element refers to a scalable setup which includes external dependencies; LDAP based user storage, Database based configuration storage (MariaDB, MySQL or Postgres). 
+need to be setup accordingly and certificates will be generated through LetsEncrypt. The Full element refers to a 
 scalable setup which includes external dependencies; LDAP based user storage, Database based configuration storage 
 (MariaDB, MySQL or Postgres). 
 ## Deployment
 Now that you have tested **Authelia** and you want to try it out in your own infrastructure,
-you can learn how to deploy and use it with [Deployment](https://docs.authelia.com/deployment/deployment-ha).
+you can learn how to deploy and use it with [Deployment](https://www.authelia.com/docs/deployment/deployment-ha).
 This guide will show you how to deploy it on bare metal as well as on
 [Kubernetes](https://kubernetes.io/).
@ -110,8 +118,8 @@ If you discover a vulnerability in Authelia, please first contact one of the mai
 either via [Matrix](#matrix) or [email](#email) as described in the [contact options](#contact-options) below.
 For details about security measures implemented in Authelia, please follow
-this [link](https://docs.authelia.com/security/measures.html) and for reading about 
+this [link](https://www.authelia.com/docs/security/measures.html) and for reading about 
-the threat model follow this [link](https://docs.authelia.com/security/threat-model.html).
+the threat model follow this [link](https://www.authelia.com/docs/security/threat-model.html).
 ### Contact Options
@ -136,18 +144,19 @@ disclosure related matters. If you need to contact us for another reason please
 ## Breaking changes
-Since Authelia is still under active development, it is subject to breaking changes.
+Since Authelia is still under active development, it is subject to breaking changes. It's recommended to pin a version 
-It's recommended to pin a version tag instead of using the `latest` tag and reading the [release notes](https://github.com/authelia/authelia/releases) before upgrading.
+tag instead of using the `latest` tag and reading the [release notes](https://github.com/authelia/authelia/releases) 
-This is where you will find information about breaking changes and what you should do to overcome those changes.
+before upgrading. This is where you will find information about breaking changes and what you should do to overcome 
 said changes.
 ## Why Open Source?
-You might wonder why Authelia is open source while it adds a great deal of security and user experience to your infrastructure at zero cost.
+You might wonder why Authelia is open source while it adds a great deal of security and user experience to your 
-It is open source because we firmly believe that security should be available for all to benefit in the face the battlefield which is the Internet
+infrastructure at zero cost. It is open source because we firmly believe that security should be available for all to 
-with near zero effort.
+benefit in the face of the battlefield which is the Internet, with near zero effort.
-Additionally, keeping the code open source is a way to leave it auditable by anyone who is willing to contribute. This way, you can be confident
+Additionally, keeping the code open source is a way to leave it auditable by anyone who is willing to contribute. This 
-that the product remains secure and does not act maliciously.
+way, you can be confident that the product remains secure and does not act maliciously.
 It's important to keep in mind Authelia is not directly exposed on the
 Internet (your reverse proxies are) however, it's still the control plane for your internal security so take care of it!
@ -156,7 +165,8 @@ Internet (your reverse proxies are) however, it's still the control plane for yo
 If you want to contribute to Authelia, please read our [contribution guidelines](./CONTRIBUTING.md).
-Authelia exists thanks to all the people who contribute so don't be shy, come chat with us on [Matrix](#matrix) and start contributing too.
+Authelia exists thanks to all the people who contribute so don't be shy, come chat with us on either [Matrix](#matrix) 
 or [Discord](#discord) and start contributing too.
 Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):
@ -233,13 +243,14 @@ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/d
 <!-- ALL-CONTRIBUTORS-LIST:END -->
-This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!
+This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. 
 Contributions of any kind welcome!
 ### Backers
-Thank you to all our backers! 🙏 [[Become a backer](https://opencollective.com/authelia-sponsors/contribute)] and help us sustain our community.
+Thank you to all our backers! 🙏 [[Become a backer](https://opencollective.com/authelia-sponsors/contribute)] and help us 
-The money we currently receive is dedicated to bootstrap a bug bounty program to give us as many eyes as we can to detect potential vulnerabilities.
+sustain our community. The money we currently receive is dedicated to bootstrap a bug bounty program to give us as many
-<a href="https://opencollective.com/authelia-sponsors#backers"><img src="https://opencollective.com/authelia-sponsors/backers.svg?width=890"></a>
+eyes as we can to detect potential vulnerabilities. <a href="https://opencollective.com/authelia-sponsors#backers"><img src="https://opencollective.com/authelia-sponsors/backers.svg?width=890"></a>
 ### Sponsors
@ -258,7 +269,8 @@ Support Authelia by becoming a sponsor. Your logo will show up here with a link
 ### Jetbrains
-Thank you to [<img src="./docs/images/logos/jetbrains.svg" alt="JetBrains" width="32"> JetBrains](https://www.jetbrains.com/?from=Authelia) for providing us with free licenses to their great tools
+Thank you to [<img src="./docs/images/logos/jetbrains.svg" alt="JetBrains" width="32"> JetBrains](https://www.jetbrains.com/?from=Authelia)
 for providing us with free licenses to their great tools.
 * [<img src="./docs/images/logos/intellij-idea.svg" alt="IDEA" width="32"> IDEA](http://www.jetbrains.com/idea/)
 * [<img src="./docs/images/logos/goland.svg" alt="GoLand" width="32"> GoLand](http://www.jetbrains.com/go/)
@ -266,7 +278,7 @@ Thank you to [<img src="./docs/images/logos/jetbrains.svg" alt="JetBrains" width
 ## License
-**Authelia** is **licensed** under the **[Apache 2.0]** license. The terms of the license are detailed
+**Authelia** is **licensed** under the **[Apache 2.0]** license. The terms of the license are detailed 
 in [LICENSE](./LICENSE).
 [![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Fauthelia%2Fauthelia.svg?type=large)](https://app.fossa.com/projects/git%2Bgithub.com%2Fauthelia%2Fauthelia?ref=badge_large)
--- a/SECURITY.md
+++ b/SECURITY.md
@ -8,8 +8,8 @@ If you discover a vulnerability in Authelia, please first contact one of the mai
 either via [Matrix](#matrix) or [email](#email) as described in the [contact options](#contact-options) below.
 For details about security measures implemented in Authelia, please follow
-this [link](https://docs.authelia.com/security/measures.html) and for reading about 
+this [link](https://www.authelia.com/docs/security/measures.html) and for reading about 
-the threat model follow this [link](https://docs.authelia.com/security/threat-model.html).
+the threat model follow this [link](https://www.authelia.com/docs/security/threat-model.html).
 ## Contact Options
--- a/config.template.yml
+++ b/config.template.yml
@ -1,10 +1,14 @@
-###############################################################
+# yamllint disable rule:comments-indentation
-#                   Authelia configuration                    #
+---
-###############################################################
+###############################################################################
 #                           Authelia Configuration                            #
 ###############################################################################
-# The host and port to listen on
+## The host and port to listen on.
 host: 0.0.0.0
 port: 9091
 ## The TLS key and cert used with Authelia.
 # tls_key: /config/ssl/key.pem
 # tls_cert: /config/ssl/cert.pem
@ -13,245 +17,250 @@ port: 9091
 ## They should be in base64 format, and have one of the following extensions: *.cer, *.crt, *.pem.
 # certificates_directory: /config/certificates
-# The theme to display: light, dark, grey
+## The theme to display: light, dark, grey.
 theme: light
-# Configuration options specific to the internal http server
+##
 ## Server Configuration
 ##
 server:
-  # Buffers usually should be configured to be the same value.
+  ## Buffers usually should be configured to be the same value.
-  # Explanation at https://docs.authelia.com/configuration/server.html
+  ## Explanation at https://www.authelia.com/docs/configuration/server.html
-  # Read buffer size configures the http server's maximum incoming request size in bytes.
+  ## Read buffer size adjusts the server's max incoming request size in bytes.
  ## Write buffer size does the same for outgoing responses.
  read_buffer_size: 4096
  # Write buffer size configures the http server's maximum outgoing response size in bytes.
  write_buffer_size: 4096
-  # Set the single level path Authelia listens on, must be alphanumeric chars and should not contain any slashes.
+  ## Set the single level path Authelia listens on.
  ## Must be alphanumeric chars and should not contain any slashes.
  path: ""
-# Level of verbosity for logs: info, debug, trace
+## Level of verbosity for logs: info, debug, trace.
 log_level: debug
-# Format the logs are written as: json, text
+
 ## Format the logs are written as: json, text.
 # log_format: json
-# File path where the logs will be written. If not set logs are written to stdout.
+
 ## File path where the logs will be written. If not set logs are written to stdout.
 # log_file_path: /config/authelia.log
-# The secret used to generate JWT tokens when validating user identity by
+## The secret used to generate JWT tokens when validating user identity by email confirmation. JWT Secret can also be
-# email confirmation.
+## set using a secret: https://www.authelia.com/docs/configuration/secrets.html
 # JWT Secret can also be set using a secret: https://docs.authelia.com/configuration/secrets.html
 jwt_secret: a_very_important_secret
-# Default redirection URL
+## Default redirection URL
-#
+##
-# If user tries to authenticate without any referer, Authelia
+## If user tries to authenticate without any referer, Authelia does not know where to redirect the user to at the end
-# does not know where to redirect the user to at the end of the
+## of the authentication process. This parameter allows you to specify the default redirection URL Authelia will use
-# authentication process.
+## in such a case.
-# This parameter allows you to specify the default redirection
+##
-# URL Authelia will use in such a case.
+## Note: this parameter is optional. If not provided, user won't be redirected upon successful authentication.
 #
 # Note: this parameter is optional. If not provided, user won't
 # be redirected upon successful authentication.
 default_redirection_url: https://home.example.com:8080/
-# TOTP Settings
+##
-#
+## TOTP Configuration
-# Parameters used for TOTP generation
+##
 ## Parameters used for TOTP generation.
 totp:
-  # The issuer name displayed in the Authenticator application of your choice
+  ## The issuer name displayed in the Authenticator application of your choice
-  # See: https://github.com/google/google-authenticator/wiki/Key-Uri-Format for more info on issuer names
+  ## See: https://github.com/google/google-authenticator/wiki/Key-Uri-Format for more info on issuer names
  issuer: authelia.com
-  # The period in seconds a one-time password is current for. Changing this will require all users to register
+  ## The period in seconds a one-time password is current for. Changing this will require all users to register
-  # their TOTP applications again.
+  ## their TOTP applications again. Warning: before changing period read the docs link below.
  # Warning: before changing period read the docs link below.
  period: 30
-  # The skew controls number of one-time passwords either side of the current one that are valid.
+  ## The skew controls number of one-time passwords either side of the current one that are valid.
-  # Warning: before changing skew read the docs link below.
+  ## Warning: before changing skew read the docs link below.
  skew: 1
-  #  See: https://docs.authelia.com/configuration/one-time-password.html#period-and-skew to read the documentation.
+  ## See: https://www.authelia.com/docs/configuration/one-time-password.html#period-and-skew to read the documentation.
-# Duo Push API
+##
-#
+## Duo Push API Configuration
-# Parameters used to contact the Duo API. Those are generated when you protect an application
+##
-# of type "Partner Auth API" in the management panel.
+## 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.example.com
  integration_key: ABCDEF
-  # Secret can also be set using a secret: https://docs.authelia.com/configuration/secrets.html
+  ## Secret can also be set using a secret: https://www.authelia.com/docs/configuration/secrets.html
  secret_key: 1234567890abcdefghifjkl
-# The authentication backend to use for verifying user passwords
+##
-# and retrieve information such as email address and groups
+## Authentication Backend Provider Configuration
-# users belong to.
+##
-#
+## Used for verifying user passwords and retrieve information such as email address and groups users belong to.
-# There are two supported backends: 'ldap' and 'file'.
+##
 ## The available providers are: `file`, `ldap`. You must use only one of these providers.
 authentication_backend:
-  # Disable both the HTML element and the API for reset password functionality
+  ## Disable both the HTML element and the API for reset password functionality.
  disable_reset_password: false
-  # The amount of time to wait before we refresh data from the authentication backend. Uses duration notation.
+  ## The amount of time to wait before we refresh data from the authentication backend. Uses duration notation.
-  # To disable this feature set it to 'disable', this will slightly reduce security because for Authelia, users
+  ## To disable this feature set it to 'disable', this will slightly reduce security because for Authelia, users will
-  # will always belong to groups they belonged to at the time of login even if they have been removed from them in LDAP.
+  ## always belong to groups they belonged to at the time of login even if they have been removed from them in LDAP.
-  # To force update on every request you can set this to '0' or 'always', this will increase processor demand.
+  ## To force update on every request you can set this to '0' or 'always', this will increase processor demand.
-  # See the below documentation for more information.
+  ## See the below documentation for more information.
-  # Duration Notation docs:  https://docs.authelia.com/configuration/index.html#duration-notation-format
+  ## Duration Notation docs:  https://www.authelia.com/docs/configuration/index.html#duration-notation-format
-  # Refresh Interval docs: https://docs.authelia.com/configuration/authentication/ldap.html#refresh-interval
+  ## Refresh Interval docs: https://www.authelia.com/docs/configuration/authentication/ldap.html#refresh-interval
  refresh_interval: 5m
-  # LDAP backend configuration.
+  ##
-  #
+  ## LDAP (Authentication Provider)
-  # This backend allows Authelia to be scaled to more
+  ##
-  # than one instance and therefore is recommended for
+  ## This is the recommended Authentication Provider in production
-  # production.
+  ## because it allows Authelia to offload the stateful operations
  ## onto the LDAP service.
  ldap:
-    # The LDAP implementation, this affects elements like the attribute utilised for resetting a password.
+    ## The LDAP implementation, this affects elements like the attribute utilised for resetting a password.
-    # Acceptable options are as follows:
+    ## Acceptable options are as follows:
-    # - 'activedirectory' - For Microsoft Active Directory.
+    ## - 'activedirectory' - For Microsoft Active Directory.
-    # - 'custom' - For custom specifications of attributes and filters.
+    ## - 'custom' - For custom specifications of attributes and filters.
-    # This currently defaults to 'custom' to maintain existing behaviour.
+    ## This currently defaults to 'custom' to maintain existing behaviour.
-    #
+    ##
-    # Depending on the option here certain other values in this section have a default value, notably all
+    ## Depending on the option here certain other values in this section have a default value, notably all of the
-    # of the attribute mappings have a default value that this config overrides, you can read more
+    ## attribute mappings have a default value that this config overrides, you can read more about these default values
-    # about these default values at https://docs.authelia.com/configuration/authentication/ldap.html#defaults
+    ## at https://www.authelia.com/docs/configuration/authentication/ldap.html#defaults
    implementation: custom
-    # The url to the ldap server. Scheme can be ldap or ldaps in the format (port optional) <scheme>://<address>[:<port>].
+    ## The url to the ldap server. Format: <scheme>://<address>[:<port>].
    ## Scheme can be ldap or ldaps in the format (port optional).
    url: ldap://127.0.0.1
-    # Use StartTLS with the LDAP connection.
+    ## Use StartTLS with the LDAP connection.
    start_tls: false
    tls:
-      # Server Name for certificate validation (in case it's not set correctly in the URL).
+      ## Server Name for certificate validation (in case it's not set correctly in the URL).
      # server_name: ldap.example.com
-      # Skip verifying the server certificate (to allow a self-signed certificate).
+      ## Skip verifying the server certificate (to allow a self-signed certificate).
      ## In preference to setting this we strongly recommend you add the public portion of the certificate to the
      ## certificates directory which is defined by the `certificates_directory` option at the top of the config.
      skip_verify: false
-      # Minimum TLS version for either Secure LDAP or LDAP StartTLS.
+      ## Minimum TLS version for either Secure LDAP or LDAP StartTLS.
      minimum_version: TLS1.2
-    # The base dn for every entries.
+    ## The distinguished name of the container searched for objects in the directory information tree.
    ## See also: additional_users_dn, additional_groups_dn.
    base_dn: dc=example,dc=com
-    # The attribute holding the username of the user. This attribute is used to populate
+    ## The attribute holding the username of the user. This attribute is used to populate the username in the session
-    # the username in the session information. It was introduced due to #561 to handle case
+    ## information. It was introduced due to #561 to handle case insensitive search queries. For you information,
-    # insensitive search queries.
+    ## Microsoft Active Directory usually uses 'sAMAccountName' and OpenLDAP usually uses 'uid'. Beware that this
-    # For you information, Microsoft Active Directory usually uses 'sAMAccountName' and OpenLDAP
+    ## attribute holds the unique identifiers for the users binding the user and the configuration stored in database.
-    # usually uses 'uid'
+    ## Therefore only single value attributes are allowed and the value must never be changed once attributed to a user
-    # Beware that this attribute holds the unique identifiers for the users binding the user and the configuration
+    ## otherwise it would break the configuration for that user. Technically, non-unique attributes like 'mail' can also
-    # stored in database. Therefore only single value attributes are allowed and the value
+    ## be used but we don't recommend using them, we instead advise to use the attributes mentioned above
-    # must never be changed once attributed to a user otherwise it would break the configuration
+    ## (sAMAccountName and uid) to follow https://www.ietf.org/rfc/rfc2307.txt.
    # for that user. Technically, non-unique attributes like 'mail' can also be used but we don't recommend using
    # them, we instead advise to use the attributes mentioned above (sAMAccountName and uid) to follow
    # https://www.ietf.org/rfc/rfc2307.txt.
    # username_attribute: uid
-    # An additional dn to define the scope to all users.
+    ## The additional_users_dn is prefixed to base_dn and delimited by a comma when searching for users.
    ## i.e. with this set to OU=Users and base_dn set to DC=a,DC=com; OU=Users,DC=a,DC=com is searched for users.
    additional_users_dn: ou=users
-    # The users filter used in search queries to find the user profile based on input filled in login form.
+    ## The users filter used in search queries to find the user profile based on input filled in login form.
-    # Various placeholders are available to represent the user input and back reference other options of the configuration:
+    ## Various placeholders are available in the user filter:
-    # - {input} is a placeholder replaced by what the user inputs in the login form.
+    ## - {input} is a placeholder replaced by what the user inputs in the login form.
-    # - {username_attribute} is a mandatory placeholder replaced by what is configured in `username_attribute`.
+    ## - {username_attribute} is a mandatory placeholder replaced by what is configured in `username_attribute`.
-    # - {mail_attribute} is a placeholder replaced by what is configured in `mail_attribute`.
+    ## - {mail_attribute} is a placeholder replaced by what is configured in `mail_attribute`.
-    # - DON'T USE - {0} is an alias for {input} supported for backward compatibility but it will be deprecated in later versions, so please don't use it.
+    ## - DON'T USE - {0} is an alias for {input} supported for backward compatibility but it will be deprecated in later
-    #
+    ##   versions, so please don't use it.
-    # Recommended settings are as follows:
+    ##
-    # - Microsoft Active Directory: (&({username_attribute}={input})(objectCategory=person)(objectClass=user))
+    ## Recommended settings are as follows:
-    # - OpenLDAP: (&({username_attribute}={input})(objectClass=person))' or '(&({username_attribute}={input})(objectClass=inetOrgPerson))
+    ## - Microsoft Active Directory: (&({username_attribute}={input})(objectCategory=person)(objectClass=user))
-    #
+    ## - OpenLDAP:
-    # To allow sign in both with username and email, one can use a filter like
+    ##   - (&({username_attribute}={input})(objectClass=person))
-    # (&(|({username_attribute}={input})({mail_attribute}={input}))(objectClass=person))
+    ##   - (&({username_attribute}={input})(objectClass=inetOrgPerson))
    ##
    ## To allow sign in both with username and email, one can use a filter like
    ## (&(|({username_attribute}={input})({mail_attribute}={input}))(objectClass=person))
    users_filter: (&({username_attribute}={input})(objectClass=person))
-    # An additional dn to define the scope of groups.
+    ## The additional_groups_dn is prefixed to base_dn and delimited by a comma when searching for groups.
    ## i.e. with this set to OU=Groups and base_dn set to DC=a,DC=com; OU=Groups,DC=a,DC=com is searched for groups.
    additional_groups_dn: ou=groups
-    # The groups filter used in search queries to find the groups of the user.
+    ## The groups filter used in search queries to find the groups of the user.
-    # - {input} is a placeholder replaced by what the user inputs in the login form.
+    ## - {input} is a placeholder replaced by what the user inputs in the login form.
-    # - {username} is a placeholder replace by the username stored in LDAP (based on `username_attribute`).
+    ## - {username} is a placeholder replace by the username stored in LDAP (based on `username_attribute`).
-    # - {dn} is a matcher replaced by the user distinguished name, aka, user DN.
+    ## - {dn} is a matcher replaced by the user distinguished name, aka, user DN.
-    # - {username_attribute} is a placeholder replaced by what is configured in `username_attribute`.
+    ## - {username_attribute} is a placeholder replaced by what is configured in `username_attribute`.
-    # - {mail_attribute} is a placeholder replaced by what is configured in `mail_attribute`.
+    ## - {mail_attribute} is a placeholder replaced by what is configured in `mail_attribute`.
-    # - DON'T USE - {0} is an alias for {input} supported for backward compatibility but it will be deprecated in later versions, so please don't use it.
+    ## - DON'T USE - {0} is an alias for {input} supported for backward compatibility but it will be deprecated in later
-    # - DON'T USE - {1} is an alias for {username} supported for backward compatibility but it will be deprecated in later version, so please don't use it.
+    ##   versions, so please don't use it.
-    # If your groups use the `groupOfUniqueNames` structure use this instead: (&(uniquemember={dn})(objectclass=groupOfUniqueNames))
+    ## - DON'T USE - {1} is an alias for {username} supported for backward compatibility but it will be deprecated in
    ##   later version, so please don't use it.
    ##
    ## If your groups use the `groupOfUniqueNames` structure use this instead:
    ##    (&(uniquemember={dn})(objectclass=groupOfUniqueNames))
    groups_filter: (&(member={dn})(objectclass=groupOfNames))
-    # The attribute holding the name of the group
+    ## The attribute holding the name of the group.
    # group_name_attribute: cn
-    # The attribute holding the mail address of the user. If multiple email addresses are defined for a user, only the first
+    ## The attribute holding the mail address of the user. If multiple email addresses are defined for a user, only the
-    # one returned by the LDAP server is used.
+    ## first one returned by the LDAP server is used.
    # mail_attribute: mail
-    # The attribute holding the display name of the user. This will be used to greet an authenticated user.
+    ## The attribute holding the display name of the user. This will be used to greet an authenticated user.
    # display_name_attribute: displayname
-    # The username and password of the admin user.
+    ## The username and password of the admin user.
    user: cn=admin,dc=example,dc=com
-    # Password can also be set using a secret: https://docs.authelia.com/configuration/secrets.html
+    ## Password can also be set using a secret: https://www.authelia.com/docs/configuration/secrets.html
    password: password
-  # File backend configuration.
+  ##
-  #
+  ## File (Authentication Provider)
-  # With this backend, the users database is stored in a file
+  ##
-  # which is updated when users reset their passwords.
+  ## With this backend, the users database is stored in a file which is updated when users reset their passwords.
-  # Therefore, this backend is meant to be used in a dev environment
+  ## Therefore, this backend is meant to be used in a dev environment and not in production since it prevents Authelia
-  # and not in production since it prevents Authelia to be scaled to
+  ## to be scaled to more than one instance. The options under 'password' have sane defaults, and as it has security
-  # more than one instance. The options under 'password' have sane
+  ## implications it is highly recommended you leave the default values. Before considering changing these settings
-  # defaults, and as it has security implications it is highly recommended
+  ## please read the docs page below:
-  # you leave the default values. Before considering changing these settings
+  ## https://www.authelia.com/docs/configuration/authentication/file.html#password-hash-algorithm-tuning
-  # please read the docs page below:
+  ##
-  # https://docs.authelia.com/configuration/authentication/file.html#password-hash-algorithm-tuning
+  ## Important: Kubernetes (or HA) users must read https://www.authelia.com/docs/features/statelessness.html
-  #
+  ##
-  ## file:
+  # file:
-  ##   path: /config/users_database.yml
+  #   path: /config/users_database.yml
-  ##   password:
+  #   password:
-  ##     algorithm: argon2id
+  #     algorithm: argon2id
-  ##     iterations: 1
+  #     iterations: 1
-  ##     key_length: 32
+  #     key_length: 32
-  ##     salt_length: 16
+  #     salt_length: 16
-  ##     memory: 1024
+  #     memory: 1024
-  ##     parallelism: 8
+  #     parallelism: 8
-# Access Control
+
-#
+##
-# Access control is a list of rules defining the authorizations applied for one
+## Access Control Configuration
-# resource to users or group of users.
+##
-#
+## Access control is a list of rules defining the authorizations applied for one resource to users or group of users.
-# If 'access_control' is not defined, ACL rules are disabled and the 'bypass'
+##
-# rule is applied, i.e., access is allowed to anyone. Otherwise restrictions follow
+## If 'access_control' is not defined, ACL rules are disabled and the 'bypass' rule is applied, i.e., access is allowed
-# the rules defined.
+## to anyone. Otherwise restrictions follow the rules defined.
-#
+##
-# Note: One can use the wildcard * to match any subdomain.
+## Note: One can use the wildcard * to match any subdomain.
-# It must stand at the beginning of the pattern. (example: *.mydomain.com)
+## It must stand at the beginning of the pattern. (example: *.mydomain.com)
-#
+##
-# Note: You must put patterns containing wildcards between simple quotes for the YAML
+## Note: You must put patterns containing wildcards between simple quotes for the YAML to be syntactically correct.
-# to be syntactically correct.
+##
-#
+## Definition: A 'rule' is an object with the following keys: 'domain', 'subject', 'policy' and 'resources'.
-# Definition: A 'rule' is an object with the following keys: 'domain', 'subject',
+##
-# 'policy' and 'resources'.
+## - 'domain' defines which domain or set of domains the rule applies to.
-#
+##
-# - 'domain' defines which domain or set of domains the rule applies to.
+## - 'subject' defines the subject to apply authorizations to. This parameter is optional and matching any user if not
-#
+##    provided. If provided, the parameter represents either a user or a group. It should be of the form
-# - 'subject' defines the subject to apply authorizations to. This parameter is
+##    'user:<username>' or 'group:<groupname>'.
-#    optional and matching any user if not provided. If provided, the parameter
+##
-#    represents either a user or a group. It should be of the form 'user:<username>'
+## - 'policy' is the policy to apply to resources. It must be either 'bypass', 'one_factor', 'two_factor' or 'deny'.
-#    or 'group:<groupname>'.
+##
-#
+## - 'resources' is a list of regular expressions that matches a set of resources to apply the policy to. This parameter
-# - 'policy' is the policy to apply to resources. It must be either 'bypass',
+##   is optional and matches any resource if not provided.
-#   'one_factor', 'two_factor' or 'deny'.
+##
-#
+## Note: the order of the rules is important. The first policy matching (domain, resource, subject) applies.
 # - 'resources' is a list of regular expressions that matches a set of resources to
 #    apply the policy to. This parameter is optional and matches any resource if not
 #    provided.
 #
 # Note: the order of the rules is important. The first policy matching
 # (domain, resource, subject) applies.
 access_control:
-  # Default policy can either be 'bypass', 'one_factor', 'two_factor' or 'deny'.
+  ## Default policy can either be 'bypass', 'one_factor', 'two_factor' or 'deny'. It is the policy applied to any
-  # It is the policy applied to any resource if there is no policy to be applied
+  ## resource if there is no policy to be applied to the user.
  # to the user.
  default_policy: deny
  networks:
@ -263,13 +272,13 @@ access_control:
      networks: 10.9.0.0/16
  rules:
-    # Rules applied to everyone
+    ## Rules applied to everyone
    - domain: public.example.com
      policy: bypass
    - domain: secure.example.com
      policy: one_factor
-      # Network based rule, if not provided any network matches.
+      ## Network based rule, if not provided any network matches.
      networks:
        - internal
        - VPN
@ -284,7 +293,7 @@ access_control:
    - domain: singlefactor.example.com
      policy: one_factor
-    # Rules applied to 'admins' group
+    ## Rules applied to 'admins' group
    - domain: "mx2.mail.example.com"
      subject: "group:admins"
      policy: deny
@ -295,28 +304,28 @@ access_control:
        - "group:moderators"
      policy: two_factor
-    # Rules applied to 'dev' group
+    ## Rules applied to 'dev' group
    - domain: dev.example.com
      resources:
        - "^/groups/dev/.*$"
      subject: "group:dev"
      policy: two_factor
-    # Rules applied to user 'john'
+    ## Rules applied to user 'john'
    - domain: dev.example.com
      resources:
        - "^/users/john/.*$"
      subject: "user:john"
      policy: two_factor
-    # Rules applied to user 'harry'
+    ## Rules applied to user 'harry'
    - domain: dev.example.com
      resources:
        - "^/users/harry/.*$"
      subject: "user:harry"
      policy: two_factor
-    # Rules applied to user 'bob'
+    ## Rules applied to user 'bob'
    - domain: "*.mail.example.com"
      subject: "user:bob"
      policy: two_factor
@ -326,46 +335,56 @@ access_control:
      subject: "user:bob"
      policy: two_factor
-# Configuration of session cookies
+##
-#
+## Session Provider Configuration
-# The session cookies identify the user once logged in.
+##
 ## The session cookies identify the user once logged in.
 ## The available providers are: `memory`, `redis`. Memory is the provider unless redis is defined.
 session:
-  # The name of the session cookie. (default: authelia_session).
+  ## The name of the session cookie.
  name: authelia_session
-  # The secret to encrypt the session data. This is only used with Redis / Redis Sentinel.
+  ## The secret to encrypt the session data. This is only used with Redis / Redis Sentinel.
-  # Secret can also be set using a secret: https://docs.authelia.com/configuration/secrets.html
+  ## Secret can also be set using a secret: https://www.authelia.com/docs/configuration/secrets.html
  secret: insecure_session_secret
-  # The time in seconds before the cookie expires and session is reset.
+  ## The value for expiration, inactivity, and remember_me_duration are in seconds or the duration notation format.
  ## See: https://www.authelia.com/docs/configuration/index.html#duration-notation-format
  ## All three of these values affect the cookie/session validity period. Longer periods are considered less secure
  ## because a stolen cookie will last longer giving attackers more time to spy or attack.
  ## The time before the cookie expires and the session is destroyed if remember me IS NOT selected.
  expiration: 1h
-  # The inactivity time in seconds before the session is reset.
+  ## The inactivity time before the session is reset. If expiration is set to 1h, and this is set to 5m, if the user
  ## does not select the remember me option their session will get destroyed after 1h, or after 5m since the last time
  ## Authelia detected user activity.
  inactivity: 5m
-  # The remember me duration.
+  ## The time before the cookie expires and the session is destroyed if remember me IS selected.
-  # Value of 0 disables remember me.
+  ## Value of 0 disables remember me.
  # Value is in seconds, or duration notation. See: https://docs.authelia.com/configuration/index.html#duration-notation-format
  # Longer periods are considered less secure because a stolen cookie will last longer giving attackers more time to spy
  # or attack. Currently the default is 1M or 1 month.
  remember_me_duration: 1M
-  # The domain to protect.
+  ## The domain to protect.
-  # Note: the authenticator must also be in that domain. If empty, the cookie
+  ## Note: the authenticator must also be in that domain.
-  # is restricted to the subdomain of the issuer.
+  ## If empty, the cookie is restricted to the subdomain of the issuer.
  domain: example.com
-  ## The redis connection details
+  ##
  ## Redis Provider
  ##
  ## Important: Kubernetes (or HA) users must read https://www.authelia.com/docs/features/statelessness.html
  ##
  redis:
    host: 127.0.0.1
    port: 6379
    ## Use a unix socket instead
    # host: /var/run/redis/redis.sock
-    ## Optional username to be used with authentication.
+    ## Username used for redis authentication. This is optional and a new feature in redis 6.0.
-    username: authelia
+    # username: authelia
-    ## Password can also be set using a secret: https://docs.authelia.com/configuration/secrets.html
+    ## Password can also be set using a secret: https://www.authelia.com/docs/configuration/secrets.html
    password: authelia
    ## This is the Redis DB Index https://redis.io/commands/select (sometimes referred to as database number, DB, etc).
@ -393,7 +412,7 @@ session:
    ## The Redis HA configuration options.
    ## This provides specific options to Redis Sentinel, sentinel_name must be defined (Master Name).
    # high_availability:
-      ## Sentinel Name / Master Name
+      ## Sentinel Name / Master Name.
      # sentinel_name: mysentinel
      ## Specific password for Redis Sentinel. The node username and password is configured above.
@ -414,89 +433,109 @@ session:
      ## Choose the host randomly.
      # route_randomly: false
-# Configuration of the authentication regulation mechanism.
+##
-#
+## Regulation Configuration
-# This mechanism prevents attackers from brute forcing the first factor.
+##
-# It bans the user if too many attempts are done in a short period of
+## This mechanism prevents attackers from brute forcing the first factor. It bans the user if too many attempts are made
-# time.
+## in a short period of time.
 regulation:
-  # The number of failed login attempts before user is banned.
+  ## The number of failed login attempts before user is banned. Set it to 0 to disable regulation.
  # Set it to 0 to disable regulation.
  max_retries: 3
-  # The time range during which the user can attempt login before being banned.
+  ## The time range during which the user can attempt login before being banned. The user is banned if the
-  # The user is banned if the authentication failed 'max_retries' times in a 'find_time' seconds window.
+  ## authentication failed 'max_retries' times in a 'find_time' seconds window. Find Time accepts duration notation.
-  # Find Time accepts duration notation. See: https://docs.authelia.com/configuration/index.html#duration-notation-format
+  ## See: https://www.authelia.com/docs/configuration/index.html#duration-notation-format
  find_time: 2m
-  # The length of time before a banned user can login again.
+  ## The length of time before a banned user can login again. Ban Time accepts duration notation.
-  # Ban Time accepts duration notation. See: https://docs.authelia.com/configuration/index.html#duration-notation-format
+  ## See: https://www.authelia.com/docs/configuration/index.html#duration-notation-format
  ban_time: 5m
-# Configuration of the storage backend used to store data and secrets.
+##
-#
+## Storage Provider Configuration
-# You must use only an available configuration: local, mysql, postgres
+##
 ## The available providers are: `local`, `mysql`, `postgres`. You must use one and only one of these providers.
 storage:
-  # The directory where the DB files will be saved
+  ##
-  ## local:
+  ## Local (Storage Provider)
-  ##   path: /config/db.sqlite3
+  ##
  ## This stores the data in a SQLite3 Database.
  ## This is only recommended for lightweight non-stateful installations.
  ##
  ## Important: Kubernetes (or HA) users must read https://www.authelia.com/docs/features/statelessness.html
  ##
  # local:
  #   path: /config/db.sqlite3
-  # Settings to connect to MySQL server
+  ##
  ## MySQL / MariaDB (Storage Provider)
  ##
  mysql:
    host: 127.0.0.1
    port: 3306
    database: authelia
    username: authelia
-    # Password can also be set using a secret: https://docs.authelia.com/configuration/secrets.html
+    ## Password can also be set using a secret: https://www.authelia.com/docs/configuration/secrets.html
    password: mypassword
-  # Settings to connect to PostgreSQL server
+  ##
  ## PostgreSQL (Storage Provider)
  ##
  # postgres:
  #   host: 127.0.0.1
  #   port: 5432
  #   database: authelia
  #   username: authelia
-  #   # Password can also be set using a secret: https://docs.authelia.com/configuration/secrets.html
+  #   ## Password can also be set using a secret: https://www.authelia.com/docs/configuration/secrets.html
  #   password: mypassword
  #   sslmode: disable
-# Configuration of the notification system.
+##
-#
+## Notification Provider
-# Notifications are sent to users when they require a password reset, a u2f
+##
-# registration or a TOTP registration.
+## Notifications are sent to users when they require a password reset, a U2F registration or a TOTP registration.
-# Use only an available configuration: filesystem, smtp.
+## The available providers are: filesystem, smtp. You must use only one of these providers.
 notifier:
-  # You can disable the notifier startup check by setting this to true.
+  ## You can disable the notifier startup check by setting this to true.
  disable_startup_check: false
-  # For testing purpose, notifications can be sent in a file
+  ##
-  ## filesystem:
+  ## File System (Notification Provider)
-  ##   filename: /config/notification.txt
+  ##
  ## Important: Kubernetes (or HA) users must read https://www.authelia.com/docs/features/statelessness.html
  ##
  # filesystem:
  #   filename: /config/notification.txt
-  # Use a SMTP server for sending notifications. Authelia uses PLAIN or LOGIN method to authenticate.
+  ##
-  # [Security] By default Authelia will:
+  ## SMTP (Notification Provider)
-  #   - 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)
+  ## Use a SMTP server for sending notifications. Authelia uses the PLAIN or LOGIN methods to authenticate.
-  #   - validate the SMTP server x509 certificate during the TLS handshake against the hosts trusted certificates (configure in tls section)
+  ## [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
  ##     (configure in tls section)
  smtp:
    username: test
-    # Password can also be set using a secret: https://docs.authelia.com/configuration/secrets.html
+    ## Password can also be set using a secret: https://www.authelia.com/docs/configuration/secrets.html
    password: password
    host: 127.0.0.1
    port: 1025
    sender: admin@example.com
-    # HELO/EHLO Identifier. Some SMTP Servers may reject the default of localhost.
+    ## HELO/EHLO Identifier. Some SMTP Servers may reject the default of localhost.
    identifier: localhost
-    # Subject configuration of the emails sent.
+    ## Subject configuration of the emails sent. {title} is replaced by the text from the notifier.
    # {title} is replaced by the text from the notifier
    subject: "[Authelia] {title}"
-    # This address is used during the startup check to verify the email configuration is correct. It's not important what it is except if your email server only allows local delivery.
+    ## This address is used during the startup check to verify the email configuration is correct.
    ## It's not important what it is except if your email server only allows local delivery.
    startup_check_address: test@authelia.com
    disable_require_tls: false
    disable_html_emails: false
    tls:
-      # Server Name for certificate validation (in case you are using the IP or non-FQDN in the host option).
+      ## Server Name for certificate validation (in case you are using the IP or non-FQDN in the host option).
      # server_name: smtp.example.com
      ## Skip verifying the server certificate (to allow a self-signed certificate).
@ -504,15 +543,16 @@ notifier:
      ## certificates directory which is defined by the `certificates_directory` option at the top of the config.
      skip_verify: false
-      # Minimum TLS version for either StartTLS or SMTPS.
+      ## Minimum TLS version for either StartTLS or SMTPS.
      minimum_version: TLS1.2
-  # Sending an email using a Gmail account is as simple as the next section.
+  ## Sending an email using a Gmail account is as simple as the next section.
-  # You need to create an app password by following: https://support.google.com/accounts/answer/185833?hl=en
+  ## You need to create an app password by following: https://support.google.com/accounts/answer/185833?hl=en
-  ## smtp:
+  # smtp:
-  ##   username: myaccount@gmail.com
+  #   username: myaccount@gmail.com
-  ##   # Password can also be set using a secret: https://docs.authelia.com/configuration/secrets.html
+  #   ## Password can also be set using a secret: https://www.authelia.com/docs/configuration/secrets.html
-  ##   password: yourapppassword
+  #   password: yourapppassword
-  ##   sender: admin@example.com
+  #   sender: admin@example.com
-  ##   host: smtp.gmail.com
+  #   host: smtp.gmail.com
-  ##   port: 587
+  #   port: 587
 ...
--- a/docs/_config.yml
+++ b/docs/_config.yml
@ -1,6 +1,6 @@
 ---
 title: Authelia
-email: clement.michaud34@gmail.com
+email: team@authelia.com
 description: Authelia is an open source multi-factor single sign-on portal for web applications
 # We need this base URL to serve the docs under https://www.authelia.com/docs/
 baseurl: "/docs/"
--- a/docs/_sass/custom/custom.scss
+++ b/docs/_sass/custom/custom.scss
@ -0,0 +1,3 @@
 .label.label-config {
    text-transform: none;
 }
--- a/docs/community/using-remote-user-header-for-sso-with-jira.md
+++ b/docs/community/using-remote-user-header-for-sso-with-jira.md
@ -17,12 +17,14 @@ backend.
 I'm using traefik with docker as an example, but any proxy that can forward
 authelia `Remote-User` header is fine.
-First of all, users should exist on both authelia and Jira AND have the same
+First of all, users should exist on both Authelia and Jira, and have the same
-username for this to work. Also you will have to [pay for a plugin](https://marketplace.atlassian.com/apps/1212581/easy-sso-jira-kerberos-ntlm-saml?hosting=server&tab=overview).
+username for this to work. Also you will have to
 [pay for a plugin](https://marketplace.atlassian.com/apps/1212581/easy-sso-jira-kerberos-ntlm-saml?hosting=server&tab=overview).
 After both steps are done:
  - Add `traefik.http.middlewares.authelia.forwardauth.authResponseHeaders=Remote-User` in the labels of authelia
-  - Add `traefik.http.routers.jira.middlewares=authelia@docker` in the labels of Jira (to actually enable authelia for the jira instance)
+  - Add `traefik.http.routers.jira.middlewares=authelia@docker` in the labels of Jira (to actually enable Authelia for 
    the Jira instance)
  - Install EasySSO in Jira
  - Go to EasySSO preferences and add the "Remote-User" header under HTTP and tick the "Username" checkbox.
  - Save
--- a/docs/configuration/authentication/file.md
+++ b/docs/configuration/authentication/file.md
@ -10,6 +10,7 @@ nav_order: 1
 **Authelia** supports a file as a users database.
 ## Configuration
 Configuring Authelia to use a file is done by specifying the path to the
@ -17,21 +18,7 @@ file in the configuration file.
 ```yaml
 authentication_backend:
  # Disable both the HTML element and the API for reset password functionality
  disable_reset_password: false
  # File backend configuration.
  #
  # With this backend, the users database is stored in a file
  # which is updated when users reset their passwords.
  # Therefore, this backend is meant to be used in a dev environment
  # and not in production since it prevents Authelia to be scaled to
  # more than one instance. The options under 'password' have sane
  # defaults, and as it has security implications it is highly recommended
  # you leave the default values. Before considering changing these settings
  # please read the docs page below:
  # https://docs.authelia.com/configuration/authentication/file.html#password-hash-algorithm-tuning
  file:
    path: /config/users.yml
    password:
@ -43,7 +30,6 @@ authentication_backend:
 ```
 ## Format
 The format of the users file is as follows.
@ -74,20 +60,96 @@ users:
    email: james.dean@authelia.com
 ```
 This file should be set with read/write permissions as it could be updated by users
 resetting their passwords.
 ## Options
 ### path
 <div markdown="1">
 type: string (path)
 {: .label .label-config .label-purple } 
 required: yes
 {: .label .label-config .label-red }
 </div>
 ### password
 #### algorithm
 <div markdown="1">
 type: string
 {: .label .label-config .label-purple } 
 default: argon2id
 {: .label .label-config .label-blue }
 required: no
 {: .label .label-config .label-green }
 </div>
 Controls the hashing algorithm used for hashing new passwords. Value must be one of `argon2id` or `sha512.
 #### iterations
 <div markdown="1">
 type: integer
 {: .label .label-config .label-purple }
 required: no
 {: .label .label-config .label-green }
 </div>
 Controls the number of hashing iterations done by the other hashing settings.
 When using `argon2id` the minimum is 1, which is also the recommended value.
 When using `sha512` the minimum is 1000, and 50000 is the recommended value.
 #### salt_length
 <div markdown="1">
 type: integer
 {: .label .label-config .label-purple } 
 default: 16
 {: .label .label-config .label-blue }
 required: no
 {: .label .label-config .label-green }
 </div>
 Controls the length of the random salt added to each password before hashing. It's recommended this value is set to 16,
 and there is no documented reason why you'd set it to anything other than this, however the minimum is 8.
 #### parallelism
 <div markdown="1">
 type: integer
 {: .label .label-config .label-purple } 
 default: 8
 {: .label .label-config .label-blue }
 required: no
 {: .label .label-config .label-green }
 </div>
 This setting is specific to `argon2id` and unused with `sha512`. Sets the number of threads used when hashing passwords,
 which affects the effective cost of hashing.
 #### memory
 This setting is specific to `argon2id` and unused with `sha512`. Sets the amount of memory allocated to a single
 password hashing action. This memory is released by go after the hashing process completes, however the operating system
 may not reclaim it until it needs the memory which may make Authelia appear to be using more memory than it technically
 is.
 ## Passwords
 The file contains hashed passwords instead of plain text passwords for security reasons.
-You can use Authelia binary or docker image to generate the hash of any password. The 
+You can use Authelia binary or docker image to generate the hash of any password. The
-hash-password command has many tunable options, you can view them with the 
+hash-password command has many tunable options, you can view them with the
 `authelia hash-password --help` command. For example if you wanted to improve the entropy
-you could generate a 16 byte salt and provide it with the `--salt` flag. 
+you could generate a 16 byte salt and provide it with the `--salt` flag.
-Example: `authelia hash-password --salt abcdefghijklhijl`. For argon2id the salt must 
+Example: `authelia hash-password --salt abcdefghijklhijl`. For argon2id the salt must
 always be valid for base64 decoding (characters a through z, A through Z, 0 through 9, and +/).
 Passwords passed to `hash-password` should be single quoted if using special characters to prevent parameter substitution.
@ -115,21 +177,20 @@ Flags:
  -z, --sha512            use sha512 as the algorithm (defaults iterations to 50000, change with -i)
 ```
 ### Password hash algorithm
-## Password hash algorithm
+The default hash algorithm is Argon2id version 19 with a salt. Argon2id is currently considered
-
+the best hashing algorithm, and in 2015 won the
 The default hash algorithm is Argon2id version 19 with a salt. Argon2id is currently considered 
 the best hashing algorithm, and in 2015 won the 
 [Password Hashing Competition](https://en.wikipedia.org/wiki/Password_Hashing_Competition).
-It benefits from customizable parameters allowing the cost of computing a hash to scale 
+It benefits from customizable parameters allowing the cost of computing a hash to scale
-into the future which makes it harder to brute-force. Argon2id was implemented due to community 
+into the future which makes it harder to brute-force. Argon2id was implemented due to community
 feedback as you can see in this closed [issue](https://github.com/authelia/authelia/issues/577).
-For backwards compatibility and user choice support for the SHA512 algorithm is still available. 
+For backwards compatibility and user choice support for the SHA512 algorithm is still available.
-While it's a reasonable hashing function given high enough iterations, as hardware improves it 
+While it's a reasonable hashing function given high enough iterations, as hardware improves it
 has a higher chance of being brute-forced.
-Hashes are identifiable as argon2id or SHA512 by their prefix of either `$argon2id$` and `$6$` 
+Hashes are identifiable as argon2id or SHA512 by their prefix of either `$argon2id$` and `$6$`
 respectively,  as described in this [wiki page](https://en.wikipedia.org/wiki/Crypt_(C)).
 **Important Note:** When using argon2id Authelia will appear to remain using the memory allocated
@ -137,77 +198,32 @@ to creating the hash. This is due to how [Go](https://golang.org/) allocates mem
 generating an argon2id hash. Go periodically garbage collects the heap, however this doesn't remove
 the memory allocation, it keeps it allocated even though it's technically unused. Under memory
 pressure the unused allocated memory will be reclaimed by the operating system, you can test
-this on linux with: 
+this on linux with:
    $ stress-ng --vm-bytes $(awk '/MemFree/{printf "%d\n", $2 * 0.9;}' < /proc/meminfo)k --vm-keep -m 1
-    
+
 If this is not desirable we recommend investigating the following options in order of most to least secure:
-  1. using the [LDAP authentication provider](./ldap.md)
+1. using the [LDAP authentication provider](./ldap.md)
-  2. adjusting the [memory](#memory) parameter
+2. adjusting the [memory](#memory) parameter
-  3. changing the [algorithm](#algorithm)
+3. changing the [algorithm](#algorithm)
 ### Password hash algorithm tuning
- 
+
-All algorithm tuning for Argon2id is supported. The only configuration variables that affect 
+All algorithm tuning for Argon2id is supported. The only configuration variables that affect
 SHA512 are iterations and salt length. The configuration variables are unique to the file
 authentication provider, thus they all exist in a key under the file authentication configuration
 key called `password`. We have set what are considered as sane and recommended defaults
-to cater for a reasonable system, if you're unsure about which settings to tune, please see the 
+to cater for a reasonable system, if you're unsure about which settings to tune, please see the
 parameters below, or for a more in depth understanding see the referenced documentation in
 [Argon2 links](./file.md#argon2-links).
 ### Password hashing configuration settings
 #### algorithm
 - Value Type: String
 - Possible Value: `argon2id` or `sha512`
 - Recommended: `argon2id`
 - What it Does: Changes the hashing algorithm
 #### iterations
   - Value Type: Int
   - Possible Value: `1` or higher for argon2id and `1000` or higher for sha512 
   (will automatically be set to `1000` on lower settings)
   - Recommended: `1` for the `argon2id` algorithm and `50000` for `sha512`
   - What it Does: Adjusts the number of times we run the password through the hashing algorithm
 #### key_length
 - Value Type: Int
 - Possible Value: `16` or higher.
 - Recommended: `32` or higher.
 - What it Does: Adjusts the length of the actual hash
 #### salt_length
  - Value Type: Int
  - Possible Value: `8` or higher.
  - Recommended: `16`
  - What it Does: Adjusts the length of the random salt we add to the password, there
   is no reason not to set this to 16
 #### parallelism
 - Value Type: Int
 - Possible Value: `1` or higher
 - Recommended: `8` or twice your CPU cores
 - What it Does: Sets the number of threads used for hashing
 #### memory
 - Value Type: Int
 - Possible Value: at least `8` times the value of `parallelism`
 - Recommended: `64` (64MB) or as much RAM as you can afford to give to hashing
 - What it Does: Sets the amount of RAM used in MB for hashing
 #### Examples for specific systems
-These examples have been tested against a single system to make sure they roughly take 
+These examples have been tested against a single system to make sure they roughly take
 0.5 seconds each. Your results may vary depending on individual specification and
-utilization, but they are a good guide to get started. You should however read the 
+utilization, but they are a good guide to get started. You should however read the
 linked documents in [Argon2 links](./file.md#argon2-links).
 |    System     |Iterations|Parallelism|Memory |
@ -218,7 +234,8 @@ linked documents in [Argon2 links](./file.md#argon2-links).
 |Intel G5 i5 NUC|    1     |     8     |  1024 |
-#### Argon2 Links
+## Argon2 Links
 [How to choose the right parameters for Argon2](https://www.twelve21.io/how-to-choose-the-right-parameters-for-argon2/)
 [Go Documentation](https://godoc.org/golang.org/x/crypto/argon2)
--- a/docs/configuration/authentication/index.md
+++ b/docs/configuration/authentication/index.md
@ -13,17 +13,33 @@ 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.
-## Disabling Reset Password
+## Configuration
 You can disable the reset password functionality for additional security as per this configuration:
 ```yaml
 # The authentication backend to use for verifying user passwords
 # and retrieve information such as email address and groups
 # users belong to.
 #
 # There are two supported backends: 'ldap' and 'file'.
 authentication_backend:
-  # Disable both the HTML element and the API for reset password functionality
+  disable_reset_password: false
-  disable_reset_password: true
+  file: {}
-```
+  ldap: {}
 ```
 ## Options
 ### disable_reset_password
 <div markdown="1">
 type: boolean
 {: .label .label-config .label-purple } 
 default: false
 {: .label .label-config .label-blue }
 required: no
 {: .label .label-config .label-green }
 </div>
 This setting controls if users can reset their password from the web frontend or not.
 ### file
 The [file](file.md) authentication provider.
 ### ldap
 The [LDAP](ldap.md) authentication provider.
--- a/docs/configuration/authentication/ldap.md
+++ b/docs/configuration/authentication/ldap.md
@ -12,159 +12,177 @@ nav_order: 2
 ## Configuration
 Configuration of the LDAP backend is done as follows
 ```yaml
 # The authentication backend to use for verifying user passwords
 # and retrieve information such as email address and groups
 # users belong to.
 #
 # There are two supported backends: 'ldap' and 'file'.
 authentication_backend:
  # Disable both the HTML element and the API for reset password functionality
  disable_reset_password: false
  # The amount of time to wait before we refresh data from the authentication backend. Uses duration notation.
  # To disable this feature set it to 'disable', this will slightly reduce security because for Authelia, users
  # will always belong to groups they belonged to at the time of login even if they have been removed from them in LDAP.
  # To force update on every request you can set this to '0' or 'always', this will increase processor demand.
  # See the below documentation for more information.
  # Duration Notation docs:  https://docs.authelia.com/configuration/index.html#duration-notation-format
  # Refresh Interval docs: https://docs.authelia.com/configuration/authentication/ldap.html#refresh-interval
  refresh_interval: 5m
  # LDAP backend configuration.
  #
  # This backend allows Authelia to be scaled to more
  # than one instance and therefore is recommended for
  # production.
  ldap:
    # The LDAP implementation, this affects elements like the attribute utilised for resetting a password.
    # Acceptable options are as follows:
    # - 'activedirectory' - For Microsoft Active Directory.
    # - 'custom' - For custom specifications of attributes and filters.
    # This currently defaults to 'custom' to maintain existing behaviour.
    #
    # Depending on the option here certain other values in this section have a default value, notably all
    # of the attribute mappings have a default value that this config overrides, you can read more
    # about these default values at https://docs.authelia.com/configuration/authentication/ldap.html#defaults
    implementation: custom
    # The url to the ldap server. Scheme can be ldap or ldaps in the format (port optional) <scheme>://<address>[:<port>].
    url: ldap://127.0.0.1
    # Use StartTLS with the LDAP connection.
    start_tls: false
    tls:
-      # Server Name for certificate validation (in case it's not set correctly in the URL).
+      server_name: ldap.example.com
      # server_name: ldap.example.com
      # Skip verifying the server certificate (to allow a self-signed certificate).
      skip_verify: false
      # Minimum TLS version for either Secure LDAP or LDAP StartTLS.
      minimum_version: TLS1.2
    # The base dn for every entries.
    base_dn: dc=example,dc=com
-    
+    username_attribute: uid
    # The attribute holding the username of the user. This attribute is used to populate
    # the username in the session information. It was introduced due to #561 to handle case
    # insensitive search queries.
    # For you information, Microsoft Active Directory usually uses 'sAMAccountName' and OpenLDAP
    # usually uses 'uid'
    # Beware that this attribute holds the unique identifiers for the users binding the user and the configuration
    # stored in database. Therefore only single value attributes are allowed and the value
    # must never be changed once attributed to a user otherwise it would break the configuration
    # for that user. Technically, non-unique attributes like 'mail' can also be used but we don't recommend using
    # them, we instead advise to use the attributes mentioned above (sAMAccountName and uid) to follow
    # https://www.ietf.org/rfc/rfc2307.txt.
    # username_attribute: uid
    # An additional dn to define the scope to all users.
    additional_users_dn: ou=users
    # The users filter used in search queries to find the user profile based on input filled in login form.
    # Various placeholders are available to represent the user input and back reference other options of the configuration:
    # - {input} is a placeholder replaced by what the user inputs in the login form. 
    # - {username_attribute} is a mandatory placeholder replaced by what is configured in `username_attribute`.
    # - {mail_attribute} is a placeholder replaced by what is configured in `mail_attribute`.
    # - DON'T USE - {0} is an alias for {input} supported for backward compatibility but it will be deprecated in later versions, so please don't use it.
    #
    # Recommended settings are as follows:
    # - Microsoft Active Directory: (&({username_attribute}={input})(objectCategory=person)(objectClass=user))
    # - OpenLDAP: (&({username_attribute}={input})(objectClass=person))' or '(&({username_attribute}={input})(objectClass=inetOrgPerson))
    #
    # To allow sign in both with username and email, one can use a filter like
    # (&(|({username_attribute}={input})({mail_attribute}={input}))(objectClass=person))
    users_filter: (&({username_attribute}={input})(objectClass=person))
    # An additional dn to define the scope of groups.
    additional_groups_dn: ou=groups
    # The groups filter used in search queries to find the groups of the user.
    # - {input} is a placeholder replaced by what the user inputs in the login form.
    # - {username} is a placeholder replace by the username stored in LDAP (based on `username_attribute`).
    # - {dn} is a matcher replaced by the user distinguished name, aka, user DN.
    # - {username_attribute} is a placeholder replaced by what is configured in `username_attribute`.
    # - {mail_attribute} is a placeholder replaced by what is configured in `mail_attribute`.
    # - DON'T USE - {0} is an alias for {input} supported for backward compatibility but it will be deprecated in later versions, so please don't use it.
    # - DON'T USE - {1} is an alias for {username} supported for backward compatibility but it will be deprecated in later version, so please don't use it.
    # If your groups use the `groupOfUniqueNames` structure use this instead: (&(uniquemember={dn})(objectclass=groupOfUniqueNames))
    groups_filter: (&(member={dn})(objectclass=groupOfNames))
-
+    group_name_attribute: cn
-    # The attribute holding the name of the group
+    mail_attribute: mail
-    # group_name_attribute: cn
+    display_name_attribute: displayname
    # The attribute holding the mail address of the user. If multiple email addresses are defined for a user, only the first
    # one returned by the LDAP server is used.
    # mail_attribute: mail
    # The attribute holding the display name of the user. This will be used to greet an authenticated user.
    # display_name_attribute: displayname
    # The username and password of the admin user.
    user: cn=admin,dc=example,dc=com
    # Password can also be set using a secret: https://docs.authelia.com/configuration/secrets.html
    password: password
 ```
-The user must have an email address in order for Authelia to perform
+## Options
 identity verification when a user attempts to reset their password or
 register a second factor device.
-## IPv6 Addresses
+### implementation
 <div markdown="1">
 type: string
 {: .label .label-config .label-purple } 
 default: custom
 {: .label .label-config .label-blue }
 required: no
 {: .label .label-config .label-green }
 </div>
 Configures the LDAP implementation used by Authelia.
 See the [Implementation Guide](#implementation-guide) for information.
 ### url
 <div markdown="1">
 type: string
 {: .label .label-config .label-purple }
 required: yes
 {: .label .label-config .label-red }
 </div>
 The LDAP URL which consists of a scheme, address, and port. Format is `<scheme>://<address>:<port>` or
 `<scheme>://<address>` where scheme is either `ldap` or `ldaps`.
 If utilising an IPv6 literal address it must be enclosed by square brackets:
 ```yaml
 url: ldap://[fd00:1111:2222:3333::1]
 ```
-## TLS Settings
+### start_tls
 <div markdown="1">
 type: boolean
 {: .label .label-config .label-purple } 
 default: false
 {: .label .label-config .label-blue }
 required: no
 {: .label .label-config .label-green }
 </div>
-### Start TLS
+Enables use of the LDAP StartTLS process which is not commonly used. You should only configure this if you know you need
 it. The initial connection will be over plain text, and Authelia will try to upgrade it with the LDAP server. LDAPS
 URL's are slightly more secure.
 The key `start_tls` enables use of the LDAP StartTLS process which is not commonly used. You should only configure this
 if you know you need it. The initial connection will be over plain text, and Authelia will try to upgrade it with the
 LDAP server. LDAPS URL's are slightly more secure.
-### TLS (section)
+### tls
-The key `tls` is a map of options for tuning TLS options. You can see how to configure the tls section [here](../index.md#tls-configuration).
+Controls the TLS connection validation process. You can see how to configure the tls
 section [here](../index.md#tls-configuration).
-## Implementation
+### base_dn
 <div markdown="1">
 type: string
 {: .label .label-config .label-purple } 
 required: yes
 {: .label .label-config .label-red }
 </div>
 Sets the base distinguished name container for all LDAP queries. If your LDAP domain is example.com this is usually 
 `dc=example,dc=com`, however you can fine tune this to be more specific for example to only include objects inside the
 authelia OU: `ou=authelia,dc=example,dc=com`. This is prefixed with the [additional_users_dn](#additional_users_dn) for
 user searches and [additional_groups_dn](#additional_groups_dn) for groups searches.
 ### username_attribute
 <div markdown="1">
 type: string
 {: .label .label-config .label-purple }
 required: no
 {: .label .label-config .label-green }
 </div>
 The LDAP attribute that maps to the username in Authelia. The default value is dependent on the [implementation](#implementation),
 refer to the [attribute defaults](#attribute-defaults) for more information.
 ### additional_users_dn
 <div markdown="1">
 type: string
 {: .label .label-config .label-purple }
 required: no
 {: .label .label-config .label-green }
 </div>
 Additional LDAP path to append to the [base_dn](#base_dn) when searching for users. Useful if you want to restrict
 exactly which OU to get users from for either security or performance reasons. For example setting it to
 `ou=users,ou=people` with a base_dn set to `dc=example,dc=com` will mean user searches will occur in
 `ou=users,ou=people,dc=example,dc=com`. The default value is dependent on the [implementation](#implementation), refer 
 to the [attribute defaults](#attribute-defaults) for more information.
 ### users_filter
 <div markdown="1">
 type: string
 {: .label .label-config .label-purple }
 required: no
 {: .label .label-config .label-green }
 </div>
 The LDAP filter to narrow down which users are valid. This is important to set correctly as to exclude disabled users.
 The default value is dependent on the [implementation](#implementation), refer to the
 [attribute defaults](#attribute-defaults) for more information.
 ### additional_groups_dn
 Similar to [additional_users_dn](#additional_users_dn) but it applies to group searches.
 ### groups_filter
 Similar to [users_filter](#users_filter) but it applies to group searches.
 ### mail_attribute
 The attribute to retrieve which contains the users email addresses. This is important for the device registration and
 password reset processes.
 The user must have an email address in order for Authelia to perform
 identity verification when a user attempts to reset their password or
 register a second factor device.
 ### display_name_attribute
 The attribute to retrieve which is shown on the Web UI to the user when they log in.
 ### user
 The distinguished name of the user paired with the password to bind with for lookup and password change operations.
 ### password
 The password of the user paired with the user to bind with for lookup and password change operations.
 Can also be defined using a [secret](../secrets.md) which is the recommended for containerized deployments.
 ## Implementation Guide
 There are currently two implementations, `custom` and `activedirectory`. The `activedirectory` implementation
 must be used if you wish to allow users to change or reset their password as Active Directory
-uses a custom attribute for this, and an input format other implementations do not use. The long term 
+uses a custom attribute for this, and an input format other implementations do not use. The long term
-intention of this is to have logical defaults for various RFC implementations of LDAP. 
+intention of this is to have logical defaults for various RFC implementations of LDAP.
 ### Defaults
 The below tables describes the current attribute defaults for each implementation.
-#### Attributes
+#### Attribute defaults
 This table describes the attribute defaults for each implementation. i.e. the username_attribute is
 described by the Username column.
@ -173,12 +191,12 @@ described by the Username column.
 |custom         |n/a           |displayname |mail|cn        |
 |activedirectory|sAMAccountName|displayname |mail|cn        |
-#### Filters
+#### Filter defaults
-The filters are probably the most important part to get correct when setting up LDAP. 
+The filters are probably the most important part to get correct when setting up LDAP.
-You want to exclude disabled accounts. The active directory example has two attribute 
+You want to exclude disabled accounts. The active directory example has two attribute
-filters that accomplish this as an example (more examples would be appreciated). The 
+filters that accomplish this as an example (more examples would be appreciated). The
-userAccountControl filter checks that the account is not disabled and the pwdLastSet 
+userAccountControl filter checks that the account is not disabled and the pwdLastSet
 makes sure that value is not 0 which means the password requires changing at the next login.
 |Implementation |Users Filter  |Groups Filter|
@ -190,19 +208,19 @@ makes sure that value is not 0 which means the password requires changing at the
 ## Refresh Interval
 This setting takes a [duration notation](../index.md#duration-notation-format) that sets the max frequency
-for how often Authelia contacts the backend to verify the user still exists and that the groups stored 
+for how often Authelia contacts the backend to verify the user still exists and that the groups stored
 in the session are up to date. This allows us to destroy sessions when the user no longer matches the
 user_filter, or deny access to resources as they are removed from groups.
 In addition to the duration notation, you may provide the value `always` or `disable`. Setting to `always`
-is the same as setting it to 0 which will refresh on every request, `disable` turns the feature off, which is 
+is the same as setting it to 0 which will refresh on every request, `disable` turns the feature off, which is
 not recommended. This completely prevents Authelia from refreshing this information, and it would only be
-refreshed when the user session gets destroyed by other means like inactivity, session expiration or logging 
+refreshed when the user session gets destroyed by other means like inactivity, session expiration or logging
 out and in.
 This value can be any value including 0, setting it to 0 would automatically refresh the session on
 every single request. This means Authelia will have to contact the LDAP backend every time an element
-on a page loads which could be substantially costly. It's a trade-off between load and security that 
+on a page loads which could be substantially costly. It's a trade-off between load and security that
 you should adapt according to your own security policy.
 ## Important notes
@ -218,8 +236,4 @@ unique identifier for your users.
 As of versions > `4.24.0` the `users_filter` must include the `username_attribute` placeholder, not including this will
 result in Authelia throwing an error.
 In versions <= `4.24.0` not including the `username_attribute` placeholder will cause issues with the session refresh
-and will result in session resets when the refresh interval has expired, default of 5 minutes. 
+and will result in session resets when the refresh interval has expired, default of 5 minutes.
 ## Loading a password from a secret instead of inside the configuration
 Password can also be defined using a [secret](../secrets.md).
--- a/docs/configuration/duo-push-notifications.md
+++ b/docs/configuration/duo-push-notifications.md
@ -12,6 +12,10 @@ 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.
 **Note:** The configuration options in the following sections are noted as required. They are however only required when
 you have this section defined. i.e. if you don't wish to use the [Duo] push notifications you can just not define this
 section of the configuration.
 ## Configuration
 The configuration is as follows:
@ -22,8 +26,45 @@ duo_api:
  secret_key: 1234567890abcdefghifjkl
 ```
 The secret key is shown as an example, you also have the option to set it using an environment
 variable as described [here](./secrets.md).
-[Duo]: https://duo.com/
+## Options
 ### hostname
 <div markdown="1">
 type: string
 {: .label .label-config .label-purple } 
 default: ""
 {: .label .label-config .label-blue }
 required: yes
 {: .label .label-config .label-red }
 </div>
 The [Duo] API hostname supplied by [Duo].
 ### integration_key
 <div markdown="1">
 type: string
 {: .label .label-config .label-purple } 
 default: ""
 {: .label .label-config .label-blue }
 required: yes
 {: .label .label-config .label-red }
 </div>
 The non-secret [Duo] integration key. Similar to a client identifier.
 ### secret_key
 <div markdown="1">
 type: string
 {: .label .label-config .label-purple } 
 default: ""
 {: .label .label-config .label-blue }
 required: yes
 {: .label .label-config .label-red }
 </div>
 The secret [Duo] key used to verify your application is valid.
 [Duo]: https://duo.com/
--- a/docs/configuration/index.md
+++ b/docs/configuration/index.md
@ -7,15 +7,16 @@ has_children: true
 # Configuration
-Authelia uses a YAML file as configuration file. A template with all possible
+Authelia uses a YAML file as configuration file. A template with all possible options can be
-options can be found [here](https://github.com/authelia/authelia/blob/master/config.template.yml), at the root of the repository.
+found [here](https://github.com/authelia/authelia/blob/master/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.
 ```console
 $ authelia --config config.custom.yml
 ```
 When running **Authelia**, you can specify your configuration by passing
 the file path as shown below.
    $ authelia --config config.custom.yml
 ## Validation
 Authelia validates the configuration when it starts. This process checks multiple factors including configuration keys
@ -23,21 +24,22 @@ that don't exist, configuration keys that have changed, the values of the keys a
 key isn't supplied at the same time as a secret for the same configuration option.
 You may also optionally validate your configuration against this validation process manually by using the validate-config
-option with the Authelia binary as shown below. Keep in mind if you're using [secrets](./secrets.md) you will have to 
+option with the Authelia binary as shown below. Keep in mind if you're using [secrets](./secrets.md) you will have to
-manually provide these if you don't want to get certain validation errors (specifically requesting you provide one of 
+manually provide these if you don't want to get certain validation errors (specifically requesting you provide one of
-the secret values). You can choose to ignore them if you know what you're doing. This command is useful prior to 
+the secret values). You can choose to ignore them if you know what you're doing. This command is useful prior to
 upgrading to prevent configuration changes from impacting downtime in an upgrade. This process does not validate
 integrations, it only checks that your configuration syntax is valid.
-    $ authelia validate-config configuration.yml
+```console
-    
+$ authelia validate-config configuration.yml
-   
+```
 ## Duration Notation Format
 We have implemented a string based notation for configuration options that take a duration. This section describes its
-usage. You can use this implementation in: session for expiration, inactivity, and remember_me_duration; and regulation 
+usage. You can use this implementation in: session for expiration, inactivity, and remember_me_duration; and regulation
 for ban_time, and find_time. This notation also supports just providing the number of seconds instead.
- 
+
 The notation is comprised of a number which must be positive and not have leading zeros, followed by a letter
 denoting the unit of time measurement. The table below describes the units of time and the associated letter.
@ -62,18 +64,42 @@ Various sections of the configuration use a uniform configuration section called
 This section documents the usage.
 ### Server Name
 <div markdown="1">
 type: string
 {: .label .label-config .label-purple } 
 default: ""
 {: .label .label-config .label-blue }
 required: no
 {: .label .label-config .label-green }
 </div>
 The key `server_name` overrides the name checked against the certificate in the verification process. Useful if you
 require to use a direct IP address for the address of the backend service but want to verify a specific SNI.
 ### Skip Verify
 <div markdown="1">
 type: boolean
 {: .label .label-config .label-purple } 
 default: false
 {: .label .label-config .label-blue }
 required: no
 {: .label .label-config .label-green }
 </div>
 The key `skip_verify` completely negates validating the certificate of the backend service. This is not recommended,
 instead you should tweak the `server_name` option, and the global option [certificates_directory](./miscellaneous.md#certificates-directory).
 ### Minimum Version
 <div markdown="1">
 type: string
 {: .label .label-config .label-purple } 
 default: TLS1.2
 {: .label .label-config .label-blue }
 required: no
 {: .label .label-config .label-green }
 </div>
 The key `minimum_version` controls the minimum TLS version Authelia will use when opening TLS connections.
 The possible values are `TLS1.3`, `TLS1.2`, `TLS1.1`, `TLS1.0`. Anything other than `TLS1.3` or `TLS1.2`
 are very old and deprecated. You should avoid using these and upgrade your backend service instead of decreasing
-this value.
+this value.
--- a/docs/configuration/miscellaneous.md
+++ b/docs/configuration/miscellaneous.md
@ -11,64 +11,119 @@ Here are the main customizable options in Authelia.
 ## Host & Port
 `optional: true`
 Defines the address and port to listen on.
 ```yaml
 host: 0.0.0.0
 port: 9091
 ```
 ### host
 <div markdown="1">
 type: string
 {: .label .label-config .label-purple } 
 default: 0.0.0.0
 {: .label .label-config .label-blue }
 required: no
 {: .label .label-config .label-green }
 </div>
 Defines the address to listen on. See also [port](#port). Should typically be `0.0.0.0` or `127.0.0.1`, the former for
 containerized environments and the later for daemonized environments like init.d and systemd.
 Note: If utilising an IPv6 literal address it must be enclosed by square brackets and quoted:
 ```yaml
 host: "[fd00:1111:2222:3333::1]"
 ```
 ### port
 <div markdown="1">
 type: integer
 {: .label .label-config .label-purple } 
 default: 9091
 {: .label .label-config .label-blue }
 required: no
 {: .label .label-config .label-green }
 </div>
 Defines the port to listen on. See also [host](#host).
 ## TLS
-`optional: true`
+Authelia's port typically listens for plain unencrypted connections. This is by design as most environments allow to
-
+security on lower areas of the OSI model. However it required, if you specify both of the tls options the port will
-Authelia can use TLS. Provide the certificate and the key with the
+listen for TLS connections.
 following configuration options:
 ```yaml
 tls_key: /config/ssl/key.pem
 tls_cert: /config/ssl/cert.pem
 ```
-## Certificates Directory
+### tls_key
 <div markdown="1">
 type: string (path)
 {: .label .label-config .label-purple } 
 default: ""
 {: .label .label-config .label-blue }
 required: situational
 {: .label .label-config .label-yellow }
 </div>
-`optional: true`
+The path to the private key for TLS connections. Must be in DER base64/PEM format.
 ### tls_cert
 <div markdown="1">
 type: string (path)
 {: .label .label-config .label-purple } 
 default: ""
 {: .label .label-config .label-blue }
 required: situational
 {: .label .label-config .label-yellow }
 </div>
 The path to the public certificate for TLS connections. Must be in DER base64/PEM format.
 ## certificates_directory
 This option defines the location of additional certificates to load into the trust chain specifically for Authelia.
 This currently affects both the SMTP notifier and the LDAP authentication backend. The certificates should all be in the
-PEM format and end with the extension `.pem`, `.crt`, or `.cer`. You can either add the individual certificates public key 
+PEM format and end with the extension `.pem`, `.crt`, or `.cer`. You can either add the individual certificates public
-or the CA public key which signed them (don't add the private key).
+key or the CA public key which signed them (don't add the private key).
 ```yaml
 certificates_directory: /config/certs/
 ```
-## Log
+## Logging
-### Log level
+### log_level
 <div markdown="1">
 type: string
 {: .label .label-config .label-purple } 
 default: info
 {: .label .label-config .label-blue }
 required: no
 {: .label .label-config .label-green }
 </div>
-`optional: true`
+Defines the level of logs used by Authelia. This level can be set to `trace`, `debug` or `info`. When setting log_level
-
+to `trace`, you will generate a large amount of log entries and expose the `/debug/vars` and `/debug/pprof/` endpoints
-Defines the level of logs used by Authelia. This level can be set to
+which should not be enabled in production.
 `trace`, `debug` or `info`. When setting log_level to `trace`, you will
 generate a large amount of log entries and expose the `/debug/vars` and
 `/debug/pprof/` endpoints which should not be enabled in production.
 ```yaml
 log_level: debug
 ```
-### Log format
+### log_format
 <div markdown="1">
 type: string
 {: .label .label-config .label-purple } 
 default: ""
 {: .label .label-config .label-blue }
 required: no
 {: .label .label-config .label-green }
 </div>
-`optional: true`
+Defines the format of the logs written by Authelia. This format can be set to `json` or `text`.
 Defines the format of the logs written by Authelia.
 This format can be set to `json` or `text`.
 ```yaml
 log_format: json
@ -85,23 +140,33 @@ time="2020-01-01T00:00:00+11:00" level=info msg="Logging severity set to info"
 time="2020-01-01T00:00:00+11:00" level=info msg="Authelia is listening for non-TLS connections on 0.0.0.0:9091"
 ```
-### Log file path
+### log_file_path
 <div markdown="1">
 type: string (path)
 {: .label .label-config .label-purple } 
 default: ""
 {: .label .label-config .label-blue }
 required: no
 {: .label .label-config .label-green }
 </div>
-`optional: true`
+Logs can be stored in a file when file path is provided. Otherwise logs are written to standard output. When setting the
-
+log_level to `debug` or `trace` this will generate large amount of log entries. Administrators will need to ensure that
-Logs can be stored in a file when file path is provided. Otherwise logs
+they rotate and/or truncate the logs over time to prevent significant long-term disk usage.
 are written to standard output. When setting the log_level to `debug` or
 `trace` this will generate large amount of log entries.
 Administrators will need to ensure that they rotate and/or truncate the
 logs over time to prevent significant long-term disk usage.
 ```yaml
 log_file_path: /config/authelia.log
 ```
-## JWT Secret
+## jwt_secret
-
+<div markdown="1">
-`optional: false`
+type: string
 {: .label .label-config .label-purple } 
 default: ""
 {: .label .label-config .label-blue }
 required: yes
 {: .label .label-config .label-red }
 </div>
 Defines the secret used to craft JWT tokens leveraged by the identity
 verification process. This can also be defined using a [secret](./secrets.md).
@ -110,18 +175,25 @@ verification process. This can also be defined using a [secret](./secrets.md).
 jwt_secret: v3ry_important_s3cr3t
 ```
-## Default redirection URL
+## default_redirection_url
 <div markdown="1">
 type: string
 {: .label .label-config .label-purple } 
 default: ""
 {: .label .label-config .label-blue }
 required: no
 {: .label .label-config .label-green }
 </div>
-`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.
-The default redirection URL is the URL where users are redirected when Authelia
+In a normal authentication workflow, a user tries to access a website and she gets redirected to the sign-in portal in
-cannot detect the target URL where the user was heading.
+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.
-In a normal authentication workflow, a user tries to access a website and she
+```yaml
-gets redirected to the sign-in portal in order to authenticate. Since the user
+default_redirection_url: https://home.example.com:8080/
-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.
--- a/docs/configuration/notifier/filesystem.md
+++ b/docs/configuration/notifier/filesystem.md
@ -8,21 +8,26 @@ nav_order: 1
 # Filesystem
-With this configuration, the message will be sent to a file. This option
+With this configuration, the message will be sent to a file. This option should only be used for testing purposes.
-should only be used for testing purposes. This method will use the plain
+This method will use the plain text email template for readability purposes.
-text email template for readability purposes.
+
 ## Configuration
 ```yaml
 # Configuration of the notification system.
 #
 # Notifications are sent to users when they require a password reset, a U2F
 # registration or a TOTP registration.
 # Use only an available configuration: filesystem, smtp.
 notifier:
  # You can disable the notifier startup check by setting this to true.
  disable_startup_check: false
  # For testing purpose, notifications can be sent in a file.
  filesystem:
    filename: /config/notification.txt
 ```
 ## Options
 ### filename
 <div markdown="1">
 type: string
 {: .label .label-config .label-purple }
 required: yes
 {: .label .label-config .label-red }
 </div>
 The file to add email text to. If it doesn't exist it will be created.
--- a/docs/configuration/notifier/index.md
+++ b/docs/configuration/notifier/index.md
@ -11,19 +11,35 @@ has_children: true
 **Authelia** sometimes needs to send messages to users in order to
 verify their identity.
-## Startup Check
+## Configuration
 ```yaml
 notifier:
  disable_startup_check: false
  filesystem: {}
  smtp: {}
 ```
 ## Options
 ### disable_startup_check
 <div markdown="1">
 type: boolean
 {: .label .label-config .label-purple }
 default: false
 {: .label .label-config .label-blue }
 required: no
 {: .label .label-config .label-green }
 </div>
 The notifier has a startup check which validates the specified provider
 configuration is correct and will be able to send emails. This can be
 disabled with the `disable_startup_check` option:
-```yaml
+### filesystem
-# Configuration of the notification system.
+
-#
+The [filesystem](filesystem.md) provider.
-# Notifications are sent to users when they require a password reset, a u2f
+
-# registration or a TOTP registration.
+### smtp
-# Use only an available configuration: filesystem, smtp.
+
-notifier:
+The [smtp](smtp.md) provider.
  # You can disable the notifier startup check by setting this to true
  disable_startup_check: false
 ```
--- a/docs/configuration/notifier/smtp.md
+++ b/docs/configuration/notifier/smtp.md
@ -10,92 +10,160 @@ nav_order: 2
 **Authelia** can send emails to users through an SMTP server.
 It can be configured as described below.
 ## Configuration
 ```yaml
 # Configuration of the notification system.
 #
 # Notifications are sent to users when they require a password reset, a u2f
 # registration or a TOTP registration.
 # Use only an available configuration: filesystem, smtp.
 notifier:
  # You can disable the notifier startup check by setting this to true.
  disable_startup_check: false
  # For testing purpose, notifications can be sent in a file
  ## filesystem:
  ##   filename: /config/notification.txt
  # 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 (configure in tls section)
  smtp:
    username: test
    # Password can also be set using a secret: https://docs.authelia.com/configuration/secrets.html
    password: password
    host: 127.0.0.1
    port: 1025
    sender: admin@example.com
    # HELO/EHLO Identifier. Some SMTP Servers may reject the default of localhost.
    identifier: localhost
    # Subject configuration of the emails sent.
    # {title} is replaced by the text from the notifier
    subject: "[Authelia] {title}"
    # This address is used during the startup check to verify the email configuration is correct. It's not important what it is except if your email server only allows local delivery.
    startup_check_address: test@authelia.com
    disable_require_tls: false
    disable_html_emails: false
    tls:
-      # Server Name for certificate validation (in case you are using the IP or non-FQDN in the host option).
+      server_name: smtp.example.com
      # server_name: smtp.example.com
      # Skip verifying the server certificate (to allow a self-signed certificate).
      skip_verify: false
      # Minimum TLS version for either StartTLS or SMTPS.
      minimum_version: TLS1.2
  # Sending an email using a Gmail account is as simple as the next section.
  # You need to create an app password by following: https://support.google.com/accounts/answer/185833?hl=en
  ## smtp:
  ##   username: myaccount@gmail.com
  ##   # Password can also be set using a secret: https://docs.authelia.com/configuration/secrets.html
  ##   password: yourapppassword
  ##   sender: admin@example.com
  ##   host: smtp.gmail.com
  ##   port: 587
 ```
-## Configuration options
+## Options
-Most configuration options are self-explanatory, however here is an explanation of the ones that may not
+
-be as obvious.
+### username
 <div markdown="1">
 type: string
 {: .label .label-config .label-purple }
 required: no
 {: .label .label-config .label-green }
 </div>
 The username sent for authentication with the SMTP server. Paired with the password.
 ### password
 <div markdown="1">
 type: string
 {: .label .label-config .label-purple } 
 required: no
 {: .label .label-config .label-green }
 </div>
 The password sent for authentication with the SMTP server. Paired with the username. Can also be defined using a
 [secret](../secrets.md) which is the recommended for containerized deployments.
 ### host
 <div markdown="1">
 type: integer
 {: .label .label-config .label-purple } 
 required: yes
 {: .label .label-config .label-red }
 </div>
 The hostname of the SMTP server.
 If utilising an IPv6 literal address it must be enclosed by square brackets and quoted:
 ```yaml
 host: "[fd00:1111:2222:3333::1]"
 ```
-### identifier
+### port
 <div markdown="1">
 type: integer
 {: .label .label-config .label-purple } 
 required: yes
 {: .label .label-config .label-red }
 </div>
 The port the SMTP service is listening on.
 ### sender
 <div markdown="1">
 type: string
 {: .label .label-config .label-purple } 
 required: no
 {: .label .label-config .label-green }
 </div>
 The address sent in the FROM header for the email. Basically who the email appears to come from. It should be noted
 that some SMTP servers require the username provided to have access to send from the specific address listed here.
 ### identifer
 <div markdown="1">
 type: string
 {: .label .label-config .label-purple } 
 default: localhost
 {: .label .label-config .label-blue }
 required: no
 {: .label .label-config .label-green }
 </div>
 The name to send to the SMTP server as the identifier with the HELO/EHLO command. Some SMTP providers like Google Mail
 reject the message if it's localhost.
 ### subject
 <div markdown="1">
 type: string
 {: .label .label-config .label-purple } 
 default: [Authelia] {title}
 {: .label .label-config .label-blue }
 required: no
 {: .label .label-config .label-green }
 </div>
 This is the subject Authelia will use in the email, it has a single placeholder at present `{title}` which should
 be included in all emails as it is the internal descriptor for the contents of the email.
 ### startup_check_address
 <div markdown="1">
 type: string
 {: .label .label-config .label-purple } 
 default: test@authelia.com
 {: .label .label-config .label-blue }
 required: no
 {: .label .label-config .label-green }
 </div>
 **Authelia** checks the SMTP server is valid at startup, one of the checks requires we ask the SMTP server if it can
 send an email from us to a specific address, this is that address. No email is actually sent in the process. It is fine
 to leave this as is, but you can customize it if you have issues or you desire to.
 ### disable_require_tls
-For security reasons the default settings for Authelia require the SMTP connection is encrypted by TLS. See [security] for
+<div markdown="1">
-more information. This option disables this measure (not recommended).
+type: boolean
 {: .label .label-config .label-purple } 
 default: false
 {: .label .label-config .label-blue }
 required: no
 {: .label .label-config .label-green }
 </div>
 For security reasons the default settings for Authelia require the SMTP connection is encrypted by TLS. See [security]
 for more information. This option disables this measure (not recommended).
 ### disable_html_emails
-This option forces Authelia to only send plain text email via the notifier. This is the default for the file based 
+<div markdown="1">
-notifier, but some users may wish to use plain text for security reasons.
+type: boolean
 {: .label .label-config .label-purple } 
 default: false
 {: .label .label-config .label-blue }
 required: no
 {: .label .label-config .label-green }
 </div>
 This setting completely disables HTML formatting of emails and only sends text emails. **Authelia** by default sends
 mixed emails which contain both HTML and text so this option is rarely necessary.
 ### tls
 Controls the TLS connection validation process. You can see how to configure the tls section
 [here](../index.md#tls-configuration).
 ### TLS (section)
 The key `tls` is a map of options for tuning TLS options. You can see how to configure the tls section [here](../index.md#tls-configuration).
 ## Using Gmail
 You need to generate an app password in order to use Gmail SMTP servers. The process is
@ -105,14 +173,9 @@ described [here](https://support.google.com/accounts/answer/185833?hl=en)
 notifier:
  smtp:
    username: myaccount@gmail.com
-    # Password can also be set using a secret: https://docs.authelia.com/configuration/secrets.html
+    # Password can also be set using a secret: https://www.authelia.com/docs/configuration/secrets.html
    password: yourapppassword
    sender: admin@example.com
    host: smtp.gmail.com
    port: 587
 ```
 ## Loading a password from a secret instead of inside the configuration
 Password can also be defined using a [secret](../secrets.md).
 [security]: ../../security/measures.md#notifier-security-measures-smtp
--- a/docs/configuration/one-time-password.md
+++ b/docs/configuration/one-time-password.md
@ -7,10 +7,11 @@ nav_order: 4
 # Time-based One-Time Password
-Authelia uses time based one-time passwords as the OTP method. You have 
+Authelia uses time based one-time passwords as the OTP method. You have
 the option to tune the settings of the TOTP generation, and you can see a
 full example of TOTP configuration below, as well as sections describing them.
 ## Configuration
 ```yaml
 totp:
  issuer: authelia.com
@ -18,8 +19,17 @@ totp:
  skew: 1
 ```
-        
+## Options
-## Issuer
+
 ### issuer
 <div markdown="1">
 type: string
 {: .label .label-config .label-purple } 
 default: Authelia
 {: .label .label-config .label-blue }
 required: no
 {: .label .label-config .label-green }
 </div>
 Applications generating one-time passwords usually display an issuer to
 differentiate applications registered by the user.
@ -34,23 +44,39 @@ a period of 30 and a skew of 1. It is highly recommended you do not change these
 you wish to set skew to 0.
 The way you configure these affects security by changing the length of time a one-time
-password is valid for. The formula to calculate the effective validity period is 
+password is valid for. The formula to calculate the effective validity period is
-`period + (period * skew * 2)`. For example period 30 and skew 1 would result in 90 
+`period + (period * skew * 2)`. For example period 30 and skew 1 would result in 90
 seconds of validity, and period 30 and skew 2 would result in 150 seconds of validity.
-### Period
+### period
 <div markdown="1">
 type: integer
 {: .label .label-config .label-purple } 
 default: 30
 {: .label .label-config .label-blue }
 required: no
 {: .label .label-config .label-green }
 </div>
 Configures the period of time in seconds a one-time password is current for. It is important
 to note that changing this value will require your users to register their application again.
 It is recommended to keep this value set to 30, the minimum is 1.
-  
+
-### Skew
+### skew
 <div markdown="1">
 type: integer
 {: .label .label-config .label-purple } 
 default: 1
 {: .label .label-config .label-blue }
 required: no
 {: .label .label-config .label-green }
 </div>
 Configures the number of one-time passwords either side of the current one that are
-considered valid, each time you increase this it makes two more one-time passwords valid. 
+considered valid, each time you increase this it makes two more one-time passwords valid.
-For example the default of 1 has a total of 3 keys valid. A value of 2 has 5 one-time passwords 
+For example the default of 1 has a total of 3 keys valid. A value of 2 has 5 one-time passwords
 valid.
-It is recommended to keep this value set to 0 or 1, the minimum is 0.
+It is recommended to keep this value set to 0 or 1, the minimum is 0.
--- a/docs/configuration/regulation.md
+++ b/docs/configuration/regulation.md
@ -14,21 +14,48 @@ authentication attempts. This helps prevent brute-force attacks.
 ```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 accepts duration notation. See: https://docs.authelia.com/configuration/index.html#duration-notation-format
  find_time: 2m
  # The length of time before a banned user can sign in again.
  # Find Time accepts duration notation. See: https://docs.authelia.com/configuration/index.html#duration-notation-format
  ban_time: 5m
 ```
-### Duration Notation
+## Options
-The configuration parameters find_time, and ban_time use duration notation. See the documentation
+### max_retries
-for [duration notation format](index.md#duration-notation-format) for more information.
+<div markdown="1">
 type: integer 
 {: .label .label-config .label-purple } 
 default: 3
 {: .label .label-config .label-blue }
 required: no
 {: .label .label-config .label-green }
 </div>
 The number of failed login attempts before a user may be banned. Setting this option to 0 disables regulation entirely.
 ### find_time
 <div markdown="1">
 type: string (duration) 
 {: .label .label-config .label-purple } 
 default: 2m
 {: .label .label-config .label-blue }
 required: no
 {: .label .label-config .label-green }
 </div>
 The period of time in [duration notation format](index.md#duration-notation-format) analyzed for failed attempts. For
 example if you set `max_retries` to 3 and `find_time` to `2m` this means the user must have 3 failed logins in
 2 minutes.
 ### ban_time
 <div markdown="1">
 type: string (duration) 
 {: .label .label-config .label-purple } 
 default: 5m
 {: .label .label-config .label-blue }
 required: no
 {: .label .label-config .label-green }
 </div>
 The period of time in [duration notation format](index.md#duration-notation-format) the user is banned for after meeting
 the `max_retries` and `find_time` configuration. After this duration the account will be able to login again.
--- a/docs/configuration/secrets.md
+++ b/docs/configuration/secrets.md
@ -171,10 +171,10 @@ Secrets can be mounted as files using the following sample manifests.
 - **Filename:** ./kustomization.yaml
 - **Command:** kubectl apply -k
 - **Notes:** this kustomization expects the Authelia configuration.yml in
-the same directory. You will need to edit the kustomization.yaml with your
+  the same directory. You will need to edit the kustomization.yaml with your
-desired secrets after the equal signs. If you change the value before the
+  desired secrets after the equal signs. If you change the value before the
-equal sign you'll have to adjust the volumes section of the daemonset
+  equal sign you'll have to adjust the volumes section of the daemonset
-template (or deployment template if you're using it).
+  template (or deployment template if you're using it).
 ```yaml
 #filename: ./kustomization.yaml
@ -305,4 +305,4 @@ spec:
                path: ldap_password
              - key: smtp_password
                path: smtp_password
-```
+```
--- a/docs/configuration/server.md
+++ b/docs/configuration/server.md
@ -12,40 +12,70 @@ The server section configures and tunes the http server module Authelia uses.
 ## Configuration
 ```yaml
 # Configuration options specific to the internal http server
 server:
  # Buffers usually should be configured to be the same value.
  # Explanation at https://docs.authelia.com/configuration/server.html
  # Read buffer size configures the http server's maximum incoming request size in bytes.
  read_buffer_size: 4096
  # Write buffer size configures the http server's maximum outgoing response size in bytes.
  write_buffer_size: 4096
  # Set the single level path Authelia listens on, must be alphanumeric chars and should not contain any slashes.
  path: ""
 ```
-### Buffer Sizes
+## Options
-The read and write buffer sizes generally should be the same. This is because when Authelia verifies 
+### read_buffer_size
-if the user is authorized to visit a URL, it also sends back nearly the same size response 
+<div markdown="1">
-(write_buffer_size) as the request (read_buffer_size).
+type: integer 
 {: .label .label-config .label-purple } 
 default: 4096
 {: .label .label-config .label-blue }
 required: no
 {: .label .label-config .label-red }
 </div>
-### Path
+Configures the maximum request size. The default of 4096 is generally sufficient for most use cases.
 ### write_buffer_size
 <div markdown="1">
 type: integer 
 {: .label .label-config .label-purple } 
 default: 4096
 {: .label .label-config .label-blue }
 required: no
 {: .label .label-config .label-green }
 </div>
 Configures the maximum response size. The default of 4096 is generally sufficient for most use cases.
 ### path
 <div markdown="1">
 type: string 
 {: .label .label-config .label-purple } 
 default: ""
 {: .label .label-config .label-blue }
 required: no
 {: .label .label-config .label-green }
 </div>
 Authelia by default is served from the root `/` location, either via its own domain or subdomain.
 Modifying this setting will allow you to serve Authelia out from a specified base path. Please note
 that currently only a single level path is supported meaning slashes are not allowed, and only
 alphanumeric characters are supported.
 Example: https://auth.example.com/, https://example.com/
 ```yaml
 server:
  path: ""
 ```
 Modifying this setting will allow you to serve Authelia out from a specified base path. Please note
 that currently only a single level path is supported meaning slashes are not allowed, and only 
 alphanumeric characters are supported.
 Example: https://auth.example.com/authelia/, https://example.com/authelia/
 ```yaml
 server:
  path: authelia
-```
+```
 ## Additional Notes
 ### Buffer Sizes
 The read and write buffer sizes generally should be the same. This is because when Authelia verifies
 if the user is authorized to visit a URL, it also sends back nearly the same size response as the request. However
 you're able to tune these individually depending on your needs.
--- a/docs/configuration/session.md
+++ b/docs/configuration/session.md
@ -1,131 +0,0 @@
 ---
 layout: default
 title: Session
 parent: Configuration
 nav_order: 8
 ---
 # 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 data. This is only used with Redis.
  # Secret can also be set using a secret: https://docs.authelia.com/configuration/secrets.html
  secret: unsecure_session_secret
  # The time in seconds before the cookie expires and session is reset.
  expiration: 1h
  # The inactivity time in seconds before the session is reset.
  inactivity: 5m
  # The remember me duration.
  # Value of 0 disables remember me.
  # Value is in seconds, or duration notation. See: https://docs.authelia.com/configuration/index.html#duration-notation-format
  # Longer periods are considered less secure because a stolen cookie will last longer giving attackers more time to spy
  # or attack. Currently the default is 1M or 1 month.
  remember_me_duration:  1M
  # 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
    ## Use a unix socket instead
    # host: /var/run/redis/redis.sock
    ## Optional username to be used with authentication.
    username: authelia
    ## Password can also be set using a secret: https://docs.authelia.com/configuration/secrets.html
    password: authelia
    ## This is the Redis DB Index https://redis.io/commands/select (sometimes referred to as database number, DB, etc).
    database_index: 0
    ## The maximum number of concurrent active connections to Redis.
    maximum_active_connections: 8
    ## The target number of idle connections to have open ready for work. Useful when opening connections is slow.
    minimum_idle_connections: 0
    ## The Redis TLS configuration. If defined will require a TLS connection to the Redis instance(s).
    tls:
      ## Server Name for certificate validation (in case you are using the IP or non-FQDN in the host option).
      server_name: myredis.example.com
      ## Skip verifying the server certificate (to allow a self-signed certificate).
      ## In preference to setting this we strongly recommend you add the public portion of the certificate to the
      ## certificates directory which is defined by the `certificates_directory` option at the top of the config.
      skip_verify: false
      ## Minimum TLS version for the connection.
      minimum_version: TLS1.2
    ## The Redis HA configuration options.
    ## This provides specific options to Redis Sentinel, sentinel_name must be defined (Master Name).
    high_availability:
      ## Sentinel Name / Master Name
      sentinel_name: mysentinel
      ## Specific password for Redis Sentinel. The node username and password is configured above.
      sentinel_password: sentinel_specific_pass
      ## The additional nodes to pre-seed the redis provider with (for sentinel).
      ## If the host in the above section is defined, it will be combined with this list to connect to sentinel.
      ## For high availability to be used you must have either defined; the host above or at least one node below.
      nodes:
        - host: sentinel-node1
          port: 6379
        - host: sentinel-node2
          port: 6379
      ## Choose the host with the lowest latency.
      route_by_latency: false
      ## Choose the host randomly.
      route_randomly: false
 ```
 ### Security
 Configuration of this section has an impact on security. You should read notes in
 [security measures](../security/measures.md#session-security) for more information.
 ### Duration Notation
 The configuration parameters expiration, inactivity, and remember_me_duration use duration notation. See the documentation
 for [duration notation format](index.md#duration-notation-format) for more information.
 ## IPv6 Addresses
 If utilising an IPv6 literal address it must be enclosed by square brackets and quoted:
 ```yaml
 host: "[fd00:1111:2222:3333::1]"
 ```
 ## Loading a password from a secret instead of inside the configuration
 Password can also be defined using a [secret](../secrets.md).
 ## Redis Sentinel
 When using Redis Sentinel, the host specified in the main redis section is added (it will be the first node) to the 
 nodes in the high availability section. This however is optional.
--- a/docs/configuration/session/index.md
+++ b/docs/configuration/session/index.md
@ -0,0 +1,126 @@
 ---
 layout: default
 title: Session
 parent: Configuration
 nav_order: 8
 has_children: true
 ---
 # 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:
  name: authelia_session
  domain: example.com
  secret: unsecure_session_secret
  expiration: 1h
  inactivity: 5m
  remember_me_duration:  1M
 ```
 ## Providers
 There are currently two providers for session storage (three if you count Redis Sentinel as a separate provider):
 * Memory (default, stateful, no additional configuration)
 * [Redis](./redis.md) (stateless).
 * [Redis Sentinel](./redis.md#high_availability) (stateless, highly available).
 ### Kubernetes or High Availability
 It's important to note when picking a provider, the stateful providers are not recommended in High Availability
 scenarios like Kubernetes. Each provider has a note beside it indicating it is *stateful* or *stateless* the stateless
 providers are recommended.
 ## Options
 ### name
 <div markdown="1">
 type: string
 {: .label .label-config .label-purple }
 default: authelia_session
 {: .label .label-config .label-blue }
 required: no
 {: .label .label-config .label-green }
 </div>
 The name of the session cookie. By default this is set to authelia_session. It's mostly useful to change this if you are
 doing development or running multiple instances of Authelia.
 ### domain
 <div markdown="1">
 type: string
 {: .label .label-config .label-purple }
 required: yes
 {: .label .label-config .label-red }
 </div>
 The domain the cookie is assigned to protect. This must be the same as the domain Authelia is served on or the root
 of the domain. For example if listening on auth.example.com the cookie should be auth.example.com or example.com.
 ### secret
 <div markdown="1">
 type: string
 {: .label .label-config .label-purple }
 required: yes
 {: .label .label-config .label-red }
 </div>
 The secret key used to encrypt session data in Redis. It's recommended this is set using a [secret](../secrets.md).
 ### expiration
 <div markdown="1">
 type: string (duration)
 {: .label .label-config .label-purple }
 default: 1h
 {: .label .label-config .label-blue }
 required: no
 {: .label .label-config .label-green }
 </div>
 The time in [duration notation format](../index.md#duration-notation-format) before the cookie expires and the session
 is destroyed. This is overriden by remember_me_duration when the remember me box is checked.
 ### inactivity
 <div markdown="1">
 type: string (duration)
 {: .label .label-config .label-purple }
 default: 5m
 {: .label .label-config .label-blue }
 required: no
 {: .label .label-config .label-green }
 </div>
 The time in [duration notation format](../index.md#duration-notation-format) the user can be inactive for until the
 session is destroyed. Useful if you want long session timers but don't want unused devices to be vulnerable.
 ### remember_me_duration
 <div markdown="1">
 type: string (duration)
 {: .label .label-config .label-purple }
 default: 1M
 {: .label .label-config .label-blue }
 required: no
 {: .label .label-config .label-green }
 </div>
 The time in [duration notation format](../index.md#duration-notation-format) the cookie expires and the session is
 destroyed when the remember me box is checked.
 ## Security
 Configuration of this section has an impact on security. You should read notes in
 [security measures](../../security/measures.md#session-security) for more information.
 ## Loading a password from a secret instead of inside the configuration
 Password can also be defined using a [secret](../secrets.md).
--- a/docs/configuration/session/redis.md
+++ b/docs/configuration/session/redis.md
@ -0,0 +1,224 @@
 ---
 layout: default
 title: Redis
 parent: Session
 grand_parent: Configuration
 nav_order: 1
 ---
 # Redis
 This is a session provider. By default Authelia uses an in-memory provider. Not configuring redis leaves Authelia
 [stateful](../../features/statelessness.md). It's important in highly available scenarios to configure this option and
 we highly recommend it in production environments. It requires you setup [redis] as well.
 ## Configuration
 ```yaml
 session:
  redis:
    host: 127.0.0.1
    port: 6379
    username: authelia
    password: authelia
    database_index: 0
    maximum_active_connections: 8
    minimum_idle_connections: 0
    tls:
      server_name: myredis.example.com
      skip_verify: false
      minimum_version: TLS1.2
    high_availability:
      sentinel_name: mysentinel
      sentinel_password: sentinel_specific_pass
      nodes:
        - host: sentinel-node1
          port: 26379
        - host: sentinel-node2
          port: 26379
      route_by_latency: false
      route_randomly: false
 ```
 ## Options
 ### host
 <div markdown="1">
 type: string
 {: .label .label-config .label-purple }
 required: yes
 {: .label .label-config .label-red }
 </div>
 The [redis] host or unix socket path. If utilising an IPv6 literal address it must be enclosed by square brackets and
 quoted:
 ```yaml
 host: "[fd00:1111:2222:3333::1]"
 ```
 ### port
 <div markdown="1">
 type: integer
 {: .label .label-config .label-purple }
 default: 6379
 {: .label .label-config .label-blue }
 required: no
 {: .label .label-config .label-green }
 </div>
 The port [redis] is listening on.
 ### username
 <div markdown="1">
 type: string
 {: .label .label-config .label-purple }
 required: no
 {: .label .label-config .label-green }
 </div>
 The username for [redis authentication](https://redis.io/commands/auth). Only supported in [redis] 6.0+, and [redis]
 currently offers backwards compatibility with password-only auth. You probably do not need to set this unless you went
 through the process of setting up [redis ACLs](https://redis.io/topics/acl).
 ### password
 <div markdown="1">
 type: string
 {: .label .label-config .label-purple }
 required: no
 {: .label .label-config .label-green }
 </div>
 The password for [redis authentication](https://redis.io/commands/auth).
 ### database_index
 <div markdown="1">
 type: integer
 {: .label .label-config .label-purple }
 default: 0
 {: .label .label-config .label-blue }
 required: no
 {: .label .label-config .label-green }
 </div>
 The index number of the [redis] database, the same value as specified with the redis SELECT command.
 ### maximum_active_connections
 <div markdown="1">
 type: integer
 {: .label .label-config .label-purple }
 default: 8
 {: .label .label-config .label-blue }
 required: no
 {: .label .label-config .label-green }
 </div>
 The maximum connections open to [redis] at the same time.
 ### minimum_idle_connections
 <div markdown="1">
 type: integer
 {: .label .label-config .label-purple }
 default: 0
 {: .label .label-config .label-blue }
 required: no
 {: .label .label-config .label-green }
 </div>
 The minimum number of [redis] connections to keep open as long as they don't exceed the maximum active connections. This
 is useful if there are long delays in establishing connections.
 ### tls
 If defined enables [redis] over TLS, and additionally controls the TLS connection validation process. You can see how to
 configure the tls section [here](../index.md#tls-configuration).
 ### high_availability
 When defining this session it enables [redis sentinel] connections. It's possible in
 the future we may add [redis cluster](https://redis.io/topics/cluster-tutorial).
 #### sentinel_name
 <div markdown="1">
 type: string
 {: .label .label-config .label-purple }
 required: yes
 {: .label .label-config .label-red }
 </div>
 The [redis sentinel] master name. This is defined in your [redis sentinel] configuration, it is not a hostname. This
 must be defined currently for a high availability configuration.
 #### sentinel_password
 <div markdown="1">
 type: string
 {: .label .label-config .label-purple }
 required: no
 {: .label .label-config .label-green }
 </div>
 The password for the [redis sentinel] connection. A [redis sentinel] username is not supported at this time due to the
 upstream library not supporting it.
 #### nodes
 A list of [redis sentinel] nodes to load balance over. This list is added to the host in the [redis] section above. It
 is required you either define the [redis] host or one [redis sentinel] node. The [redis] host must be a [redis sentinel]
 host, not a regular one. The individual [redis] hosts are determined using [redis sentinel] commands.
 Each node has a host and port configuration. Example:
 ```yaml
 - host: redis-sentinel-0
  port: 26379
 ```
 ##### host
 <div markdown="1">
 type: boolean
 {: .label .label-config .label-purple }
 default: false
 {: .label .label-config .label-blue }
 required: no
 {: .label .label-config .label-green }
 </div>
 The host of this [redis sentinel] node.
 ##### port
 <div markdown="1">
 type: integer
 {: .label .label-config .label-purple }
 default: 26379
 {: .label .label-config .label-blue }
 required: no
 {: .label .label-config .label-green }
 </div>
 The port of this [redis sentinel] node.
 #### route_by_latency
 <div markdown="1">
 type: boolean
 {: .label .label-config .label-purple }
 default: false
 {: .label .label-config .label-blue }
 required: no
 {: .label .label-config .label-green }
 </div>
 Prioritizes low latency [redis sentinel] nodes when set to true.
 #### route_randomly
 <div markdown="1">
 type: boolean
 {: .label .label-config .label-purple }
 default: false
 {: .label .label-config .label-blue }
 required: no
 {: .label .label-config .label-green }
 </div>
 Randomly chooses [redis sentinel] nodes when set to true.
 [redis]: https://redis.io
 [redis sentinel]: https://redis.io/topics/sentinel
--- a/docs/configuration/storage/index.md
+++ b/docs/configuration/storage/index.md
@ -17,4 +17,4 @@ The available options are:
 * [MariaDB](./mariadb.md)
 * [MySQL](./mysql.md)
 * [Postgres](./postgres.md)
-* [SQLite](./sqlite.md)
+* [SQLite](./sqlite.md)
--- a/docs/configuration/storage/mariadb.md
+++ b/docs/configuration/storage/mariadb.md
@ -8,6 +8,10 @@ nav_order: 1
 # MariaDB
 The MySQL storage provider also serves as a MariaDB provider.
 ## Configuration
 ```yaml
 storage:
  mysql:
@ -15,17 +19,68 @@ storage:
    port: 3306
    database: authelia
    username: authelia
    # Password can also be set using a secret: https://docs.authelia.com/configuration/secrets.html
    password: mypassword
 ```
-## IPv6 Addresses
+## Options
 ### host
 <div markdown="1">
 type: string
 {: .label .label-config .label-purple } 
 default: localhost
 {: .label .label-config .label-blue }
 required: no
 {: .label .label-config .label-green }
 </div>
 The database server host.
 If utilising an IPv6 literal address it must be enclosed by square brackets and quoted:
 ```yaml
 host: "[fd00:1111:2222:3333::1]"
 ```
-## Loading a password from a secret instead of inside the configuration
+### port
 <div markdown="1">
 type: integer
 {: .label .label-config .label-purple } 
 default: 3306
 {: .label .label-config .label-blue }
 required: no
 {: .label .label-config .label-green }
 </div>
-Password can also be defined using a [secret](../secrets.md).
+The port the database server is listening on.
 ### database
 <div markdown="1">
 type: string
 {: .label .label-config .label-purple }
 required: yes
 {: .label .label-config .label-red }
 </div>
 The database name on the database server that the assigned [user](#username) has access to for the purpose of
 **Authelia**.
 ### username
 <div markdown="1">
 type: string
 {: .label .label-config .label-purple }
 required: yes
 {: .label .label-config .label-red }
 </div>
 The username paired with the password used to connect to the database.
 ### password
 <div markdown="1">
 type: string
 {: .label .label-config .label-purple }
 required: yes
 {: .label .label-config .label-red }
 </div>
 The password paired with the username used to connect to the database. Can also be defined using a
 [secret](../secrets.md) which is also the recommended way when running as a container.
--- a/docs/configuration/storage/mysql.md
+++ b/docs/configuration/storage/mysql.md
@ -8,6 +8,10 @@ nav_order: 2
 # MySQL
 The MySQL storage provider.
 ## Configuration
 ```yaml
 storage:
  mysql:
@ -15,17 +19,68 @@ storage:
    port: 3306
    database: authelia
    username: authelia
    # Password can also be set using a secret: https://docs.authelia.com/configuration/secrets.html
    password: mypassword
 ```
-## IPv6 Addresses
+## Options
 ### host
 <div markdown="1">
 type: string
 {: .label .label-config .label-purple } 
 default: localhost
 {: .label .label-config .label-blue }
 required: no
 {: .label .label-config .label-green }
 </div>
 The database server host.
 If utilising an IPv6 literal address it must be enclosed by square brackets and quoted:
 ```yaml
 host: "[fd00:1111:2222:3333::1]"
 ```
-## Loading a password from a secret instead of inside the configuration
+### port
 <div markdown="1">
 type: integer
 {: .label .label-config .label-purple } 
 default: 3306
 {: .label .label-config .label-blue }
 required: no
 {: .label .label-config .label-green }
 </div>
-Password can also be defined using a [secret](../secrets.md).
+The port the database server is listening on.
 ### database
 <div markdown="1">
 type: string
 {: .label .label-config .label-purple }
 required: yes
 {: .label .label-config .label-red }
 </div>
 The database name on the database server that the assigned [user](#username) has access to for the purpose of
 **Authelia**.
 ### username
 <div markdown="1">
 type: string
 {: .label .label-config .label-purple }
 required: yes
 {: .label .label-config .label-red }
 </div>
 The username paired with the password used to connect to the database.
 ### password
 <div markdown="1">
 type: string
 {: .label .label-config .label-purple }
 required: yes
 {: .label .label-config .label-red }
 </div>
 The password paired with the username used to connect to the database. Can also be defined using a
 [secret](../secrets.md) which is also the recommended way when running as a container.
--- a/docs/configuration/storage/postgres.md
+++ b/docs/configuration/storage/postgres.md
@ -8,6 +8,10 @@ nav_order: 3
 # PostgreSQL
 The PostgreSQL storage provider.
 ## Configuration
 ```yaml
 storage:
  postgres:
@ -15,26 +19,79 @@ storage:
    port: 5432
    database: authelia
    username: authelia
    # Password can also be set using a secret: https://docs.authelia.com/configuration/secrets.html
    password: mypassword
    sslmode: disable
 ```
-## IPv6 Addresses
+## Options
 ### host
 <div markdown="1">
 type: string
 {: .label .label-config .label-purple } 
 default: localhost
 {: .label .label-config .label-blue }
 required: no
 {: .label .label-config .label-green }
 </div>
 The database server host.
 If utilising an IPv6 literal address it must be enclosed by square brackets and quoted:
 ```yaml
 host: "[fd00:1111:2222:3333::1]"
 ```
-## SSL Mode
+### port
 <div markdown="1">
 type: integer
 {: .label .label-config .label-purple } 
 default: 5432
 {: .label .label-config .label-blue }
 required: no
 {: .label .label-config .label-green }
 </div>
-SSL mode configures how to handle SSL connections with Postgres. 
+The port the database server is listening on.
 ### database
 The database name on the database server that the assigned [user](#username) has access to for the purpose of
 **Authelia**.
 ### username
 <div markdown="1">
 type: string
 {: .label .label-config .label-purple }
 required: yes
 {: .label .label-config .label-red }
 </div>
 The username paired with the password used to connect to the database.
 ### password
 <div markdown="1">
 type: string
 {: .label .label-config .label-purple }
 required: yes
 {: .label .label-config .label-red }
 </div>
 The password paired with the username used to connect to the database. Can also be defined using a
 [secret](../secrets.md) which is also the recommended way when running as a container.
 ### sslmode
 <div markdown="1">
 type: string
 {: .label .label-config .label-purple }
 default: disable
 {: .label .label-config .label-blue }
 required: no
 {: .label .label-config .label-green }
 </div>
 SSL mode configures how to handle SSL connections with Postgres.
 Valid options are 'disable', 'require', 'verify-ca', or 'verify-full'.
 See the [PostgreSQL Documentation](https://www.postgresql.org/docs/12/libpq-ssl.html)
-or [pgx - PostgreSQL Driver and Toolkit Documentation](https://pkg.go.dev/github.com/jackc/pgx?tab=doc) 
+or [pgx - PostgreSQL Driver and Toolkit Documentation](https://pkg.go.dev/github.com/jackc/pgx?tab=doc)
 for more information.
 ## Loading a password from a secret instead of inside the configuration
 Password can also be defined using a [secret](../secrets.md).
--- a/docs/configuration/storage/sqlite.md
+++ b/docs/configuration/storage/sqlite.md
@ -12,12 +12,26 @@ If you don't have a SQL server, you can use [SQLite](https://en.wikipedia.org/wi
 However please note that this setup will prevent you from running multiple
 instances of Authelia since the database will be a local file.
-## Configuration
+Use of this storage provider leaves Authelia [stateful](../features/statelessness.md). It's important in highly
 available scenarios to use one of the other providers, and we highly recommend it in production environments, but this
 requires you setup an external database.
-Just give the path to the sqlite database. It will be created if the file does not exist.
+## Configuration
 ```yaml
 storage:
  local:
    path: /config/db.sqlite3
 ```
 ## Options
 ### path
 <div markdown="1">
 type: string
 {: .label .label-config .label-blue }
 required: yes
 {: .label .label-config .label-red }
 </div>
 The path where the SQLite3 database file will be stored. It will be created if the file does not exist.
--- a/docs/configuration/theme.md
+++ b/docs/configuration/theme.md
@ -17,6 +17,5 @@ There are currently 3 available themes for Authelia:
 ## Configuration
 ```yaml
 # The theme to display: light, dark, grey
 theme: light
-```
+```
--- a/docs/contributing/authelia-scripts.md
+++ b/docs/contributing/authelia-scripts.md
@ -7,28 +7,38 @@ nav_order: 2
 # Authelia Scripts
-Authelia comes with a set of dedicated scripts doing a broad range of operations such as
+Authelia comes with a set of dedicated scripts to perform a broad range of operations such as building the distributed 
-building the distributed version of Authelia, building the Docker image, running suites,
+version of Authelia, building the Docker image, running suites, testing the code, etc...
 testing the code, etc...
-Those scripts becomes available after sourcing the bootstrap.sh script with
+Those scripts become available after sourcing the bootstrap.sh script with
-    $ source bootstrap.sh
+```console
 $ source bootstrap.sh
 ```
 Then, you can access the scripts usage by running the following command:
-    $ authelia-scripts --help
+```console
 $ authelia-scripts --help
 ```
 For instance, you can build Authelia (Go binary and frontend) with:
-    $ authelia-scripts build
+```console
 $ authelia-scripts build
 ```
 Or build the official Docker image with:
-    $ authelia-scripts docker build
+```console
 $ authelia-scripts docker build
 ```
 Or start the *Standalone* suite with:
-    $ authelia-scripts suites setup Standalone
+```console
 $ authelia-scripts suites setup Standalone
 ```
-You will find more information in the scripts usage helpers.
+You will find more information in the scripts usage helpers.
--- a/docs/contributing/build-and-dev.md
+++ b/docs/contributing/build-and-dev.md
@ -7,84 +7,82 @@ nav_order: 1
 # Build & Dev
-**Authelia** is written in Go and comes with a dedicated CLI called
+**Authelia** is written in Go and comes with a dedicated CLI called [authelia-scripts](./authelia-scripts.md) which is 
-[authelia-scripts](./authelia-scripts.md) which is available after
+available after running `source bootstrap.sh`. This CLI provides many useful tools to help you during development.
 running `source bootstrap.sh`. This CLI provides many useful tools
 to help you during development.
-In order to build and contribute to **Authelia**, you need to make
+In order to build and contribute to **Authelia**, you need to make sure Go >= v1.16, Docker, docker-compose and 
-sure Go >= v1.13, Docker, docker-compose and Node >= v12 are installed on
+Node >= v12 are installed on your machine.
 your machine.
 ## Get started
-**Authelia** is made of Go application serving the API and a
+**Authelia** is made of Go application serving the API and a [React](https://reactjs.org/) application for the portal.
 [React](https://reactjs.org/) application for the portal.
-In order to ease development, Authelia uses the concept of [suites] to
+In order to ease development, Authelia uses the concept of [suites] to run Authelia from source code so that your 
-run Authelia from source code so that your patches are included. This
+patches are included. This is a kind of virtual environment running **Authelia** in a complete ecosystem 
-is a kind of virtual environment running **Authelia** in a complete
+(LDAP, Redis, SQL server). Note that Authelia is hot-reloaded in the environment so that your patches are instantly 
-ecosystem (LDAP, Redis, SQL server). Note that Authelia is hot-reloaded
+included.
 in the environment so that your patches are instantly included.
 The next command starts the suite called *Standalone*:
-    $ authelia-scripts suites setup Standalone
+```console
 $ authelia-scripts suites setup Standalone
 ```
-Most of the suites are using docker-compose to bootstrap the
+Most of the suites are using docker-compose to bootstrap the environment. Therefore, you can check the logs of all 
-environment. Therefore, you can check the logs of all application
+application by running the following command on the component you want to monitor.
 by running the following command on the component you want to
 monitor.
-    $ docker logs authelia_authelia-backend_1 -f
+```console
 $ docker logs authelia_authelia-backend_1 -f
 ```
-Then, edit the code and observe how **Authelia** is automatically
+Then, edit the code and observe how **Authelia** is automatically reloaded.
 reloaded.
 ### Unit tests
 To run the unit tests, run:
-    $ authelia-scripts unittest
+```console
 $ authelia-scripts unittest
 ```
 ### Integration tests
-Integration tests are located under the `internal/suites` directory
+Integration tests are located under the `internal/suites` directory and are based on Selenium. A suite is a combination 
-and are based on Selenium. A suite is a combination of environment
+of environment and tests. Executing a suite therefore means starting the environment, running the tests and tearing down 
-and tests. Executing a suite therefore means starting the environment,
+the environment. Each step can be run independently:
 running the tests and tearing down the environment. Each step can be
 run independently:
-    # List the available suites
+```console
-    $ authelia-scripts suites list
+# List the available suites
-    Standalone
+$ authelia-scripts suites list
-    DuoPush
+Standalone
-    LDAP
+DuoPush
-    Traefik
+LDAP
 Traefik
-    # Start the environment of Standalone suite.
+# Start the environment of Standalone suite.
-    $ authelia-scripts suites setup Standalone
+$ authelia-scripts suites setup Standalone
-    # Run the tests related to the currently running suite.
+# Run the tests related to the currently running suite.
-    $ authelia-scripts suites test
+$ authelia-scripts suites test
-    # Tear down the environment
+# Tear down the environment
-    $ authelia-scripts suites teardown Standalone
+$ authelia-scripts suites teardown Standalone
 ```
 In order to test all suites (approx 30 minutes), you need to make sure there is no currently running suite and then you 
 should run:
-In order to test all suites (approx 30 minutes), you need to make
+```console
-sure there is no currently running suite and then you should run:
+$ authelia-scripts suites test
 ```
-    $ authelia-scripts suites test
+Also, you don't need to start the suite before testing it. Given you're not running any suite, just use the following 
 command to test the *Standalone* suite.
-Also, you don't need to start the suite before testing it. Given
+```console
-you're not running any suite, just use the following command to
+$ authelia-scripts suites test Standalone
-test the *Standalone* suite.
+```
    $ authelia-scripts suites test Standalone
 The suite will be spawned, tests will be run and then the suite
 will be torn down automatically.
 The suite will be spawned, tests will be run and then the suite will be torn down automatically.
 [suites]: ./suites.md
--- a/docs/contributing/commitmsg-guidelines.md
+++ b/docs/contributing/commitmsg-guidelines.md
@ -26,9 +26,11 @@ Each commit message consists of a **header**, a **body**, and a **footer**.
 The `header` is mandatory and must conform to the [Commit Message Header](#commit-message-header) format.
 The `body` is mandatory for all commits except for those of type "docs".
-When the body is present it must be at least 20 characters long and must conform to the [Commit Message Body](#commit-message-body) format.
+When the body is present it must be at least 20 characters long and must conform to the 
 [Commit Message Body](#commit-message-body) format.
-The `footer` is optional. The [Commit Message Footer](#commit-message-footer) format describes what the footer is used for, and the structure it must have.
+The `footer` is optional. The [Commit Message Footer](#commit-message-footer) format describes what the footer is used 
 for, and the structure it must have.
 Any line of the commit message cannot be longer than 100 characters.
@ -50,8 +52,10 @@ The `<type>` and `<summary>` fields are mandatory, the `(<scope>)` field is opti
 #### Allowed `<type>` values:
-* **build** Changes that affect the build system or external dependencies (example scopes: bundler, deps, docker, go, npm)
+* **build** Changes that affect the build system or external dependencies 
-* **ci** Changes to our CI configuration files and scripts (example scopes: autheliabot, buildkite, codecov, golangci-lint, renovate, reviewdog)
+  (example scopes: bundler, deps, docker, go, npm)
 * **ci** Changes to our CI configuration files and scripts 
  (example scopes: autheliabot, buildkite, codecov, golangci-lint, renovate, reviewdog)
 * **docs** Documentation only changes
 * **feat** A new feature
 * **fix** A bug fix
@ -62,7 +66,8 @@ The `<type>` and `<summary>` fields are mandatory, the `(<scope>)` field is opti
 #### Allowed `<scope>` values:
-The scope should be the name of the package affected (as perceived by the person reading the changelog generated from commit messages).
+The scope should be the name of the package affected 
 (as perceived by the person reading the changelog generated from commit messages).
 * authentication
 * authorization
@ -91,7 +96,9 @@ There are currently a few exceptions to the "use package name" rule:
 * `web`: used for changes to the React based frontend
-* none/empty string: useful for `test`, `refactor` and changes that are done across multiple packages (e.g. `test: add missing unit tests`) and for docs changes that are not related to a specific package (e.g. `docs: fix typo in tutorial`).
+* none/empty string: useful for `test`, `refactor` and changes that are done across multiple packages 
  (e.g. `test: add missing unit tests`) and for docs changes that are not related to a 
  specific package (e.g. `docs: fix typo in tutorial`).
 #### Summary
@ -106,13 +113,15 @@ Use the summary field to provide a succinct description of the change:
 Just as in the summary, use the imperative, present tense: "fix" not "fixed" nor "fixes".
-Explain the motivation for the change in the commit message body. This commit message should explain _why_ you are making the change.
+Explain the motivation for the change in the commit message body. This commit message should explain _why_ you are 
-You can include a comparison of the previous behavior with the new behavior in order to illustrate the impact of the change.
+making the change. You can include a comparison of the previous behavior with the new behavior in order to illustrate 
 the impact of the change.
 ### Commit Message Footer
-The footer can contain information about breaking changes and is also the place to reference GitHub issues and other PRs that this commit closes or is related to.
+The footer can contain information about breaking changes and is also the place to reference GitHub issues and other PRs 
 that this commit closes or is related to.
 ```
 BREAKING CHANGE: <breaking change summary>
@ -123,7 +132,8 @@ BREAKING CHANGE: <breaking change summary>
 Fixes #<issue number>
 ```
-Breaking Change section should start with the phrase "BREAKING CHANGE: " followed by a summary of the breaking change, a blank line, and a detailed description of the breaking change that also includes migration instructions.
+Breaking Change section should start with the phrase "BREAKING CHANGE: " followed by a summary of the breaking change, a 
 blank line, and a detailed description of the breaking change that also includes migration instructions.
 ### Revert commits
--- a/docs/contributing/index.md
+++ b/docs/contributing/index.md
@ -11,16 +11,20 @@ has_children: true
 **Authelia** and its development workflow can be tested with Docker and docker-compose on Linux.
-In order to deploy the current version of Authelia locally, run the following command and follow the instructions of bootstrap.sh:
+In order to deploy the current version of Authelia locally, run the following command and follow the instructions of 
 bootstrap.sh:
-    $ source bootstrap.sh
+```console
 $ source bootstrap.sh
 ```
 Then, start the *Standalone* [suite].
 ```console
 $ authelia-scripts suites setup Standalone
 ```
-    $ authelia-scripts suites setup Standalone
+A [suite] is kind of a virtual environment for running Authelia in a complete ecosystem. If you want more details please 
-
+read the related [documentation](./suites.md).
 A [suite] is kind of a virtual environment for running Authelia in a complete ecosystem.
 If you want more details please read the related [documentation](./suites.md).
 ## FAQ
@ -28,25 +32,30 @@ If you want more details please read the related [documentation](./suites.md).
 Here are the versions used for testing in Buildkite:
-    $ docker --version
+```console
-    Docker version 19.03.5, build 633a0ea838
+$ docker --version
 Docker version 19.03.5, build 633a0ea838
-    $ docker-compose --version
+$ docker-compose --version
-    docker-compose version 1.24.1, build unknown
+docker-compose version 1.24.1, build unknown
 ```
 ### How can I serve my application under example.com?
-Don't worry, you don't need to own the domain *example.com* to test Authelia.
+Don't worry, you don't need to own the domain *example.com* to test Authelia. Copy the following lines in 
-Copy the following lines in your `/etc/hosts`.
+your `/etc/hosts`.
-    192.168.240.100 home.example.com
+```
-    192.168.240.100 login.example.com
+192.168.240.100 home.example.com
-    192.168.240.100 singlefactor.example.com
+192.168.240.100 login.example.com
-    192.168.240.100 public.example.com
+192.168.240.100 singlefactor.example.com
-    192.168.240.100 secure.example.com
+192.168.240.100 public.example.com
-    192.168.240.100 mail.example.com
+192.168.240.100 secure.example.com
-    192.168.240.100 mx1.mail.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 added you can access the listed sub-domains from your browser, and they will target the reverse proxy.
+`192.168.240.100` is the IP attributed by Docker to the reverse proxy. Once added you can access the listed sub-domains 
 from your browser, and they will target the reverse proxy.
 [suite]: ./suites.md
--- a/docs/contributing/style-guide.md
+++ b/docs/contributing/style-guide.md
@ -0,0 +1,44 @@
 ---
 layout: default
 title: Style Guide
 parent: Contributing
 nav_order: 4
 ---
 # Style Guide
 This is a general guide to the code style we aim to abide by. This is by no means an exhaustive list and we're
 constantly changing and improving it. This is also a work in progress document.
 For our commit messages please see our [Commit Message Guidelines](./commitmsg-guidelines.md).
 ## Tools
 We implement the following tools that help us abide by our style guide and include the configuration for them inside
 our repository:
 - [golangci-lint](https://github.com/golangci/golangci-lint)
 - [yamllint](https://yamllint.readthedocs.io/en/stable/)
 - [eslint](https://eslint.org/)
 - [prettier](https://prettier.io/)
 ## Exceptions
 This is a style **guide** not a cudgel, there are always going to be exceptions to these guidelines when it makes sense 
 not to follow them. One notable exception is the README.md for the repository. The line length of the 
 [All Contributors](https://allcontributors.org/) individual sections are longer than 120 characters and it doesn't make
 sense to apply the [line length](#line-length) guidelines.
 ## Specific Guidelines
 ### Line Length
 We aim to keep all files to a maximum line length of 120 characters. This allows for most modern computer systems to
 display two files side by side (vertically split). As always, keep in mind you should not restrict your line length
 when it doesn't make sense to.
 This includes but is not limited to the following file types:
 - Go (*.go)
 - YAML (*.yml, *.yaml)
 - Markdown (*.md)
 - JavaScript (*.js)  
 - TypeScript (*.ts, *.tsx)
--- a/docs/contributing/suites.md
+++ b/docs/contributing/suites.md
@ -2,7 +2,7 @@
 layout: default
 title: Suites
 parent: Contributing
-nav_order: 3
+nav_order: 5
 ---
 # Suites
--- a/docs/deployment/deployment-kubernetes.md
+++ b/docs/deployment/deployment-kubernetes.md
@ -11,7 +11,16 @@ nav_order: 3
    <img src="../images/logos/kubernetes.logo.png" width="100" style="padding-right: 10px">
 </p>
-UNDER CONSTRUCTION
+## UNDER CONSTRUCTION
 The following areas are actively being worked on for Kubernetes:
 1. Detailed Documentaiton
 2. [Helm Chart (v3)](https://github.com/authelia/chartrepo)
 3. Kustomize Deployment
 4. Manifest Examples
 Users are welcome to reach out directly on our [Matrix Room](https://riot.im/app/#/room/#authelia:matrix.org) or 
 [Discord Server](https://discord.authelia.com) if they are looking for help setting up on Kubernetes in the meantime. 
 ## FAQ
--- a/docs/deployment/deployment-lite.md
+++ b/docs/deployment/deployment-lite.md
@ -31,7 +31,7 @@ setup can easily be adapted to utilise said [service](../configuration/storage/i
 ## Steps
 - `git clone https://github.com/authelia/authelia.git`
- `cd authelia/compose/lite`
+- `cd authelia/examples/compose/lite`
 - Modify the `users_database.yml` the default username and password is `authelia`
 - Modify the `configuration.yml` and `docker-compose.yml` with your respective domains and secrets
 - `docker-compose up -d`
--- a/docs/faq.md
+++ b/docs/faq.md
@ -8,4 +8,5 @@ nav_order: 8
 ## How can the backend be aware of the authenticated users?
-This question is solved [here](https://docs.authelia.com/deployment/supported-proxies/#how-can-the-backend-be-aware-of-the-authenticated-users).
+This question is solved
 [here](https://www.authelia.com/docs/deployment/supported-proxies/#how-can-the-backend-be-aware-of-the-authenticated-users).
--- a/docs/features/statelessness.md
+++ b/docs/features/statelessness.md
@ -0,0 +1,57 @@
 ---
 layout: default
 title: Statelessness
 parent: Features
 nav_order: 7
 ---
 # Statelessness
 **Authelia** supports operating as a stateless application. This is incredibly important
 when running in highly available deployments like you may see in platforms like Kubernetes.
 ## Stateful Considerations
 There are some components within **Authelia** that may optionally be made stateful by using
 certain providers. Examples of this are as follows:
 ### Session Provider
 **Severity:** *BREAKING*.
 **Solution:** Use a session provider other than memory (Redis).
 If you do not configure an external provider for the session configuration
 it stores the session in memory. This is unacceptable for the operation of
 **Authelia** and is thus not supported for high availability.
 ### Storage Provider
 **Severity:** *BREAKING*.
 **Solution:** Use a session provider other than SQLite3 (MySQL, MariaDB, PostgreSQL).
 Use of the local storage provider (SQLite3) is not supported in high availability setups
 due to a design limitation with how SQLite3 operates. Use any of the other storage providers.
 ### Notification Provider
 **Severity:** *HIGH*.
 **Solution:** Use a notification provider other than file system (SMTP).
 Use of the file system notification provider prevents users from several key tasks which heavily impact usability of
 the system, and technically reduce security. Users will be unable to reset passwords or register new 2FA devices on
 their own. The file system provider is not supported for high availability. 
 ### Authentication Provider
 **Severity:** *MEDIUM (limiting)*.
 **Solution:** Use an authentication provider other than file (LDAP), or distribute the file and disable password reset.
 Use of the file authentication provider (YAML) is only partially supported with high availability setups. It's 
 recommended if you don't use a stateless provider that you disable password reset and make sure the file is distributed 
 to all instances. We do not support using the file type in these scenarios.
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@ -13,7 +13,7 @@ nav_order: 2
 These commands are intended to be run sequentially:
 - `git clone https://github.com/authelia/authelia.git`
- `cd authelia/compose/local`
+- `cd authelia/examples/compose/local`
 - `sudo ./setup.sh` *sudo is required to modify the `/etc/hosts` file*
 You can now visit the following locations; replace example.com with the domain you specified in the setup script:
--- a/docs/roadmap.md
+++ b/docs/roadmap.md
@ -17,7 +17,7 @@ Below are the prioritised roadmap items:
 1. [Authelia acts as an OpenID Connect Provider](https://github.com/authelia/authelia/issues/189). This is a high
 priority because currently the only way to pass authentication information back to the protected app is through the
 use of HTTP headers as described
-[here](https://docs.authelia.com/deployment/supported-proxies/#how-can-the-backend-be-aware-of-the-authenticated-users)
+[here](https://www.authelia.com/docs/deployment/supported-proxies/#how-can-the-backend-be-aware-of-the-authenticated-users)
 however, many apps either do not support this method or are starting to move away from this in favour of OpenID Connect or OAuth2
 internally or via plugins.
--- a/docs/security/index.md
+++ b/docs/security/index.md
@ -15,8 +15,8 @@ If you discover a vulnerability in Authelia, please first contact one of the mai
 either via [Matrix](#matrix) or [email](#email) as described in the [contact options](#contact-options) below.
 For details about security measures implemented in Authelia, please follow
-this [link](https://docs.authelia.com/security/measures.html) and for reading about 
+this [link](https://www.authelia.com/docs/security/measures.html) and for reading about 
-the threat model follow this [link](https://docs.authelia.com/security/threat-model.html).
+the threat model follow this [link](https://www.authelia.com/docs/security/threat-model.html).
 ## Contact Options
--- a/examples/compose/lite/authelia/configuration.yml
+++ b/examples/compose/lite/authelia/configuration.yml
@ -1,3 +1,4 @@
 ---
 ###############################################################
 #                   Authelia configuration                    #
 ###############################################################
@ -11,7 +12,7 @@ default_redirection_url: https://public.example.com
 totp:
  issuer: authelia.com
-#duo_api:
+# duo_api:
 #  hostname: api-123456789.example.com
 #  integration_key: ABCDEF
 #  # This secret can also be set using the env variables AUTHELIA_DUO_API_SECRET_KEY_FILE
@ -36,9 +37,9 @@ session:
  name: authelia_session
  # This secret can also be set using the env variables AUTHELIA_SESSION_SECRET_FILE
  secret: unsecure_session_secret
-  expiration: 3600 # 1 hour
+  expiration: 3600  # 1 hour
-  inactivity: 300 # 5 minutes
+  inactivity: 300  # 5 minutes
-  domain: example.com # Should match whatever your root protected domain is
+  domain: example.com  # Should match whatever your root protected domain is
  redis:
    host: redis
@ -62,4 +63,5 @@ notifier:
    password: password
    host: mail.example.com
    port: 25
-    sender: admin@example.com
+    sender: admin@example.com
 ...
--- a/examples/compose/lite/authelia/users_database.yml
+++ b/examples/compose/lite/authelia/users_database.yml
@ -1,3 +1,4 @@
 ---
 ###############################################################
 #                         Users Database                      #
 ###############################################################
@ -8,8 +9,10 @@
 users:
  authelia:
    displayname: "Authelia User"
-    password: "$6$rounds=50000$BpLnfgDsc2WD8F2q$Zis.ixdg9s/UOJYrs56b5QEZFiZECu0qZVNsIYxBaNJ7ucIL.nlxVCT5tqh8KHG8X4tlwCFm5r6NTOZZ5qRFN/" # Password is 'authelia'
+    # Password is Authelia
    password: "$6$rounds=50000$BpLnfgDsc2WD8F2q$Zis.ixdg9s/UOJYrs56b5QEZFiZECu0qZVNsIYxBaNJ7ucIL.nlxVCT5tqh8KHG8X4tlwCFm5r6NTOZZ5qRFN/"  # yamllint disable-line rule:line-length
    email: authelia@authelia.com
    groups:
      - admins
-      - dev
+      - dev
 ...
--- a/examples/compose/lite/docker-compose.yml
+++ b/examples/compose/lite/docker-compose.yml
@ -1,3 +1,4 @@
 ---
 version: '3.3'
 networks:
@ -18,9 +19,9 @@ services:
      - 'traefik.http.routers.authelia.entrypoints=https'
      - 'traefik.http.routers.authelia.tls=true'
      - 'traefik.http.routers.authelia.tls.certresolver=letsencrypt'
-      - 'traefik.http.middlewares.authelia.forwardauth.address=http://authelia:9091/api/verify?rd=https://auth.example.com'
+      - 'traefik.http.middlewares.authelia.forwardauth.address=http://authelia:9091/api/verify?rd=https://auth.example.com'  # yamllint disable-line rule:line-length
      - 'traefik.http.middlewares.authelia.forwardauth.trustForwardHeader=true'
-      - 'traefik.http.middlewares.authelia.forwardauth.authResponseHeaders=Remote-User, Remote-Groups, Remote-Name, Remote-Email'
+      - 'traefik.http.middlewares.authelia.forwardauth.authResponseHeaders=Remote-User,Remote-Groups,Remote-Name,Remote-Email'  # yamllint disable-line rule:line-length
    expose:
      - 9091
    restart: unless-stopped
@ -108,3 +109,4 @@ services:
    expose:
      - 80
    restart: unless-stopped
 ...
--- a/examples/compose/local/.gitignore
+++ b/examples/compose/local/.gitignore
--- a/examples/compose/local/authelia/configuration.yml
+++ b/examples/compose/local/authelia/configuration.yml
@ -1,3 +1,4 @@
 ---
 ###############################################################
 #                   Authelia configuration                    #
 ###############################################################
@ -27,9 +28,9 @@ access_control:
 session:
  name: authelia_session
  secret: unsecure_session_secret
-  expiration: 3600 # 1 hour
+  expiration: 3600  # 1 hour
-  inactivity: 300 # 5 minutes
+  inactivity: 300  # 5 minutes
-  domain: example.com # Should match whatever your root protected domain is
+  domain: example.com  # Should match whatever your root protected domain is
 regulation:
  max_retries: 3
@ -42,4 +43,5 @@ storage:
 notifier:
  filesystem:
-    filename: /config/notification.txt
+    filename: /config/notification.txt
 ...
--- a/examples/compose/local/authelia/users_database.yml
+++ b/examples/compose/local/authelia/users_database.yml
@ -1,3 +1,4 @@
 ---
 ###############################################################
 #                         Users Database                      #
 ###############################################################
@ -12,4 +13,5 @@ users:
    email: <USERNAME>@example.com
    groups:
      - admins
-      - dev
+      - dev
 ...
--- a/examples/compose/local/docker-compose.yml
+++ b/examples/compose/local/docker-compose.yml
@ -1,3 +1,4 @@
 ---
 version: '3.3'
 networks:
@ -18,9 +19,9 @@ services:
      - 'traefik.http.routers.authelia.entrypoints=https'
      - 'traefik.http.routers.authelia.tls=true'
      - 'traefik.http.routers.authelia.tls.options=default'
-      - 'traefik.http.middlewares.authelia.forwardauth.address=http://authelia:9091/api/verify?rd=https://authelia.example.com'
+      - 'traefik.http.middlewares.authelia.forwardauth.address=http://authelia:9091/api/verify?rd=https://authelia.example.com'  # yamllint disable-line rule:line-length
      - 'traefik.http.middlewares.authelia.forwardauth.trustForwardHeader=true'
-      - 'traefik.http.middlewares.authelia.forwardauth.authResponseHeaders=Remote-User, Remote-Groups, Remote-Name, Remote-Email'
+      - 'traefik.http.middlewares.authelia.forwardauth.authResponseHeaders=Remote-User,Remote-Groups,Remote-Name,Remote-Email'  # yamllint disable-line rule:line-length
    expose:
      - 9091
    restart: unless-stopped
@ -92,4 +93,5 @@ services:
      - 'traefik.http.routers.public.middlewares=authelia@docker'
    expose:
      - 80
-    restart: unless-stopped
+    restart: unless-stopped
 ...
--- a/examples/compose/local/setup.sh
+++ b/examples/compose/local/setup.sh
--- a/examples/compose/local/traefik/certificates.yml
+++ b/examples/compose/local/traefik/certificates.yml
@ -1,4 +1,6 @@
 ---
 tls:
  certificates:
    - certFile: /etc/traefik/certs/cert.pem
-      keyFile: /etc/traefik/certs/key.pem
+      keyFile: /etc/traefik/certs/key.pem
 ...
--- a/internal/configuration/config.template.yml
+++ b/internal/configuration/config.template.yml
@ -1,10 +1,14 @@
-###############################################################
+# yamllint disable rule:comments-indentation
-#                   Authelia configuration                    #
+---
-###############################################################
+###############################################################################
 #                           Authelia Configuration                            #
 ###############################################################################
-# The host and port to listen on
+## The host and port to listen on.
 host: 0.0.0.0
 port: 9091
 ## The TLS key and cert used with Authelia.
 # tls_key: /config/ssl/key.pem
 # tls_cert: /config/ssl/cert.pem
@ -13,245 +17,250 @@ port: 9091
 ## They should be in base64 format, and have one of the following extensions: *.cer, *.crt, *.pem.
 # certificates_directory: /config/certificates
-# The theme to display: light, dark, grey
+## The theme to display: light, dark, grey.
 theme: light
-# Configuration options specific to the internal http server
+##
 ## Server Configuration
 ##
 server:
-  # Buffers usually should be configured to be the same value.
+  ## Buffers usually should be configured to be the same value.
-  # Explanation at https://docs.authelia.com/configuration/server.html
+  ## Explanation at https://www.authelia.com/docs/configuration/server.html
-  # Read buffer size configures the http server's maximum incoming request size in bytes.
+  ## Read buffer size adjusts the server's max incoming request size in bytes.
  ## Write buffer size does the same for outgoing responses.
  read_buffer_size: 4096
  # Write buffer size configures the http server's maximum outgoing response size in bytes.
  write_buffer_size: 4096
-  # Set the single level path Authelia listens on, must be alphanumeric chars and should not contain any slashes.
+  ## Set the single level path Authelia listens on.
  ## Must be alphanumeric chars and should not contain any slashes.
  path: ""
-# Level of verbosity for logs: info, debug, trace
+## Level of verbosity for logs: info, debug, trace.
 log_level: debug
-# Format the logs are written as: json, text
+
 ## Format the logs are written as: json, text.
 # log_format: json
-# File path where the logs will be written. If not set logs are written to stdout.
+
 ## File path where the logs will be written. If not set logs are written to stdout.
 # log_file_path: /config/authelia.log
-# The secret used to generate JWT tokens when validating user identity by
+## The secret used to generate JWT tokens when validating user identity by email confirmation. JWT Secret can also be
-# email confirmation.
+## set using a secret: https://www.authelia.com/docs/configuration/secrets.html
 # JWT Secret can also be set using a secret: https://docs.authelia.com/configuration/secrets.html
 jwt_secret: a_very_important_secret
-# Default redirection URL
+## Default redirection URL
-#
+##
-# If user tries to authenticate without any referer, Authelia
+## If user tries to authenticate without any referer, Authelia does not know where to redirect the user to at the end
-# does not know where to redirect the user to at the end of the
+## of the authentication process. This parameter allows you to specify the default redirection URL Authelia will use
-# authentication process.
+## in such a case.
-# This parameter allows you to specify the default redirection
+##
-# URL Authelia will use in such a case.
+## Note: this parameter is optional. If not provided, user won't be redirected upon successful authentication.
 #
 # Note: this parameter is optional. If not provided, user won't
 # be redirected upon successful authentication.
 default_redirection_url: https://home.example.com:8080/
-# TOTP Settings
+##
-#
+## TOTP Configuration
-# Parameters used for TOTP generation
+##
 ## Parameters used for TOTP generation.
 totp:
-  # The issuer name displayed in the Authenticator application of your choice
+  ## The issuer name displayed in the Authenticator application of your choice
-  # See: https://github.com/google/google-authenticator/wiki/Key-Uri-Format for more info on issuer names
+  ## See: https://github.com/google/google-authenticator/wiki/Key-Uri-Format for more info on issuer names
  issuer: authelia.com
-  # The period in seconds a one-time password is current for. Changing this will require all users to register
+  ## The period in seconds a one-time password is current for. Changing this will require all users to register
-  # their TOTP applications again.
+  ## their TOTP applications again. Warning: before changing period read the docs link below.
  # Warning: before changing period read the docs link below.
  period: 30
-  # The skew controls number of one-time passwords either side of the current one that are valid.
+  ## The skew controls number of one-time passwords either side of the current one that are valid.
-  # Warning: before changing skew read the docs link below.
+  ## Warning: before changing skew read the docs link below.
  skew: 1
-  #  See: https://docs.authelia.com/configuration/one-time-password.html#period-and-skew to read the documentation.
+  ## See: https://www.authelia.com/docs/configuration/one-time-password.html#period-and-skew to read the documentation.
-# Duo Push API
+##
-#
+## Duo Push API Configuration
-# Parameters used to contact the Duo API. Those are generated when you protect an application
+##
-# of type "Partner Auth API" in the management panel.
+## 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.example.com
  integration_key: ABCDEF
-  # Secret can also be set using a secret: https://docs.authelia.com/configuration/secrets.html
+  ## Secret can also be set using a secret: https://www.authelia.com/docs/configuration/secrets.html
  secret_key: 1234567890abcdefghifjkl
-# The authentication backend to use for verifying user passwords
+##
-# and retrieve information such as email address and groups
+## Authentication Backend Provider Configuration
-# users belong to.
+##
-#
+## Used for verifying user passwords and retrieve information such as email address and groups users belong to.
-# There are two supported backends: 'ldap' and 'file'.
+##
 ## The available providers are: `file`, `ldap`. You must use only one of these providers.
 authentication_backend:
-  # Disable both the HTML element and the API for reset password functionality
+  ## Disable both the HTML element and the API for reset password functionality.
  disable_reset_password: false
-  # The amount of time to wait before we refresh data from the authentication backend. Uses duration notation.
+  ## The amount of time to wait before we refresh data from the authentication backend. Uses duration notation.
-  # To disable this feature set it to 'disable', this will slightly reduce security because for Authelia, users
+  ## To disable this feature set it to 'disable', this will slightly reduce security because for Authelia, users will
-  # will always belong to groups they belonged to at the time of login even if they have been removed from them in LDAP.
+  ## always belong to groups they belonged to at the time of login even if they have been removed from them in LDAP.
-  # To force update on every request you can set this to '0' or 'always', this will increase processor demand.
+  ## To force update on every request you can set this to '0' or 'always', this will increase processor demand.
-  # See the below documentation for more information.
+  ## See the below documentation for more information.
-  # Duration Notation docs:  https://docs.authelia.com/configuration/index.html#duration-notation-format
+  ## Duration Notation docs:  https://www.authelia.com/docs/configuration/index.html#duration-notation-format
-  # Refresh Interval docs: https://docs.authelia.com/configuration/authentication/ldap.html#refresh-interval
+  ## Refresh Interval docs: https://www.authelia.com/docs/configuration/authentication/ldap.html#refresh-interval
  refresh_interval: 5m
-  # LDAP backend configuration.
+  ##
-  #
+  ## LDAP (Authentication Provider)
-  # This backend allows Authelia to be scaled to more
+  ##
-  # than one instance and therefore is recommended for
+  ## This is the recommended Authentication Provider in production
-  # production.
+  ## because it allows Authelia to offload the stateful operations
  ## onto the LDAP service.
  ldap:
-    # The LDAP implementation, this affects elements like the attribute utilised for resetting a password.
+    ## The LDAP implementation, this affects elements like the attribute utilised for resetting a password.
-    # Acceptable options are as follows:
+    ## Acceptable options are as follows:
-    # - 'activedirectory' - For Microsoft Active Directory.
+    ## - 'activedirectory' - For Microsoft Active Directory.
-    # - 'custom' - For custom specifications of attributes and filters.
+    ## - 'custom' - For custom specifications of attributes and filters.
-    # This currently defaults to 'custom' to maintain existing behaviour.
+    ## This currently defaults to 'custom' to maintain existing behaviour.
-    #
+    ##
-    # Depending on the option here certain other values in this section have a default value, notably all
+    ## Depending on the option here certain other values in this section have a default value, notably all of the
-    # of the attribute mappings have a default value that this config overrides, you can read more
+    ## attribute mappings have a default value that this config overrides, you can read more about these default values
-    # about these default values at https://docs.authelia.com/configuration/authentication/ldap.html#defaults
+    ## at https://www.authelia.com/docs/configuration/authentication/ldap.html#defaults
    implementation: custom
-    # The url to the ldap server. Scheme can be ldap or ldaps in the format (port optional) <scheme>://<address>[:<port>].
+    ## The url to the ldap server. Format: <scheme>://<address>[:<port>].
    ## Scheme can be ldap or ldaps in the format (port optional).
    url: ldap://127.0.0.1
-    # Use StartTLS with the LDAP connection.
+    ## Use StartTLS with the LDAP connection.
    start_tls: false
    tls:
-      # Server Name for certificate validation (in case it's not set correctly in the URL).
+      ## Server Name for certificate validation (in case it's not set correctly in the URL).
      # server_name: ldap.example.com
-      # Skip verifying the server certificate (to allow a self-signed certificate).
+      ## Skip verifying the server certificate (to allow a self-signed certificate).
      ## In preference to setting this we strongly recommend you add the public portion of the certificate to the
      ## certificates directory which is defined by the `certificates_directory` option at the top of the config.
      skip_verify: false
-      # Minimum TLS version for either Secure LDAP or LDAP StartTLS.
+      ## Minimum TLS version for either Secure LDAP or LDAP StartTLS.
      minimum_version: TLS1.2
-    # The base dn for every entries.
+    ## The distinguished name of the container searched for objects in the directory information tree.
    ## See also: additional_users_dn, additional_groups_dn.
    base_dn: dc=example,dc=com
-    # The attribute holding the username of the user. This attribute is used to populate
+    ## The attribute holding the username of the user. This attribute is used to populate the username in the session
-    # the username in the session information. It was introduced due to #561 to handle case
+    ## information. It was introduced due to #561 to handle case insensitive search queries. For you information,
-    # insensitive search queries.
+    ## Microsoft Active Directory usually uses 'sAMAccountName' and OpenLDAP usually uses 'uid'. Beware that this
-    # For you information, Microsoft Active Directory usually uses 'sAMAccountName' and OpenLDAP
+    ## attribute holds the unique identifiers for the users binding the user and the configuration stored in database.
-    # usually uses 'uid'
+    ## Therefore only single value attributes are allowed and the value must never be changed once attributed to a user
-    # Beware that this attribute holds the unique identifiers for the users binding the user and the configuration
+    ## otherwise it would break the configuration for that user. Technically, non-unique attributes like 'mail' can also
-    # stored in database. Therefore only single value attributes are allowed and the value
+    ## be used but we don't recommend using them, we instead advise to use the attributes mentioned above
-    # must never be changed once attributed to a user otherwise it would break the configuration
+    ## (sAMAccountName and uid) to follow https://www.ietf.org/rfc/rfc2307.txt.
    # for that user. Technically, non-unique attributes like 'mail' can also be used but we don't recommend using
    # them, we instead advise to use the attributes mentioned above (sAMAccountName and uid) to follow
    # https://www.ietf.org/rfc/rfc2307.txt.
    # username_attribute: uid
-    # An additional dn to define the scope to all users.
+    ## The additional_users_dn is prefixed to base_dn and delimited by a comma when searching for users.
    ## i.e. with this set to OU=Users and base_dn set to DC=a,DC=com; OU=Users,DC=a,DC=com is searched for users.
    additional_users_dn: ou=users
-    # The users filter used in search queries to find the user profile based on input filled in login form.
+    ## The users filter used in search queries to find the user profile based on input filled in login form.
-    # Various placeholders are available to represent the user input and back reference other options of the configuration:
+    ## Various placeholders are available in the user filter:
-    # - {input} is a placeholder replaced by what the user inputs in the login form.
+    ## - {input} is a placeholder replaced by what the user inputs in the login form.
-    # - {username_attribute} is a mandatory placeholder replaced by what is configured in `username_attribute`.
+    ## - {username_attribute} is a mandatory placeholder replaced by what is configured in `username_attribute`.
-    # - {mail_attribute} is a placeholder replaced by what is configured in `mail_attribute`.
+    ## - {mail_attribute} is a placeholder replaced by what is configured in `mail_attribute`.
-    # - DON'T USE - {0} is an alias for {input} supported for backward compatibility but it will be deprecated in later versions, so please don't use it.
+    ## - DON'T USE - {0} is an alias for {input} supported for backward compatibility but it will be deprecated in later
-    #
+    ##   versions, so please don't use it.
-    # Recommended settings are as follows:
+    ##
-    # - Microsoft Active Directory: (&({username_attribute}={input})(objectCategory=person)(objectClass=user))
+    ## Recommended settings are as follows:
-    # - OpenLDAP: (&({username_attribute}={input})(objectClass=person))' or '(&({username_attribute}={input})(objectClass=inetOrgPerson))
+    ## - Microsoft Active Directory: (&({username_attribute}={input})(objectCategory=person)(objectClass=user))
-    #
+    ## - OpenLDAP:
-    # To allow sign in both with username and email, one can use a filter like
+    ##   - (&({username_attribute}={input})(objectClass=person))
-    # (&(|({username_attribute}={input})({mail_attribute}={input}))(objectClass=person))
+    ##   - (&({username_attribute}={input})(objectClass=inetOrgPerson))
    ##
    ## To allow sign in both with username and email, one can use a filter like
    ## (&(|({username_attribute}={input})({mail_attribute}={input}))(objectClass=person))
    users_filter: (&({username_attribute}={input})(objectClass=person))
-    # An additional dn to define the scope of groups.
+    ## The additional_groups_dn is prefixed to base_dn and delimited by a comma when searching for groups.
    ## i.e. with this set to OU=Groups and base_dn set to DC=a,DC=com; OU=Groups,DC=a,DC=com is searched for groups.
    additional_groups_dn: ou=groups
-    # The groups filter used in search queries to find the groups of the user.
+    ## The groups filter used in search queries to find the groups of the user.
-    # - {input} is a placeholder replaced by what the user inputs in the login form.
+    ## - {input} is a placeholder replaced by what the user inputs in the login form.
-    # - {username} is a placeholder replace by the username stored in LDAP (based on `username_attribute`).
+    ## - {username} is a placeholder replace by the username stored in LDAP (based on `username_attribute`).
-    # - {dn} is a matcher replaced by the user distinguished name, aka, user DN.
+    ## - {dn} is a matcher replaced by the user distinguished name, aka, user DN.
-    # - {username_attribute} is a placeholder replaced by what is configured in `username_attribute`.
+    ## - {username_attribute} is a placeholder replaced by what is configured in `username_attribute`.
-    # - {mail_attribute} is a placeholder replaced by what is configured in `mail_attribute`.
+    ## - {mail_attribute} is a placeholder replaced by what is configured in `mail_attribute`.
-    # - DON'T USE - {0} is an alias for {input} supported for backward compatibility but it will be deprecated in later versions, so please don't use it.
+    ## - DON'T USE - {0} is an alias for {input} supported for backward compatibility but it will be deprecated in later
-    # - DON'T USE - {1} is an alias for {username} supported for backward compatibility but it will be deprecated in later version, so please don't use it.
+    ##   versions, so please don't use it.
-    # If your groups use the `groupOfUniqueNames` structure use this instead: (&(uniquemember={dn})(objectclass=groupOfUniqueNames))
+    ## - DON'T USE - {1} is an alias for {username} supported for backward compatibility but it will be deprecated in
    ##   later version, so please don't use it.
    ##
    ## If your groups use the `groupOfUniqueNames` structure use this instead:
    ##    (&(uniquemember={dn})(objectclass=groupOfUniqueNames))
    groups_filter: (&(member={dn})(objectclass=groupOfNames))
-    # The attribute holding the name of the group
+    ## The attribute holding the name of the group.
    # group_name_attribute: cn
-    # The attribute holding the mail address of the user. If multiple email addresses are defined for a user, only the first
+    ## The attribute holding the mail address of the user. If multiple email addresses are defined for a user, only the
-    # one returned by the LDAP server is used.
+    ## first one returned by the LDAP server is used.
    # mail_attribute: mail
-    # The attribute holding the display name of the user. This will be used to greet an authenticated user.
+    ## The attribute holding the display name of the user. This will be used to greet an authenticated user.
    # display_name_attribute: displayname
-    # The username and password of the admin user.
+    ## The username and password of the admin user.
    user: cn=admin,dc=example,dc=com
-    # Password can also be set using a secret: https://docs.authelia.com/configuration/secrets.html
+    ## Password can also be set using a secret: https://www.authelia.com/docs/configuration/secrets.html
    password: password
-  # File backend configuration.
+  ##
-  #
+  ## File (Authentication Provider)
-  # With this backend, the users database is stored in a file
+  ##
-  # which is updated when users reset their passwords.
+  ## With this backend, the users database is stored in a file which is updated when users reset their passwords.
-  # Therefore, this backend is meant to be used in a dev environment
+  ## Therefore, this backend is meant to be used in a dev environment and not in production since it prevents Authelia
-  # and not in production since it prevents Authelia to be scaled to
+  ## to be scaled to more than one instance. The options under 'password' have sane defaults, and as it has security
-  # more than one instance. The options under 'password' have sane
+  ## implications it is highly recommended you leave the default values. Before considering changing these settings
-  # defaults, and as it has security implications it is highly recommended
+  ## please read the docs page below:
-  # you leave the default values. Before considering changing these settings
+  ## https://www.authelia.com/docs/configuration/authentication/file.html#password-hash-algorithm-tuning
-  # please read the docs page below:
+  ##
-  # https://docs.authelia.com/configuration/authentication/file.html#password-hash-algorithm-tuning
+  ## Important: Kubernetes (or HA) users must read https://www.authelia.com/docs/features/statelessness.html
-  #
+  ##
-  ## file:
+  # file:
-  ##   path: /config/users_database.yml
+  #   path: /config/users_database.yml
-  ##   password:
+  #   password:
-  ##     algorithm: argon2id
+  #     algorithm: argon2id
-  ##     iterations: 1
+  #     iterations: 1
-  ##     key_length: 32
+  #     key_length: 32
-  ##     salt_length: 16
+  #     salt_length: 16
-  ##     memory: 1024
+  #     memory: 1024
-  ##     parallelism: 8
+  #     parallelism: 8
-# Access Control
+
-#
+##
-# Access control is a list of rules defining the authorizations applied for one
+## Access Control Configuration
-# resource to users or group of users.
+##
-#
+## Access control is a list of rules defining the authorizations applied for one resource to users or group of users.
-# If 'access_control' is not defined, ACL rules are disabled and the 'bypass'
+##
-# rule is applied, i.e., access is allowed to anyone. Otherwise restrictions follow
+## If 'access_control' is not defined, ACL rules are disabled and the 'bypass' rule is applied, i.e., access is allowed
-# the rules defined.
+## to anyone. Otherwise restrictions follow the rules defined.
-#
+##
-# Note: One can use the wildcard * to match any subdomain.
+## Note: One can use the wildcard * to match any subdomain.
-# It must stand at the beginning of the pattern. (example: *.mydomain.com)
+## It must stand at the beginning of the pattern. (example: *.mydomain.com)
-#
+##
-# Note: You must put patterns containing wildcards between simple quotes for the YAML
+## Note: You must put patterns containing wildcards between simple quotes for the YAML to be syntactically correct.
-# to be syntactically correct.
+##
-#
+## Definition: A 'rule' is an object with the following keys: 'domain', 'subject', 'policy' and 'resources'.
-# Definition: A 'rule' is an object with the following keys: 'domain', 'subject',
+##
-# 'policy' and 'resources'.
+## - 'domain' defines which domain or set of domains the rule applies to.
-#
+##
-# - 'domain' defines which domain or set of domains the rule applies to.
+## - 'subject' defines the subject to apply authorizations to. This parameter is optional and matching any user if not
-#
+##    provided. If provided, the parameter represents either a user or a group. It should be of the form
-# - 'subject' defines the subject to apply authorizations to. This parameter is
+##    'user:<username>' or 'group:<groupname>'.
-#    optional and matching any user if not provided. If provided, the parameter
+##
-#    represents either a user or a group. It should be of the form 'user:<username>'
+## - 'policy' is the policy to apply to resources. It must be either 'bypass', 'one_factor', 'two_factor' or 'deny'.
-#    or 'group:<groupname>'.
+##
-#
+## - 'resources' is a list of regular expressions that matches a set of resources to apply the policy to. This parameter
-# - 'policy' is the policy to apply to resources. It must be either 'bypass',
+##   is optional and matches any resource if not provided.
-#   'one_factor', 'two_factor' or 'deny'.
+##
-#
+## Note: the order of the rules is important. The first policy matching (domain, resource, subject) applies.
 # - 'resources' is a list of regular expressions that matches a set of resources to
 #    apply the policy to. This parameter is optional and matches any resource if not
 #    provided.
 #
 # Note: the order of the rules is important. The first policy matching
 # (domain, resource, subject) applies.
 access_control:
-  # Default policy can either be 'bypass', 'one_factor', 'two_factor' or 'deny'.
+  ## Default policy can either be 'bypass', 'one_factor', 'two_factor' or 'deny'. It is the policy applied to any
-  # It is the policy applied to any resource if there is no policy to be applied
+  ## resource if there is no policy to be applied to the user.
  # to the user.
  default_policy: deny
  networks:
@ -263,13 +272,13 @@ access_control:
      networks: 10.9.0.0/16
  rules:
-    # Rules applied to everyone
+    ## Rules applied to everyone
    - domain: public.example.com
      policy: bypass
    - domain: secure.example.com
      policy: one_factor
-      # Network based rule, if not provided any network matches.
+      ## Network based rule, if not provided any network matches.
      networks:
        - internal
        - VPN
@ -284,7 +293,7 @@ access_control:
    - domain: singlefactor.example.com
      policy: one_factor
-    # Rules applied to 'admins' group
+    ## Rules applied to 'admins' group
    - domain: "mx2.mail.example.com"
      subject: "group:admins"
      policy: deny
@ -295,28 +304,28 @@ access_control:
        - "group:moderators"
      policy: two_factor
-    # Rules applied to 'dev' group
+    ## Rules applied to 'dev' group
    - domain: dev.example.com
      resources:
        - "^/groups/dev/.*$"
      subject: "group:dev"
      policy: two_factor
-    # Rules applied to user 'john'
+    ## Rules applied to user 'john'
    - domain: dev.example.com
      resources:
        - "^/users/john/.*$"
      subject: "user:john"
      policy: two_factor
-    # Rules applied to user 'harry'
+    ## Rules applied to user 'harry'
    - domain: dev.example.com
      resources:
        - "^/users/harry/.*$"
      subject: "user:harry"
      policy: two_factor
-    # Rules applied to user 'bob'
+    ## Rules applied to user 'bob'
    - domain: "*.mail.example.com"
      subject: "user:bob"
      policy: two_factor
@ -326,46 +335,56 @@ access_control:
      subject: "user:bob"
      policy: two_factor
-# Configuration of session cookies
+##
-#
+## Session Provider Configuration
-# The session cookies identify the user once logged in.
+##
 ## The session cookies identify the user once logged in.
 ## The available providers are: `memory`, `redis`. Memory is the provider unless redis is defined.
 session:
-  # The name of the session cookie. (default: authelia_session).
+  ## The name of the session cookie.
  name: authelia_session
-  # The secret to encrypt the session data. This is only used with Redis / Redis Sentinel.
+  ## The secret to encrypt the session data. This is only used with Redis / Redis Sentinel.
-  # Secret can also be set using a secret: https://docs.authelia.com/configuration/secrets.html
+  ## Secret can also be set using a secret: https://www.authelia.com/docs/configuration/secrets.html
  secret: insecure_session_secret
-  # The time in seconds before the cookie expires and session is reset.
+  ## The value for expiration, inactivity, and remember_me_duration are in seconds or the duration notation format.
  ## See: https://www.authelia.com/docs/configuration/index.html#duration-notation-format
  ## All three of these values affect the cookie/session validity period. Longer periods are considered less secure
  ## because a stolen cookie will last longer giving attackers more time to spy or attack.
  ## The time before the cookie expires and the session is destroyed if remember me IS NOT selected.
  expiration: 1h
-  # The inactivity time in seconds before the session is reset.
+  ## The inactivity time before the session is reset. If expiration is set to 1h, and this is set to 5m, if the user
  ## does not select the remember me option their session will get destroyed after 1h, or after 5m since the last time
  ## Authelia detected user activity.
  inactivity: 5m
-  # The remember me duration.
+  ## The time before the cookie expires and the session is destroyed if remember me IS selected.
-  # Value of 0 disables remember me.
+  ## Value of 0 disables remember me.
  # Value is in seconds, or duration notation. See: https://docs.authelia.com/configuration/index.html#duration-notation-format
  # Longer periods are considered less secure because a stolen cookie will last longer giving attackers more time to spy
  # or attack. Currently the default is 1M or 1 month.
  remember_me_duration: 1M
-  # The domain to protect.
+  ## The domain to protect.
-  # Note: the authenticator must also be in that domain. If empty, the cookie
+  ## Note: the authenticator must also be in that domain.
-  # is restricted to the subdomain of the issuer.
+  ## If empty, the cookie is restricted to the subdomain of the issuer.
  domain: example.com
-  ## The redis connection details
+  ##
  ## Redis Provider
  ##
  ## Important: Kubernetes (or HA) users must read https://www.authelia.com/docs/features/statelessness.html
  ##
  redis:
    host: 127.0.0.1
    port: 6379
    ## Use a unix socket instead
    # host: /var/run/redis/redis.sock
-    ## Optional username to be used with authentication.
+    ## Username used for redis authentication. This is optional and a new feature in redis 6.0.
-    username: authelia
+    # username: authelia
-    ## Password can also be set using a secret: https://docs.authelia.com/configuration/secrets.html
+    ## Password can also be set using a secret: https://www.authelia.com/docs/configuration/secrets.html
    password: authelia
    ## This is the Redis DB Index https://redis.io/commands/select (sometimes referred to as database number, DB, etc).
@ -393,7 +412,7 @@ session:
    ## The Redis HA configuration options.
    ## This provides specific options to Redis Sentinel, sentinel_name must be defined (Master Name).
    # high_availability:
-      ## Sentinel Name / Master Name
+      ## Sentinel Name / Master Name.
      # sentinel_name: mysentinel
      ## Specific password for Redis Sentinel. The node username and password is configured above.
@ -414,89 +433,109 @@ session:
      ## Choose the host randomly.
      # route_randomly: false
-# Configuration of the authentication regulation mechanism.
+##
-#
+## Regulation Configuration
-# This mechanism prevents attackers from brute forcing the first factor.
+##
-# It bans the user if too many attempts are done in a short period of
+## This mechanism prevents attackers from brute forcing the first factor. It bans the user if too many attempts are made
-# time.
+## in a short period of time.
 regulation:
-  # The number of failed login attempts before user is banned.
+  ## The number of failed login attempts before user is banned. Set it to 0 to disable regulation.
  # Set it to 0 to disable regulation.
  max_retries: 3
-  # The time range during which the user can attempt login before being banned.
+  ## The time range during which the user can attempt login before being banned. The user is banned if the
-  # The user is banned if the authentication failed 'max_retries' times in a 'find_time' seconds window.
+  ## authentication failed 'max_retries' times in a 'find_time' seconds window. Find Time accepts duration notation.
-  # Find Time accepts duration notation. See: https://docs.authelia.com/configuration/index.html#duration-notation-format
+  ## See: https://www.authelia.com/docs/configuration/index.html#duration-notation-format
  find_time: 2m
-  # The length of time before a banned user can login again.
+  ## The length of time before a banned user can login again. Ban Time accepts duration notation.
-  # Ban Time accepts duration notation. See: https://docs.authelia.com/configuration/index.html#duration-notation-format
+  ## See: https://www.authelia.com/docs/configuration/index.html#duration-notation-format
  ban_time: 5m
-# Configuration of the storage backend used to store data and secrets.
+##
-#
+## Storage Provider Configuration
-# You must use only an available configuration: local, mysql, postgres
+##
 ## The available providers are: `local`, `mysql`, `postgres`. You must use one and only one of these providers.
 storage:
-  # The directory where the DB files will be saved
+  ##
-  ## local:
+  ## Local (Storage Provider)
-  ##   path: /config/db.sqlite3
+  ##
  ## This stores the data in a SQLite3 Database.
  ## This is only recommended for lightweight non-stateful installations.
  ##
  ## Important: Kubernetes (or HA) users must read https://www.authelia.com/docs/features/statelessness.html
  ##
  # local:
  #   path: /config/db.sqlite3
-  # Settings to connect to MySQL server
+  ##
  ## MySQL / MariaDB (Storage Provider)
  ##
  mysql:
    host: 127.0.0.1
    port: 3306
    database: authelia
    username: authelia
-    # Password can also be set using a secret: https://docs.authelia.com/configuration/secrets.html
+    ## Password can also be set using a secret: https://www.authelia.com/docs/configuration/secrets.html
    password: mypassword
-  # Settings to connect to PostgreSQL server
+  ##
  ## PostgreSQL (Storage Provider)
  ##
  # postgres:
  #   host: 127.0.0.1
  #   port: 5432
  #   database: authelia
  #   username: authelia
-  #   # Password can also be set using a secret: https://docs.authelia.com/configuration/secrets.html
+  #   ## Password can also be set using a secret: https://www.authelia.com/docs/configuration/secrets.html
  #   password: mypassword
  #   sslmode: disable
-# Configuration of the notification system.
+##
-#
+## Notification Provider
-# Notifications are sent to users when they require a password reset, a u2f
+##
-# registration or a TOTP registration.
+## Notifications are sent to users when they require a password reset, a U2F registration or a TOTP registration.
-# Use only an available configuration: filesystem, smtp.
+## The available providers are: filesystem, smtp. You must use only one of these providers.
 notifier:
-  # You can disable the notifier startup check by setting this to true.
+  ## You can disable the notifier startup check by setting this to true.
  disable_startup_check: false
-  # For testing purpose, notifications can be sent in a file
+  ##
-  ## filesystem:
+  ## File System (Notification Provider)
-  ##   filename: /config/notification.txt
+  ##
  ## Important: Kubernetes (or HA) users must read https://www.authelia.com/docs/features/statelessness.html
  ##
  # filesystem:
  #   filename: /config/notification.txt
-  # Use a SMTP server for sending notifications. Authelia uses PLAIN or LOGIN method to authenticate.
+  ##
-  # [Security] By default Authelia will:
+  ## SMTP (Notification Provider)
-  #   - 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)
+  ## Use a SMTP server for sending notifications. Authelia uses the PLAIN or LOGIN methods to authenticate.
-  #   - validate the SMTP server x509 certificate during the TLS handshake against the hosts trusted certificates (configure in tls section)
+  ## [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
  ##     (configure in tls section)
  smtp:
    username: test
-    # Password can also be set using a secret: https://docs.authelia.com/configuration/secrets.html
+    ## Password can also be set using a secret: https://www.authelia.com/docs/configuration/secrets.html
    password: password
    host: 127.0.0.1
    port: 1025
    sender: admin@example.com
-    # HELO/EHLO Identifier. Some SMTP Servers may reject the default of localhost.
+    ## HELO/EHLO Identifier. Some SMTP Servers may reject the default of localhost.
    identifier: localhost
-    # Subject configuration of the emails sent.
+    ## Subject configuration of the emails sent. {title} is replaced by the text from the notifier.
    # {title} is replaced by the text from the notifier
    subject: "[Authelia] {title}"
-    # This address is used during the startup check to verify the email configuration is correct. It's not important what it is except if your email server only allows local delivery.
+    ## This address is used during the startup check to verify the email configuration is correct.
    ## It's not important what it is except if your email server only allows local delivery.
    startup_check_address: test@authelia.com
    disable_require_tls: false
    disable_html_emails: false
    tls:
-      # Server Name for certificate validation (in case you are using the IP or non-FQDN in the host option).
+      ## Server Name for certificate validation (in case you are using the IP or non-FQDN in the host option).
      # server_name: smtp.example.com
      ## Skip verifying the server certificate (to allow a self-signed certificate).
@ -504,15 +543,16 @@ notifier:
      ## certificates directory which is defined by the `certificates_directory` option at the top of the config.
      skip_verify: false
-      # Minimum TLS version for either StartTLS or SMTPS.
+      ## Minimum TLS version for either StartTLS or SMTPS.
      minimum_version: TLS1.2
-  # Sending an email using a Gmail account is as simple as the next section.
+  ## Sending an email using a Gmail account is as simple as the next section.
-  # You need to create an app password by following: https://support.google.com/accounts/answer/185833?hl=en
+  ## You need to create an app password by following: https://support.google.com/accounts/answer/185833?hl=en
-  ## smtp:
+  # smtp:
-  ##   username: myaccount@gmail.com
+  #   username: myaccount@gmail.com
-  ##   # Password can also be set using a secret: https://docs.authelia.com/configuration/secrets.html
+  #   ## Password can also be set using a secret: https://www.authelia.com/docs/configuration/secrets.html
-  ##   password: yourapppassword
+  #   password: yourapppassword
-  ##   sender: admin@example.com
+  #   sender: admin@example.com
-  ##   host: smtp.gmail.com
+  #   host: smtp.gmail.com
-  ##   port: 587
+  #   port: 587
 ...
--- a/internal/configuration/validator/authentication.go
+++ b/internal/configuration/validator/authentication.go
@ -176,13 +176,13 @@ func validateLdapAuthenticationBackend(configuration *schema.LDAPAuthenticationB
 		if !strings.Contains(configuration.UsersFilter, "{username_attribute}") {
 			validator.Push(errors.New("Unable to detect {username_attribute} placeholder in users_filter, your configuration is broken. " +
-				"Please review configuration options listed at https://docs.authelia.com/configuration/authentication/ldap.html"))
+				"Please review configuration options listed at https://www.authelia.com/docs/configuration/authentication/ldap.html"))
 		}
 		// This test helps the user know that users_filter is broken after the breaking change induced by this commit.
 		if !strings.Contains(configuration.UsersFilter, "{0}") && !strings.Contains(configuration.UsersFilter, "{input}") {
 			validator.Push(errors.New("Unable to detect {input} placeholder in users_filter, your configuration might be broken. " +
-				"Please review configuration options listed at https://docs.authelia.com/configuration/authentication/ldap.html"))
+				"Please review configuration options listed at https://www.authelia.com/docs/configuration/authentication/ldap.html"))
 		}
 	}
--- a/internal/configuration/validator/authentication_test.go
+++ b/internal/configuration/validator/authentication_test.go
@ -411,7 +411,7 @@ func (suite *LdapAuthenticationBackendSuite) TestShouldRaiseWhenUsersFilterDoesN
 	suite.Assert().False(suite.validator.HasWarnings())
 	suite.Require().Len(suite.validator.Errors(), 1)
-	suite.Assert().EqualError(suite.validator.Errors()[0], "Unable to detect {username_attribute} placeholder in users_filter, your configuration is broken. Please review configuration options listed at https://docs.authelia.com/configuration/authentication/ldap.html")
+	suite.Assert().EqualError(suite.validator.Errors()[0], "Unable to detect {username_attribute} placeholder in users_filter, your configuration is broken. Please review configuration options listed at https://www.authelia.com/docs/configuration/authentication/ldap.html")
 }
 func (suite *LdapAuthenticationBackendSuite) TestShouldHelpDetectNoInputPlaceholder() {
@ -422,7 +422,7 @@ func (suite *LdapAuthenticationBackendSuite) TestShouldHelpDetectNoInputPlacehol
 	suite.Assert().False(suite.validator.HasWarnings())
 	suite.Require().Len(suite.validator.Errors(), 1)
-	suite.Assert().EqualError(suite.validator.Errors()[0], "Unable to detect {input} placeholder in users_filter, your configuration might be broken. Please review configuration options listed at https://docs.authelia.com/configuration/authentication/ldap.html")
+	suite.Assert().EqualError(suite.validator.Errors()[0], "Unable to detect {input} placeholder in users_filter, your configuration might be broken. Please review configuration options listed at https://www.authelia.com/docs/configuration/authentication/ldap.html")
 }
 func (suite *LdapAuthenticationBackendSuite) TestShouldAdaptLDAPURL() {
--- a/internal/handlers/handler_verify.go
+++ b/internal/handlers/handler_verify.go
@ -347,7 +347,7 @@ func generateVerifySessionHasUpToDateProfileTraceLogs(ctx *middlewares.AutheliaC
 func verifySessionHasUpToDateProfile(ctx *middlewares.AutheliaCtx, targetURL *url.URL, userSession *session.UserSession,
 	refreshProfile bool, refreshProfileInterval time.Duration) error {
 	// TODO: Add a check for LDAP password changes based on a time format attribute.
-	// See https://docs.authelia.com/security/threat-model.html#potential-future-guarantees
+	// See https://www.authelia.com/docs/security/threat-model.html#potential-future-guarantees
 	ctx.Logger.Tracef("Checking if we need check the authentication backend for an updated profile for %s.", userSession.Username)
 	if !refreshProfile || userSession.Username == "" || targetURL == nil {