BasicAuth

Adding Basic Authentication

BasicAuth

The BasicAuth middleware grants access to services to authorized users only.

Configuration Examples

Docker & Swarm

  1. # Declaring the user list
  2. #
  3. # Note: when used in docker-compose.yml all dollar signs in the hash need to be doubled for escaping.
  4. # To create user:password pair, it's possible to use this command:
  5. # echo $(htpasswd -nB user) | sed -e s/\\$/\\$\\$/g
  6. #
  7. # Also note that dollar signs should NOT be doubled when they not evaluated (e.g. Ansible docker_container module).
  8. labels:
  9.   - "traefik.http.middlewares.test-auth.basicauth.users=test:$$apr1$$H6uskkkW$$IgXLP6ewTrSuBkTrqE8wj/,test2:$$apr1$$d9hr9HBB$$4HxwgUir3HP4EsggP/QNo0"

Kubernetes

  1. # Declaring the user list
  2. apiVersion: traefik.io/v1alpha1
  3. kind: Middleware
  4. metadata:
  5.   name: test-auth
  6. spec:
  7.   basicAuth:
  8.     secret: secretName

Consul Catalog

  1. - "traefik.http.middlewares.test-auth.basicauth.users=test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/,test2:$apr1$d9hr9HBB$4HxwgUir3HP4EsggP/QNo0"

File (YAML)

  1. # Declaring the user list
  2. http:
  3.   middlewares:
  4.     test-auth:
  5.       basicAuth:
  6.         users:
  7.           - "test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/"
  8.           - "test2:$apr1$d9hr9HBB$4HxwgUir3HP4EsggP/QNo0"

File (TOML)

  1. # Declaring the user list
  2. [http.middlewares]
  3.   [http.middlewares.test-auth.basicAuth]
  4.   users = [
  5.     "test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/",
  6.     "test2:$apr1$d9hr9HBB$4HxwgUir3HP4EsggP/QNo0",
  7.   ]

Configuration Options

General

Passwords must be hashed using MD5, SHA1, or BCrypt.

Tip

Use htpasswd to generate the passwords.

users

The users option is an array of authorized users. Each user must be declared using the name:hashed-password format.

  • If both users and usersFile are provided, the two are merged. The contents of usersFile have precedence over the values in users.
  • For security reasons, the field users doesn’t exist for Kubernetes IngressRoute, and one should use the secret field instead.

Kubernetes kubernetes.io/basic-auth secret type

Kubernetes supports a special kubernetes.io/basic-auth secret type. This secret must contain two keys: username and password. Please note that these keys are not hashed or encrypted in any way, and therefore is less secure than other methods. You can find more information on the Kubernetes Basic Authentication Secret Documentation

Docker & Swarm

  1. # Declaring the user list
  2. #
  3. # Note: when used in docker-compose.yml all dollar signs in the hash need to be doubled for escaping.
  4. # To create a user:password pair, the following command can be used:
  5. # echo $(htpasswd -nb user password) | sed -e s/\\$/\\$\\$/g
  6. #
  7. # Also note that dollar signs should NOT be doubled when they not evaluated (e.g. Ansible docker_container module).
  8. labels:
  9.   - "traefik.http.middlewares.test-auth.basicauth.users=test:$$apr1$$H6uskkkW$$IgXLP6ewTrSuBkTrqE8wj/,test2:$$apr1$$d9hr9HBB$$4HxwgUir3HP4EsggP/QNo0"

Kubernetes

  1. # Declaring the user list
  2. apiVersion: traefik.io/v1alpha1
  3. kind: Middleware
  4. metadata:
  5.   name: test-auth
  6. spec:
  7.   basicAuth:
  8.     secret: authsecret
  10. ---
  11. # Note: in a kubernetes secret the string (e.g. generated by htpasswd) must be base64-encoded first.
  12. # To create an encoded user:password pair, the following command can be used:
  13. # htpasswd -nb user password | openssl base64
  15. apiVersion: v1
  16. kind: Secret
  17. metadata:
  18.   name: authsecret
  19.   namespace: default
  20. data:
  21.   users: |2
  22.     dGVzdDokYXByMSRINnVza2trVyRJZ1hMUDZld1RyU3VCa1RycUU4d2ovCnRlc3QyOiRhcHIxJGQ5
  23.     aHI5SEJCJDRIeHdnVWlyM0hQNEVzZ2dQL1FObzAK
  25. ---
  26. # This is an alternate auth secret that demonstrates the basic-auth secret type.
  27. # Note: the password is not hashed, and is merely base64 encoded.
  29. apiVersion: v1
  30. kind: Secret
  31. metadata:
  32.   name: authsecret2
  33.   namespace: default
  34. type: kubernetes.io/basic-auth
  35. data:
  36.   username: dXNlcg== # username: user
  37.   password: cGFzc3dvcmQ= # password: password

Consul Catalog

  1. # Declaring the user list
  2. - "traefik.http.middlewares.test-auth.basicauth.users=test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/,test2:$apr1$d9hr9HBB$4HxwgUir3HP4EsggP/QNo0"

File (YAML)

  1. # Declaring the user list
  2. http:
  3.   middlewares:
  4.     test-auth:
  5.       basicAuth:
  6.         users:
  7.           - "test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/"
  8.           - "test2:$apr1$d9hr9HBB$4HxwgUir3HP4EsggP/QNo0"

