tailwart/authelia/CLAUDE.md

CLAUDE.md — authelia

Guidance for Claude Code in this repo. Read before editing.

What this is

A standalone Authelia deployment — SSO portal, 2FA, and (optional) OIDC provider — as a Tailscale sidecar, plugged into the shared tailnet Postgres (storage) and Redis (sessions), with the shared SMTP relay for reset/2FA mail. Sibling to tailwart; same pattern, different job. Domain: infinidim.net (portal auth.infinidim.net).

Self-contained and outside any upstream repo (own .env, compose, config, ACL snippet). Reads only the tailnet at runtime.

Architecture

  main box Caddy (tag:reverse-proxy)            tailnet-only auth
  ┌────────────────────────────┐               ┌───────────────────────┐
  │ auth.infinidim.net  ───────┼──────────────▶│ ts-authelia sidecar    │
  │   reverse_proxy :9091      │   tailnet     │  authelia (no WAN, no  │
  │ protected vhosts:          │               │  host ports) :9091     │
  │   forward_auth → :9091     │               └──────────┬─────────────┘
  └────────────────────────────┘                          │
                                                   ┌───────┴───────┐
                                                   ▼       ▼       ▼
                                              Postgres  Redis   SMTP relay

• Sidecar (tag:authelia), network_mode: service:ts-authelia, no host ports.
• Authelia listens :9091 on the tailnet. The main box Caddy (layer 7, not a separate edge) fronts the portal and wires forward_auth for protected services — see caddy-forward-auth.snippet. This is ordinary L7, unlike tailwart's L4 mail edge.
• Storage → Postgres (authelia role/db), sessions → Redis (logical DB AUTHELIA_REDIS_DB), mail → shared relay.

The .env contract

.env (gitignored) is the whole surface. Secrets and infra hostnames reach Authelia as AUTHELIA_* env overrides (set in docker-compose.yml), which take precedence over config/configuration.yml. That keeps the committed yml free of secrets and MagicDNS names. The yml holds only non-secret structure (access_control, session.cookies, totp, regulation).

Prerequisites (shared tailnet infra)

1. Postgres role+db: authelia / AUTHELIA_DB_NAME. Create via a one-off CREATE ROLE authelia LOGIN PASSWORD '…'; CREATE DATABASE authelia OWNER authelia; against the-record-prod (the federatedSocial shared Postgres).
2. Redis: nothing to create — uses logical DB index AUTHELIA_REDIS_DB (4) so it won't collide with the fediverse apps or tailwart (which uses 3).
3. config/users_database.yml: at least one user with an argon2id hash: docker run --rm authelia/authelia:latest authelia crypto hash generate argon2 --password 'PASS'.
4. Admin console: assign tag:authelia to the OAuth client (Devices/Core + Keys/AuthKeys) and add acl-snippet.hujson to the policy.
5. Main box Caddy: add caddy-forward-auth.snippet (portal vhost + the (authelia) import) and a cert for auth.infinidim.net.

Pitfalls

• Authelia config schema drifts hard between minor versions (4.37→4.38 moved session to cookies[], added identity_validation, changed storage.postgres to address). The image is pinned to 4.39.20 and the yml passes authelia config validate against it. Re-validate before bumping the tag: docker run --rm -e ... -v ./config:/config:ro authelia/authelia:<tag> authelia config validate.
• Don't put secrets in configuration.yml. Use the AUTHELIA_* env path.
• Redis DB index collisions. tailwart=3, authelia=4. Keep them distinct.
• Postgres password drift. Role passwords only apply on CREATE/ALTER; test auth over the tailnet (scram), never 127.0.0.1 (that pg_hba line is trust and accepts any password — it'll lie to you).
• forward_auth is layer 7, on the main Caddy. Don't confuse it with tailwart's L4 edge — different mechanism entirely.

What not to do

• Don't write into /opt/federatedSocial (read its .env if needed).
• Don't add ports: to the Authelia container — the main Caddy is the only public path in.
• Don't commit .env.
• Don't break the sidecar netns boundary.