# Authentik forward-auth (via Traefik)

Veola can delegate identity to Authentik using Traefik's `forwardAuth`
middleware. Veola itself does not speak OIDC; it trusts identity headers that
Authentik's proxy outpost sets, and matches/creates a local user by **email**.
Local password login stays available as a break-glass fallback.

## 1. Veola config

```toml
[auth]
mode = "forward"
trusted_proxies = ["172.18.0.0/16"]   # CIDR(s) of the Traefik container/host
admin_group = "veola-admins"           # Authentik group that grants admin
```

`trusted_proxies` is mandatory in forward mode: forward-auth headers are only
honored when the **direct** connection (before `X-Forwarded-For` rewriting)
comes from one of these CIDRs. Without it the headers are spoofable. Use the
address Traefik connects from (its Docker network range, or `127.0.0.1/32` if
co-located).

Header names default to Authentik's (`X-Authentik-Username`,
`X-Authentik-Email`, `X-Authentik-Name`, `X-Authentik-Groups`); override under
`[auth]` only if your outpost differs.

## 2. Authentik

- Create a **Proxy Provider** in *forward auth (single application)* mode with
  the external host (e.g. `https://veola.example.com`).
- Bind it to an Application, and bind the embedded/standalone outpost.
- Create a group (default name `veola-admins`) and add operators who should be
  Veola admins. Everyone else lands as a regular user. Role is re-synced from
  the group on every request.

## 3. Traefik

```yaml
http:
  middlewares:
    authentik:
      forwardAuth:
        address: "http://authentik-server:9000/outpost.goauthentik.io/auth/traefik"
        trustForwardHeader: true
        authResponseHeaders:
          - X-authentik-username
          - X-authentik-email
          - X-authentik-name
          - X-authentik-groups

  routers:
    veola:
      rule: "Host(`veola.example.com`)"
      service: veola
      middlewares:
        - authentik
      tls:
        certResolver: letsencrypt
```

Traefik must strip any client-supplied `X-Authentik-*` and `X-Forwarded-*`
headers on ingress so only the outpost can set them.

## Break-glass

`/login` and `/setup` still work for local password accounts. If Authentik is
down, reach Veola directly (bypassing the proxy) from a trusted network and log
in with a local admin account. Forward-auth is a no-op for connections that do
not originate from `trusted_proxies`.