145 lines
4.1 KiB
Markdown
145 lines
4.1 KiB
Markdown
# authelia-setup
|
|
|
|
Reusable Authelia SSO + Caddy reverse proxy stack.
|
|
Single login covers all subdomains. Two-factor via TOTP app. Password reset via SMTP.
|
|
|
|
## What this does
|
|
|
|
- **Caddy** — reverse proxy with automatic HTTPS via Let's Encrypt
|
|
- **Authelia** — SSO portal at `auth.mydomain.com`, protects any subdomain with `import authelia` in the Caddyfile
|
|
- **Brevo/Migadu SMTP** — sends TOTP registration and password reset emails
|
|
|
|
## Machine requirements
|
|
|
|
- Ubuntu 24.04 LTS
|
|
- Docker: `curl -fsSL https://get.docker.com | sh && sudo usermod -aG docker $USER`
|
|
- No GPU needed
|
|
|
|
## Directory structure
|
|
|
|
```
|
|
homelab-auth/
|
|
├── caddy/
|
|
│ └── Caddyfile ← replace mydomain.com with real domain
|
|
├── authelia/
|
|
│ ├── docker-compose.yml
|
|
│ └── config/
|
|
│ ├── configuration.yml ← replace mydomain.com with real domain
|
|
│ └── users.yml ← replace mydomain.com, add real emails and hashes
|
|
└── README.md
|
|
```
|
|
|
|
## First time setup
|
|
|
|
### 1. DNS
|
|
At your domain registrar add two records:
|
|
```
|
|
@ → A → this machine's public IP
|
|
* → CNAME → mydomain.com
|
|
```
|
|
|
|
### 2. Replace placeholders
|
|
In every file replace `mydomain.com` with your real domain.
|
|
In `users.yml` replace `REPLACE_WITH_HASH` with real password hashes (see below).
|
|
|
|
### 3. Create secrets
|
|
```bash
|
|
mkdir -p ~/docker/authelia/config/secrets
|
|
|
|
openssl rand -hex 32 > ~/docker/authelia/config/secrets/jwt_secret
|
|
openssl rand -hex 32 > ~/docker/authelia/config/secrets/session_secret
|
|
openssl rand -hex 32 > ~/docker/authelia/config/secrets/storage_secret
|
|
echo "your-smtp-password" > ~/docker/authelia/config/secrets/smtp_password
|
|
|
|
chmod 600 ~/docker/authelia/config/secrets/*
|
|
```
|
|
|
|
### 4. Create .env files
|
|
`~/docker/authelia/.env`:
|
|
```
|
|
MY_DOMAIN=yourdomain.com
|
|
SMTP_USER=authelia@yourdomain.com
|
|
DOCKER_MY_NETWORK=caddy_net
|
|
TZ=America/New_York
|
|
```
|
|
|
|
### 5. Generate password hashes
|
|
Run once per unique password — all users can share one temporary password:
|
|
```bash
|
|
docker run --rm authelia/authelia:4.39.20 authelia crypto hash generate argon2 --password 'TempPass2026!'
|
|
```
|
|
Paste the output into `users.yml` for each user. Tell users to use "Forgot Password" on first login to set their own.
|
|
|
|
### 6. Create Docker network
|
|
```bash
|
|
docker network create caddy_net
|
|
```
|
|
|
|
### 7. Start Authelia
|
|
```bash
|
|
cd ~/docker/authelia
|
|
mkdir -p data
|
|
sudo chown -R 1000:1000 config data
|
|
docker compose up -d
|
|
docker compose logs -f
|
|
```
|
|
|
|
### 8. Start Caddy
|
|
```bash
|
|
cd ~/docker/caddy
|
|
docker compose up -d
|
|
```
|
|
|
|
### 9. Generate Caddy basic auth hash (if using basic auth anywhere)
|
|
```bash
|
|
docker exec caddy caddy hash-password --plaintext 'yourpassword'
|
|
```
|
|
|
|
### 10. Reload Caddy after any Caddyfile changes
|
|
```bash
|
|
docker exec -w /etc/caddy caddy caddy reload
|
|
```
|
|
|
|
## Adding a new protected service
|
|
In the Caddyfile add:
|
|
```caddyfile
|
|
newservice.mydomain.com {
|
|
import authelia
|
|
reverse_proxy INTERNAL_IP:PORT
|
|
}
|
|
```
|
|
Then reload Caddy. No Authelia changes needed.
|
|
|
|
## Adding a service WITHOUT Authelia (has its own login)
|
|
```caddyfile
|
|
newservice.mydomain.com {
|
|
reverse_proxy INTERNAL_IP:PORT
|
|
}
|
|
```
|
|
|
|
## Adding users
|
|
1. Edit `~/docker/authelia/config/users.yml`
|
|
2. Add user block with hash
|
|
3. Restart Authelia: `docker compose restart authelia`
|
|
4. Tell user to use "Forgot Password" to set their own password
|
|
|
|
## TOTP setup (per user, first login)
|
|
1. User logs in with username + temporary password
|
|
2. Authelia emails a TOTP registration link
|
|
3. User scans QR code with Google Authenticator, Authy, Bitwarden, or 1Password
|
|
4. Every login after: username + password + 6-digit code
|
|
|
|
## Updating Authelia
|
|
Only update when you have a specific reason (bug fix, security issue).
|
|
Change the version tag in `docker-compose.yml` then:
|
|
```bash
|
|
docker compose pull authelia
|
|
docker compose up -d authelia
|
|
```
|
|
|
|
## Notes
|
|
- Secrets never go in git — they live in `config/secrets/` which is gitignored
|
|
- `.env` files never go in git
|
|
- Session cookies are valid across all `*.mydomain.com` subdomains — one login covers everything
|
|
- SQLite database lives in `~/docker/authelia/data/` — back this up to preserve user TOTP registrations
|