Workload · Guarding your self-hosted apps

Authelia self hosted: one sign-in page and 2FA in front of every app

Running Authelia yourself puts a single sign-in page, with an optional second factor, in front of every web app behind your reverse proxy: the proxy asks Authelia about each request, and Authelia answers let it through, refuse it, or send the visitor to sign in first. To start it needs HTTPS, a domain you control, a list of users, a database, a way to send email and a few long random secrets. Below is all of it on one small Linux machine, plus what to change once more people depend on it.

The short version
  1. Works with Traefik, Caddy, NGINX, HAProxy, Envoy and other proxies
  2. Second factor by authenticator app, security key or Duo push
  3. SQLite and in-memory sessions for one box; PostgreSQL and Redis beyond that
  4. Listens on port 9091, which stays inside your Docker network

What Authelia does for the apps behind it

Authelia is a gatekeeper that your reverse proxy consults before it passes a request on. It is wired to the proxy, never to the apps themselves, so page contents and uploads never flow through it; only the parts that prove who someone is, such as the session cookie, reach it.

When a visitor arrives without a session cookie, Authelia sends them to its own portal. Once they have signed in, they carry a cookie that is valid for the protected domain and its subdomains, so one sign-in covers every app under it. Each later request is checked against your rules, and the proxy lets it through or blocks it on Authelia's answer.

That suits tools that ship with no login, or a weak one: dashboards, admin pages, media apps, home-lab services. Authelia can also act as an OpenID Connect 1.0 provider, but forward auth, shown below, is the usual way in. It is open source under the Apache 2.0 licence.

The pieces it wants before it will start

Authelia is set up from one static file, configuration.yml, and must be reached by visitors over HTTPS: the docs say this is not optional even for testing, and every app it protects must also be reached over https or wss. Beyond that, you choose a provider for each job:

JobFine for one machineRecommended for production or several copies
Who your users areA YAML users fileAn LDAP directory
Storage (2FA devices, bans, history)SQLite, a single local filePostgreSQL
SessionsMemory, the defaultRedis or Redis Sentinel
Sending identity checksA text file, for testing onlySMTP email

Three secrets are needed too: identity_validation.reset_password.jwt_secret, which signs password-reset emails; session.secret; and storage.encryption_key, which encrypts sensitive columns in the database and must be at least 20 characters (the docs advise 64 or more random letters and digits). The session cookie domain needs at least one dot, cannot be localhost and cannot be a public suffix, so you need a real domain of your own.

SQLite and memory sessions make Authelia stateful: you cannot run a second copy beside the first. For one instance in front of your own apps that is fine; the day you want two, move to PostgreSQL and Redis.

How big a machine it needs

Authelia's documentation publishes no memory or CPU figure, so size the machine for what sits beside it: the proxy, the apps you protect, and PostgreSQL or Redis if you add them. A Cloud VPS fits when Authelia guards a handful of apps on the same box: root access, its own IPv4 and an IPv6 /96, a browser console for the day SSH will not answer, and Ubuntu, Debian, AlmaLinux or Rocky Linux. Pick the Docker app at order time and the machine installs Docker and Docker Compose on its first start.

Start small and watch docker stats for a week. A VPS moves up to any bigger size on request, restarting once and keeping its files and addresses; it cannot move down, because a disk cannot shrink.

Authelia's mail goes out on port 587, and ports 465 and 587 are open on every new VPS. Port 25 stays closed until you ask; Authelia does not need it.

Up and running in an evening

  1. Point DNS at the server: an auth hostname for the portal and one hostname per app, each with an A record for the IPv4 and an AAAA record for the IPv6 address.
  2. Make the folders, generate the secrets and hash your password with the first block below. Run the random-value command three times and save each value in its own file in data/authelia/secrets (JWT_SECRET, SESSION_SECRET, STORAGE_ENCRYPTION_KEY), plus SMTP_PASSWORD for your mail account. The hash command prompts for the password, so it stays out of your shell history.
  3. Create data/authelia/config/users_database.yml in the layout of Authelia's password guide: per user a displayname, the argon2 hash, email and groups. Nobody can sign themselves up; only people in this file exist.
  4. Write data/authelia/config/configuration.yml, starting from the example below, with your own domains and mail server.
  5. Take the standalone Compose example from Authelia's Docker guide (config at /config, secrets at /secrets, each read through a _FILE variable). The example joins an existing Docker network called net; create it first with docker network create net. Delete its PostgreSQL password line, add AUTHELIA_NOTIFIER_SMTP_PASSWORD_FILE: '/secrets/SMTP_PASSWORD', and add a Caddy service on the same network that publishes ports 80 and 443 and keeps a persistent data volume. Publish no port for Authelia.
  6. Give Caddy the Caddyfile below (v2.5.1 or newer). With the DNS records in place, it fetches and renews the certificates itself.
  7. Run docker compose up -d, then docker compose logs authelia. Authelia checks at start-up that it can reach your mail server; fix any error rather than switching the check off.
  8. Open the app's address: you should land on the Authelia portal and, after signing in, be asked to register a second factor.
