truenas-stacks/identity-authentik/README.md

Identity / SSO - Authentik

This stack stages an Authentik migration in parallel with the current Authelia deployment so cutover can happen app-by-app with easy rollback.

Current design choices:

• Authentik server + worker only
• shared Postgres for durable storage
• embedded outpost for Traefik forward-auth
• no Redis dependency
• no Docker socket mount
• keep Authelia alive until all apps validate cleanly

Why this shape:

• it future-proofs the identity plane without turning migration into a flag day
• it preserves easy rollback while Authentik is proven per app
• it matches the homelab preference for shared database infra over one-off local state
• embedded outpost is enough for this size and avoids extra moving parts

Files:

• docker-compose.yaml
• .env.example
• custom-templates/.gitkeep

Bootstrap:

1. Copy this directory to PD at /mnt/docker-ssd/docker/compose/identity-authentik

2. Copy .env.example to .env and replace every CHANGE_ME

3. If email-based password resets or invitations are needed, set the SMTP vars in .env using the official Authentik email settings (AUTHENTIK_EMAIL__HOST, __PORT, __USERNAME, __PASSWORD, __USE_TLS or __USE_SSL, __TIMEOUT, __FROM). Port 587 normally means AUTHENTIK_EMAIL__USE_TLS=true and AUTHENTIK_EMAIL__USE_SSL=false.

4. Create the Authentik database/user in shared Postgres

5. Validate and start:

   cd /mnt/docker-ssd/docker/compose/identity-authentik docker compose --env-file .env config docker compose --env-file .env up -d

6. Verify readiness:

   docker compose ps docker logs authentik-server --tail=50 curl -fsS http://127.0.0.1:9000/-/health/ready/

7. If SMTP is enabled, send a test mail from inside the Authentik server container before relying on password reset or invitation flows.

8. Complete initial login with the bootstrap admin on the internal URL first, then wire the public Pangolin hostname https://authentik.paccoco.com. Grafana and other OIDC clients should use that public hostname instead of the LAN-only http://10.5.30.6:9000 base URL.

9. Build providers before cutover:

   • Grafana: OAuth2/OIDC provider
   • Gitea: proxy provider, forward auth, single application
   • Technitium: proxy provider, forward auth, single application
   • Traefik dashboard: proxy provider, forward auth, single application

10. Bind those proxy providers to the embedded outpost.

11. Cut apps over one at a time from Authelia forward-auth to Authentik forward-auth.

12. Only remove Authelia after every migrated app and logout flow is verified.

Notes:

• Authentik listens internally on port 9000 for HTTP and serves the embedded outpost paths there too.
• The Traefik middleware should call: http://authentik-server:9000/outpost.goauthentik.io/auth/traefik
• Each forward-auth protected app also needs a higher-priority router for: PathPrefix(/outpost.goauthentik.io/) routed to Authentik, or the login flow will break.
• Grafana should end on native OIDC instead of remaining behind forward-auth long-term.