authelia/docs/security.md

# Security

## Protection against cookie theft

Authelia uses two mechanisms to protect against cookie theft:
1. session attribute `httpOnly` set to true make client-side code unable to
read the cookie.
2. session attribute `secure` ensure the cookie will never be sent over an
insecure HTTP connections.

## Protection against multi-domain cookie attacks

Since Authelia uses multi-domain cookies to perform single sign-on, an
attacker who poisoned a user's DNS cache can easily retrieve the user's
cookies by making the user send a request to one of the attacker's IPs.

To mitigate this risk, it's advisable to only use HTTPS connections with valid
certificates and enforce it with HTTP Strict Transport Security ([HSTS]) so
that the attacker must also require the certificate to retrieve the cookies.

Note that using [HSTS] has consequences. That's why you should read the blog
post nginx has written on [HSTS].

## Notifier security measures (SMTP)

By default the SMTP Notifier implementation does not allow connections that are not secure.
As such all connections require the following:

1. TLS Connection (STARTTLS or SMTPS) has been negotiated before authentication or sending emails (unauthenticated 
connections require it as well)
2. Valid X509 Certificate presented to the client during the TLS handshake

There is an option to disable both of these security measures however they are
not recommended. You should only do this in a situation where you control all 
networks between Authelia and the SMTP server. The following configuration options
exist to configure the security level:

### SMTPS vs STARTTLS

By default all connections start as plain text and are upgraded via STARTTLS. SMTPS is supported, however due to the
fact it was basically considered deprecated before the turn of the century, there is no way to configure it. It happens
automatically when a SMTP notifier is configured with the SMTPS port of 465.

### Configuration Option: disable_verify_cert

This is a YAML boolean type (true/false, y/n, 1/0, etc). This disables the X509 PKI
verification mechanism. We recommend using the trusted_cert option over this, as 
disabling this security feature makes you vulnerable to MITM attacks.

### Configuration Option: disable_require_tls

This is a YAML boolean type (true/false, y/n, 1/0, etc). This disables the 
requirement that all connections must be over TLS. This is only usable currently
with authentication disabled (comment the password) and as such is only an
option for SMTP servers that allow unauthenticated relay (bad practice).

### Configuration Option: trusted_cert

This is a YAML string type. This specifies the file location of a pub certificate
that can be used to validate the authenticity of a server with a self signed
certificate. This can either be the public cert of the certificate authority
used to sign the certificate or the public key itself. They must be in the PEM
format. The certificate is added in addition to the certificates trusted by the 
host machine. If the certificate is invalid, inaccessible, or is otherwise not 
configured; Authelia just uses the hosts certificates.

### Explanation
There are a few reasons for the security measures implemented:
1. Transmitting username's and passwords over plain-text is an obvious vulnerability
2. The emails generated by Authelia, if transmitted in plain-text could allow
an attacker to intercept a link used to setup 2FA; which reduces security
3. Not validating the identity of the server allows man-in-the-middle attacks

## More protections measures with Nginx

You can also apply the following headers to your nginx configuration for
improving security. Please read the documentation of those headers before
applying them blindly.

```
# We don't want any credentials / TOTP secret key / QR code to be cached by
# the client
add_header Cache-Control "no-store";
add_header Pragma "no-cache";

# Clickjacking / XSS protection

# We don't want Authelia's login page to be rendered within a <frame>, 
# <iframe> or <object> from an external website.
add_header X-Frame-Options "SAMEORIGIN";

# Block pages from loading when they detect reflected XSS attacks.
add_header X-XSS-Protection "1; mode=block";
```

## Contributing

If you find possible vulnerabilities or threats, do not hesitate to contribute
either by writing a test case demonstrating the possible attack and if
possible some solutions to prevent it or submit a PR.

[HSTS]: https://www.nginx.com/blog/http-strict-transport-security-hsts-and-nginx/