BasicAuth

The BasicAuth middleware is a quick way to restrict access to your services to known users.

Docker

Kubernetes

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

Consul Catalog

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

Marathon

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

Rancher

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

File (TOML)

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

File (YAML)

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

Configuration Options

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 will 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.

Docker

# Declaring the user list
#
# Note: all dollar signs in the hash need to be doubled for escaping.
# To create a user:password pair, the following command can be used:
# echo $(htpasswd -nb user password) | sed -e s/\\$/\\$\\$/g
labels:
  - "traefik.http.middlewares.test-auth.basicauth.users=test:$$apr1$$H6uskkkW$$IgXLP6ewTrSuBkTrqE8wj/,test2:$$apr1$$d9hr9HBB$$4HxwgUir3HP4EsggP/QNo0"

Kubernetes

# Declaring the user list
apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-auth
spec:
  basicAuth:
    secret: authsecret
---
# Note: in a kubernetes secret the string (e.g. generated by htpasswd) must be base64-encoded first.
# To create an encoded user:password pair, the following command can be used:
# htpasswd -nb user password | openssl base64
apiVersion: v1
kind: Secret
metadata:
  namespace: default
  users: |2
    dGVzdDokYXByMSRINnVza2trVyRJZ1hMUDZld1RyU3VCa1RycUU4d2ovCnRlc3QyOiRhcHIxJGQ5
    aHI5SEJCJDRIeHdnVWlyM0hQNEVzZ2dQL1FObzAK

Consul Catalog

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

Marathon

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

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

File (TOML)

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

File (YAML)

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

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

Kubernetes

apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-auth
spec:
  basicAuth:
    secret: authsecret
---
apiVersion: v1
kind: Secret
metadata:
  name: authsecret
  namespace: default
data:
  users: |2
    dGVzdDokYXByMSRINnVza2trVyRJZ1hMUDZld1RyU3VCa1RycUU4d2ovCnRlc3QyOiRhcHIxJGQ5
    aHI5SEJCJDRIeHdnVWlyM0hQNEVzZ2dQL1FObzAK

Consul Catalog

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

Marathon

"labels": {
  "traefik.http.middlewares.test-auth.basicauth.usersfile": "/path/to/my/usersfile"
}

Rancher

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

File (TOML)

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

File (YAML)

http:
  middlewares:
    test-auth:
      basicAuth:
        usersFile: "/path/to/my/usersfile"

A file containing test/test and test2/test2

test2:$apr1$d9hr9HBB$4HxwgUir3HP4EsggP/QNo0

realm

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

Docker

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

Kubernetes

apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-auth
spec:
  basicAuth:
    realm: MyRealm

Consul Catalog

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

Marathon

"labels": {
  "traefik.http.middlewares.test-auth.basicauth.realm": "MyRealm"
}

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

File (TOML)

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

File (YAML)

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

Docker

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

Kubernetes

apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: my-auth
spec:
  basicAuth:
    # ...
    headerField: X-WebAuth-User

Consul Catalog

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

Marathon

"labels": {
  "traefik.http.middlewares.my-auth.basicauth.headerField": "X-WebAuth-User"
}

File (TOML)

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

File (YAML)

http:
  middlewares:
    my-auth:
      basicAuth:
        # ...
        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

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

Kubernetes

apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-auth
spec:
  basicAuth:
    removeHeader: true

Consul Catalog

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

Marathon

"labels": {
  "traefik.http.middlewares.test-auth.basicauth.removeheader": "true"
}

Rancher

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

File (TOML)

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

File (YAML)

http:
  middlewares:
    test-auth:
      basicAuth: