Application Stacks AWS

Authelia on AWS User Guide

| Product: Authelia on AWS

Overview

This image runs Authelia, the open source authentication and authorization server that provides single sign-on and multi-factor authentication for your web applications. Authelia acts as a companion to a reverse proxy: instead of every application implementing its own login, the proxy forwards each request to Authelia, which enforces a per-resource access policy and presents a single, branded login portal with optional two-factor authentication.

The Authelia server binary is installed at /usr/local/bin/authelia and runs as a dedicated unprivileged authelia system account under a systemd service that starts it on boot and restarts it on failure. Authelia uses the file authentication backend (users in /etc/authelia/users_database.yml, passwords argon2id hashed), a local SQLite storage database and the filesystem notifier, all of which live on a dedicated, independently resizable EBS data volume mounted at /var/lib/authelia.

Authelia binds to the loopback interface only (127.0.0.1:9091) and is never exposed directly. An nginx reverse proxy publishes the Authelia portal and runs the standard forward-authentication integration. The administrator password is generated on the first boot of every deployed instance, so two instances launched from the same Amazon Machine Image never share a password. It is written to /root/authelia-credentials.txt with mode 0600 so that only the root user can read it.

The demo domain and self-signed TLS

Authelia's session cookies require a real registrable domain (an IP address cannot be used), and Authelia 4.39 additionally requires a secure HTTPS scheme for its session URLs. To make the appliance work end to end out of the box with no DNS and no certificate authority, the image ships a self-contained demo domain authelia.local (with secure.authelia.local for the demo protected application), served over HTTPS by nginx with a self-signed certificate. First boot maps both names to 127.0.0.1 in /etc/hosts on the instance.

This is a demonstration convenience. For any real deployment you replace the demo domain with your own domain and the self-signed certificate with a real certificate, as described in Step 9 and Step 10 below.

Prerequisites

Before you deploy this image you need:

  • An Amazon Web Services account where you can launch EC2 instances
  • IAM permissions to launch instances, create security groups, and subscribe to AWS Marketplace products
  • An EC2 key pair in the target Region for SSH access to the instance
  • A VPC and subnet in the target Region, with a security group allowing inbound port 22 from your management network, and ports 80 and 443 from the networks that need to reach the portal
  • The AWS CLI (version 2) installed locally if you plan to deploy from the command line

Step 1: Launch the Instance from the AWS Marketplace

Sign in to the AWS Management Console, open the EC2 service, and select Launch instance. Under Application and OS Images choose AWS Marketplace AMIs and search for Authelia. Select the cloudimg listing and choose Select, then Continue on the subscription summary.

Pick an instance type of t3.small or larger. Choose your EC2 key pair under Key pair (login). Under Network settings select your VPC and subnet, and either create or select a security group that opens port 22 from your management network and ports 80 and 443 for the portal. Leave the root volume at the default size or larger.

Select Launch instance. First boot initialisation takes a few seconds after the instance state becomes Running and the status checks pass.

Step 2: Launch the Instance from the AWS CLI

The following block launches an instance from the cloudimg Authelia Marketplace AMI into an existing subnet and security group. Replace <ami-id> with the AMI ID shown on the Marketplace listing, <key-name> with your EC2 key pair name, <subnet-id> with your subnet ID, and <security-group-id> with a security group that opens ports 22, 80 and 443 as described above.

aws ec2 run-instances \
  --image-id <ami-id> \
  --instance-type t3.small \
  --key-name <key-name> \
  --subnet-id <subnet-id> \
  --security-group-ids <security-group-id> \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=authelia}]'

When the instance reaches the Running state and its status checks pass, note its public IP address or DNS name from the EC2 console or with aws ec2 describe-instances.

Step 3: Connect to Your Instance

Connect over SSH using your key pair and the login user for your operating system variant.

OS variant SSH login user
Ubuntu 24.04 ubuntu 
ssh -i <key-name>.pem ubuntu@<public-ip>

Step 4: Retrieve the Admin Password

The Authelia administrator password is unique to your instance and was generated on first boot. Read it as root:

sudo cat /root/authelia-credentials.txt

The file lists the portal URL, the demo application URL, the admin user (admin) and the generated password, along with the one line you add to your workstation hosts file to reach the demo. Keep this password somewhere safe.

Step 5: Confirm Authelia Is Running

Over SSH, confirm the Authelia server and the nginx proxy are active:

sudo systemctl is-active authelia nginx

Both services report as active:

active
active

Authelia binds to loopback only, so its health endpoint is reachable from the instance over plain HTTP on port 9091:

curl -s -o /dev/null -w 'HTTP %{http_code}\n' http://127.0.0.1:9091/api/health

HTTP 200

Confirm the installed version:

authelia --version

authelia version v4.39.20

Step 6: Reach the Authelia Portal from Your Workstation

Because the appliance uses the self-contained demo domain authelia.local, you reach the demo by pointing the demo names at the instance from your own machine. Add the following line to your workstation hosts file (for example /etc/hosts on Linux or macOS, or C:\Windows\System32\drivers\etc\hosts on Windows), replacing <instance-public-ip> with your instance's public IP address:

