Traefik ForwardAuth

SpartanAuth’s ForwardAuth endpoint lets you protect any service running behind Traefik without writing any authentication code in your service. Traefik calls SpartanAuth to verify each request before forwarding it.

How it works

1. A request arrives at Traefik for a protected service
2. Traefik calls GET https://api.spartanauth.com/api/v1/auth/verify with the original request headers
3. SpartanAuth validates the JWT in the Authorization header:
   • HTTP 200 — token is valid; Traefik forwards the request with extra identity headers
   • HTTP 401 — token is missing or invalid; Traefik rejects the request
4. Your backend service receives the forwarded request with X-Auth-User and X-Auth-Subject headers set

Response headers

When authentication succeeds, SpartanAuth sets these headers on the forwarded request:

Header	Value
X-Auth-User	The user’s email address
X-Auth-Subject	The user’s sub (stable UUID identifier)

Your backend can read these headers directly — no JWT parsing or introspection required.

Configuration

Dynamic configuration (YAML)

http:
  middlewares:
    spartanauth:
      forwardAuth:
        address: "https://api.spartanauth.com/api/v1/auth/verify"
        authResponseHeaders:
          - "X-Auth-User"
          - "X-Auth-Subject"

  routers:
    my-protected-service:
      rule: "Host(`myapp.example.com`)"
      service: my-service
      middlewares:
        - spartanauth

Dynamic configuration (TOML)

[http.middlewares]
  [http.middlewares.spartanauth.forwardAuth]
    address = "https://api.spartanauth.com/api/v1/auth/verify"
    authResponseHeaders = ["X-Auth-User", "X-Auth-Subject"]

[http.routers.my-protected-service]
  rule = "Host(`myapp.example.com`)"
  service = "my-service"
  middlewares = ["spartanauth"]

Docker labels

labels:
  # Define the ForwardAuth middleware
  - "traefik.http.middlewares.spartanauth.forwardauth.address=https://api.spartanauth.com/api/v1/auth/verify"
  - "traefik.http.middlewares.spartanauth.forwardauth.authResponseHeaders=X-Auth-User,X-Auth-Subject"
  # Apply the middleware to your service's router
  - "traefik.http.routers.my-service.middlewares=spartanauth@docker"

Client authentication

Your frontend must include the JWT in the Authorization header for every request to a protected route:

Authorization: Bearer <jwt>