How to Secure the Traefik API and Dashboard Using Authentication Middleware

Protect the Traefik API and dashboard by attaching authentication middlewares such as BasicAuth, DigestAuth, or ForwardAuth to a router that routes to the internal api@internal service, while ensuring api.insecure remains disabled in production.

The Traefik API and dashboard expose sensitive routing configuration and must be secured before deployment. In the traefik/traefik repository, the recommended approach uses native HTTP middlewares that intercept requests to the internal API service. This guide covers the authentication mechanisms available and provides configuration examples for Docker, Kubernetes, and file-based deployments.

Authentication Middleware Options

Traefik provides several built-in middlewares for securing the dashboard and API endpoints. As documented in docs/content/reference/install-configuration/api-dashboard.md, you attach these to a router that routes to the internal api@internal service.

BasicAuth

The BasicAuth middleware implements HTTP Basic authentication using hashed passwords. Configuration details are defined in docs/content/middlewares/http/basicauth.md. Store credentials securely using MD5, SHA1, or BCrypt hashing.

DigestAuth

The DigestAuth middleware provides RFC 7616 HTTP Digest authentication, offering improved security over BasicAuth by preventing plaintext password transmission. Reference the implementation details in docs/content/middlewares/http/digestauth.md.

ForwardAuth

The ForwardAuth middleware delegates authentication decisions to an external service, supporting OAuth2, OIDC, or custom authentication providers. According to docs/content/middlewares/http/forwardauth.md, this middleware forwards the request to a specified URL and expects a 2xx status code for access grants.

IPAllowlist

The IPAllowlist middleware (defined in docs/content/middlewares/http/ipallowlist.md) restricts access based on source IP addresses or CIDR ranges. Use this as a complementary layer or for internal networks where authentication credentials are impractical.

Traefik API Security Configuration

Securing the dashboard requires understanding Traefik's two-configuration model:

1. Static configuration enables the API itself via the api provider
2. Dynamic configuration defines routers, services, and middlewares that protect the api@internal service

In docs/content/reference/install-configuration/api-dashboard.md, the core options include:

• api.dashboard: Enables the dashboard UI (default: false)
• api.insecure: Never enable in production; exposes the API without TLS on the traefik entrypoint (default: false)
• api.basePath: Customizes the base path for all API and dashboard URLs (default: /)

Implementation Examples

Docker Compose

When running Traefik in a container, define labels to create a router that matches dashboard paths and applies middlewares:

labels:
  - "traefik.http.routers.dashboard.rule=Host(`traefik.example.com`) && (PathPrefix(`/api`) || PathPrefix(`/dashboard`))"
  - "traefik.http.routers.dashboard.service=api@internal"
  - "traefik.http.routers.dashboard.middlewares=dashboard-auth,ipallowlist"
  - "traefik.http.middlewares.dashboard-auth.basicauth.users=admin:$$apr1$$H6uskkkW$$IgXLP6ewTrSuBkTrqE8wj/"
  - "traefik.http.middlewares.ipallowlist.ipallowlist.sourceRange=10.0.0.0/8,192.168.0.0/16"

Note that dollar signs in Docker labels require escaping as $$.

Docker Swarm

Docker Swarm uses the same label syntax but requires a dummy service for port detection, as noted in docs/content/reference/install-configuration/api-dashboard.md:

deploy:
  labels:
    - "traefik.http.routers.dashboard.rule=Host(`traefik.example.com`) && (PathPrefix(`/api`) || PathPrefix(`/dashboard`))"
    - "traefik.http.routers.dashboard.service=api@internal"
    - "traefik.http.routers.dashboard.middlewares=dashboard-auth"
    - "traefik.http.middlewares.dashboard-auth.basicauth.users=test:$$apr1$$H6uskkkW$$IgXLP6ewTrSuBkTrqE8wj/"
    - "traefik.http.services.dummy-svc.loadbalancer.server.port=9999"

Kubernetes CRD

For Kubernetes deployments using Custom Resource Definitions, create a Middleware object and reference it in an IngressRoute:

apiVersion: v1
kind: Secret
metadata:
  name: traefik-dashboard-auth-secret
type: kubernetes.io/basic-auth
stringData:
  username: admin
  password: super-secret
---
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: dashboard-auth
spec:
  basicAuth:
    secret: traefik-dashboard-auth-secret
---
apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
  name: traefik-dashboard
spec:
  entryPoints:
    - websecure
  routes:
    - match: Host(`traefik.example.com`) && (PathPrefix(`/api`) || PathPrefix(`/dashboard`))
      kind: Rule
      services:
        - name: api@internal
          kind: TraefikService
      middlewares:
        - name: dashboard-auth