<instance-public-ip> authelia.local secure.authelia.local

Now browse to the Authelia portal:

https://authelia.local/

Because the demo certificate is self-signed, your browser shows a certificate warning the first time. This is expected for the demo; accept the warning to continue (you replace the certificate with a real one for production, see Step 10). You are presented with the Authelia sign-in portal.

The Authelia single sign-on login portal

Sign in as admin with the password from the credentials file.

The Authelia portal with the administrator credentials entered

Step 7: See the Forward-Authentication Flow

The image ships a demo protected application at https://secure.authelia.local/secure, guarded by Authelia through the standard nginx forward-authentication integration. When nginx receives a request for the protected resource it issues an internal subrequest to Authelia's /api/authz/auth-request endpoint. If you are not authenticated, Authelia returns a redirect and nginx sends your browser to the portal (with the original URL preserved as the rd= return target); once you have signed in, the same subrequest is approved and nginx serves the page.

Browse to the protected application:

https://secure.authelia.local/secure

If you are not yet signed in you are redirected to the Authelia portal. After signing in with the admin credentials, you are returned to the protected page, which confirms that Authelia authenticated and authorized the request.

The demo protected page served after a successful login

Step 8: Add Users

Users live in the file authentication backend at /etc/authelia/users_database.yml, with argon2id hashed passwords. Generate a hash for a new user's password with the Authelia CLI:

authelia crypto hash generate argon2 --password 'choose-a-strong-password'

Copy the printed Digest: value and add a new entry under users: in /etc/authelia/users_database.yml, for example:

users:
  alice:
    disabled: false
    displayname: 'Alice Smith'
    password: '<paste-the-argon2id-digest-here>'
    email: 'alice@example.com'
    groups:
      - 'users'

Authelia watches the user database and picks up changes automatically; if you prefer, restart the service to be sure:

sudo systemctl restart authelia

Step 9: Protect Your Own Applications

To bring your own application under single sign-on, add it as a reverse-proxied site in nginx with the same auth_request block the demo uses (see /etc/nginx/sites-available/authelia), then add an access control rule for it in /etc/authelia/configuration.yml under access_control.rules. Each rule sets a policy of bypass, one_factor or two_factor per domain or path, for example:

access_control:
  default_policy: 'deny'
  rules:
    - domain: 'app.example.com'
      policy: 'one_factor'

Reload the services after editing:

sudo systemctl reload nginx
sudo systemctl restart authelia

Step 10: Set Your Own Domain and a Real Certificate

For production, replace the demo domain and the self-signed certificate. Edit /etc/authelia/configuration.yml and set your own domain under session.cookies (the domain, authelia_url and default_redirection_url, all using https://) and add access_control rules for your applications. Authelia requires the session URLs to use HTTPS, so you must serve the portal over TLS with a certificate for your domain.

The image generates a self-signed certificate at /etc/nginx/tls/authelia-selfsigned.crt and /etc/nginx/tls/authelia-selfsigned.key, referenced by the nginx site. The bundled certificate covers the demo names:

sudo openssl x509 -in /etc/nginx/tls/authelia-selfsigned.crt -noout -subject -ext subjectAltName

subject=CN = authelia.local
X509v3 Subject Alternative Name:
    DNS:authelia.local, DNS:secure.authelia.local

Replace it with a real certificate for your domain. The simplest approach is to obtain a certificate with Certbot for the public name you point at the instance, then update the ssl_certificate and ssl_certificate_key paths in /etc/nginx/sites-available/authelia and reload nginx. Alternatively, terminate TLS on an Application Load Balancer in front of the instance with an ACM certificate and forward to nginx. Restrict the security group so ports 80 and 443 are reachable only from the networks that need the portal.

Step 11: The Data Volume

Authelia's identity state lives on a dedicated EBS volume mounted at /var/lib/authelia: the SQLite storage database (db.sqlite3), the filesystem notifier output (notification.txt) and per-instance generated secrets. This keeps identity state off the operating system disk and lets you resize or snapshot it independently. Confirm the mount with:

df -h /var/lib/authelia

Filesystem      Size  Used Avail Use% Mounted on
/dev/nvme1n1    9.8G  312K  9.3G   1% /var/lib/authelia

To grow the store, expand the EBS volume in the AWS console, then grow the filesystem on the instance with sudo resize2fs on the underlying device.

Step 12: Backup and Maintenance

Back up Authelia's identity state by snapshotting the /var/lib/authelia EBS volume, which captures the user database state, the SQLite store and the secrets. Apply operating system security updates with sudo apt-get update && sudo apt-get upgrade and reboot when a new kernel is installed; Authelia and nginx start automatically on boot.

Support

This image is published and supported by cloudimg. Support covers deployment, reverse proxy and forward authentication configuration, access control rules, two factor enrolment, LDAP or file user backends, SMTP notifications, TLS and bringing your own applications under single sign-on. Contact cloudimg through the support channel listed on the AWS Marketplace listing.

All product and company names are trademarks or registered trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.