mkdir -p data/authelia/config data/authelia/secrets
docker run --rm authelia/authelia:latest authelia crypto rand --length 64 --charset alphanumeric
docker run --rm -it authelia/authelia:latest authelia crypto hash generate argon2
server:
  address: 'tcp://:9091/'
authentication_backend:
  file:
    path: '/config/users_database.yml'
access_control:
  default_policy: 'deny'
  rules:
    - domain: 'nextcloud.example.com'
      policy: 'two_factor'
session:
  cookies:
    - domain: 'example.com'
      authelia_url: 'https://auth.example.com'
storage:
  local:
    path: '/config/db.sqlite3'
notifier:
  smtp:
    address: 'submission://smtp.example.com:587'
    username: 'auth@example.com'
    sender: 'auth@example.com'
auth.example.com {
        reverse_proxy authelia:9091
}

nextcloud.example.com {
        forward_auth authelia:9091 {
                uri /api/authz/forward-auth
                copy_headers Remote-User Remote-Groups Remote-Email Remote-Name
        }

        reverse_proxy nextcloud:80
}

Already running containers? Docker Compose on a VPS covers one app behind HTTPS; protecting it is the forward_auth block above.

Choosing the second factor and the rules

Authelia offers three second factors: time-based one-time codes from an authenticator app, WebAuthn security keys such as a YubiKey, and push notifications through Duo. Passkeys are supported as well, for signing in without a password. Before someone registers a device, Authelia confirms it is really them by sending a message through the notifier, which is why the mail settings have to work.

Rules are read top down, and the first one whose conditions all match wins. Each ends in a policy: deny, bypass (no sign-in), one_factor (password) or two_factor. Rules can match domain, user or group, path, client network and HTTP method, so the admins group can reach an admin path while everyone else gets the rest.

  • Keep default_policy: 'deny', so a hostname you forgot to write a rule for stays closed.
  • Put bypass rules near the top, and only for paths that truly must be public, such as a health check.
  • A rule that names users or groups cannot use bypass, because Authelia has to know who someone is first.
  • Failed passwords are throttled by default: three failures within two minutes can earn a five-minute ban.

Keeping it healthy

  • Back up the config folder and the secrets together. Sensitive columns are encrypted with storage.encryption_key, so db.sqlite3 without the key is half a backup. Stop the container briefly while copying the SQLite file.
  • Update on purpose. Read the release notes and take a fresh backup before pulling a new image.
  • Keep port 9091 private. Only the proxy talks to Authelia. If another proxy sits in front, trust only its exact address, never whole private ranges copied from an example.
  • Keep secrets out of configuration.yml. Use the _FILE variables, so secrets stay out of backups of the config and out of screenshots.
  • Read the logs. docker compose logs authelia shows refused sign-ins and bans.

When this is the wrong setup

Authelia only protects what travels through the proxy over HTTPS. SSH, databases and game servers need their own locks. An app with its own required login will ask for a second sign-in unless it trusts the Remote-User header or speaks OpenID Connect.

One instance is also one point of failure: if Authelia is down, the proxy has nobody to ask and protected apps stop letting people in. A team that cannot accept that needs two or more copies on PostgreSQL and Redis; running them on a cluster you manage is covered under Kubernetes on bare metal, and when the apps behind Authelia need every core, a dedicated server gives you the whole machine on an unmetered port.

Questions people ask

Does Authelia replace the logins inside my apps?
It adds a layer in front of them. Apps with no login are simply protected; apps with their own accounts still show their login unless they trust the user headers Authelia passes on or connect through OpenID Connect.
Can I test it on a bare IP address or over HTTP?
No. Authelia requires HTTPS for itself and every app it protects, even while testing, and its session cookie needs a real domain with at least one dot. A domain of your own plus a proxy that fetches certificates automatically gets you past this quickly.
Do I need Redis and PostgreSQL from day one?
Not for a single instance. The docs recommend SQLite for testing and light deployments, and memory sessions work on one machine. Move to PostgreSQL and Redis for production-grade storage or a second copy of Authelia, because the local options cannot be shared.
What happens if I lose the storage encryption key?
Sensitive values in the database are encrypted with that key, so treat it as part of the database: keep it in your backups next to the database file or dump, and never change it casually.
Will email from Authelia leave a Cloud VPS?
Yes, through ports 465 and 587, which are open on every new machine and are what Authelia's SMTP notifier uses with a mail provider. Port 25 is closed until you ask for it, and Authelia does not need it.

Put a lock on your self-hosted apps

Get a Cloud VPS with Docker ready, and have Authelia and your proxy answering on HTTPS the same evening.

Get a server for Authelia

Read next