Traefik Integration#

Overview#

Tinyauth integrates with Traefik as a reverse proxy via Traefik's ForwardAuth middleware. When a request hits a protected service, Traefik forwards it to Tinyauth's /api/auth/traefik endpoint. Tinyauth checks authentication/authorization and responds with 200 (allow) or a redirect to the login page (deny). Traefik then either passes the request through or blocks it based on that response.

The integration is built around a single generic handler — proxy_controller.go — that serves all supported proxy types (traefik, caddy, envoy, nginx) under the /api/auth/:proxy route 1. For traefik, only ForwardAuth is used (unlike nginx which also supports AuthRequest, or envoy which also supports ExtAuthz).

How It Works#

Browser → Traefik → Tinyauth /api/auth/traefik → 200 OK → upstream service
                                                 → 302 redirect → login page

When Traefik calls the ForwardAuth endpoint, Tinyauth reads the request context from X-Forwarded-Host, X-Forwarded-URI, and X-Forwarded-Proto headers 2. Browser vs. non-browser is detected from the User-Agent header 3 — for browser clients Tinyauth returns 302 redirects, for API clients it returns 401/403 JSON with an x-tinyauth-location header.

On success, Tinyauth sets auth identity headers that Traefik can forward to the upstream service via authResponseHeaders 4:

Configuration#

Minimal Production Setup#

The docker-compose.example.yml shows the minimal production configuration:

• Traefik runs with --providers.docker and mounts the Docker socket 5
• Tinyauth defines the ForwardAuth middleware via a Docker label: traefik.http.middlewares.tinyauth.forwardauth.address: http://tinyauth:3000/api/auth/traefik 6
• Protected services reference that middleware with traefik.http.routers.<name>.middlewares: tinyauth 7
• TINYAUTH_APPURL must be set to the public URL of Tinyauth itself 8

Development Setup#

The docker-compose.dev.yml extends this with:

• Both websecure (HTTPS) and web (HTTP) entrypoints 9
• TLS on the Tinyauth frontend router 10
• authResponseHeaders explicitly declared on the middleware so Traefik forwards identity headers to upstream services: remote-user, remote-sub, remote-name, remote-email, remote-groups 11
• The Docker socket mounted into the Tinyauth backend container for label-based service discovery 12
• Split frontend (tinyauth-frontend) and backend (tinyauth-backend) services compared to the single container in production 13

Key Labels Reference#

# Define the middleware (on the tinyauth service)
traefik.http.middlewares.tinyauth.forwardauth.address: http://tinyauth:3000/api/auth/traefik
traefik.http.middlewares.tinyauth.forwardauth.authResponseHeaders: remote-user,remote-sub,remote-name,remote-email,remote-groups

# Protect a service (on any downstream service)
traefik.http.routers.<name>.middlewares: tinyauth

Related Topics#

• Trusted Proxies — For IP-based ACLs to work correctly through Traefik, configure TINYAUTH_AUTH_TRUSTEDPROXIES with the Traefik container's IP or the Docker network subnet CIDR. See Trusted Proxy and Client IP Resolution 14.
• Docker Label Service Discovery — Tinyauth can read per-app ACL settings from Docker container labels (tinyauth.apps.*), driven by the same Docker socket mount used in the dev compose file. See Docker Label-Based Service Discovery 15.
• Other Supported Proxies — The same proxy controller handles Caddy (ForwardAuth), Nginx (AuthRequest + ForwardAuth), and Envoy (ExtAuthz + ForwardAuth) — see getProxyType and determineAuthModules.