authentik — identity provider for vps-playground

Authentik deployed on the shared vps-playground VPS. Acts as the identity-aware ingress in front of platform workloads: Traefik delegates auth decisions to Authentik via forward-auth, workloads receive a verified user identity as trusted headers.

This repo is the canonical, version-controlled definition of how Authentik runs on the VPS. The actual deployment lives in Coolify on the host described in vps-playground/vps-control-plane.

What's in here

File	Purpose
docker-compose.yml	Authentik services (server + worker + postgres). Mirrors upstream with one delta (see comment at top).
.env.example	Required environment variables. Real values live in Coolify, not in git.
traefik-dynamic/authentik.yml	Traefik forward-auth middleware definition. Reference as authentik@file on workload routers.

Deploy via Coolify

Prerequisite: a working Coolify install (see vps-control-plane).

1. Generate secrets locally (don't reuse across environments):

   openssl rand -base64 36 | tr -d '\n'   # → PG_PASS
   openssl rand -base64 60 | tr -d '\n'   # → AUTHENTIK_SECRET_KEY

2. Coolify UI → New Resource → Docker Compose:

   • Source: this repo, main branch
   • Compose path: docker-compose.yml
   • Domain: https://auth.3eee17bc.nip.io (3eee17bc is the hex-encoded VPS IP; replace with your registered parent if you have one)
   • Target service: server, port 9000
   • Environment variables: paste from .env.example, fill in the generated secrets

3. Deploy. Wait for the Let's Encrypt cert. First boot runs migrations (~30s).

4. Bootstrap admin. Visit https://auth.3eee17bc.nip.io/if/flow/initial-setup/ — Authentik's first-run flow lets you create the admin account.

5. Install the forward-auth middleware via Ansible. The platform repo (vps-playground/vps-control-plane) ships a coolify_proxy_dynamic role that fetches traefik-dynamic/authentik.yml from this repo at the pinned ref in ansible/inventory/group_vars/all/main.yml and drops it into /data/coolify/proxy/dynamic/. From the platform repo:

   just coolify     # or: just coolify-check first

   Traefik picks the file up automatically (file watcher). Verify in Coolify → Servers → localhost → Proxy → Logs for Adding middleware [authentik].

   This file is also fetchable directly at https://raw.githubusercontent.com/vps-playground/authentik/main/traefik-dynamic/authentik.yml. Don't deploy it by hand — the Ansible path is the only supported flow, because it's reproducible from a fresh VM.

Configuring forward-auth in Authentik

After deploy, in the Authentik admin UI:

1. Applications → Providers → Create → Proxy Provider:

   • Mode: Forward auth (domain level)
   • External host: https://auth.3eee17bc.nip.io
   • Cookie domain: 3eee17bc.nip.io

2. Applications → Applications → Create → bind to the provider above. Slug domain-level.

3. Applications → Outposts → edit the embedded outpost → add the application.

That single domain-level provider protects every workload that opts in via the authentik@file middleware. Per-application policies (group membership, etc.) attach to Applications in Authentik, not at the middleware layer.

Workload integration

A workload becomes "identity-aware" by:

1. Joining Coolify's Traefik network (default for Coolify apps).
2. Adding the middleware label on its router:

   traefik.http.routers.<name>.middlewares=authentik@file
   

3. Reading user identity from X-Authentik-Username / X-Authentik-Email / X-Authentik-Groups headers.

For path-level exemptions (e.g. /healthz, /.well-known/acme-challenge/), define a second router on the same service without the middleware, with a higher priority and a path match.

For the full design rationale, per-workload contract, and footguns: ADR-0011 Identity-aware ingress via Authentik forward-auth in platform-conventions. For deploy and operations on this specific VPS: vps-control-plane/docs/identity-deploy.md.

Updates

Bump AUTHENTIK_TAG in .env (or in Coolify env vars) and redeploy. Always check release notes for schema migrations — Authentik runs them on boot but breaking changes occasionally need manual steps.

To resync the upstream compose:

curl -fsSL https://goauthentik.io/docker-compose.yml -o /tmp/upstream.yml
diff -u /tmp/upstream.yml docker-compose.yml   # review, then re-apply the documented delta