Jump to content

Authelia

From ArchWiki


Authelia is an open-source authentication and authorization server providing two-factor authentication and single sign-on (SSO) for applications via a web portal. It acts as a companion to reverse proxies like nginx, Caddy, Traefik, or HAProxy to enforce access control policies.

Installation

Note Authelia requires a reverse proxy to function. See the upstream documentation for integration guides.

Install one of the following packages:

Both packages create the authelia system user and group.

Configuration

Package-provided structure

The packages create /etc/authelia/ for configuration files and install tmpfiles.d configuration to manage permissions: 

/usr/lib/tmpfiles.d/authelia.tmpfiles.conf
#Type Path                                    Mode User       Group      Age         Argument
Z     /etc/authelia/*                         0640 authelia   authelia   -           -
e     /etc/authelia                           0755 authelia   authelia   -           -
/usr/lib/tmpfiles.d/authelia.tmpfiles.config.conf
#Type Path                                    Mode User       Group      Age         Argument
f     /etc/authelia/configuration.yml         0440 authelia   authelia   -           -
Z     /etc/authelia/configuration.*.yml       0440 authelia   authelia   -           -
Z     /etc/authelia/configuration.yml.*       0440 authelia   authelia   -           -

Place your main Authelia configuration at /etc/authelia/configuration.yml. See the Authelia documentation for configuration options.

Authelia supports multiple options as storage provider and authentication backend. A simple dev setup could use sqlite3 for storage and a yaml file as user database. Such a file based setup does not support high availability scenarios. An RDBMS such as Postgresql and an LDAP server should be used in production scenarios to support high availability.

Note This section describes the file based dev setup. Do not use this in production.

Following the Filesystem Hierarchy Standard, it is recommended to separate configuration from runtime application data should you want to use file based storage options for Authelia.

  • Configuration (static): /etc/authelia/
  • Application data (runtime state): /var/lib/authelia/

Setting up the data directory

Create the data directory: 

# mkdir -p /var/lib/authelia
# chown authelia:authelia /var/lib/authelia
# chmod 0750 /var/lib/authelia

To use SQLite for storage, configure the database path in /etc/authelia/configuration.yml: 

/etc/authelia/configuration.yml
storage:
  local:
    path: /var/lib/authelia/db.sqlite3

To use a file-based user database, you may also place it in /var/lib/authelia/: 

/etc/authelia/configuration.yml
authentication_backend:
  file:
    path: /var/lib/authelia/users_database.yml

Securing with tmpfiles.d

To ensure proper permissions are maintained across reboots and during system updates, create a tmpfiles.d configuration for /var/lib/authelia/: 

/etc/tmpfiles.d/authelia.conf
#Type Path                                    Mode User       Group      Age         Argument

# Application data directory
d     /var/lib/authelia                       0750 authelia   authelia   -           -
z     /var/lib/authelia/db.sqlite3            0640 authelia   authelia   -           -
z     /var/lib/authelia/users_database.yml    0640 authelia   authelia   -           -
Note Use lowercase z to set permissions on specific files without recursion, preventing issues with directory traversal.

Apply the configuration immediately: 

# systemd-tmpfiles --create /etc/tmpfiles.d/authelia.conf

Usage

Start/enable authelia.service.

Check the service status: 

# systemctl status authelia

View logs: 

# journalctl -u authelia -f

Troubleshooting

Permission denied errors

If Authelia fails to start with permission errors, ensure:

  1. The authelia user has read access to configuration files
  2. The authelia user has read/write access to the data directory
  3. Directory permissions include the execute bit (+x) for directories

Manually fix permissions: 

# chown -R authelia:authelia /etc/authelia /var/lib/authelia
# chmod 0750 /etc/authelia /var/lib/authelia
# chmod 0640 /etc/authelia/configuration.yml
# chmod 0640 /var/lib/authelia/*

Then reapply tmpfiles configuration: 

# systemd-tmpfiles --create

Configuration validation

Validate your configuration before starting the service: 

# authelia validate-config --config /etc/authelia/configuration.yml

See also