Traefik BasicAuth Documentation - Traefik

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

Configuration Examples

yaml

# Declaring the user list
http:
  middlewares:
    test-auth:
      basicAuth:
        users:
          - "test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/"
          - "test2:$apr1$d9hr9HBB$4HxwgUir3HP4EsggP/QNo0"

toml

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

yaml

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

json

{
  // ...
  "Tags": [
    "traefik.http.middlewares.test-auth.basicauth.users=test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/,test2:$apr1$d9hr9HBB$4HxwgUir3HP4EsggP/QNo0"
  ]
}

yaml

# Declaring the user list
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-auth
spec:
  basicAuth:
    secret: secretName

Configuration Options

Field	Description	Default	Required
<a id="opt-users" href="#opt-users" title="#opt-users">`users`</a>	Array of authorized users. Each user must be declared using the `name:hashed-password` format. (More information here)	""	No
<a id="opt-usersFile" href="#opt-usersFile" title="#opt-usersFile">`usersFile`</a>	Path to an external file that contains the authorized users for the middleware.
The file content is a list of `name:hashed-password`. (More information here)	""	No
<a id="opt-realm" href="#opt-realm" title="#opt-realm">`realm`</a>	Allow customizing the realm for the authentication.	"traefik"	No
<a id="opt-headerField" href="#opt-headerField" title="#opt-headerField">`headerField`</a>	Allow defining a header field to store the authenticated user.	""	No
<a id="opt-removeHeader" href="#opt-removeHeader" title="#opt-removeHeader">`removeHeader`</a>	Allow removing the authorization header before forwarding the request to your service.	false	No

Passwords format

Passwords must be hashed using MD5, SHA1, or BCrypt. Use htpasswd to generate the passwords.

users & usersFile

If both users and usersFile are provided, they are merged. The contents of usersFile have precedence over the values in users.
Because referencing a file path isn’t feasible on Kubernetes, the users & usersFile field isn’t used in Kubernetes IngressRoute. Instead, use the secret field.

Kubernetes Secrets

The option users supports Kubernetes secrets.

!!! note "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](https://kubernetes.io/docs/concepts/configuration/secret/#basic-authentication-secret)

{% include-markdown "includes/traefik-for-business-applications.md" %}