File-based Dynamic Configuration

Alternatively, define the protection in a dynamic configuration file:

http:
  routers:
    dashboard:
      rule: Host(`traefik.example.com`) && (PathPrefix(`/api`) || PathPrefix(`/dashboard`))
      service: api@internal
      middlewares:
        - auth
        - ipallowlist
  middlewares:
    auth:
      basicAuth:
        users:
          - "admin:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/"
    ipallowlist:
      ipAllowlist:
        sourceRange:
          - "10.0.0.0/8"
          - "192.168.0.0/16"

Helm Values

When deploying via the official Helm chart, configure the dashboard ingress route and middlewares through values:

ingressRoute:
  dashboard:
    enabled: true
    matchRule: Host(`traefik.example.com`)
    entryPoints: ["websecure"]
    middlewares:
      - name: dashboard-auth
extraObjects:
  - apiVersion: v1
    kind: Secret
    metadata:
      name: dashboard-auth-secret
    type: kubernetes.io/basic-auth
    stringData:
      username: admin
      password: super-secret
  - apiVersion: traefik.io/v1alpha1
    kind: Middleware
    metadata:
      name: dashboard-auth
    spec:
      basicAuth:
        secret: dashboard-auth-secret

ForwardAuth Configuration

To delegate authentication to an external identity provider:

http:
  routers:
    dashboard:
      rule: Host(`traefik.example.com`) && (PathPrefix(`/api`) || PathPrefix(`/dashboard`))
      service: api@internal
      middlewares:
        - forward-auth
  middlewares:
    forward-auth:
      forwardAuth:
        address: "https://auth.mycompany.com/verify"
        trustForwardHeader: true
        authResponseHeaders:
          - "X-User"
          - "X-Email"

This configuration references the schema defined in docs/content/middlewares/http/forwardauth.md.

Source Code Reference

The dashboard implementation resides in pkg/api/dashboard/dashboard.go, which defines the HTTP handlers served by api@internal. Configuration parsing for the API settings is handled in the static configuration loader, while middleware logic is implemented in the respective packages. Sample static configurations appear in pkg/config/dynamic/traefik.toml and traefik.sample.toml. The complete middleware specifications are documented in docs/content/middlewares/http/basicauth.md, docs/content/middlewares/http/digestauth.md, and docs/content/middlewares/http/forwardauth.md.

Summary

• Never expose the dashboard publicly without authentication middleware attached to the router serving api@internal.
• Use BasicAuth or DigestAuth for simple password protection, referencing docs/content/middlewares/http/basicauth.md and docs/content/middlewares/http/digestauth.md.
• Implement ForwardAuth to integrate with OAuth2/OIDC providers using the schema in docs/content/middlewares/http/forwardauth.md.
• Layer IPAllowlist middleware from docs/content/middlewares/http/ipallowlist.md to restrict access by network range.
• Disable api.insecure in production environments to prevent unauthorized access via the default entrypoint.

Frequently Asked Questions

What is the difference between BasicAuth and DigestAuth in Traefik?

BasicAuth transmits credentials with each request using Base64 encoding and requires HTTPS to prevent interception, while DigestAuth uses a challenge-response mechanism defined in RFC 7616 that prevents password transmission over the network entirely. DigestAuth is more secure but less widely supported by clients; both are configured similarly in Traefik middleware definitions according to their respective documentation files.

Can I use OAuth2 or OIDC to protect the Traefik dashboard?

Yes, but not directly through native middleware. You must use the ForwardAuth middleware to delegate authentication to an external service such as Keycloak, Authelia, or a custom OAuth2 proxy. As specified in docs/content/middlewares/http/forwardauth.md, Traefik forwards the request to your authentication service, which validates the session and returns appropriate headers.

Why should I avoid enabling api.insecure in production?

The api.insecure option exposes the dashboard and API on the traefik entrypoint without TLS and without requiring authentication middleware, as noted in docs/content/reference/install-configuration/api-dashboard.md. This allows anyone with network access to view and potentially modify your routing configuration. Always disable this flag in production and use TLS-terminated entrypoints with authentication middleware instead.

How do I restrict dashboard access to specific IP addresses only?

Configure the IPAllowlist middleware (documented in docs/content/middlewares/http/ipallowlist.md) with the sourceRange parameter containing allowed CIDR blocks. Attach this middleware alongside or in place of authentication middleware to the dashboard router. For example, allow only private RFC 1918 addresses by specifying 10.0.0.0/8 and 192.168.0.0/16 in the middleware configuration.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}