feat: major documentation refresh (#3475)

This marks the launch of the new documentation website.

1 files changed, 528 insertions, 0 deletions

diff --git a/docs/content/en/configuration/security/access-control.md b/docs/content/en/configuration/security/access-control.md
new file mode 100644
index 000000000..32ba44151
--- /dev/null
+++ b/docs/content/en/configuration/security/access-control.md
@@ -0,0 +1,528 @@
+---
+title: "Access Control"
+description: "Configuring the Access Control or RBAC settings."
+lead: "Authelia supports a comprehensive access control system. This section describes configuring this."
+date: 2022-03-20T12:52:27+11:00
+draft: false
+images: []
+menu:
+  configuration:
+    parent: "security"
+weight: 104200
+toc: true
+aliases:
+  - /c/acl
+  - /docs/configuration/access-control.html
+---
+
+## Configuration
+
+```yaml
+access_control:
+  default_policy: deny
+  networks:
+  - name: internal
+    networks:
+    - '10.0.0.0/8'
+    - '172.16.0.0/12'
+    - '192.168.0.0/18'
+  rules:
+  - domain: 'private.example.com'
+    domain_regex: '^(\d+\-)?priv-img.example.com$'
+    policy: one_factor
+    networks:
+    - 'internal'
+    - '1.1.1.1'
+    subject:
+    - ['user:adam']
+    - ['user:fred']
+    - ['group:admins']
+    methods:
+    - GET
+    - HEAD
+    resources:
+    - '^/api.*'
+```
+
+## Options
+
+### default_policy
+
+{{< confkey type="string" default="deny" required="no" >}}
+
+The default [policy](#policies) defines the policy applied if no [rules](#rules) section apply to the information known
+about the request. It is recommended that this is configured to [deny](#deny) for security reasons. Sites which you do
+not wish to secure at all with Authelia should not be configured in your reverse proxy to perform authentication with
+Authelia at all for performance reasons.
+
+See [Policies](#policies) for more information.
+
+### networks (global)
+
+{{< confkey type="list" required="no" >}}
+
+The main/global networks section contains a list of networks with a name label that can be reused in the
+[rules](#networks) section instead of redefining the same networks over and over again. This additionally makes
+complicated network related configuration a lot cleaner and easier to read.
+
+This section has two options, `name` and `networks`. Where the `networks` section is a list of IP addresses in CIDR
+notation and where `name` is a friendly name to label the collection of networks for reuse in the [networks](#networks)
+section of the [rules](#rules) section below.
+
+This configuration option *does nothing* by itself, it's only useful if you use these aliases in the [rules](#networks)
+section below.
+
+### rules
+
+{{< confkey type="list" required="no" >}}
+
+The rules have many configuration options. A rule matches when all criteria of the rule match the request excluding the
+`policy` which is the [policy](#policies) applied to the request.
+
+A rule defines two primary things:
+
+* the policy applied when all criteria match
+* the matching criteria of the request presented to the reverse proxy
+
+The criteria is broken into several parts:
+
+* [domain](#domain): domain or list of domains targeted by the request.
+* [domain_regex](#domain_regex): regex form of [domain](#domain).
+* [resources](#resources): pattern or list of patterns that the path should match.
+* [subject](#subject): the user or group of users to define the policy for.
+* [networks](#networks): the network addresses, ranges (CIDR notation) or groups from where the request originates.
+* [methods](#methods): the http methods used in the request.
+
+A rule is matched when all criteria of the rule match. Rules are evaluated in sequential order, and the first rule that
+is a match for a given request is the rule applied; subsequent rules have *no effect*. This is particularly
+__important__ for bypass rules. Bypass rules should generally appear near the top of the rules list. However you need to
+carefully evaluate your rule list __in order__ to see which rule matches a particular scenario. A comprehensive
+understanding of how rules apply is also recommended.
+
+#### domain
+
+{{< confkey type="list(string)" required="yes" >}}
+
+*__Required:__ This criteria and/or the [domain_regex](#domain_regex) criteria are required.*
+
+This criteria matches the domain name and has two methods of configuration, either as a single string or as a list of
+strings. When it's a list of strings the rule matches when __any__ of the domains in the list match the request domain.
+When used in conjunction with [domain_regex](#domain_regex) the rule will match when either the [domain](#domain) or the
+[domain_regex](#domain_regex) criteria matches.
+
+Rules may start with a few different wildcards:
+
+* The standard wildcard is `*.`, which when in front of a domain means that any subdomain is effectively a match. For
+  example `*.example.com` would match `abc.example.com` and `secure.example.com`. When using a wildcard like this the
+  string __must__ be quoted like `"*.example.com"`.
+* The user wildcard is `{user}.`, which when in front of a domain dynamically matches the username of the user. For
+  example `{user}.example.com` would match `fred.example.com` if the user logged in was named `fred`. *__Warning:__ this is
+  officially deprecated as the [domain_regex](#domain_regex) criteria completely replaces the functionality in a much
+  more useful way. It is strongly recommended you do not use this as it will be removed in a future version, most likely
+  v5.0.0.*
+* The group wildcard is `{group}.`, which when in front of a domain dynamically matches if the logged in user has the
+  group in that location. For example `{group}.example.com` would match `admins.example.com` if the user logged in was
+  in the following groups `admins,users,people` because `admins` is in the list.
+
+Domains in this section must be the domain configured in the [session](../session/introduction.md#domain) configuration
+or subdomains of that domain. This is because a website can only write cookies for a domain it is part of. It is
+theoretically possible for us to do this with multiple domains however we would have to be security conscious in our
+implementation, and it is not currently a priority.
+
+##### Examples
+
+*Single domain of `*.example.com` matched. All rules in this list are effectively the same rule just expressed in
+different ways.*
+
+```yaml
+access_control:
+  rules:
+  - domain: '*.example.com'
+    policy: bypass
+  - domain:
+    - '*.example.com'
+    policy: bypass
+```
+
+*Multiple domains matched. These rules will match either `apple.example.com` or `orange.example.com`. All rules in this
+list are effectively the same rule just expressed in different ways.*
+
+```yaml
+access_control:
+  rules:
+  - domain: ['apple.example.com', 'banana.example.com']
+    policy: bypass
+  - domain:
+    - apple.example.com
+    - banana.example.com
+    policy: bypass
+```
+
+*Multiple domains matched either via a static domain or via a [domain_regex](#domain_regex). This rule will match
+either `apple.example.com`, `pub-data.example.com`, or `img-data.example.com`.*
+
+```yaml
+access_control:
+  rules:
+  - domain: 'apple.example.com'
+    domain_regex: '^(pub|img)-data\.example\.com$'
+    policy: bypass
+```
+
+### domain_regex
+
+{{< confkey type="list(string)" required="yes" >}}
+
+*__Required:__ This criteria and/or the [domain](#domain) criteria are required.*
+
+*__Important Note:__ If you intend to use this criteria with a bypass rule please read
+[bypass and subjects](#bypass-and-user-identity) before doing so.*
+
+*__Important Note:__ to utilize regex you must escape it properly. See
+[regular expressions](../prologue/common.md#regular-expressions) for more information.*
+
+This criteria matches the domain name and has two methods of configuration, either as a single string or as a list of
+strings. When it's a list of strings the rule matches when __any__ of the domains in the list match the request domain.
+When used in conjunction with [domain](#domain) the rule will match when either the [domain](#domain) or the
+[domain_regex](#domain_regex) criteria matches.
+
+This criteria takes any standard go regex pattern to match the requests. We additionally utilize two special named match
+groups which match attributes of the user:
+
+| Group Name |    Match Value    |
+|:----------:|:-----------------:|
+|    User    |     username      |
+|   Group    | groups (contains) |
+
+For the group match it matches if the user has any group name that matches, and both matches are case-insensitive due to
+the fact domain names should not be compared in a case-sensitive way as per the
+[RFC4343](https://www.rfc-editor.org/rfc/rfc4343.html) abstract and
+[RFC3986 Section 3.2.2](https://www.rfc-editor.org/rfc/rfc3986#section-3.2.2).
+
+#### Examples
+
+*An advanced multiple domain regex example with user/group matching. This will match the user `john` in the groups
+`example` and `example1`, when the request is made to `user-john.example.com`, `group-example.example.com`, or
+`group-example1.example.com`, it would not match when the request is made to `user-fred.example.com` or
+`group-admin.example.com`.*
+
+```yaml
+access_control:
+  rules:
+  - domain_regex:
+    - '^user-(?P<User>\w+)\.example\.com$'
+    - '^group-(?P<Group>\w+)\.example\.com$'
+    policy: one_factor
+```
+
+*Multiple domains example, one with a static domain and one with a regex domain. This will match requests to
+`protected.example.com`, `img-private.example.com`, or `data-private.example.com`.*
+
+```yaml
+access_control:
+  rules:
+  - domain: 'protected.example.com'
+  - domain_regex: '^(img|data)-private\.example\.com'
+    policy: one_factor
+```
+
+#### policy
+
+{{< confkey type="string" required="yes" >}}
+
+The specific [policy](#policies) to apply to the selected rule. This is not criteria for a match, this is the action to
+take when a match is made.
+
+#### subject
+
+{{< confkey type="list(list(string))" required="no" >}}
+
+*__Note:__ this rule criteria __may not__ be used for the `bypass` policy the minimum required authentication level to
+identify the subject is `one_factor`. We have taken an opinionated stance on preventing this configuration as it could
+result in problematic security scenarios with badly thought out configurations and cannot see a likely configuration
+scenario that would require users to do this. If you have a scenario in mind please open an
+[issue](https://github.com/authelia/authelia/issues/new) on GitHub.*
+
+This criteria matches identifying characteristics about the subject. Currently this is either user or groups the user
+belongs to. This allows you to effectively control exactly what each user is authorized to access or to specifically
+require two-factor authentication to specific users. Subjects are prefixed with either `user:` or `group:` to identify
+which part of the identity to check.
+
+The format of this rule is unique in as much as it is a list of lists. The logic behind this format is to allow for both
+`OR` and `AND` logic. The first level of the list defines the `OR` logic, and the second level defines the `AND` logic.
+Additionally each level of these lists does not have to be explicitly defined.
+
+##### Examples
+
+*Matches when the user has the username `john`, __or__ the user is in the groups `admin` __and__ `app-name`, __or__ the
+user is in the group `super-admin`. All rules in this list are effectively the same rule just expressed in different
+ways.*
+
+```yaml
+access_control:
+  rules:
+  - domain: example.com
+    policy: two_factor
+    subject:
+    - 'user:john'
+    - ['group:admin', 'group:app-name']
+    - 'group:super-admin'
+  - domain: example.com
+    policy: two_factor
+    subject:
+    - ['user:john']
+    - ['group:admin', 'group:app-name']
+    - ['group:super-admin']
+```
+
+*Matches when the user is in the `super-admin` group. All rules in this list are effectively the same rule just
+expressed in different ways.*
+
+```yaml
+access_control:
+  rules:
+  - domain: example.com
+    policy: one_factor
+    subject: 'group:super-admin'
+  - domain: example.com
+    policy: one_factor
+    subject:
+    - 'group:super-admin'
+  - domain: example.com
+    policy: one_factor
+    subject:
+    - ['group:super-admin']
+```
+
+#### methods
+
+{{< confkey type="list(string)" required="no" >}}
+
+This criteria matches the HTTP request method. This is primarily useful when trying to bypass authentication for specific
+request types when those requests would prevent essential or public operation of the website. An example is when you
+need to do CORS preflight requests you could apply the `bypass` policy to `OPTIONS` requests.
+
+It's important to note that Authelia cannot preserve request data when redirecting the user. For example if the user had
+permission to do GET requests, their authentication level was `one_factor`, and POST requests required them to do
+`two_factor` authentication, they would lose the form data. Additionally it is sometimes not possible to redirect users
+who have done requests other than HEAD or GET which means the user experience may suffer. These are the reasons it's
+only recommended to use this to increase security where essential and for CORS preflight.
+
+The accepted and valid methods for this configuration option are those specified in well known RFC's. The RFC's and the
+relevant methods are listed in this table:
+
+|    RFC    |                        Methods                        |                     Additional Documentation                     |
+|:---------:|:-----------------------------------------------------:|:----------------------------------------------------------------:|
+| [RFC7231] | GET, HEAD, POST, PUT, DELETE, CONNECT, OPTIONS, TRACE | [MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods) |
+| [RFC5789] |                         PATCH                         | [MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods) |
+| [RFC4918] | PROPFIND, PROPPATCH, MKCOL, COPY, MOVE, LOCK, UNLOCK  |                                                                  |
+
+##### Examples
+
+*Bypass `OPTIONS` requests to the `example.com` domain.*
+
+```yaml
+access_control:
+  rules:
+  - domain: example.com
+    policy: bypass
+    methods:
+    - OPTIONS
+```
+
+#### networks
+
+{{< confkey type="list(string)" required="no" >}}
+
+This criteria is a list of values which can be an IP Address, network address range in CIDR notation, or an alias from
+the [global](#networks-global) section. It matches against the first address in the `X-Forwarded-For` header, or if there
+are none it will fall back to the IP address of the packet TCP source IP address. For this reason it's important for you
+to configure the proxy server correctly in order to accurately match requests with this criteria. *__Note:__ you may
+combine CIDR networks with the alias rules as you please.*
+
+The main use case for this criteria is adjust the security requirements of a resource based on the location of a user.
+You can theoretically consider a specific network to be one of the factors involved in authentiation, you can deny
+specific networks, etc.
+
+For example if you have an application exposed on both the local networks and the external networks, you are able to
+distinguish between those requests and apply differing policies to each. Either denying access when the user is on the
+external networks and allowing specific external clients to access it as well as internal clients, or by requiring less
+privileges when a user is on the local networks.
+
+There are a large number of scenarios regarding networks and the order of the rules. This provides a lot of flexibility
+for administrators to tune the security to their specific needs if desired.
+
+##### Examples
+
+*Require [two_factor](#two_factor) for all clients other than internal clients and `112.134.145.167`. The first two
+rules in this list are effectively the same rule just expressed in different ways.*
+
+```yaml
+access_control:
+  default_policy: two_factor
+  networks:
+  - name: internal
+    networks:
+      - '10.0.0.0/8'
+      - '172.16.0.0/12'
+      - '192.168.0.0/18'
+  rules:
+  - domain: secure.example.com
+    policy: one_factor
+    networks:
+    - '10.0.0.0/8'
+    - '172.16.0.0/12'
+    - '192.168.0.0/18'
+    - '112.134.145.167/32'
+  - domain: secure.example.com
+    policy: one_factor
+    networks:
+    - 'internal'
+    - '112.134.145.167/32'
+  - domain: secure.example.com
+    policy: two_factor
+```
+
+#### resources
+
+{{< confkey type="list(string)" required="no" >}}
+
+*__Important Note:__ to utilize regex you must escape it properly. See
+[regular expressions](../prologue/common.md#regular-expressions) for more information.*
+
+This criteria matches the path and query of the request using regular expressions. The rule is expressed as a list of
+strings. If any one of the regular expressions in the list matches the request it's considered a match. A useful tool
+for debugging these regular expressions is called [Regex 101](https://regex101.com/) (ensure you pick the `Golang`
+option).
+
+*__Note:__ Prior to 4.27.0 the regular expressions only matched the path excluding the query parameters. After 4.27.0
+they match the entire path including the query parameters. When upgrading you may be required to alter some of your
+resource rules to get them to operate as they previously did.*
+
+It's important when configuring resource rules that you enclose them in quotes otherwise you may run into some issues
+with escaping the expressions. Failure to do so may prevent Authelia from starting. It's technically optional but will
+likely save you a lot of time if you do it for all resource rules.
+
+##### Examples
+
+*Applies the [bypass](#bypass) policy when the domain is `app.example.com` and the url is `/api`, or starts with either
+`/api/` or `/api?`.*
+
+```yaml
+access_control:
+  rules:
+  - domain: app.example.com
+    policy: bypass
+    resources:
+    - '^/api([/?].*)?$'
+```
+
+## Policies
+
+The policy of the first matching rule in the configured list decides the policy applied to the request, if no rule
+matches the request the [default_policy](#default_policy) is applied.
+
+### deny
+
+This is the policy applied by default, and is what we recommend as the default policy for all installs. Its effect
+is literally to deny the user access to the resource. Additionally you can use this policy to conditionally deny
+access in desired situations. Examples include denying access to an API that has no authentication mechanism built in.
+
+### bypass
+
+This policy skips all authentication and allows anyone to use the resource. This policy is not available with a rule
+that includes a [subject](#subject) restriction because the minimum authentication level required to obtain information
+about the subject is [one_factor](#one_factor).
+
+#### bypass and user identity
+
+The [bypass](#bypass) policy cannot be used when the rule uses a criteria that requires we know the users identity. This
+means:
+
+* If the rule defines [subjects](#subject) criteria
+* If the rule defines [domain regex](#domain_regex) criteria which contains either the user or group named match groups
+
+This is because these criteria types require knowing who the user is in order to determine if their identity matches the
+request. This information can only be known after 1FA, which means the minimum policy that can be used logically is
+[one_factor](#one_factor).
+
+### one_factor
+
+This policy requires the user at minimum complete 1FA successfully (username and password). This means if they have
+performed 2FA then they will be allowed to access the resource.
+
+### two_factor
+
+This policy requires the user to complete 2FA successfully. This is currently the highest level of authentication
+policy available.
+
+## Detailed example
+
+Here is a detailed example of an example access control section:
+
+```yaml
+access_control:
+  default_policy: deny
+  networks:
+    - name: internal
+      networks:
+        - '10.10.0.0/16'
+        - '192.168.2.0/24'
+    - name: VPN
+      networks: 10.9.0.0/16
+  rules:
+    - domain: 'public.example.com'
+      policy: bypass
+
+    - domain: '*.example.com'
+      policy: bypass
+      methods:
+        - OPTIONS
+
+    - domain: 'secure.example.com'
+      policy: one_factor
+      networks:
+        - 'internal'
+        - 'VPN'
+        - '192.168.1.0/24'
+        - '10.0.0.1'
+
+    - domain:
+      - 'secure.example.com'
+      - 'private.example.com'
+      policy: two_factor
+
+    - domain: 'singlefactor.example.com'
+      policy: one_factor
+
+    - domain: 'mx2.mail.example.com'
+      subject: 'group:admins'
+      policy: deny
+
+    - domain: '*.example.com'
+      subject:
+        - 'group:admins'
+        - 'group:moderators'
+      policy: two_factor
+
+    - domain: dev.example.com
+      resources:
+      - '^/groups/dev/.*$'
+      subject: 'group:dev'
+      policy: two_factor
+
+    - domain: dev.example.com
+      resources:
+      - '^/users/john/.*$'
+      subject:
+      - ['group:dev', 'user:john']
+      - 'group:admins'
+      policy: two_factor
+
+    - domain: '{user}.example.com'
+      policy: bypass
+```
+
+[RFC7231]: https://www.rfc-editor.org/rfc/rfc7231.html
+[RFC5789]: https://www.rfc-editor.org/rfc/rfc5789.html
+[RFC4918]: https://www.rfc-editor.org/rfc/rfc4918.html