How to Use Authelia: The Beginner's Guide

CodexFuse Team · 2026-11-02T23:01:41.527Z · 13 min read min read

If you want to know how to use Authelia, you are really asking one question: how do I put a single login page with two-factor authentication in front of all my self-hosted services? Authelia is the lightweight answer to that question. It is a single Go binary, packaged as one Docker container, that acts as an authentication gateway between your reverse proxy and your apps. Below is the full beginner arc: install, secrets, configuration, reverse-proxy wiring for Nginx, Caddy, and Traefik, access-control policies, and your first TOTP enrollment.

This guide is for homelab owners and VPS users who already run apps behind a reverse proxy. If your apps each take a different username and password, Authelia gives you one login with 2FA for all of them. The closest OIDC-native sibling is covered in our Logto beginner guide — Logto is the OIDC-SDK lane, while this page is the forward-auth portal lane.

What Is Authelia, Exactly?

Authelia is an open-source single sign-on and two-factor authentication portal for self-hosted applications. Instead of building logins into each app, your reverse proxy asks Authelia whether each visitor is authenticated before forwarding their request, and Authelia presents one portal login — username, password, then TOTP or push notification — for every service you put behind it.

Authelia's default integration is forwarded authentication — the Authelia forward auth model: a simple per-request authorization flow where Nginx, Caddy, or Traefik forwards the request to Authelia and only proceeds when Authelia approves it. It also ships a built-in OpenID Connect 1.0 provider (OpenID Certified since v4.38, per the vendor) for apps that speak OIDC natively. It is not a full SAML-capable identity provider — that lane belongs to tools like Authentik, which we compare below.

How Does Authelia Work with a Reverse Proxy?

The request flow has exactly four steps. First, a visitor opens your app's URL. Second, the reverse proxy pauses the request and asks Authelia "is this visitor authenticated?" Third, if not, Authelia shows the login portal; the visitor signs in once and completes 2FA. Fourth, the proxy forwards the request to the app, adding headers like Remote-User and Remote-Email so the app knows who you are.

This model is why Authelia is popular on home servers: apps that have no login at all — dashboards, wikis, file browsers — suddenly get enterprise-grade authentication without changing a line of their code. The whole thing is one container, one YAML config file, and about 30 MB of RAM (vendor and third-party claim, not independently measured).

What Do You Need Before You Start?

You need three things. First, a server running Docker — a VPS is what most self-hosters use, but a home mini-PC works identically. Second, a reverse proxy already in front of your apps — Nginx, Caddy, or Traefik, which we wire up in sections below. Third, a domain name pointing at your server, because Authelia must be served over HTTPS; the official Get Started guide states this is mandatory, "not optional even for testing."

You do not need a database server, a Redis instance, or a mail server yet. SQLite, a local file notifier, and the YAML config carry a beginner setup just fine. We will upgrade each only when the guide says so.

How Do You Install Authelia with Docker?

The official Authelia Docker deployment uses a single container with two mounted volumes: one for configuration and one for secrets. Follow this seven-step Authelia setup arc and you will have a running instance with a generated config template ready to edit.

1. Pull the official image: docker pull docker.io/authelia/authelia:latest (also published on ghcr.io as ghcr.io/authelia/authelia). At the time of writing the current release is v4.39.28; pinning :4.39 instead of :latest keeps surprise upgrades away.
2. Create the directory layout the official compose expects: data/authelia/config for the YAML files and data/authelia/secrets for the secret files.
3. Write the compose file with the two volumes mounted and the secret env vars pointing at files (shown in the next section).
4. Run docker compose up -d.
5. On first start, Authelia writes a version-specific config.template.yml into the config directory. Copy it to configuration.yml — this is the file you will edit.
6. Edit configuration.yml: server host, log level, theme, default 2FA method, password policy, access control, session, storage, notifier, and your users.
7. Restart the container and confirm it listens on port 9091 before touching any proxy config.

services:
  authelia:
    container_name: authelia
    image: docker.io/authelia/authelia:4.39
    restart: unless-stopped
    volumes:
      - ${PWD}/data/authelia/config:/config
      - ${PWD}/data/authelia/secrets:/secrets
    environment:
      AUTHELIA_IDENTITY_VALIDATION_RESET_PASSWORD_JWT_SECRET_FILE: /secrets/JWT_TOKEN
      AUTHELIA_SESSION_SECRET_FILE: /secrets/SESSION_SECRET
      AUTHELIA_STORAGE_ENCRYPTION_KEY_FILE: /secrets/STORAGE_ENCRYPTION_KEY

The official docs also ship ready-made compose bundles (examples/compose/lite and examples/compose/local) in the GitHub repo. The lite bundle ships with a default user password of authelia — change it immediately if you start from the bundle. For the full Docker arc including compose, volumes, and networks, see our Docker beginner guide.

How Do You Generate and Store Authelia's Secrets?

