234 lines
8.0 KiB
Markdown
234 lines
8.0 KiB
Markdown
---
|
|
title: "Common"
|
|
description: "Common configuration options and notations."
|
|
lead: "This section details common configuration elements within the Authelia configuration. This section is mainly used as a reference for other sections as necessary."
|
|
date: 2022-06-15T17:51:47+10:00
|
|
draft: false
|
|
images: []
|
|
menu:
|
|
configuration:
|
|
parent: "prologue"
|
|
weight: 100200
|
|
toc: true
|
|
aliases:
|
|
- /c/common
|
|
---
|
|
|
|
## Duration Notation Format
|
|
|
|
We have implemented a string/integer based notation for configuration options that take a duration of time. This section
|
|
describes the implementation of this. You can use this implementation in various areas of configuration such as:
|
|
|
|
* session:
|
|
* expiration
|
|
* inactivity
|
|
* remember_me
|
|
* regulation:
|
|
* ban_time
|
|
* find_time
|
|
* ntp:
|
|
* max_desync
|
|
* webauthn:
|
|
* timeout
|
|
|
|
The way this format works is you can either configure an integer or a string in the specific configuration areas. If you
|
|
supply an integer, it is considered a representation of seconds. If you supply a string, it parses the string in blocks
|
|
of quantities and units (number followed by a unit letter). For example `5h` indicates a quantity of 5 units of `h`.
|
|
|
|
The following is ignored:
|
|
- all spaces
|
|
- leading zeros
|
|
|
|
While you can use multiple of these blocks in combination, we suggest keeping it simple and use a single value.
|
|
|
|
### Unit Legend
|
|
|
|
#### Short Units
|
|
|
|
These values have been available for a long time.
|
|
|
|
| Unit | Associated Letter |
|
|
|:-------:|:-----------------:|
|
|
| Years | y |
|
|
| Months | M |
|
|
| Weeks | w |
|
|
| Days | d |
|
|
| Hours | h |
|
|
| Minutes | m |
|
|
| Seconds | s |
|
|
|
|
#### Long Units
|
|
|
|
These values are more human readable but have only been available since v4.38.0.
|
|
|
|
| Unit | Human Readable Long Unit |
|
|
|:------------:|:-----------------------------:|
|
|
| Years | `year`, `years` |
|
|
| Months | `month`, `months` |
|
|
| Weeks | `week`, `weeks` |
|
|
| Days | `day`, `days` |
|
|
| Hours | `hour`, `hours` |
|
|
| Minutes | `minute`, `minutes` |
|
|
| Seconds | `second`, `seconds` |
|
|
| Milliseconds | `millisecond`, `milliseconds` |
|
|
|
|
### Examples
|
|
|
|
| Desired Value | Configuration Examples |
|
|
|:---------------------:|:-------------------------------------:|
|
|
| 1 hour and 30 minutes | `90m` or `1h30m` or `5400` or `5400s` |
|
|
| 1 day | `1d` or `24h` or `86400` or `86400s` |
|
|
| 10 hours | `10h` or `600m` or `9h60m` or `36000` |
|
|
|
|
## Address
|
|
|
|
The address type is a string that takes the following format:
|
|
|
|
```text
|
|
[<scheme>://]<ip>[:<port>]
|
|
```
|
|
|
|
The square brackets indicate optional sections, and the angled brackets indicate required sections. The following
|
|
sections elaborate on this. Sections may only be optional for the purposes of parsing, there may be a configuration
|
|
requirement that one of these is provided.
|
|
|
|
### scheme
|
|
|
|
The entire scheme is optional, but if the scheme host delimiter `://` is in the string, the scheme must be present. The
|
|
scheme must be one of `tcp://`, or `udp://`. The default scheme is `tcp://`.
|
|
|
|
### ip
|
|
|
|
The IP is required. If specifying an IPv6 it should be wrapped in square brackets. For example for the IPv6 address
|
|
`::1` with the `tcp://` scheme and port `80`: `tcp://[::1]:80`.
|
|
|
|
### port
|
|
|
|
The entire port is optional, but if the host port delimiter `:` exists it must also include a numeric port.
|
|
|
|
## Regular Expressions
|
|
|
|
We have several sections of configuration that utilize regular expressions. It's recommended to validate your regex
|
|
manually either via tools like [Regex 101](https://regex101.com/) (ensure you pick the `Golang` option) or some other
|
|
means.
|
|
|
|
It's important when attempting to utilize a backslash that it's utilized correctly. The YAML parser is likely to parse
|
|
this as you trying to use YAML escape syntax instead of regex escape syntax. To avoid this use single quotes instead of
|
|
no quotes or double quotes.
|
|
|
|
Good Example:
|
|
|
|
```yaml
|
|
domain_regex: '^(admin|secure)\.example\.com$'
|
|
```
|
|
|
|
Bad Example:
|
|
|
|
```yaml
|
|
domain_regex: "^(admin|secure)\.example\.com$"
|
|
```
|
|
|
|
## TLS Configuration
|
|
|
|
Various sections of the configuration use a uniform configuration section called TLS. Notably LDAP and SMTP.
|
|
This section documents the usage.
|
|
|
|
### server_name
|
|
|
|
{{< confkey type="string" required="no" >}}
|
|
|
|
The key `server_name` overrides the name checked against the certificate in the verification process. Useful if you
|
|
require an IP address for the host of the backend service but want to verify a specific certificate server name.
|
|
|
|
### skip_verify
|
|
|
|
{{< confkey type="boolean" default="false" required="no" >}}
|
|
|
|
The key `skip_verify` completely negates validating the certificate of the backend service. This is not recommended,
|
|
instead you should tweak the `server_name` option, and the global option
|
|
[certificates directory](../miscellaneous/introduction.md#certificatesdirectory).
|
|
|
|
### minimum_version
|
|
|
|
{{< confkey type="string" default="TLS1.2" required="no" >}}
|
|
|
|
Controls the minimum TLS version Authelia will use when performing TLS handshakes.
|
|
The possible values are `TLS1.3`, `TLS1.2`, `TLS1.1`, `TLS1.0`, `SSL3.0`. Anything other than `TLS1.3` or `TLS1.2`
|
|
are very old and deprecated. You should avoid using these and upgrade your backend service instead of decreasing
|
|
this value. At the time of this writing `SSL3.0` will always produce errors.
|
|
|
|
### maximum_version
|
|
|
|
{{< confkey type="string" default="TLS1.3" required="no" >}}
|
|
|
|
Controls the maximum TLS version Authelia will use when performing TLS handshakes.
|
|
The possible values are `TLS1.3`, `TLS1.2`, `TLS1.1`, `TLS1.0`, `SSL3.0`. Anything other than `TLS1.3` or `TLS1.2`
|
|
are very old and deprecated. You should avoid using these and upgrade your backend service instead of decreasing
|
|
this value. At the time of this writing `SSL3.0` will always produce errors.
|
|
|
|
### certificate_chain
|
|
|
|
{{< confkey type="string" required="no" >}}
|
|
|
|
The certificate chain/bundle to be used with the [private_key](#privatekey) to perform mutual TLS authentication with
|
|
the server.
|
|
|
|
The value must be one or more certificates encoded in the DER base64 ([RFC4648]) encoded PEM format.
|
|
|
|
### private_key
|
|
|
|
{{< 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 private key to be used with the [certificate_chain](#certificatechain) for mutual TLS authentication.
|
|
|
|
The value must be one private key encoded in the DER base64 ([RFC4648]) encoded PEM format. If more than one certificate
|
|
is provided, in top down order, each certificate must be signed by the next certificate if provided.
|
|
|
|
[RFC4648]: https://datatracker.ietf.org/doc/html/rfc4648
|
|
|
|
## Server Buffers
|
|
|
|
### read
|
|
|
|
{{< confkey type="integer" default="4096" required="no" >}}
|
|
|
|
Configures the maximum request size. The default of 4096 is generally sufficient for most use cases.
|
|
|
|
### write
|
|
|
|
{{< confkey type="integer" default="4096" required="no" >}}
|
|
|
|
Configures the maximum response size. The default of 4096 is generally sufficient for most use cases.
|
|
|
|
## Server Timeouts
|
|
|
|
### read
|
|
|
|
{{< confkey type="duration" default="6s" required="no" >}}
|
|
|
|
*__Note:__ This setting uses the [duration notation format](#duration-notation-format). Please see the
|
|
[common options](#duration-notation-format) documentation for information on this format.*
|
|
|
|
Configures the server read timeout.
|
|
|
|
### write
|
|
|
|
{{< confkey type="duration" default="6s" required="no" >}}
|
|
|
|
*__Note:__ This setting uses the [duration notation format](#duration-notation-format). Please see the
|
|
[common options](#duration-notation-format) documentation for information on this format.*
|
|
|
|
Configures the server write timeout.
|
|
|
|
### idle
|
|
|
|
{{< confkey type="duration" default="30s" required="no" >}}
|
|
|
|
*__Note:__ This setting uses the [duration notation format](#duration-notation-format). Please see the
|
|
[common options](#duration-notation-format) documentation for information on this format.*
|
|
|
|
Configures the server idle timeout.
|