Authentication and access control

These middlewares decide whether a request gets to proceed through the chain. Most are short, focused implementations.

Basic auth

pkg/middlewares/auth/basic_auth.go (and users.go). Uses htpasswd-style credentials, supporting the bcrypt, SHA, and APR1 hashes via github.com/abbot/go-http-auth.

http:
  middlewares:
    api-auth:
      basicAuth:
        users:
          - 'admin:$apr1$mYr0aRq$iEy5...'
        usersFile: /etc/traefik/users
        realm: Restricted
        removeHeader: true
        headerField: X-WebAuth-User

The middleware:

• Looks up the user, computes the hash, compares.
• On success, sets X-WebAuth-User (or the configured field) so upstream services know who's calling.
• On failure, returns 401 with a WWW-Authenticate challenge.

Digest auth

pkg/middlewares/auth/digest_auth.go. Same configuration shape as basic auth but using HTTP Digest authentication. Rarely used today — basic auth over TLS is the modern convention.

Forward auth

pkg/middlewares/auth/forward.go. The most flexible authentication middleware. Configures Traefik to call an upstream /auth endpoint for each request:

http:
  middlewares:
    sso:
      forwardAuth:
        address: http://oauth2-proxy:4180/oauth2/auth
        trustForwardHeader: true
        authResponseHeaders:
          - X-Auth-Email
          - X-Forwarded-User
        authResponseHeadersRegex: '^X-Auth-'
        authRequestHeaders:
          - Cookie
        addAuthCookiesToResponse: ['_oauth2_proxy']
        tls:
          insecureSkipVerify: false

Behavior:

• The middleware sends an HTTP GET to the configured address with selected headers from the original request.
• A 2xx response means "let it through". The middleware may also copy specified response headers onto the original request before forwarding to the upstream service.
• A 3xx response is forwarded to the client (typical for OAuth flows that redirect to the IdP).
• A non-2xx, non-3xx response short-circuits the chain and is returned to the client.

This is the building block for OAuth2 / OIDC integrations via projects like oauth2-proxy.

IP allow list

pkg/middlewares/ipallowlist/. Allows requests originating from specific CIDRs:

http:
  middlewares:
    internal-only:
      ipAllowList:
        sourceRange:
          - 10.0.0.0/8
          - 192.168.0.0/16
        ipStrategy:
          depth: 2
          excludedIPs:
            - 127.0.0.1/32

ipStrategy controls how the source IP is derived from PROXY-protocol headers and X-Forwarded-For. The shared logic lives in pkg/middlewares/extractor.go.

pkg/middlewares/ipwhitelist/ is the deprecated alias retained for backwards compatibility. New configurations should use ipAllowList.

TCP IP allow list

pkg/middlewares/tcp/ includes a TCP variant for IP allow listing. It runs before TLS termination on the TCP entry point, which is important when you want to drop unwanted connections without doing the TLS handshake.

Pass TLS client certificate

pkg/middlewares/passtlsclientcert/. Extracts fields from the negotiated client certificate and forwards them as headers:

http:
  middlewares:
    mtls:
      passTLSClientCert:
        pem: true
        info:
          subject:
            commonName: true
          issuer:
            commonName: true

Useful when an upstream needs to authenticate the client itself but doesn't want to terminate TLS.

Recovery

pkg/middlewares/recovery/. Catches panics and converts them into HTTP 500 responses. It's not configurable and is always present at the top of every middleware chain — pkg/server/middleware/middlewares.go adds it automatically.

Anatomy

A typical authentication middleware:

type authMiddleware struct {
    next        http.Handler
    name        string
    // configuration ...
}

func New(ctx context.Context, next http.Handler, cfg dynamic.BasicAuth, name string) (http.Handler, error) {
    // validate cfg, build credential store
    return &authMiddleware{next: next, name: name, /* ... */}, nil
}

func (a *authMiddleware) ServeHTTP(w http.ResponseWriter, r *http.Request) {
    if !authenticate(r) {
        w.Header().Set("WWW-Authenticate", `Basic realm="`+a.realm+`"`)
        w.WriteHeader(http.StatusUnauthorized)
        return
    }
    a.next.ServeHTTP(w, r)
}

func (a *authMiddleware) GetTracingInformation() (string, string, trace.SpanKind) {
    return a.name, "BasicAuthType", trace.SpanKindInternal
}

For other middleware categories see Resilience, Transformations, and Observability.