File (TOML)

  1. # Declaring the user list
  2. [http.middlewares]
  3.   [http.middlewares.test-auth.basicAuth]
  4.     users = [
  5.       "test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/",
  6.       "test2:$apr1$d9hr9HBB$4HxwgUir3HP4EsggP/QNo0",
  7.     ]

usersFile

The usersFile option is the path to an external file that contains the authorized users for the middleware.

The file content is a list of name:hashed-password.

  • If both users and usersFile are provided, the two are merged. The contents of usersFile have precedence over the values in users.
  • Because it does not make much sense to refer to a file path on Kubernetes, the usersFile field doesn’t exist for Kubernetes IngressRoute, and one should use the secret field instead.

Docker & Swarm

  1. labels:
  2.   - "traefik.http.middlewares.test-auth.basicauth.usersfile=/path/to/my/usersfile"

Kubernetes

  1. apiVersion: traefik.io/v1alpha1
  2. kind: Middleware
  3. metadata:
  4.   name: test-auth
  5. spec:
  6.   basicAuth:
  7.     secret: authsecret
  9. ---
  10. apiVersion: v1
  11. kind: Secret
  12. metadata:
  13.   name: authsecret
  14.   namespace: default
  16. data:
  17.   users: |2
  18.     dGVzdDokYXByMSRINnVza2trVyRJZ1hMUDZld1RyU3VCa1RycUU4d2ovCnRlc3QyOiRhcHIxJGQ5
  19.     aHI5SEJCJDRIeHdnVWlyM0hQNEVzZ2dQL1FObzAK

Consul Catalog

  1. - "traefik.http.middlewares.test-auth.basicauth.usersfile=/path/to/my/usersfile"

File (YAML)

  1. http:
  2.   middlewares:
  3.     test-auth:
  4.       basicAuth:
  5.         usersFile: "/path/to/my/usersfile"

File (TOML)

  1. [http.middlewares]
  2.   [http.middlewares.test-auth.basicAuth]
  3.     usersFile = "/path/to/my/usersfile"

A file containing test/test and test2/test2

  1. test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/
  2. test2:$apr1$d9hr9HBB$4HxwgUir3HP4EsggP/QNo0

realm

You can customize the realm for the authentication with the realm option. The default value is traefik.

Docker & Swarm

  1. labels:
  2.   - "traefik.http.middlewares.test-auth.basicauth.realm=MyRealm"

Kubernetes

  1. apiVersion: traefik.io/v1alpha1
  2. kind: Middleware
  3. metadata:
  4.   name: test-auth
  5. spec:
  6.   basicAuth:
  7.     realm: MyRealm

Consul Catalog

  1. - "traefik.http.middlewares.test-auth.basicauth.realm=MyRealm"

File (YAML)

  1. http:
  2.   middlewares:
  3.     test-auth:
  4.       basicAuth:
  5.         realm: "MyRealm"

File (TOML)

  1. [http.middlewares]
  2.   [http.middlewares.test-auth.basicAuth]
  3.     realm = "MyRealm"

headerField

You can define a header field to store the authenticated user using the headerFieldoption.

Docker & Swarm

  1. labels:
  2.   - "traefik.http.middlewares.my-auth.basicauth.headerField=X-WebAuth-User"

Kubernetes

  1. apiVersion: traefik.io/v1alpha1
  2. kind: Middleware
  3. metadata:
  4.   name: my-auth
  5. spec:
  6.   basicAuth:
  7.     # ...
  8.     headerField: X-WebAuth-User

Consul Catalog

  1. - "traefik.http.middlewares.my-auth.basicauth.headerField=X-WebAuth-User"

File (YAML)

  1. http:
  2.   middlewares:
  3.     my-auth:
  4.       basicAuth:
  5.         # ...
  6.         headerField: "X-WebAuth-User"

File (TOML)

  1. [http.middlewares.my-auth.basicAuth]
  2.   # ...
  3.   headerField = "X-WebAuth-User"

removeHeader

Set the removeHeader option to true to remove the authorization header before forwarding the request to your service. (Default value is false.)

Docker & Swarm

  1. labels:
  2.   - "traefik.http.middlewares.test-auth.basicauth.removeheader=true"

Kubernetes

  1. apiVersion: traefik.io/v1alpha1
  2. kind: Middleware
  3. metadata:
  4.   name: test-auth
  5. spec:
  6.   basicAuth:
  7.     removeHeader: true

Consul Catalog

  1. - "traefik.http.middlewares.test-auth.basicauth.removeheader=true"

File (YAML)

  1. http:
  2.   middlewares:
  3.     test-auth:
  4.       basicAuth:
  5.         removeHeader: true

File (TOML)

  1. [http.middlewares]
  2.   [http.middlewares.test-auth.basicAuth]
  3.     removeHeader = true

Using Traefik OSS in Production?

If you are using Traefik at work, consider adding enterprise-grade API gateway capabilities or commercial support for Traefik OSS.

Adding API Gateway capabilities to Traefik OSS is fast and seamless. There’s no rip and replace and all configurations remain intact. See it in action via this short video.