From f3fd79d7310dfcee912e34ba5e47e73dd0d05468 Mon Sep 17 00:00:00 2001 From: Amir Zarrinkafsh Date: Tue, 10 Mar 2020 09:37:46 +1100 Subject: [PATCH] [DOCS] Review all docs and adjust since the initial refactoring (#698) * [DOCS] Review all docs and adjust since the initial refactoring * [DOCS] Minor tweaks --- docs/configuration/access-control.md | 22 ++++++++++---------- docs/configuration/authentication/file.md | 7 ++----- docs/configuration/duo-push-notifications.md | 2 +- docs/configuration/miscellaneous.md | 4 ++-- docs/configuration/notifier/filesystem.md | 2 +- docs/configuration/regulation.md | 4 ++-- docs/configuration/secrets.md | 4 ++-- docs/configuration/storage/index.md | 6 +++--- docs/contributing/build-and-dev.md | 2 +- docs/deployment/deployment-ha.md | 4 ++-- docs/deployment/supported-proxies/index.md | 2 +- docs/features/regulation.md | 4 ++-- docs/home/architecture.md | 6 +++--- docs/security/measures.md | 2 +- 14 files changed, 34 insertions(+), 37 deletions(-) diff --git a/docs/configuration/access-control.md b/docs/configuration/access-control.md index 3c944cc9..fac13d5b 100644 --- a/docs/configuration/access-control.md +++ b/docs/configuration/access-control.md @@ -11,27 +11,27 @@ nav_order: 2 ## Access Control List With **Authelia** you can define a list of rules that are going to be evaluated in -order when authorization is delegated to Authelia. +sequential order when authorization is delegated to Authelia. -The first matching rule of the list defines the policy applied to the resource and, if -no rule matches the resource, a customizable default policy is applied. +The first matching rule of the list defines the policy applied to the resource, if +no rule matches the resource a customizable default policy is applied. ## Access Control Rule A rule defines two things: -* the matching criterion of the request presented to the reverse proxy -* the policy applied when all criterion match. +* the matching criteria of the request presented to the reverse proxy +* the policy applied when all criteria match. -The criterion are: +The criteria are: * domain: domain targeted by the request. * resources: list of patterns that the path should match (one is sufficient). * subject: the user or group of users to define the policy for. * networks: the network range from where should comes the request. -A rule is matched when all criterion of the rule match +A rule is matched when all criteria of the rule match. ## Policies @@ -78,12 +78,12 @@ a rule, one can just duplicate the rule as many times as there are subjects. A list of network ranges can be specified in a rule in order to apply different policies when requests come from different networks. -The main use case is when, let say a resource should be exposed both on the Internet and from an +The main use case is when, lets say a resource should be exposed both on the Internet and from an authenticated VPN for instance. Passing a second factor a first time to get access to the VPN and -a second time to get access to the application can sometimes be cumbersome if the endpoint is not -that much sensitive. +a second time to get access to the application can sometimes be cumbersome if the endpoint is not +considered overly sensitive. -Even if Authelia provides that flexbility, you might prefer higher level of security and avoid +Even if Authelia provides this flexibility, you might prefer a higher level of security and avoid this option entirely. You and only you can define your security policy and it's up to you to configure Authelia accordingly. diff --git a/docs/configuration/authentication/file.md b/docs/configuration/authentication/file.md index 0bc31281..fb812df6 100644 --- a/docs/configuration/authentication/file.md +++ b/docs/configuration/authentication/file.md @@ -183,11 +183,8 @@ linked documents in [Argon2 links](./file.md#argon2-links). #### Argon2 Links -[How to choose the right parameters for Argon2] +[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) -[IETF Draft](https://tools.ietf.org/id/draft-irtf-cfrg-argon2-09.html) - - -[How to choose the right parameters for Argon2]: https://www.twelve21.io/how-to-choose-the-right-parameters-for-argon2/ \ No newline at end of file +[IETF Draft](https://tools.ietf.org/id/draft-irtf-cfrg-argon2-09.html) \ No newline at end of file diff --git a/docs/configuration/duo-push-notifications.md b/docs/configuration/duo-push-notifications.md index 343f530f..acbbb298 100644 --- a/docs/configuration/duo-push-notifications.md +++ b/docs/configuration/duo-push-notifications.md @@ -21,7 +21,7 @@ The configuration is as follows: integration_key: ABCDEF secret_key: 1234567890abcdefghifjkl -The secret key is shown as an example but you'd better set it using an environment +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/ \ No newline at end of file diff --git a/docs/configuration/miscellaneous.md b/docs/configuration/miscellaneous.md index 824313b6..fb61c3e4 100644 --- a/docs/configuration/miscellaneous.md +++ b/docs/configuration/miscellaneous.md @@ -13,7 +13,7 @@ Here are the main customizable options in Authelia. `optional: true` -Defines the address to listen on. +Defines the address and port to listen on. host: 0.0.0.0 port: 9091 @@ -36,7 +36,7 @@ following configuration options: `optional: true` Defines the level of logs used by Authelia. This level can be set to -`trace`, `debug`, `info`. +`trace`, `debug` or `info`. log_level: debug diff --git a/docs/configuration/notifier/filesystem.md b/docs/configuration/notifier/filesystem.md index c1a76506..4ffca6c9 100644 --- a/docs/configuration/notifier/filesystem.md +++ b/docs/configuration/notifier/filesystem.md @@ -9,7 +9,7 @@ nav_order: 1 # Filesystem With this configuration, the message will be sent to a file. This option -should be used only for testing purpose. +should only be used for testing purposes. ```yaml notifier: diff --git a/docs/configuration/regulation.md b/docs/configuration/regulation.md index 51174a75..d2e5f7fd 100644 --- a/docs/configuration/regulation.md +++ b/docs/configuration/regulation.md @@ -7,8 +7,8 @@ nav_order: 7 # Regulation -**Authelia** can temporarily ban accounts when there was too many -authentication attempts. This helps prevent brute force attacks. +**Authelia** can temporarily ban accounts when there are too many +authentication attempts. This helps prevent brute-force attacks. ## Configuration diff --git a/docs/configuration/secrets.md b/docs/configuration/secrets.md index 0ed03048..cd25e954 100644 --- a/docs/configuration/secrets.md +++ b/docs/configuration/secrets.md @@ -14,8 +14,8 @@ below. ## Environment variables -A secret can be configured using an environment variable with name -starting with AUTHELIA_ and followed by the path of the option capitalized +A secret can be configured using an environment variable with the +prefix AUTHELIA_ followed by the path of the option capitalized and with dots replaced by underscores. For instance the LDAP password is identified by the path diff --git a/docs/configuration/storage/index.md b/docs/configuration/storage/index.md index a04e8403..dd5f7b6f 100644 --- a/docs/configuration/storage/index.md +++ b/docs/configuration/storage/index.md @@ -8,13 +8,13 @@ has_children: true # Storage backends -**Authelia** supports multiple storage backends. This backend is used +**Authelia** supports multiple storage backends. The backend is used to store user preferences, 2FA device handles and secrets, authentication logs, etc... The available options are: -* [SQLite](./sqlite.md) * [MariaDB](./mariadb.md) * [MySQL](./mysql.md) -* [Postgres](./postgres.md) \ No newline at end of file +* [Postgres](./postgres.md) +* [SQLite](./sqlite.md) \ No newline at end of file diff --git a/docs/contributing/build-and-dev.md b/docs/contributing/build-and-dev.md index 5184c367..ba6bacca 100644 --- a/docs/contributing/build-and-dev.md +++ b/docs/contributing/build-and-dev.md @@ -24,7 +24,7 @@ your machine. In order to ease development, Authelia uses the concept of [suites] to run Authelia from source code so that your patches are included. This is a kind of virtual environment running **Authelia** in a complete -ecosystem (LDAP, Redis, SQL server). Note that Authelia is hotreloaded +ecosystem (LDAP, Redis, SQL server). Note that Authelia is hot-reloaded in the environment so that your patches are instantly included. The next command starts the suite called *Standalone*: diff --git a/docs/deployment/deployment-ha.md b/docs/deployment/deployment-ha.md index 4bb025e4..3edc16da 100644 --- a/docs/deployment/deployment-ha.md +++ b/docs/deployment/deployment-ha.md @@ -28,7 +28,7 @@ be used with Authelia. With such a setup **Authelia** can easily be scaled to multiple instances to evenly handle the traffic. **NOTE**: If you don't have all those components, don't worry, there is a way to -deploy **Authelia** with only nginx. This is described in [Deployment for Devs]. +deploy **Authelia** with only nginx. This is described in [Deployment - Lite](./deployment-lite.md). Here are the available steps to deploy **Authelia** given the configuration file is **/path/to/your/configuration.yml**. Note that you can @@ -37,7 +37,7 @@ the root of the repo. **NOTE**: Prefer using environment variables to set secrets in production otherwise pay attention to the permissions of the configuration file. See -[configuration.md](../configuration/secrets.md) for more information. +[secrets](../configuration/secrets.md) for more information. ### Deploy with the distributable version diff --git a/docs/deployment/supported-proxies/index.md b/docs/deployment/supported-proxies/index.md index 00fdca5b..a58589dc 100644 --- a/docs/deployment/supported-proxies/index.md +++ b/docs/deployment/supported-proxies/index.md @@ -30,7 +30,7 @@ The target URL can be provided using one of the following ways: * With `X-Original-URL` header containing the complete URL of the initial request. * With a combination of `X-Forwarded-Proto`, `X-Forwarded-Host` and `X-Forwarded-URI` headers. -In the case of Traefik, those headers are automatically provided and therefore don't +In the case of Traefik, these headers are automatically provided and therefore don't appear in the configuration examples. ## Redirection to the login portal diff --git a/docs/features/regulation.md b/docs/features/regulation.md index 8ce81b64..7b77bb63 100644 --- a/docs/features/regulation.md +++ b/docs/features/regulation.md @@ -8,8 +8,8 @@ nav_order: 6 # Regulation **Authelia** takes the security of users very seriously and comes with -a way to avoid brute forcing the first factor by regulating the -authentication attempts and temporarily ban an account when too many +a way to avoid brute-forcing the first factor credentials by regulating the +authentication attempts and temporarily banning an account when too many attempts have been made. ## Configuration diff --git a/docs/home/architecture.md b/docs/home/architecture.md index 2ff19d55..7c7dd098 100644 --- a/docs/home/architecture.md +++ b/docs/home/architecture.md @@ -20,9 +20,9 @@ the reverse proxy but never directly connected to application backends. ## Workflow -Reverse proxies are configured so that every incoming requests generates an authentication -request sent to Authelia and to which Authelia responds to order the reverse -proxy to let the incoming request pass through or block it because user is not authenticated +Reverse proxies are configured so that every incoming request generates an authentication +request sent to Authelia. Authelia responds and will instruct the reverse proxy to either allow +the incoming request to pass through, or block it because the user is not authenticated or is not sufficiently authorized. ### Step by step diff --git a/docs/security/measures.md b/docs/security/measures.md index a2f65028..b3956119 100644 --- a/docs/security/measures.md +++ b/docs/security/measures.md @@ -42,7 +42,7 @@ string generator, which is seeded every time it's used by a cryptographically se This ensures that even if an attacker obtains the file, each password has to be brute forced individually. Lastly Authelia's implementation of Argon2id is highly tunable. You can tune the key length, salt -used, iterations (time), paralellism, and memory usage. To read more about this please read how to +used, iterations (time), parallelism, and memory usage. To read more about this please read how to [configure](../configuration/authentication/file.md) file authentication. ## Notifier security measures (SMTP)