Authelia needs three secrets to run, and this is the rule beginners get wrong most often: they go in files, never in the YAML, never in the compose file, never in git. Generate each with a random generator (openssl rand -hex 32 works) and write them into the /secrets volume.

The three secrets are the session secret (signs session cookies), the storage encryption key (encrypts TOTP secrets and tokens in the database — minimum 20 characters, 64+ strongly recommended), and the identity-verification JWT secret (signs password-reset tokens). Wire each through the _FILE environment variable shown in the compose file above. The official secrets documentation strongly urges against raw environment-variable secrets — the reasoning comes from Diogo Mónica's "Twelve-Factor App" work — and warns that defining the same secret via both a file and an environment variable makes Authelia refuse to start. If you must keep a secret inside the YAML during testing, set that file's permissions to 0600.

How Do You Write Your First configuration.yml?

The Authelia configuration.yml file is static — there is no web GUI for core config; you edit the file and restart. The single most important block is access control: start with default_policy: deny and open up specific domains, never the reverse. The official access-control docs recommend deny for security reasons, and the Get Started guide suggests a starter block of deny plus one one_factor rule on your wildcard domain.

access_control:
  default_policy: deny
  rules:
    - domain: '*.example.com'
      policy: one_factor
    - domain: 'private.example.com'
      policy: two_factor

Two other blocks deserve care on first setup. The session.cookies list must name every SSO domain Authelia protects, plus the authelia_url of the portal itself. Storage defaults to SQLite at /config/db.sqlite3; the docs say SQLite prevents running multiple instances and that PostgreSQL is highly recommended for production or highly available scenarios — for a beginner homelab, SQLite is the right default. Finally, configure a notifier: SMTP is recommended for production, and a local file fallback exists (the dev.to community guide shows reading it with docker compose exec authelia cat /config/notification.txt). Without a notifier, 2FA registration emails and password-reset messages go nowhere.

How Do You Wire Nginx to Authelia?

Nginx protects an app with the auth_request module: every request is paused, proxied to Authelia's authorization endpoint, and only forwarded when Authelia answers 200. Your Nginx build needs the http_auth_request and http_realip modules for the official config to work.

set $upstream_authelia http://authelia:9091/api/authz/auth-request;
location /internal/authelia/authz {
    internal;
    proxy_pass $upstream_authelia;
    proxy_set_header X-Original-Method $request_method;
    proxy_set_header X-Original-URL $scheme://$host$request_uri;
    proxy_set_header X-Forwarded-For $remote_addr;
    proxy_set_header Content-Length "";
    proxy_pass_request_body off;
}

In each protected location you then add auth_request /internal/authelia/authz;, capture the response headers into variables (auth_request_set $user $upstream_http_remote_user; and friends), and redirect 401s to the portal with error_page 401 =302 $redirection_url; — this is the official modern method from the Authelia Nginx integration docs.

How Do You Wire Caddy to Authelia?

Caddy's wiring is the shortest of the three: the forward_auth directive inside your site block, available since Caddy v2.5.1. Authelia's auth endpoint for Caddy is /api/authz/forward-auth, and the copy_headers line passes the identity headers through to the app. Our Caddy beginner guide covers the site-block basics this snippet builds on.

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
}

How Do You Wire Traefik to Authelia?

Traefik protects apps with a forwardAuth middleware that you define once and attach to any router. The official docs are integration-tested against Traefik v3.7.13 and v2.11.57. Define the middleware with the Docker labels below, then attach it with traefik.http.routers.<app>.middlewares: 'authelia@docker' on each protected app's router.

traefik.http.middlewares.authelia.forwardAuth.address: 'http://authelia:9091/api/authz/forward-auth'
traefik.http.middlewares.authelia.forwardAuth.trustForwardHeader: 'true'
traefik.http.middlewares.authelia.forwardAuth.authResponseHeaders: 'Remote-User,Remote-Groups,Remote-Email,Remote-Name'

Note the three proxies differ only in wiring syntax; the auth decisions, portal, and 2FA are identical underneath. A common beginner question is which proxy to pick: if you want the shortest config, Caddy; if you want maximum community guides, Nginx; if your apps are already discovered via Docker labels, Traefik.

How Do You Protect Your First App?

Protection happens in two places. First, the access-control rules in configuration.yml decide the policy per domain: bypass, one_factor, or two_factor. Second, the proxy wiring from the previous sections enforces it. To protect your first app, add a two_factor rule for its domain, wire its location or router to Authelia, restart, and open the app in a private window — you should land on the Authelia portal, not the app.

Keep default_policy: deny throughout this step. The deny-by-default lesson is the whole point of the exercise: every new service you add is locked until you explicitly write a rule for it. An app that is accidentally open because the default was permissive is exactly the breach Authelia exists to prevent.

How Do You Enroll Your First 2FA Device?

Authelia 2FA enrollment happens at first login — there is no separate enrollment ceremony. After you sign in with your username and password, the portal prompts you to register your first 2FA device and shows a QR code to scan with Google Authenticator, Authy, or any TOTP app. Do this over HTTPS (which you already have, since Authelia requires it) or the enrollment secret is exposed on the wire.

