truenas-stacks/docs/operations/IDENTITY_AND_SSO.md

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: repo-staged, not assumed live until deployed on PD

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.