From 7f19078efbd086ee7e14308095261bf34d9a304a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Cl=C3=A9ment=20Michaud?= Date: Sat, 1 Feb 2020 14:17:39 +0100 Subject: [PATCH] [MISC] Document usage of env variables for setting secrets. (#606) Closes #579. --- config.template.yml | 17 ++++++++++------- docs/configuration.md | 21 +++++++++++++++++++++ docs/deployment-production.md | 7 +++++-- 3 files changed, 36 insertions(+), 9 deletions(-) diff --git a/config.template.yml b/config.template.yml index 646ab625..a3c81d88 100644 --- a/config.template.yml +++ b/config.template.yml @@ -11,6 +11,7 @@ logs_level: debug # The secret used to generate JWT tokens when validating user identity by # email confirmation. +# This secret can also be set using the env variables AUTHELIA_JWT_SECRET jwt_secret: a_very_important_secret # Default redirection URL @@ -44,6 +45,7 @@ totp: 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 secret_key: 1234567890abcdefghifjkl # The authentication backend to use for verifying user passwords @@ -64,33 +66,27 @@ authentication_backend: skip_verify: false # The base dn for every entries base_dn: dc=example,dc=com - # An additional dn to define the scope to all users additional_users_dn: ou=users - # The users filter used to find the user DN # {0} is a matcher replaced by username. # 'cn={0}' by default. users_filter: (cn={0}) - # An additional dn to define the scope of groups additional_groups_dn: ou=groups - # The groups filter used for retrieving groups of a given user. # {0} is a matcher replaced by username. # {dn} is a matcher replaced by user DN. # {uid} is a matcher replaced by user uid. # 'member={dn}' by default. 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 # File backend configuration. @@ -207,6 +203,7 @@ session: name: authelia_session # The secret to encrypt the session cookie. + # This secret can also be set using the env variables AUTHELIA_SESSION_SECRET secret: unsecure_session_secret # The time in seconds before the cookie expires and session is reset. @@ -224,6 +221,7 @@ session: redis: host: 127.0.0.1 port: 6379 + # This secret can also be set using the env variables AUTHELIA_SESSION_REDIS_PASSWORD password: authelia # Configuration of the authentication regulation mechanism. @@ -257,6 +255,7 @@ storage: port: 3306 database: authelia username: authelia + # This secret can also be set using the env variables AUTHELIA_STORAGE_MYSQL_PASSWORD password: mypassword # Settings to connect to MySQL server @@ -265,6 +264,7 @@ storage: # port: 3306 # database: authelia # username: authelia + # # This secret can also be set using the env variables AUTHELIA_STORAGE_POSTGRES_PASSWORD # password: mypassword # Configuration of the notification system. @@ -290,6 +290,7 @@ notifier: # - use the disable_verify_cert boolean value to disable the validation (prefer the trusted_cert option as it's more secure) smtp: username: test + # This secret can also be set using the env variables AUTHELIA_NOTIFIER_SMTP_PASSWORD password: password host: 127.0.0.1 port: 1025 @@ -297,10 +298,12 @@ notifier: ## disable_require_tls: false ## disable_verify_cert: false ## trusted_cert: "" + # 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 + ## # This secret can also be set using the env variables AUTHELIA_NOTIFIER_SMTP_PASSWORD ## password: yourapppassword ## sender: admin@example.com ## host: smtp.gmail.com diff --git a/docs/configuration.md b/docs/configuration.md index cfdc0c5d..ae4d43ac 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -10,3 +10,24 @@ the file path as the first argument of **Authelia**. $ authelia --config config.custom.yml + +## Secrets + +Configuration of Authelia requires some secrets or passwords. Please +note that the recommended way to set secrets in Authelia is to use +environment variables. + +A secret in Authelia configuration could be set by providing the +environment variable prefixed by AUTHELIA_ and with name equals to +the capitalized path of the configuration key and with dots replaced +by underscores. + +For instance the LDAP password is identified by the path +**authentication_backend.ldap.password**, so this password could +alternatively be set using the environment variable called +**AUTHELIA_AUTHENTICATION_BACKEND_LDAP_PASSWORD**. + +If for some reason you prefer keeping the secrets in the configuration +file, be sure to apply the right permissions to the file in order to +prevent secret leaks if an another application gets compromised on your +server. The UNIX permissions should probably be something like 600. \ No newline at end of file diff --git a/docs/deployment-production.md b/docs/deployment-production.md index 6eb5cfa1..edaef099 100644 --- a/docs/deployment-production.md +++ b/docs/deployment-production.md @@ -20,7 +20,7 @@ persist user configurations and one or more nginx reverse proxies configured to 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 +**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]. Here are the available steps to deploy **Authelia** given @@ -28,6 +28,10 @@ the configuration file is **/path/to/your/configuration.yml**. Note that you can create your own configuration file from [config.template.yml] located at 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.md#secrets) for more information. + ### Deploy with the distributable version # Build it if not done already @@ -38,7 +42,6 @@ the root of the repo. $ docker run -v /path/to/your/configuration.yml:/etc/authelia/configuration.yml -e TZ=Europe/Paris authelia/authelia - ## On top of Kubernetes