FAIRVISOR Docs
⌘K
GitHub fairvisor.com

Traefik

Traefik’s forwardAuth middleware delegates request authorization to an external service. Fairvisor Edge’s /v1/decision endpoint is fully compatible.

Kubernetes CRD

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: fairvisor-auth
  namespace: default
spec:
  forwardAuth:
    address: http://fairvisor-edge.default.svc.cluster.local:8080/v1/decision
    trustForwardHeader: true
    authResponseHeaders:
      - X-Fairvisor-Reason
      - Retry-After
      - RateLimit
      - RateLimit-Limit
      - RateLimit-Remaining
      - RateLimit-Reset

authResponseHeaders lists the headers from the Fairvisor response that Traefik should forward to the backend (on allow) or to the client (on reject). Include at minimum Retry-After and X-Fairvisor-Reason. Policy/rule attribution is debug-session-only (X-Fairvisor-Debug-*).

Attaching to an IngressRoute

apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
  name: my-api
  namespace: default
spec:
  entryPoints:
    - web
  routes:
    - match: PathPrefix(`/api/`)
      kind: Rule
      services:
        - name: my-api-service
          port: 3000
      middlewares:
        - name: fairvisor-auth

Docker Compose labels

services:
  my-api:
    image: my-api:latest
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.my-api.rule=PathPrefix(`/api/`)"
      - "traefik.http.routers.my-api.middlewares=fairvisor-auth@docker"
      - "traefik.http.middlewares.fairvisor-auth.forwardauth.address=http://fairvisor-edge:8080/v1/decision"
      - "traefik.http.middlewares.fairvisor-auth.forwardauth.trustforwardheader=true"
      - "traefik.http.middlewares.fairvisor-auth.forwardauth.authResponseHeaders=Retry-After,X-Fairvisor-Reason,RateLimit-Remaining"

Static configuration (traefik.yml)

http:
  middlewares:
    fairvisor-auth:
      forwardAuth:
        address: "http://fairvisor-edge:8080/v1/decision"
        trustForwardHeader: true
        authResponseHeaders:
          - X-Fairvisor-Reason
          - Retry-After
          - RateLimit-Limit
          - RateLimit-Remaining
          - RateLimit-Reset

Headers forwarded to Fairvisor

Traefik forwards the original request headers to the forwardAuth endpoint, including Authorization. Fairvisor Edge extracts JWT claims, client IP, and other descriptor keys from these headers automatically.

trustForwardHeader: true instructs Traefik to trust the X-Forwarded-For header from upstream, so Fairvisor sees the correct client IP when Traefik sits behind another proxy.

Timeout

The default forwardAuth timeout in Traefik is 30 seconds. Reduce it to a few hundred milliseconds to avoid stalling requests if Fairvisor Edge is slow:

forwardAuth:
  address: "http://fairvisor-edge:8080/v1/decision"
  authRequestHeaders:
    - Authorization
  # Traefik does not expose a direct timeout field here;
  # configure the Fairvisor Edge service dial/read timeout
  # via the Traefik service definition.

Failure mode

Traefik forwardAuth fails-closed by default: if the auth service is unreachable, the request is rejected with 500. To implement fail-open, run a small nginx sidecar in front of Fairvisor Edge that returns 200 on upstream errors, or handle it at the service mesh level.

MD