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

docs: improve secrets documentation (#3565) 

Improve documentation around secrets.
pull/3566/head^2
James Elliott 2022-06-21 19:45:08 +10:00 committed by GitHub
parent 143c838efd
commit b102ebb6bb
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
12 changed files with 113 additions and 338 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
docs/content/en/configuration/first-factor/ldap.md
View File

@ -209,8 +209,14 @@ The distinguished name of the user paired with the password to bind with for loo
{{< confkey type="string" required="yes" >}}
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](../methods/secrets.md) which is the recommended for containerized deployments.
*__Important Note:__ This can also be defined using a [secret](../methods/secrets.md) which is __strongly recommended__
especially for containerized deployments.*
The password paired with the [user](#user) used to bind to the LDAP server for lookup and password change operations.
It's __strongly recommended__ this is a
[Random Alphanumeric String](../miscellaneous/guides.md#generating-a-random-alphanumeric-string) with 64 or more
characters and the user password is changed to this value.
## Refresh Interval

17
docs/content/en/configuration/identity-providers/open-id-connect.md
View File

@ -85,22 +85,27 @@ identity_providers:
{{< confkey type="string" required="yes" >}}
The HMAC secret used to sign the [JWT]'s. The provided string is hashed to a SHA256 ([RFC6234]) byte string for the
purpose of meeting the required format. This secret must be generated by the administrator and can be done by following
the [Generating a Random Alphanumeric String](../miscellaneous/guides.md#generating-a-random-alphanumeric-string) guide.
*__Important Note:__ This can also be defined using a [secret](../methods/secrets.md) which is __strongly recommended__
especially for containerized deployments.*
Should be defined using a [secret](../methods/secrets.md) which is the recommended for containerized deployments.
The HMAC secret used to sign the [JWT]'s. The provided string is hashed to a SHA256 ([RFC6234]) byte string for the
purpose of meeting the required format.
It's __strongly recommended__ this is a
[Random Alphanumeric String](../miscellaneous/guides.md#generating-a-random-alphanumeric-string) with 64 or more
characters.
### issuer_private_key
{{< confkey type="string" required="yes" >}}
*__Important Note:__ This can also be defined using a [secret](../methods/secrets.md) which is __strongly recommended__
especially for containerized deployments.*
The private key in DER base64 ([RFC4648]) encoded PEM format used to encrypt the [OpenID Connect] [JWT]'s. The key must
be generated by the administrator and can be done by following the
[Generating an RSA Keypair](../miscellaneous/guides.md#generating-an-rsa-keypair) guide.
Should be defined using a [secret](../methods/secrets.md) which is the recommended for containerized deployments.
### access_token_lifespan
{{< confkey type="duration" default="1h" required="no" >}}

325
docs/content/en/configuration/methods/secrets.md
View File

@ -52,21 +52,36 @@ Here is the list of the environment variables which are considered secrets and c
secrets can be loaded into the configuration if they end with one of the suffixes above, you can set the value of any
other configuration using the environment but instead of loading a file the value of the environment variable is used.
| Configuration Key | Environment Variable |
|:-------------------------------------------------:|:--------------------------------------------------------:|
| tls_key | AUTHELIA_TLS_KEY_FILE |
| jwt_secret | AUTHELIA_JWT_SECRET_FILE |
| duo_api.secret_key | AUTHELIA_DUO_API_SECRET_KEY_FILE |
| session.secret | AUTHELIA_SESSION_SECRET_FILE |
| session.redis.password | AUTHELIA_SESSION_REDIS_PASSWORD_FILE |
| session.redis.high_availability.sentinel_password | AUTHELIA_REDIS_HIGH_AVAILABILITY_SENTINEL_PASSWORD_FILE |
| storage.encryption_key | AUTHELIA_STORAGE_ENCRYPTION_KEY_FILE |
| storage.mysql.password | AUTHELIA_STORAGE_MYSQL_PASSWORD_FILE |
| storage.postgres.password | AUTHELIA_STORAGE_POSTGRES_PASSWORD_FILE |
| notifier.smtp.password | AUTHELIA_NOTIFIER_SMTP_PASSWORD_FILE |
| authentication_backend.ldap.password | AUTHELIA_AUTHENTICATION_BACKEND_LDAP_PASSWORD_FILE |
| identity_providers.oidc.issuer_private_key | AUTHELIA_IDENTITY_PROVIDERS_OIDC_ISSUER_PRIVATE_KEY_FILE |
| identity_providers.oidc.hmac_secret | AUTHELIA_IDENTITY_PROVIDERS_OIDC_HMAC_SECRET_FILE |
| Configuration Key | Environment Variable |
|:---------------------------------------------------:|:--------------------------------------------------------:|
| [server.tls.key] | AUTHELIA_SERVER_TLS_KEY_FILE |
| [jwt_secret] | AUTHELIA_JWT_SECRET_FILE |
| [duo_api.secret_key] | AUTHELIA_DUO_API_SECRET_KEY_FILE |
| [session.secret] | AUTHELIA_SESSION_SECRET_FILE |
| [session.redis.password] | AUTHELIA_SESSION_REDIS_PASSWORD_FILE |
| [session.redis.high_availability.sentinel_password] | AUTHELIA_REDIS_HIGH_AVAILABILITY_SENTINEL_PASSWORD_FILE |
| [storage.encryption_key] | AUTHELIA_STORAGE_ENCRYPTION_KEY_FILE |
| [storage.mysql.password] | AUTHELIA_STORAGE_MYSQL_PASSWORD_FILE |
| [storage.postgres.password] | AUTHELIA_STORAGE_POSTGRES_PASSWORD_FILE |
| [notifier.smtp.password] | AUTHELIA_NOTIFIER_SMTP_PASSWORD_FILE |
| [authentication_backend.ldap.password] | AUTHELIA_AUTHENTICATION_BACKEND_LDAP_PASSWORD_FILE |
| [identity_providers.oidc.issuer_private_key] | AUTHELIA_IDENTITY_PROVIDERS_OIDC_ISSUER_PRIVATE_KEY_FILE |
| [identity_providers.oidc.hmac_secret] | AUTHELIA_IDENTITY_PROVIDERS_OIDC_HMAC_SECRET_FILE |
[server.tls.key]: ../miscellaneous/server.md#key
[jwt_secret]: ../miscellaneous/introduction.md#jwt_secret
[duo_api.secret_key]: ../second-factor/duo.md#secret_key
[session.secret]: ../session/introduction.md#secret
[session.redis.password]: ../session/redis.md#password
[session.redis.high_availability.sentinel_password]: ../session/redis.md#sentinel_password
[storage.encryption_key]: ../storage/introduction.md#encryption_key
[storage.mysql.password]: ../storage/mysql.md#password
[storage.postgres.password]: ../storage/postgres.md#password
[notifier.smtp.password]: ../notifications/smtp.md#password
[authentication_backend.ldap.password]: ../first-factor/ldap.md#password
[identity_providers.oidc.issuer_private_key]: ../identity-providers/open-id-connect.md#issuer_private_key
[identity_providers.oidc.hmac_secret]: ../identity-providers/open-id-connect.md#hmac_secret
## Secrets in configuration file
@ -86,281 +101,7 @@ via environment variables in plain text.
See [this article](https://diogomonica.com/2017/03/27/why-you-shouldnt-use-env-variables-for-secret-data/) for reasons
why setting them via the file counterparts is highly encouraged.
## Docker
## Examples
Secrets can be provided in a `docker-compose.yml` either with Docker secrets or
bind mounted secret files, examples of these are provided below.
### Compose with Docker secrets
This example assumes secrets are stored in `/path/to/authelia/secrets/{secretname}`
on the host and are exposed with Docker secrets in a `docker-compose.yml` file:
```yaml
version: '3.8'
networks:
net:
driver: bridge
secrets:
jwt:
file: /path/to/authelia/secrets/jwt
duo:
file: /path/to/authelia/secrets/duo
session:
file: /path/to/authelia/secrets/session
redis:
file: /path/to/authelia/secrets/redis
mysql:
file: /path/to/authelia/secrets/mysql
smtp:
file: /path/to/authelia/secrets/smtp
ldap:
file: /path/to/authelia/secrets/ldap
services:
authelia:
image: authelia/authelia
container_name: authelia
secrets:
- jwt
- duo
- session
- redis
- mysql
- smtp
- ldap
volumes:
- /path/to/authelia:/config
networks:
- net
expose:
- 9091
restart: unless-stopped
environment:
- AUTHELIA_JWT_SECRET_FILE=/run/secrets/jwt
- AUTHELIA_DUO_API_SECRET_KEY_FILE=/run/secrets/duo
- AUTHELIA_SESSION_SECRET_FILE=/run/secrets/session
- AUTHELIA_SESSION_REDIS_PASSWORD_FILE=/run/secrets/redis
- AUTHELIA_STORAGE_MYSQL_PASSWORD_FILE=/run/secrets/mysql
- AUTHELIA_NOTIFIER_SMTP_PASSWORD_FILE=/run/secrets/smtp
- AUTHELIA_AUTHENTICATION_BACKEND_LDAP_PASSWORD_FILE=/run/secrets/ldap
- TZ=Australia/Melbourne
```
### Compose with bind mounted secret files
This example assumes secrets are stored in `/path/to/authelia/secrets/{secretname}`
on the host and are exposed with bind mounted secret files in a `docker-compose.yml` file
at `/config/secrets/`:
```yaml
version: '3.8'
networks:
net:
driver: bridge
services:
authelia:
image: authelia/authelia
container_name: authelia
volumes:
- /path/to/authelia:/config
networks:
- net
expose:
- 9091
restart: unless-stopped
environment:
- AUTHELIA_JWT_SECRET_FILE=/config/secrets/jwt
- AUTHELIA_DUO_API_SECRET_KEY_FILE=/config/secrets/duo
- AUTHELIA_SESSION_SECRET_FILE=/config/secrets/session
- AUTHELIA_SESSION_REDIS_PASSWORD_FILE=/config/secrets/redis
- AUTHELIA_STORAGE_MYSQL_PASSWORD_FILE=/config/secrets/mysql
- AUTHELIA_NOTIFIER_SMTP_PASSWORD_FILE=/config/secrets/smtp
- AUTHELIA_AUTHENTICATION_BACKEND_LDAP_PASSWORD_FILE=/config/secrets/ldap
- TZ=Australia/Melbourne
```
## Kubernetes
Secrets can be mounted as files using the following sample manifests.
To create a secret, the following manifest can be used
```yaml
---
kind: Secret
apiVersion: v1
metadata:
name: a-nice-name
namespace: your-authelia-namespace
data:
duo_key: >-
UXE1WmM4S0pldnl6eHRwQ3psTGpDbFplOXFueUVyWEZhYjE0Z01IRHN0RT0K
jwt_secret: >-
anotherBase64EncodedSecret
...
```
where `UXE1WmM4S0pldnl6eHRwQ3psTGpDbFplOXFueUVyWEZhYjE0Z01IRHN0RT0K` is Base64 encoded for
`Qq5Zc8KJevyzxtpCzlLjClZe9qnyErXFab14gMHDstE`, the actual content of the secret. You can generate these contents with
```console
LENGTH=64
tr -cd '[:alnum:]' < /dev/urandom \
| fold -w "${LENGTH}" \
| head -n 1 \
| tr -d '\n' \
| tee actualSecretContent.txt \
| base64 --wrap 0 \
; echo
```
which writes the secret's content to the `actualSecretContent.txt` file and print the Base64 encoded version on `stdout`. `${LENGTH}` is the length in characters of the secret content generated by this pipe. If you don't want the contents to be written to `actualSecretContent.txt`, just delete the line with the `tee` command.
### Kustomization
* __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 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 template (or deployment template if you're using it).
```yaml
#filename: ./kustomization.yaml
generatorOptions:
disableNameSuffixHash: true
labels:
type: generated
app: authelia
configMapGenerator:
- name: authelia
files:
- configuration.yml
secretGenerator:
- name: authelia
literals:
- jwt_secret=myverysecuresecret
- session_secret=mysessionsecret
- redis_password=myredispassword
- sql_password=mysqlpassword
- ldap_password=myldappassword
- duo_secret=myduosecretkey
- smtp_password=mysmtppassword
```
### DaemonSet
* __Filename:__ ./daemonset.yaml
* __Command:__ kubectl apply -f ./daemonset.yaml
* __Notes:__ assumes Kubernetes API 1.16 or greater
```yaml
#filename: daemonset.yaml
#command: kubectl apply -f daemonset.yaml
#notes: assumes kubernetes api 1.16+
apiVersion: apps/v1
kind: DaemonSet
metadata:
name: authelia
namespace: authelia
labels:
app: authelia
spec:
selector:
matchLabels:
app: authelia
updateStrategy:
type: RollingUpdate
template:
metadata:
labels:
app: authelia
spec:
containers:
- name: authelia
image: authelia/authelia:latest
imagePullPolicy: IfNotPresent
env:
- name: AUTHELIA_JWT_SECRET_FILE
value: /app/secrets/jwt
- name: AUTHELIA_DUO_API_SECRET_KEY_FILE
value: /app/secrets/duo
- name: AUTHELIA_SESSION_SECRET_FILE
value: /app/secrets/session
- name: AUTHELIA_AUTHENTICATION_BACKEND_LDAP_PASSWORD_FILE
value: /app/secrets/ldap_password
- name: AUTHELIA_NOTIFIER_SMTP_PASSWORD_FILE
value: /app/secrets/smtp_password
- name: AUTHELIA_STORAGE_MYSQL_PASSWORD_FILE
value: /app/secrets/sql_password
- name: AUTHELIA_SESSION_REDIS_PASSWORD_FILE
value: /app/secrets/redis_password
- name: TZ
value: America/Toronto
ports:
- name: authelia-port
containerPort: 9091
startupProbe:
httpGet:
path: /api/state
port: authelia-port
initialDelaySeconds: 15
timeoutSeconds: 5
periodSeconds: 5
failureThreshold: 4
livenessProbe:
httpGet:
path: /api/state
port: authelia-port
initialDelaySeconds: 60
timeoutSeconds: 5
periodSeconds: 30
failureThreshold: 2
readinessProbe:
httpGet:
path: /api/state
port: authelia-port
initialDelaySeconds: 15
timeoutSeconds: 5
periodSeconds: 5
failureThreshold: 5
volumeMounts:
- mountPath: /config
name: config-volume
- mountPath: /app/secrets
name: secrets
readOnly: true
volumes:
- name: config-volume
configMap:
name: authelia
items:
- key: configuration.yml
path: configuration.yml
- name: secrets
secret:
secretName: authelia
items:
- key: jwt_secret
path: jwt
- key: duo_secret
path: duo
- key: session_secret
path: session
- key: redis_password
path: redis_password
- key: sql_password
path: sql_password
- key: ldap_password
path: ldap_password
- key: smtp_password
path: smtp_password
```
See the [Docker Integration](../../integration/deployment/docker.md) and
[Kubernetes Integration](../../integration/kubernetes/introduction/index.md) guides for examples of secrets.

8
docs/content/en/configuration/miscellaneous/introduction.md
View File

@ -69,8 +69,12 @@ default_2fa_method: totp
{{< confkey type="string" required="yes" >}}
Defines the secret used to craft JWT tokens leveraged by the identity
verification process. This can also be defined using a [secret](../methods/secrets.md).
*__Important Note:__ This can also be defined using a [secret](../methods/secrets.md) which is __strongly recommended__
especially for containerized deployments.*
Defines the secret used to craft JWT tokens leveraged by the identity verification process. This can a random string.
It's strongly recommended this is a [Random Alphanumeric String](guides.md#generating-a-random-alphanumeric-string) with
64 or more characters.
### theme

12
docs/content/en/configuration/notifications/smtp.md
View File

@ -74,12 +74,14 @@ The username sent for authentication with the SMTP server. Paired with the passw
{{< confkey type="string" required="no" >}}
The password sent for authentication with the SMTP server. Paired with the username. Can also be defined using a
[secret](../methods/secrets.md) which is the recommended for containerized deployments.
*__Important Note:__ This can also be defined using a [secret](../methods/secrets.md) which is __strongly recommended__
especially for containerized deployments.*
We recommend generating a random string with 64 characters or more for this purposes which can be done by following the
[Generating a Random Alphanumeric String](../miscellaneous/guides.md#generating-a-random-alphanumeric-string)
guide.
The password paired with the [username](#username) sent for authentication with the SMTP server.
It's __strongly recommended__ this is a
[Random Alphanumeric String](../miscellaneous/guides.md#generating-a-random-alphanumeric-string) with 64 or more
characters and the user password is changed to this value.
### sender

10
docs/content/en/configuration/second-factor/duo.md
View File

@ -47,20 +47,22 @@ true.
{{< confkey type="string" required="yes" >}}
The [Duo] API hostname supplied by [Duo].
The [Duo] API hostname. This is provided in the [Duo] dashboard.
### integration_key
{{< confkey type="string" required="yes" >}}
The non-secret [Duo] integration key. Similar to a client identifier.
The non-secret [Duo] integration key. Similar to a client identifier. This is provided in the [Duo] dashboard.
### secret_key
{{< confkey type="string" required="yes" >}}
The secret [Duo] key used to verify your application is valid. It's recommended to set this via a
[secret](../methods/secrets.md).
*__Important Note:__ This can also be defined using a [secret](../methods/secrets.md) which is __strongly recommended__
especially for containerized deployments.*
The secret [Duo] key used to verify your application is valid. This is provided in the [Duo] dashboard.
### enable_self_enrollment

15
docs/content/en/configuration/session/introduction.md
View File

@ -82,12 +82,14 @@ state but it's available as an option anyway.
{{< confkey type="string" required="yes" >}}
The secret key used to encrypt session data in Redis. It's recommended this is set using a
[secret](../methods/secrets.md).
*__Important Note:__ This can also be defined using a [secret](../methods/secrets.md) which is __strongly recommended__
especially for containerized deployments.*
We recommend generating a random string with 64 characters or more for this purposes which can be done by following the
[Generating a Random Alphanumeric String](../miscellaneous/guides.md#generating-a-random-alphanumeric-string)
guide.
The secret key used to encrypt session data in Redis.
It's __strongly recommended__ this is a
[Random Alphanumeric String](../miscellaneous/guides.md#generating-a-random-alphanumeric-string) with 64 or more
characters.
### expiration
@ -124,6 +126,3 @@ this to `-1` disables this feature entirely.
Configuration of this section has an impact on security. You should read notes in
[security measures](../../overview/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](../methods/secrets.md).

16
docs/content/en/configuration/session/redis.md
View File

@ -80,11 +80,14 @@ through the process of setting up [redis ACLs](https://redis.io/topics/acl).
{{< confkey type="string" required="no" >}}
*__Important Note:__ This can also be defined using a [secret](../methods/secrets.md) which is __strongly recommended__
especially for containerized deployments.*
The password for [redis authentication](https://redis.io/commands/auth).
We recommend generating a random string with 64 characters or more for this purposes which can be done by following the
[Generating a Random Alphanumeric String](../miscellaneous/guides.md#generating-a-random-alphanumeric-string)
guide.
It's __strongly recommended__ this is a
[Random Alphanumeric String](../miscellaneous/guides.md#generating-a-random-alphanumeric-string) with 64 or more
characters and the user password is changed to this value.
### database_index
@ -134,10 +137,17 @@ be authenticated with traditional [requirepass] authentication.
{{< confkey type="string" required="no (yes if sentinel_username is supplied)" >}}
*__Important Note:__ This can also be defined using a [secret](../methods/secrets.md) which is __strongly recommended__
especially for containerized deployments.*
The password for the [redis sentinel] connection. If specified with sentinel_username, configures Authelia to
authenticate to the Redis Sentinel with ACL-based authentication. Otherwise, this is used for [requirepass]
authentication.
It's __strongly recommended__ this is a
[Random Alphanumeric String](../miscellaneous/guides.md#generating-a-random-alphanumeric-string) with 64 or more
characters and the user password is changed to this value.
#### nodes
A list of [redis sentinel] nodes to load balance over. This list is added to the host in the [redis] section above. It

12
docs/content/en/configuration/storage/introduction.md
View File

@ -35,15 +35,17 @@ storage:
{{< confkey type="string" required="yes" >}}
*__Important Note:__ This can also be defined using a [secret](../methods/secrets.md) which is __strongly recommended__
especially for containerized deployments.*
The encryption key used to encrypt data in the database. We encrypt data by creating a sha256 checksum of the provided
value, and use that to encrypt the data with the AES-GCM 256bit algorithm.
The minimum length of this key is 20 characters, however we generally recommend above 64 characters.
The minimum length of this key is 20 characters.
This secret must be generated by the administrator and can
be done by following the
[Generating a Random Alphanumeric String](../miscellaneous/guides.md#generating-a-random-alphanumeric-string)
guide.
It's __strongly recommended__ this is a
[Random Alphanumeric String](../miscellaneous/guides.md#generating-a-random-alphanumeric-string) with 64 or more
characters.
See [securty measures](../../overview/security/measures.md#storage-security-measures) for more information.

12
docs/content/en/configuration/storage/mysql.md
View File

@ -86,12 +86,14 @@ The username paired with the password used to connect to the database.
{{< confkey type="string" required="yes" >}}
The password paired with the username used to connect to the database. Can also be defined using a
[secret](../methods/secrets.md) which is also the recommended way when running as a container.
*__Important Note:__ This can also be defined using a [secret](../methods/secrets.md) which is __strongly recommended__
especially for containerized deployments.*
We recommend generating a random string with 64 characters or more for this purposes which can be done by following the
[Generating a Random Alphanumeric String](../miscellaneous/guides.md#generating-a-random-alphanumeric-string)
guide.
The password paired with the [username](#username) used to connect to the database.
It's __strongly recommended__ this is a
[Random Alphanumeric String](../miscellaneous/guides.md#generating-a-random-alphanumeric-string) with 64 or more
characters and the user password is changed to this value.
### timeout

12
docs/content/en/configuration/storage/postgres.md
View File

@ -95,12 +95,14 @@ The username paired with the password used to connect to the database.
{{< confkey type="string" required="yes" >}}
The password paired with the username used to connect to the database. Can also be defined using a
[secret](../methods/secrets.md) which is also the recommended way when running as a container.
*__Important Note:__ This can also be defined using a [secret](../methods/secrets.md) which is __strongly recommended__
especially for containerized deployments.*
We recommend generating a random string with 64 characters or more for this purposes which can be done by following the
[Generating a Random Alphanumeric String](../miscellaneous/guides.md#generating-a-random-alphanumeric-string)
guide.
The password paired with the [username](#username) used to connect to the database.
It's __strongly recommended__ this is a
[Random Alphanumeric String](../miscellaneous/guides.md#generating-a-random-alphanumeric-string) with 64 or more
characters and the user password is changed to this value.
### timeout

2
docs/content/en/integration/deployment/docker.md
View File

@ -34,7 +34,7 @@ The following is an example [Docker Compose] deployment with just *Authelia* and
It expects the following:
* The file `data/authelia/config/configuration.yml` is present and the configuration file.
* The files `data/authelia/secrets/*` exist and contain the relevant secrets.
* The files `data/authelia/secrets/*` exist and contain the relevant [secrets](../../configuration/methods/secrets.md).
* You're using PostgreSQL.
* You have an external network named `net` which is in bridge mode.