After enrollment, every new browser or device goes through password plus the rotating six-digit code. The notifier you configured earlier also delivers password-reset links and can send notifications on new device registrations, depending on your config. If you ever lose the authenticator app, the configured notifier is your recovery path — one more reason the notifier block is not optional.

Authelia vs Authentik: Which One Should Beginners Pick?

This is the comparison every self-hoster eventually asks, so here is the honest answer. Authelia is an authentication proxy: one Go binary, one container, one YAML file, typically under 30 MB of RAM, doing forward authentication in front of your reverse proxy. Authentik is a full identity provider: SAML, LDAP, RADIUS, and SCIM support, self-service registration, and a much heavier stack (third-party comparisons put it around 800 MB of RAM with Postgres and Redis containers). Our Authentik beginner guide covers the full-IdP lane in the same beginner style.

The community rule of thumb (stackharbor.com, October 2026): pick Authelia when your apps have no OIDC client of their own and a reverse proxy already fronts everything; pick Authentik when you need SAML, an LDAP server, RADIUS or SCIM, or when people must self-register. They are sibling products in different lanes — this page is the lightweight forward-auth lane, and it links to, rather than replaces, the full-IdP guide.

What Are the 7 Mistakes Beginners Make with Authelia?

Sources

1. Authelia official Get Started guide — https://www.authelia.com/integration/prologue/get-started/ (fetched 2026-11-03; HTTPS mandatory, config template on first run, session.cookies guidance)
2. Authelia official Docker deployment docs — https://www.authelia.com/integration/deployment/docker/ (fetched 2026-11-03; compose, _FILE secrets, lite/local bundles)
3. Authelia secrets configuration methods — https://www.authelia.com/configuration/methods/secrets/ (fetched 2026-11-03; the three secrets, file-only rule, 0600 guidance)
4. Authelia access-control configuration — https://www.authelia.com/configuration/security/access-control/ (fetched 2026-11-03; default_policy deny recommendation)
5. Authelia SQLite storage docs — https://www.authelia.com/configuration/storage/sqlite/ (fetched 2026-11-03; SQLite default path, single-instance limit, Postgres for HA)
6. Authelia Nginx integration docs — https://www.authelia.com/integration/proxies/nginx/ (fetched 2026-11-03; auth_request snippet)
7. Authelia Caddy integration docs — https://www.authelia.com/integration/proxies/caddy/ (fetched 2026-11-03; forward_auth snippet, v2.5.1+)
8. Authelia Traefik integration docs — https://www.authelia.com/integration/proxies/traefik/ (fetched 2026-11-03; forwardAuth labels, tested versions)
9. Authelia GitHub releases — https://github.com/authelia/authelia/releases (fetched 2026-11-03; v4.39.28 current, no v5)
10. Vultr docs "How to Deploy Authelia" (fetched 2026-11-03; Traefik arc, <20MB image / <30MB RAM vendor claim)
11. 29vps.com "Install Authelia: 2FA + SSO for VPS on Linux" (fetched 2026-11-03; Nginx arc, first-login TOTP enrollment)
12. dev.to Vultr "Deploying Authelia on Ubuntu 24.04" (fetched 2026-11-03; Docker Compose + Traefik, file notifier fallback)
13. stackharbor.com Authelia vs Authentik comparison (2026-10-25) (fetched 2026-11-03; the pick-Authelia/pick-Authentik framing)
14. selfhosting.sh Authelia coverage (fetched 2026-11-03; OpenID Certified v4.38, RAM comparison framing)

Frequently Asked Questions

Is Authelia free to use?

Yes. Authelia is open source and free forever — there are no paid tiers, seats, or feature gates. You only pay for the server it runs on, which for most homelabs is a VPS or a machine you already own.

Does Authelia work with Nginx, Caddy, and Traefik?

Yes, all three, plus others. Nginx uses the auth_request module, Caddy uses forward_auth (v2.5.1+), and Traefik uses a forwardAuth middleware. The auth decision, portal, and 2FA are identical underneath — only the wiring syntax differs, and this guide shows all three.

Do I need a database server for Authelia?

No. SQLite is the default and is recommended for homelab and single-server setups; it stores everything in /config/db.sqlite3. Only move to PostgreSQL (plus Redis for sessions) when you need high availability across multiple Authelia instances.

Can Authelia replace Authentik?

Only in the forward-auth lane. If your goal is one login with 2FA in front of apps behind a reverse proxy, Authelia is the lighter choice. If you need SAML, an LDAP directory, RADIUS, SCIM provisioning, or user self-registration, you need a full identity provider like Authentik.

What happens if I lose my TOTP authenticator app?

Recovery flows through the notifier you configured: Authelia can email password-reset and identity-verification links via SMTP. This is why the notifier block is not optional — without it, a lost authenticator means manual database surgery to reset your 2FA registration.