# Identity / SSO

This stack introduces Authelia as the homelab identity plane.

Current design choices:

- Authelia only, no LDAP yet
- shared Postgres for durable storage
- shared Redis for session storage
- file-backed users database for initial bootstrap
- Pangolin/Newt exposure at auth.paccoco.com

Why this shape:

- it gets a real SSO control plane online without dragging in extra moving parts
- it matches the homelab preference for shared DB infrastructure over SQLite
- file users are fine at this size and can be migrated to LDAP later if needed

Files:

- docker-compose.yaml
- .env.example
- authelia/configuration.yml.example
- authelia/users_database.example.yml

Bootstrap:

1. Copy this directory to PD at /mnt/docker-ssd/docker/compose/identity
2. Copy .env.example to .env and replace every CHANGE_ME
3. Copy authelia/configuration.yml.example to authelia/configuration.yml
4. Render concrete secrets into `authelia/configuration.yml`; do not leave template placeholders or `${...}` references in the live file.
5. Copy authelia/users_database.example.yml to authelia/users_database.yml
6. Create an Authelia password hash:

   docker run --rm authelia/authelia:latest authelia crypto hash generate argon2 --password 'CHANGE_ME'

7. Replace the sample hash in users_database.yml
8. Create the authelia database/user in shared Postgres
9. Set `AUTHELIA_SESSION_REDIS_PASSWORD` from the live shared Redis stack on PD.
10. Create a Pangolin resource:
   Domain: auth.paccoco.com
   Scheme: http
   Host: authelia
   Port: 9091
11. Validate and start:

   cd /mnt/docker-ssd/docker/compose/identity
   docker compose --env-file .env config
   docker compose --env-file .env up -d
   docker exec authelia authelia config validate --config /config/configuration.yml

This repo stage gives you the identity control plane itself.

OIDC client rollout is intentionally a second pass because it needs:

- a real signing-key strategy
- per-app client IDs and secrets
- app-specific callback URLs verified against live domains

First client recommendation:

- Grafana via Generic OAuth against Authelia OIDC
- Keep Grafana local-admin login enabled for the first cutover so recovery is easy if the public auth route or claims mapping is wrong

Do not try to wire every app at once. Get Authelia healthy first, then cut services over one at a time.
