--- title: "How to Set Up Authelia 2FA with Nginx on Ubuntu 24.04" description: "Deploy Authelia with Docker on Ubuntu 24.04 and put it in front of Nginx sites to require a password plus a TOTP code or security key before access is granted." category: "Identity and Access Management" language: en source: https://cubepath.com/docs/identity-and-access-management/authelia-two-factor-authentication-gateway updated: 2026-09-25 --- # How to Set Up Authelia 2FA with Nginx on Ubuntu 24.04 Authelia is an open source authentication server that works with your reverse proxy to add a login portal and two-factor authentication (TOTP codes or WebAuthn security keys) in front of any web application, without changing the application. In this tutorial you will run Authelia with Docker Compose on Ubuntu 24.04, serve its portal at `https://auth.example.com`, and configure Nginx so `https://app.example.com` is only reachable after a password and a second factor. ## Prerequisites To follow this guide you need: - A server running Ubuntu 24.04 LTS with a non-root `sudo` user, for example a CubePath VPS. 1 GB of RAM is enough. - Two DNS A records pointing to the server: `auth.example.com` for the Authelia portal and `app.example.com` for the protected application. Both must be subdomains of the same domain, because Authelia's session cookie is set on that parent domain. Replace `example.com` with your own domain throughout. - Ports 80 and 443 open to the internet. - The application you want to protect, listening on `127.0.0.1:3000`. Step 5 starts a test page if you do not have one yet. ## Step 1 - Installing Docker, Nginx and Certbot Install Docker Engine and the Compose plugin from the Ubuntu repositories, along with Nginx and Certbot: ```bash sudo apt update sudo apt install docker.io docker-compose-v2 nginx certbot python3-certbot-nginx ``` Open HTTP and HTTPS in UFW, making sure SSH stays allowed: ```bash sudo ufw allow OpenSSH sudo ufw allow 'Nginx Full' sudo ufw enable ``` Verify that Docker is running: ```bash sudo systemctl is-active docker ``` ```output active ``` ## Step 2 - Generating secrets Authelia needs three random secrets: one to sign password reset links, one for the session, and one to encrypt its database (which stores the TOTP seeds). Keep them in files instead of the configuration so they never end up in a copied config or a screenshot: ```bash sudo mkdir -p /opt/authelia/config /opt/authelia/secrets for name in jwt_secret session_secret storage_encryption_key; do openssl rand -hex 32 | sudo tee "/opt/authelia/secrets/${name}" > /dev/null done sudo chmod 600 /opt/authelia/secrets/* ``` Check that the three files exist and are only readable by root: ```bash sudo ls -l /opt/authelia/secrets ``` ```output -rw------- 1 root root 65 Sep 24 12:01 jwt_secret -rw------- 1 root root 65 Sep 24 12:01 session_secret -rw------- 1 root root 65 Sep 24 12:01 storage_encryption_key ``` > Warning: Back up `storage_encryption_key`. If you lose it, Authelia cannot decrypt the stored TOTP and WebAuthn registrations and every user has to enroll again. ## Step 3 - Configuring Authelia Create the main configuration file: ```bash sudo nano /opt/authelia/config/configuration.yml ``` ```yaml server: address: 'tcp://:9091' log: level: info totp: issuer: example.com webauthn: display_name: Example authentication_backend: file: path: /config/users_database.yml access_control: default_policy: deny rules: - domain: app.example.com subject: - 'group:admins' policy: two_factor session: expiration: 1h inactivity: 15m cookies: - domain: example.com authelia_url: https://auth.example.com default_redirection_url: https://app.example.com regulation: max_retries: 3 find_time: 2m ban_time: 10m storage: local: path: /config/db.sqlite3 notifier: filesystem: filename: /config/notification.txt ``` What each section does: - `access_control` denies everything by default and requires a second factor for members of the `admins` group on `app.example.com`. Rules are evaluated top to bottom and the first match wins. - `session.cookies` sets the session cookie on `example.com`, so one login covers every protected subdomain. `authelia_url` is the portal address users are redirected to. - `regulation` bans a user for 10 minutes after 3 failed logins within 2 minutes. - `notifier.filesystem` writes emails (such as the one-time codes used to register a second factor) to a file instead of sending them. It is fine for a first setup; switch to `notifier.smtp` for real users. Next, create a user. Generate an Argon2 password hash; the command prompts for the password twice: ```bash sudo docker run --rm -it authelia/authelia:4.39 authelia crypto hash generate argon2 ``` ```output Enter Password: Confirm Password: Digest: $argon2id$v=19$m=65536,t=3,p=4$Rk1Ln0mS3Cz9E8uJ1aVtZw$m0e9oG6cZ7d1Q2r5u8vX3yT4w1k2n5p8s0a3d6f9g1h ``` Copy the full `Digest` value into the users file: ```bash sudo nano /opt/authelia/config/users_database.yml ``` ```yaml users: jsmith: disabled: false displayname: 'John Smith' password: '$argon2id$v=19$m=65536,t=3,p=4$Rk1Ln0mS3Cz9E8uJ1aVtZw$m0e9oG6cZ7d1Q2r5u8vX3yT4w1k2n5p8s0a3d6f9g1h' email: jsmith@example.com groups: - admins ``` Keep the single quotes around the hash, because it contains `$` characters. ## Step 4 - Starting Authelia with Docker Compose Create the Compose file. The secrets are passed through Authelia's `_FILE` environment variables, and port 9091 is bound to localhost so the service is only reachable through Nginx: ```bash sudo nano /opt/authelia/compose.yaml ``` ```yaml services: authelia: image: authelia/authelia:4.39 container_name: authelia restart: unless-stopped ports: - "127.0.0.1:9091:9091" volumes: - ./config:/config - ./secrets:/secrets:ro environment: TZ: UTC AUTHELIA_IDENTITY_VALIDATION_RESET_PASSWORD_JWT_SECRET_FILE: /secrets/jwt_secret AUTHELIA_SESSION_SECRET_FILE: /secrets/session_secret AUTHELIA_STORAGE_ENCRYPTION_KEY_FILE: /secrets/storage_encryption_key ``` The image tag pins the 4.39 release line; check the [Authelia releases](https://github.com/authelia/authelia/releases) for newer versions. Validate the configuration before starting, then start the container: ```bash cd /opt/authelia sudo docker compose run --rm authelia authelia validate-config --config /config/configuration.yml sudo docker compose up -d ``` ```output Configuration parsed and loaded successfully without errors. ``` Check that the service answers on its health endpoint: ```bash curl -s http://127.0.0.1:9091/api/health; echo ``` ```output {"status":"OK"} ``` If the container keeps restarting, `sudo docker compose logs authelia` names the configuration key that is wrong. ## Step 5 - Starting a test application If your real application already listens on `127.0.0.1:3000`, skip this step. Otherwise open a second terminal and start a simple page to protect: ```bash mkdir -p ~/testapp && echo "Hello from the protected app" > ~/testapp/index.html python3 -m http.server 3000 --bind 127.0.0.1 --directory ~/testapp ``` ## Step 6 - Configuring Nginx You need two server blocks: one for the Authelia portal and one for the protected application. Start with the portal: ```bash sudo nano /etc/nginx/sites-available/auth.example.com ``` ```nginx server { listen 80; listen [::]:80; server_name auth.example.com; location / { proxy_pass http://127.0.0.1:9091; proxy_set_header Host $host; proxy_set_header X-Original-URL $scheme://$http_host$request_uri; proxy_set_header X-Forwarded-Proto $scheme; proxy_set_header X-Forwarded-Host $http_host; proxy_set_header X-Forwarded-URI $request_uri; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Real-IP $remote_addr; } } ``` For the application, Nginx sends a subrequest to Authelia's `/api/authz/auth-request` endpoint before every request. If the user is not logged in, Authelia answers `401` with a `Location` header pointing to the portal, and Nginx turns that into a redirect: ```bash sudo nano /etc/nginx/sites-available/app.example.com ``` ```nginx server { listen 80; listen [::]:80; server_name app.example.com; # Subrequest endpoint, not reachable from outside location /internal/authelia/authz { internal; proxy_pass http://127.0.0.1:9091/api/authz/auth-request; proxy_set_header X-Original-Method $request_method; proxy_set_header X-Original-URL $scheme://$http_host$request_uri; proxy_set_header X-Forwarded-For $remote_addr; proxy_set_header Content-Length ""; proxy_set_header Connection ""; proxy_pass_request_body off; proxy_http_version 1.1; } location / { auth_request /internal/authelia/authz; # Redirect unauthenticated users to the Authelia portal auth_request_set $redirection_url $upstream_http_location; error_page 401 =302 $redirection_url; # Pass the user identity to the application auth_request_set $user $upstream_http_remote_user; auth_request_set $groups $upstream_http_remote_groups; auth_request_set $name $upstream_http_remote_name; auth_request_set $email $upstream_http_remote_email; proxy_set_header Remote-User $user; proxy_set_header Remote-Groups $groups; proxy_set_header Remote-Name $name; proxy_set_header Remote-Email $email; proxy_pass http://127.0.0.1:3000; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } } ``` Enable both sites and check the syntax: ```bash sudo ln -s /etc/nginx/sites-available/auth.example.com /etc/nginx/sites-enabled/ sudo ln -s /etc/nginx/sites-available/app.example.com /etc/nginx/sites-enabled/ sudo nginx -t sudo systemctl reload nginx ``` Authelia only works over HTTPS. Request certificates for both names; Certbot adds the TLS configuration and an HTTP to HTTPS redirect to each server block: ```bash sudo certbot --nginx -d auth.example.com -d app.example.com --redirect ``` ## Step 7 - Logging in and registering a second factor First confirm that an anonymous request is redirected to the portal: ```bash curl -sI https://app.example.com/ | grep -i '^location' ``` ```output location: https://auth.example.com/?rd=https%3A%2F%2Fapp.example.com%2F&rm=GET ``` Open `https://app.example.com/` in a browser. You land on the Authelia portal. Sign in as `jsmith` with the password you hashed in Step 3. Because the rule requires `two_factor` and no device is registered yet, Authelia asks you to register one. Before it shows a QR code or accepts a security key, Authelia verifies your identity with a one-time code sent by email. With the filesystem notifier, read it from the server: ```bash sudo cat /opt/authelia/config/notification.txt ``` ```output Date: 2026-09-24 12:20:41 +0000 UTC Recipient: { John Smith jsmith@example.com } Subject: Confirm your identity ... ABCD1234 ``` Enter the code in the portal, then either: - **TOTP:** scan the QR code with an authenticator app (Aegis, Google Authenticator, 1Password and similar) and enter the six-digit code, or - **WebAuthn:** register a hardware key such as a YubiKey, or a platform passkey, following the browser prompts. After registration Authelia redirects you to `https://app.example.com/`, which now shows `Hello from the protected app`. Sign out at `https://auth.example.com/logout` and sign in again to confirm that the second factor is requested. When you finish testing, stop the Python server with `Ctrl+C` and point `proxy_pass` in `app.example.com` to your real application. ## Step 8 - Writing access control rules Real deployments usually mix policies. The four policies are `bypass` (no login), `one_factor` (password only), `two_factor` (password and second factor) and `deny`. An example for several services: ```yaml access_control: default_policy: deny rules: # Health checks and public files do not need a login - domain: app.example.com resources: - '^/health$' - '^/public/.*$' policy: bypass # Admin panels: admins only, with 2FA - domain: admin.example.com subject: - 'group:admins' policy: two_factor # Internal tools: any user in the users or admins group, with 2FA - domain: - grafana.example.com - wiki.example.com subject: - 'group:users' - 'group:admins' policy: two_factor ``` Each protected hostname needs its own Nginx server block with the same `auth_request` configuration as `app.example.com`. After editing the rules, validate and restart: ```bash cd /opt/authelia sudo docker compose run --rm authelia authelia validate-config --config /config/configuration.yml sudo docker compose restart authelia ``` ## Troubleshooting **Redirect loop between the app and the portal.** The session cookie is not reaching the browser for the app's domain. Check that `session.cookies[].domain` is the parent domain (`example.com`, not `auth.example.com`), that both sites use HTTPS, and that `authelia_url` matches the portal address exactly. **Nginx returns `500` on the protected site.** The subrequest cannot reach Authelia. Check `curl http://127.0.0.1:9091/api/health` and `/var/log/nginx/error.log`. **Valid TOTP codes are rejected.** TOTP depends on the clock. Run `timedatectl` and make sure `System clock synchronized: yes` is shown on the server, and that the phone's time is set automatically. **A user lost their TOTP device.** Delete the registration so the user can enroll again at the next login: ```bash sudo docker exec authelia authelia storage user totp delete jsmith --config /config/configuration.yml ``` **The user is banned after failed attempts.** The ban set by `regulation` expires after `ban_time`. Look for `regulation` messages with `sudo docker compose logs authelia`. ## Conclusion Authelia now protects `app.example.com` with a password and a second factor, and a single session covers every subdomain you add behind Nginx. Next, configure the SMTP notifier so users receive codes by email, replace the users file with the LDAP backend to reuse an existing directory, and add Redis for sessions if you run more than one Authelia instance.