Learn Traefik - Authentication Middlewares

#Introduction

Protecting services from unauthorized access is the first need of every deployment. Episode 9 covers four Traefik authentication middlewares: BasicAuth, DigestAuth, ForwardAuth, and IPWhiteList — each with different strengths and trade-offs.

BasicAuth is simple and enough for many internal cases. ForwardAuth is the most powerful: authentication is delegated to external services like Authelia, Authentik, or OAuth2 Proxy, enabling SSO, TOTP, and centralized policies. By the end of the episode, you will know when to use which.

#BasicAuth

#Username, Password, and htpasswd

BasicAuth requests credentials via an Authorization header of type Basic. Passwords must not be stored in plaintext — Traefik accepts hashes created with htpasswd. Generate a hash with the htpasswd command:

htpasswd -nbB admin "super-secret"
docker run --rm httpd:alpine htpasswd -nbB admin "super-secret"

The output takes the form admin:$2y$05$.... Paste that result into the middleware:

http:
  middlewares:
    admin-auth:
      basicAuth:
        users:
          - "admin:$2y$05$0UvReaDF8s0BbQpqBFBp8e1gV6Q2Y0hH9o5QyTq3a4j7kLmZxS2C"
        realm: "Admin Zone"
        removeHeader: true

• users: list of username:hash; multiple users are separated by lines.
• realm: the text shown by the browser in the login dialog.
• removeHeader: true: removes the Authorization header before forwarding to the backend — prevents credentials from leaking to the application.

A router using this middleware:

http:
  routers:
    admin:
      rule: "Host(`admin.localhost`)"
      entrypoints:
        - web
      service: admin-svc
      middlewares:
        - admin-auth
  services:
    admin-svc:
      loadBalancer:
        servers:
          - url: "http://10.0.0.50:8080"

#DigestAuth

#Authentication Without Sending the Password

DigestAuth uses challenge-response: the password is never sent as text, only a digest of the combined values. Traefik accepts the MD5 hash of username:realm:password instead of the plaintext password:

printf "admin:Admin Zone:super-secret" | md5sum

http:
  middlewares:
    dig-auth:
      digestAuth:
        users:
          - "admin:c5b0c4f1a6d4c6e5d86ac4a5b2f3a2b3"
        realm: "Digest Zone"
        removeHeader: true

DigestAuth is safer than BasicAuth in terms of credential transfer, but its implementation is less commonly supported by modern clients and more complex to operate. For most cases, BasicAuth or ForwardAuth is a more sensible choice.

#ForwardAuth

#Delegating to an External Service

ForwardAuth sends the request to an authentication service URL. If the service responds with 2xx, access is allowed; if it responds with 401 or 403, the request is rejected. This is the gateway to enterprise SSO:

http:
  middlewares:
    auth-authelia:
      forwardAuth:
        address: "http://authelia:9091/api/authz/forward-auth"
        authResponseHeaders:
          - Remote-User
          - Remote-Groups
        trustForwardHeader: true

• address: the check endpoint URL of the authentication service.
• authResponseHeaders: headers from the auth service response that are forwarded to the backend, e.g. Remote-User.
• trustForwardHeader: true: trusts X-Forwarded-* headers from a proxy in front — only enable if Traefik is behind a trusted proxy.

#Popular Integrations

This pattern is used by popular services:

• Authelia: full-featured SSO with TOTP, u2f, and LDAP backend.
• Authentik: unified identity with customizable authorization flows.
• OAuth2 Proxy: OAuth gateway for Google, GitHub, GitLab, and more.
• Custom service: your own API only needs to return a status code.

The ForwardAuth flow is one of the most common patterns in enterprise-grade Traefik homelab setups.

#IPWhiteList

#Restricting Based on Source Address

Sometimes what you need is not a login, but restricting where requests may come from. IPWhiteList accepts or rejects based on the source IP, with CIDR support:

http:
  middlewares:
    internal-only:
      ipWhiteList:
        sourceRange:
          - "192.168.1.0/24"
          - "127.0.0.1/32"

All requests from outside the range above are rejected with 403. If Traefik sits behind another proxy, the source IP seen is the proxy's IP — that is when you need the ipStrategy setting with depth to count how many proxy hops to skip before finding the client's real IP:

http:
  middlewares:
    vpn-only:
      ipWhiteList:
        sourceRange:
          - "10.8.0.0/16"
        ipStrategy:
          depth: 2

A depth: 2 value tells Traefik to read the first two hops from the X-Forwarded-For header to find the client's real IP. Combine IPWhiteList with BasicAuth for layered defense.

#Closing

Key takeaways:

• BasicAuth is simple; create password hashes with htpasswd -nbB.
• removeHeader: true prevents credentials from leaking to the backend.
• DigestAuth sends a digest, not the password, but is rarely used by modern clients.
• ForwardAuth delegates authentication to Authelia, Authentik, OAuth2 Proxy, or a custom service.
• IPWhiteList restricts access by IP address or CIDR range.
• Combine several authentication layers for solid defense.

In episode 10 next we will cover headers and security middlewares — the headers middleware for custom headers, the security header suite such as CSP, X-Frame-Options, and HSTS, complete CORS configuration, and how to enable force HTTPS. After this, your services will meet the basic security standards of the modern web.