239 lines
7.7 KiB
Markdown
239 lines
7.7 KiB
Markdown
---
|
|
title: "Server"
|
|
description: "Configuring the Server Settings."
|
|
lead: "Authelia runs an internal webserver. This section describes how to configure and tune this."
|
|
date: 2022-06-15T17:51:47+10:00
|
|
draft: false
|
|
images: []
|
|
menu:
|
|
configuration:
|
|
parent: "miscellaneous"
|
|
weight: 199200
|
|
toc: true
|
|
aliases:
|
|
- /c/server
|
|
- /docs/configuration/server.html
|
|
---
|
|
|
|
## Configuration
|
|
|
|
{{< config-alert-example >}}
|
|
|
|
```yaml
|
|
server:
|
|
address: 'tcp://:9091'
|
|
umask: 0022
|
|
path: ''
|
|
disable_healthcheck: false
|
|
tls:
|
|
key: ''
|
|
certificate: ''
|
|
client_certificates: []
|
|
headers:
|
|
csp_template: ''
|
|
buffers:
|
|
read: 4096
|
|
write: 4096
|
|
timeouts:
|
|
read: '6s'
|
|
write: '6s'
|
|
idle: '30s'
|
|
endpoints:
|
|
enable_pprof: false
|
|
enable_expvars: false
|
|
authz:
|
|
forward-auth:
|
|
implementation: 'ForwardAuth'
|
|
authn_strategies: []
|
|
ext-authz:
|
|
implementation: 'ExtAuthz'
|
|
authn_strategies: []
|
|
auth-request:
|
|
implementation: 'AuthRequest'
|
|
authn_strategies: []
|
|
legacy:
|
|
implementation: 'Legacy'
|
|
authn_strategies: []
|
|
```
|
|
|
|
## Options
|
|
|
|
### address
|
|
|
|
{{< confkey type="address" default="tcp://:9091" required="no" >}}
|
|
|
|
*__Reference Note:__ This configuration option uses the [address common syntax](../prologue/common.md#address). Please
|
|
see the [documentation](../prologue/common.md#address) on this format for more information.*
|
|
|
|
Configures the listener address for the Main HTTP Server. The address itself is a listener and the scheme must either be
|
|
the `unix` scheme or one of the `tcp` schemes.
|
|
|
|
__Examples:__
|
|
|
|
```yaml
|
|
server:
|
|
address: tcp://127.0.0.1:9091
|
|
```
|
|
|
|
```yaml
|
|
server:
|
|
address: unix:///var/run/authelia.sock
|
|
```
|
|
|
|
### umask
|
|
|
|
{{< confkey type="int" required="no" >}}
|
|
|
|
If set temporarily changes the umask during the creation of the unix domain socket if configured as such in the
|
|
[address](#address). Typically this should be set before the process is actually running and users should not use this
|
|
option, however it's recognized in various specific scenarios this may not be completely adequate.
|
|
|
|
One such example is when you want the proxy to have permission to the socket but not the files, in which case running a
|
|
umask of `0077` by default is good, and running a umask of `0027` so that the group Authelia is running as has
|
|
permission to the socket.
|
|
|
|
This value should typically be prefixed with a `0` to ensure the relevant parsers handle it correctly.
|
|
|
|
### path
|
|
|
|
{{< confkey type="string " required="no" >}}
|
|
|
|
Authelia by default is served from the root `/` location, either via its own domain or subdomain.
|
|
|
|
Modifying this setting will allow you to serve Authelia out from a specified base path. Please note
|
|
that currently only a single level path is supported meaning slashes are not allowed, and only
|
|
alphanumeric characters are supported.
|
|
|
|
__Example:__
|
|
|
|
```yaml
|
|
server:
|
|
path: ""
|
|
```
|
|
|
|
*Works for https://auth.example.com/, https://example.com/, etc*.
|
|
|
|
__Example:__
|
|
|
|
```yaml
|
|
server:
|
|
path: authelia
|
|
```
|
|
|
|
*Works for https://auth.example.com/authelia/, https://example.com/authelia/, etc*.
|
|
|
|
### asset_path
|
|
|
|
{{< confkey type="string " required="no" >}}
|
|
|
|
Authelia by default serves all static assets from an embedded filesystem in the Go binary.
|
|
|
|
Modifying this setting will allow you to override and serve specific assets for Authelia from a specified path. All
|
|
assets that can be overridden must be placed in the `asset_path`. The structure of this directory and the assets which
|
|
can be overriden is documented in the
|
|
[Sever Asset Overrides Reference Guide](../../reference/guides/server-asset-overrides.md).
|
|
|
|
### disable_healthcheck
|
|
|
|
{{< confkey type="boolean" default="false" required="no" >}}
|
|
|
|
On startup Authelia checks for the existence of /app/healthcheck.sh and /app/.healthcheck.env and if both of these exist
|
|
it writes the configuration vars for the healthcheck to the /app/.healthcheck.env file. In instances where this is not
|
|
desirable it's possible to disable these interactions entirely.
|
|
|
|
An example situation where this is the case is in Kubernetes when set security policies that prevent writing to the
|
|
ephemeral storage of a container or just don't want to enable the internal health check.
|
|
|
|
### tls
|
|
|
|
Authelia typically listens for plain unencrypted connections. This is by design as most environments allow to
|
|
security on lower areas of the OSI model. However it required, if you specify both the [tls key](#key) and
|
|
[tls certificate](#certificate) options, Authelia will listen for TLS connections.
|
|
|
|
The key must be generated by the administrator and can be done by following the
|
|
[Generating an RSA Self Signed Certificate](../../reference/guides/generating-secure-values.md#generating-an-rsa-self-signed-certificate)
|
|
guide provided a self-signed certificate is fit for purpose. If a self-signed certificate is fit for purpose is beyond
|
|
the scope of the documentation and if it is not fit for purpose we instead recommend generating a certificate signing
|
|
request or obtaining a certificate signed by one of the many ACME certificate providers. Methods to achieve this are
|
|
beyond the scope of this guide.
|
|
|
|
#### key
|
|
|
|
{{< confkey type="string" required="situational" >}}
|
|
|
|
The path to the private key for TLS connections. Must be in DER base64/PEM format.
|
|
|
|
#### certificate
|
|
|
|
{{< confkey type="string" required="situational" >}}
|
|
|
|
The path to the public certificate for TLS connections. Must be in DER base64/PEM format.
|
|
|
|
#### client_certificates
|
|
|
|
{{< confkey type="list(string)" required="situational" >}}
|
|
|
|
The list of file paths to certificates used for authenticating clients. Those certificates can be root
|
|
or intermediate certificates. If no item is provided mutual TLS is disabled.
|
|
|
|
### headers
|
|
|
|
#### csp_template
|
|
|
|
{{< confkey type="string" required="no" >}}
|
|
|
|
This customizes the value of the Content-Security-Policy header. It will replace all instances of the below placeholder
|
|
with the nonce value of the Authelia react bundle. This is an advanced option to customize and you should do sufficient
|
|
research about how browsers utilize and understand this header before attempting to customize it.
|
|
|
|
{{< csp >}}
|
|
|
|
### buffers
|
|
|
|
Configures the server buffers. See the [Server Buffers](../prologue/common.md#server-buffers) documentation for more
|
|
information.
|
|
|
|
### timeouts
|
|
|
|
Configures the server timeouts. See the [Server Timeouts](../prologue/common.md#server-timeouts) documentation for more
|
|
information.
|
|
|
|
### endpoints
|
|
|
|
#### enable_pprof
|
|
|
|
{{< confkey type="boolean" default="false" required="no" >}}
|
|
|
|
*__Security Note:__ This is a developer endpoint. __DO NOT__ enable it unless you know why you're enabling it.
|
|
__DO NOT__ enable this in production.*
|
|
|
|
Enables the go [pprof](https://pkg.go.dev/net/http/pprof) endpoints.
|
|
|
|
#### enable_expvars
|
|
|
|
{{< confkey type="boolean" default="false" required="no" >}}
|
|
|
|
*__Security Note:__ This is a developer endpoint. __DO NOT__ enable it unless you know why you're enabling it.
|
|
__DO NOT__ enable this in production.*
|
|
|
|
Enables the go [expvar](https://pkg.go.dev/expvar) endpoints.
|
|
|
|
#### authz
|
|
|
|
This is an *__advanced__* option allowing configuration of the authorization endpoints and has its own section.
|
|
Generally this does not need to be configured for most use cases. See the
|
|
[authz configuration](./server-endpoints-authz.md) for more information.
|
|
|
|
## Additional Notes
|
|
|
|
### Buffer Sizes
|
|
|
|
The read and write buffer sizes generally should be the same. This is because when Authelia verifies
|
|
if the user is authorized to visit a URL, it also sends back nearly the same size response as the request. However
|
|
you're able to tune these individually depending on your needs.
|
|
|
|
### Asset Overrides
|
|
|
|
If replacing the Logo for your Authelia portal it is recommended to upload a transparent PNG of your desired logo.
|
|
Authelia will automatically resize the logo to an appropriate size to present in the frontend.
|