# Identity and SSO

Authelia is the staged identity provider for the homelab.

## Why Authelia

- centralizes auth for the growing pile of web apps
- works with shared Postgres/Redis already in the lab
- supports OIDC for apps that speak it properly
- avoids inventing separate local auth for every exposed service

## Current scope

- stack path: identity/
- host target: PlausibleDeniability
- public entrypoint: auth.paccoco.com
- status: Authelia is live on PD; Traefik-based protected app routing is the next cutover layer

## Access-control direction

Traefik is the internal router and Authelia is the policy engine.

Current intended protected domains:
- `gitea.paccoco.com`
- `grafana.paccoco.com`
- `traefik.paccoco.com`

App-native SSO exception:
- `dns.paccoco.com` now uses Technitium's own OIDC flow with Authentik instead of Traefik forward-auth, so the app owns `/sso/login` and `/sso/callback` directly.

Current baseline group policy:
- `admins` -> full access to the domains above

Planned expansion pattern:
- create additional Authelia groups per audience or app class
- grant access in `access_control.rules` by domain + `group:<name>` subject
- keep Pangolin SSO disabled for routes that Traefik/Authelia protect, to avoid double auth

## Initial bootstrap flow

1. Copy identity/.env.example to identity/.env and generate fresh secrets.
2. Copy identity/authelia/configuration.yml.example to identity/authelia/configuration.yml.
3. Render concrete secrets and passwords into identity/authelia/configuration.yml on PD; do not rely on runtime env interpolation inside the YAML.
4. Copy identity/authelia/users_database.example.yml to identity/authelia/users_database.yml.
5. Generate an Argon2 password hash with the Authelia image and replace the sample hash.
6. Create the authelia Postgres database and user in the shared database stack.
7. Set `AUTHELIA_SESSION_REDIS_PASSWORD` from the live shared Redis stack on PD.
8. Add a Pangolin resource for auth.paccoco.com pointing at container authelia:9091.
9. Validate with docker compose --env-file .env config and docker exec authelia authelia config validate --config /config/configuration.yml.

## Rollout order

This repo stage is the control-plane bootstrap, not the full client cutover.

After Authelia is healthy on PD, wire OIDC or forward-auth clients one at a time.

Recommended first targets:

- Grafana
- Gitea
- any new public app before it gains yet another standalone login

## Grafana first-cutover notes

- Use Authelia OIDC as a Generic OAuth provider in Grafana.
- Keep Grafana's local admin login enabled for the first rollout.
- After OIDC is verified, disable Pangolin auth in front of Grafana to avoid double-auth.

## Gitea prep notes

- The live Gitea stack is the `dev/` compose on PD.
- Disable public self-registration before or during the SSO prep pass.
- Keep local admin login working for the first OIDC test.
- Stage the exact Gitea auth-source values in `docs/operations/GITEA_SSO_PREP.md` before creating the live source.

## Notes

- File-backed users are intentional for the initial rollout; this is enough for the current household scale.
- If identity sprawl grows later, migrate the authentication backend to LDAP instead of bolting extra auth stores onto apps ad hoc.
- OIDC signing keys and per-app client secrets should be generated during deployment on PD, not committed to the repo.