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. Create the Authentik database/user in shared Postgres

4. Validate and start:

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

5. Verify readiness:

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

6. 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.

7. 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

8. Bind those proxy providers to the embedded outpost.

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

10. 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.