RPJosh
/
authelia
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

[DOCS] Adjust yaml snippets and misc adjustments (#855) 

* [DOCS] Adjust yaml snippets

* use two spaces
* use yaml syntax highlighting
* other misc uniformity changes
* fix misc grammar
* add responsible disclosure link

Co-Authored-By: Amir Zarrinkafsh <nightah@me.com>
pull/848/head^2
James Elliott 2020-04-11 14:46:07 +10:00 committed by GitHub
parent b3ce7fc379
commit b0b3d61954
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
18 changed files with 220 additions and 196 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

63
docs/configuration/access-control.md
View File

@ -92,40 +92,41 @@ configure Authelia accordingly.
Here is a complete example of complex access control list that can be defined in Authelia.
access_control:
default_policy: deny
```yaml
access_control:
default_policy: deny
rules:
- domain: public.example.com
policy: bypass
rules:
- domain: public.example.com
policy: bypass
- domain: secure.example.com
policy: one_factor
networks:
- 192.168.1.0/24
- domain: secure.example.com
policy: one_factor
networks:
- 192.168.1.0/24
- domain: secure.example.com
policy: two_factor
- domain: secure.example.com
policy: two_factor
- domain: singlefactor.example.com
policy: one_factor
- domain: singlefactor.example.com
policy: one_factor
- domain: "mx2.mail.example.com"
subject: "group:admins"
policy: deny
- domain: "*.example.com"
subject: "group:admins"
policy: two_factor
- domain: "mx2.mail.example.com"
subject: "group:admins"
policy: deny
- domain: dev.example.com
resources:
- "^/groups/dev/.*$"
subject: "group:dev"
policy: two_factor
- domain: "*.example.com"
subject: "group:admins"
policy: two_factor
- domain: dev.example.com
resources:
- "^/users/john/.*$"
subject: "user:john"
policy: two_factor
- domain: dev.example.com
resources:
- "^/groups/dev/.*$"
subject: "group:dev"
policy: two_factor
- domain: dev.example.com
resources:
- "^/users/john/.*$"
subject: "user:john"
policy: two_factor
```

74
docs/configuration/authentication/file.md
View File

@ -15,44 +15,46 @@ nav_order: 1
Configuring Authelia to use a file is done by specifying the path to the
file in the configuration file.
authentication_backend:
disable_reset_password: false
file:
path: /var/lib/authelia/users.yml
password:
algorithm: argon2id
iterations: 1
salt_length: 16
parallelism: 8
memory: 1024
```yaml
authentication_backend:
disable_reset_password: false
file:
path: /var/lib/authelia/users.yml
password:
algorithm: argon2id
iterations: 1
salt_length: 16
parallelism: 8
memory: 1024
```
## Format
The format of the users file is as follows.
users:
john:
password: "$argon2id$v=19$m=65536,t=3,p=2$BpLnfgDsc2WD8F2q$o/vzA4myCqZZ36bUGsDY//8mKUYNZZaR0t4MFFSs+iM"
email: john.doe@authelia.com
groups:
- admins
- dev
harry:
password: "$argon2id$v=19$m=65536,t=3,p=2$BpLnfgDsc2WD8F2q$o/vzA4myCqZZ36bUGsDY//8mKUYNZZaR0t4MFFSs+iM"
email: harry.potter@authelia.com
groups: []
bob:
password: "$argon2id$v=19$m=65536,t=3,p=2$BpLnfgDsc2WD8F2q$o/vzA4myCqZZ36bUGsDY//8mKUYNZZaR0t4MFFSs+iM"
email: bob.dylan@authelia.com
groups:
- dev
james:
password: "$argon2id$v=19$m=65536,t=3,p=2$BpLnfgDsc2WD8F2q$o/vzA4myCqZZ36bUGsDY//8mKUYNZZaR0t4MFFSs+iM"
email: james.dean@authelia.com
```yaml
users:
john:
password: "$argon2id$v=19$m=65536,t=3,p=2$BpLnfgDsc2WD8F2q$o/vzA4myCqZZ36bUGsDY//8mKUYNZZaR0t4MFFSs+iM"
email: john.doe@authelia.com
groups:
- admins
- dev
harry:
password: "$argon2id$v=19$m=65536,t=3,p=2$BpLnfgDsc2WD8F2q$o/vzA4myCqZZ36bUGsDY//8mKUYNZZaR0t4MFFSs+iM"
email: harry.potter@authelia.com
groups: []
bob:
password: "$argon2id$v=19$m=65536,t=3,p=2$BpLnfgDsc2WD8F2q$o/vzA4myCqZZ36bUGsDY//8mKUYNZZaR0t4MFFSs+iM"
email: bob.dylan@authelia.com
groups:
- dev
james:
password: "$argon2id$v=19$m=65536,t=3,p=2$BpLnfgDsc2WD8F2q$o/vzA4myCqZZ36bUGsDY//8mKUYNZZaR0t4MFFSs+iM"
email: james.dean@authelia.com
```
This file should be set with read/write permissions as it could be updated by users
@ -73,7 +75,7 @@ always be valid for base64 decoding (characters a through z, A through Z, 0 thro
For instance to generate a hash with the docker image just run:
$ docker run authelia/authelia:latest authelia hash-password yourpassword
$ Password hash: $argon2id$v=19$m=65536$3oc26byQuSkQqksq$zM1QiTvVPrMfV6BVLs2t4gM+af5IN7euO0VB6+Q8ZFs
Password hash: $argon2id$v=19$m=65536$3oc26byQuSkQqksq$zM1QiTvVPrMfV6BVLs2t4gM+af5IN7euO0VB6+Q8ZFs
Full CLI Help Documentation:
@ -116,8 +118,10 @@ 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
`stress-ng --vm-bytes $(awk '/MemFree/{printf "%d\n", $2 * 0.9;}' < /proc/meminfo)k --vm-keep -m 1`.
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)
2. adjusting the [memory](#memory) parameter

114
docs/configuration/authentication/ldap.md
View File

@ -16,66 +16,66 @@ Configuration of the LDAP backend is done as follows
```yaml
authentication_backend:
disable_reset_password: false
ldap:
# The url to the ldap server. Scheme can be ldap:// or ldaps://
url: ldap://127.0.0.1
disable_reset_password: false
ldap:
# The url to the ldap server. Scheme can be ldap:// or ldaps://
url: ldap://127.0.0.1
# Skip verifying the server certificate (to allow self-signed certificate).
skip_verify: false
# Skip verifying the server certificate (to allow self-signed certificate).
skip_verify: false
# The base dn for every entries
base_dn: dc=example,dc=com
# The base dn for every entries
base_dn: dc=example,dc=com
# 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'
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 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.
groups_filter: (&(member={dn})(objectclass=groupOfNames))
# The attribute holding the name of the group
group_name_attribute: cn
# The attribute holding the mail address of the user
mail_attribute: mail
# The username and password of the admin user.
user: cn=admin,dc=example,dc=com
# This secret can also be set using the env variables AUTHELIA_AUTHENTICATION_BACKEND_LDAP_PASSWORD
password: password
# The 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'
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 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.
groups_filter: (&(member={dn})(objectclass=groupOfNames))
# The attribute holding the name of the group
group_name_attribute: cn
# The attribute holding the mail address of the user
mail_attribute: mail
# The username and password of the admin user.
user: cn=admin,dc=example,dc=com
# This secret can also be set using the env variables AUTHELIA_AUTHENTICATION_BACKEND_LDAP_PASSWORD
password: password
```
The user must have an email address in order for Authelia to perform

10
docs/configuration/duo-push-notifications.md
View File

@ -15,11 +15,13 @@ to know how to set up push notifications in Authelia.
## Configuration
The configuration is as follows:
```yaml
duo_api:
hostname: api-123456789.example.com
integration_key: ABCDEF
secret_key: 1234567890abcdefghifjkl
```
duo_api:
hostname: api-123456789.example.com
integration_key: ABCDEF
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).

4
docs/configuration/google-analytics.md
View File

@ -10,4 +10,6 @@ nav_order: 4
It is possible to provide a Google Analytics ID to Authelia in order
to monitor the usage of the Sign-In portal.
google_analytics: UA-00000-01
```yaml
google_analytics: UA-00000-01
```

25
docs/configuration/miscellaneous.md
View File

@ -15,8 +15,10 @@ Here are the main customizable options in Authelia.
Defines the address and port to listen on.
host: 0.0.0.0
port: 9091
```yaml
host: 0.0.0.0
port: 9091
```
## TLS
@ -25,9 +27,10 @@ Defines the address and port to listen on.
Authelia can use TLS. Provide the certificate and the key with the
following configuration options:
tls_key: /var/lib/authelia/ssl/key.pem
tls_cert: /var/lib/authelia/ssl/cert.pem
```yaml
tls_key: /var/lib/authelia/ssl/key.pem
tls_cert: /var/lib/authelia/ssl/cert.pem
```
## Log
@ -38,7 +41,9 @@ following configuration options:
Defines the level of logs used by Authelia. This level can be set to
`trace`, `debug` or `info`.
log_level: debug
```yaml
log_level: debug
```
### Log file path
@ -47,7 +52,9 @@ Defines the level of logs used by Authelia. This level can be set to
Logs can be stored in a file when file path is provided. Otherwise logs
are written to standard output.
log_file_path: /var/log/authelia.log
```yaml
log_file_path: /var/log/authelia.log
```
## JWT Secret
@ -57,7 +64,9 @@ are written to standard output.
Defines the secret used to craft JWT tokens leveraged by the identity
verification process
jwt_secret: v3ry_important_s3cr3t
```yaml
jwt_secret: v3ry_important_s3cr3t
```
## Default redirection URL

4
docs/configuration/notifier/filesystem.md
View File

@ -13,6 +13,6 @@ should only be used for testing purposes.
```yaml
notifier:
filesystem:
filename: /tmp/authelia/notification.txt
filesystem:
filename: /tmp/authelia/notification.txt
```

14
docs/configuration/notifier/smtp.md
View File

@ -55,11 +55,11 @@ described [here](https://support.google.com/accounts/answer/185833?hl=en)
```yaml
notifier:
smtp:
username: myaccount@gmail.com
# This secret can also be set using the env variables AUTHELIA_NOTIFIER_SMTP_PASSWORD
password: yourapppassword
sender: admin@example.com
host: smtp.gmail.com
port: 587
smtp:
username: myaccount@gmail.com
# This secret can also be set using the env variables AUTHELIA_NOTIFIER_SMTP_PASSWORD
password: yourapppassword
sender: admin@example.com
host: smtp.gmail.com
port: 587
```

11
docs/configuration/one-time-password.md
View File

@ -11,10 +11,13 @@ 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.
totp:
issuer: authelia.com
period: 30
skew: 1
```yaml
totp:
issuer: authelia.com
period: 30
skew: 1
```
## Issuer

20
docs/configuration/regulation.md
View File

@ -14,18 +14,18 @@ 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 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 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
# 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

14
docs/configuration/storage/mariadb.md
View File

@ -10,11 +10,11 @@ nav_order: 1
```yaml
storage:
mysql:
host: 127.0.0.1
port: 3306
database: authelia
username: authelia
# This secret can also be set using the env variables AUTHELIA_STORAGE_MYSQL_PASSWORD
password: mypassword
mysql:
host: 127.0.0.1
port: 3306
database: authelia
username: authelia
# This secret can also be set using the env variables AUTHELIA_STORAGE_MYSQL_PASSWORD
password: mypassword
```

14
docs/configuration/storage/mysql.md
View File

@ -10,11 +10,11 @@ nav_order: 2
```yaml
storage:
mysql:
host: 127.0.0.1
port: 3306
database: authelia
username: authelia
# This secret can also be set using the env variables AUTHELIA_STORAGE_MYSQL_PASSWORD
password: mypassword
mysql:
host: 127.0.0.1
port: 3306
database: authelia
username: authelia
# This secret can also be set using the env variables AUTHELIA_STORAGE_MYSQL_PASSWORD
password: mypassword
```

14
docs/configuration/storage/postgres.md
View File

@ -10,11 +10,11 @@ nav_order: 3
```yaml
storage:
postgres:
host: 127.0.0.1
port: 5432
database: authelia
username: authelia
# This secret can also be set using the env variables AUTHELIA_STORAGE_POSTGRES_PASSWORD
password: mypassword
postgres:
host: 127.0.0.1
port: 5432
database: authelia
username: authelia
# This secret can also be set using the env variables AUTHELIA_STORAGE_POSTGRES_PASSWORD
password: mypassword
```

4
docs/configuration/storage/sqlite.md
View File

@ -18,6 +18,6 @@ Just give the path to the sqlite database. It will be created if the file does n
```yaml
storage:
local:
path: /var/lib/authelia/db.sqlite3
local:
path: /var/lib/authelia/db.sqlite3
```

10
docs/contributing/authelia-scripts.md
View File

@ -12,22 +12,22 @@ testing the code, etc...
Those scripts becomes available after sourcing the bootstrap.sh script with
source bootstrap.sh
$ source bootstrap.sh
Then, you can access the scripts usage by running the following command:
authelia-scripts --help
$ authelia-scripts --help
For instance, you can build Authelia (Go binary and frontend) with:
authelia-scripts build
$ authelia-scripts build
Or build the official Docker image with:
authelia-scripts docker build
$ authelia-scripts docker build
Or start the *Standalone* suite with:
authelia-scripts suites setup Standalone
$ authelia-scripts suites setup Standalone
You will find more information in the scripts usage helpers.

2
docs/contributing/suites.md
View File

@ -46,7 +46,7 @@ specific suite like *HighAvailability*, you can do so with the next command:
Running all tests is easy. Make sure that no suite is already running and run:
authelia-scripts suites test
$ authelia-scripts suites test
### Run tests in headless mode

7
docs/features/password-reset.md
View File

@ -7,9 +7,10 @@ nav_order: 4
# Password Reset
**Authelia** provides workflow to let users reset their password when they lose it.
**Authelia** provides a workflow to let users reset their password when they lose it.
To disable reset password functionality please see the [configuration docs](../configuration/authentication/index.md#disabling-reset-password).
A simple click on `Forgot password?` for starting the process. Note that resetting a
A simple click on `Reset password?` for starting the process. Note that resetting a
password requires a new identity verification using the e-mail of the user.
<p align="center">
@ -22,7 +23,7 @@ Give your username and receive an e-mail to verify your identity.
<img src="../images/RESET-PASSWORD-STEP1.png" width="400">
</p>
Once your identity is verified, fill in the form to reset your password.
Once your identity has been verified, fill in the form to reset your password.
<p align="center">
<img src="../images/RESET-PASSWORD-STEP2.png" width="400">

12
docs/security/index.md
View File

@ -7,9 +7,11 @@ has_children: true
# Security
Security is taken very seriously here, therefore we follow the rule of
responsible disclosure and we encourage you to do so.
Authelia takes security very seriously. We follow the rule of
[responsible disclosure](https://en.wikipedia.org/wiki/Responsible_disclosure), and we
encourage the community to as well.
Would you like to report any vulnerability discovered in Authelia, please
first contact **clems4ever** on [Matrix](https://riot.im/app/#/room/#authelia:matrix.org)
or by [email](mailto:clement.michaud34@gmail.com).
If you discover a vulnerability in Authelia, please first contact **clems4ever** on
[Matrix](https://riot.im/app/#/room/#authelia:matrix.org) or by
[email](mailto:clement.michaud34@gmail.com).