API Key Authentication

API Key Authentication Middleware

The API Key authentication middleware allows you to secure an API by requiring a base64-encoded secret key to be given, via HTTP header, cookie or query parameter.

Middleware Options

secretParam

Required, Default=""

The secretParam option should contain the name of the secret used by the middleware. For example, if the secret is passed via HTTP header, the value of secretParam should be the name of the header in which the secret is given.

Docker

labels:
  - "traefik.http.middlewares.test-apikey.plugin.apiKey.secretParam=mysecret"

Kubernetes

apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-apikey
spec:
  plugin:
    apiKey:
      secretParam: mysecret

Consul Catalog

- "traefik.http.middlewares.test-apikey.plugin.apiKey.secretParam=mysecret"

Marathon

"labels": {
    "traefik.http.middlewares.test-apikey.plugin.apiKey.secretParam": "mysecret"
}

Rancher

labels:
  - "traefik.http.middlewares.test-apikey.plugin.apiKey.secretParam=mysecret"

File (YAML)

http:
  middlewares:
    test-apikey:
      plugin:
        apiKey:
          secretParam: mysecret

File (TOML)

[http.middlewares]
  [http.middlewares.test-apikey.plugin.apiKey]
    secretParam = "mysecret"

secretNonBase64Encoded

Optional, Default=false

The secretNonBase64Encoded option defines whether the secret sent by the client is base64 encoded.

Docker

labels:
  - "traefik.http.middlewares.test-apikey.plugin.apiKey.secretNonBase64Encoded=true"

Kubernetes

apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-apikey
spec:
  plugin:
    apiKey:
      secretNonBase64Encoded: true

Consul Catalog

- "traefik.http.middlewares.test-apikey.plugin.apiKey.secretNonBase64Encoded=true"

Marathon

"labels": {
    "traefik.http.middlewares.test-apikey.plugin.apiKey.secretNonBase64Encoded": "true"
}

Rancher

labels:
  - "traefik.http.middlewares.test-apikey.plugin.apiKey.secretNonBase64Encoded=true"

File (YAML)

http:
  middlewares:
    test-apikey:
      plugin:
        apiKey:
          secretNonBase64Encoded: true

File (TOML)

[http.middlewares]
  [http.middlewares.test-apikey.plugin.apiKey]
    secretNonBase64Encoded = true

secretValues

Required, Default=[]

The secretValues option should contain the hash of the API keys. Supported hashing algorithms are Bcrypt, SHA1 and MD5. The hash should be generated using htpasswd.

Generating hashes using htpasswd

htpasswd -nbB "" mypassword | cut -c 2- # hash "mypassword" using bcrypt
$2y$05$Lw8/QZ2NPfe2W/kcuI3eyOViCwwmRhIt4kzpd7MUxY4r/jLWGlquq

htpasswd -nbs "" mypassword | cut -c 2- # hash "mypassword" using sha1
{SHA}kd/Z3bQZiv/FwZTNjObTOP3kcOI=

htpasswd -nbm "" mypassword | cut -c 2- # hash "mypassword" using md5
$apr1$N9VxTJ9u$hwPGeJyzqvl1p1vwJo4HL1

Sensitive Values from Kubernetes Secrets

When configuring the secretValues, it is possible to reference Kubernetes Secrets The reference to a Kubernetes Secret takes the form of a URN:

urn:k8s:secret:[name]:[valueKey]

apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-apikey
spec:
  plugin:
    apiKey:
      secretValues:
        - urn:k8s:secret:secretName:secretKey
        - urn:k8s:secret:secretName:secretKey

Docker

labels:
  - "traefik.http.middlewares.test-apikey.plugin.apiKey.secretValues=$2y$05$W8revhHpKlbH1UfCzpR0He/dK9mjXZRLjfq5RkYZKU7//EUrWz3lG,$2y$05$Lw8/QZ2NPfe2W/kcuI3eyOViCwwmRhIt4kzpd7MUxY4r/jLWGlquq"

Kubernetes

apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-apikey
spec:
  plugin:
    apiKey:
      secretValues:
        - $2y$05$W8revhHpKlbH1UfCzpR0He/dK9mjXZRLjfq5RkYZKU7//EUrWz3lG
        - $2y$05$Lw8/QZ2NPfe2W/kcuI3eyOViCwwmRhIt4kzpd7MUxY4r/jLWGlquq

Consul Catalog

- "traefik.http.middlewares.test-apikey.plugin.apiKey.secretValues=$2y$05$W8revhHpKlbH1UfCzpR0He/dK9mjXZRLjfq5RkYZKU7//EUrWz3lG,$2y$05$Lw8/QZ2NPfe2W/kcuI3eyOViCwwmRhIt4kzpd7MUxY4r/jLWGlquq"

Marathon

"labels": {
    "traefik.http.middlewares.test-apikey.plugin.apiKey.secretValues": "$2y$05$W8revhHpKlbH1UfCzpR0He/dK9mjXZRLjfq5RkYZKU7//EUrWz3lG,$2y$05$Lw8/QZ2NPfe2W/kcuI3eyOViCwwmRhIt4kzpd7MUxY4r/jLWGlquq"
}

Rancher

labels:
  - "traefik.http.middlewares.test-apikey.plugin.apiKey.secretValues=$2y$05$W8revhHpKlbH1UfCzpR0He/dK9mjXZRLjfq5RkYZKU7//EUrWz3lG,$2y$05$Lw8/QZ2NPfe2W/kcuI3eyOViCwwmRhIt4kzpd7MUxY4r/jLWGlquq"

File (YAML)

http:
  middlewares:
    test-apikey:
      plugin:
        apiKey:
          secretValues: 
            - $2y$05$W8revhHpKlbH1UfCzpR0He/dK9mjXZRLjfq5RkYZKU7//EUrWz3lG
            - $2y$05$Lw8/QZ2NPfe2W/kcuI3eyOViCwwmRhIt4kzpd7MUxY4r/jLWGlquq

File (TOML)

[http.middlewares]
  [http.middlewares.test-apikey.plugin.apiKey]
    secretValue = ["$2y$05$W8revhHpKlbH1UfCzpR0He/dK9mjXZRLjfq5RkYZKU7//EUrWz3lG","$2y$05$Lw8/QZ2NPfe2W/kcuI3eyOViCwwmRhIt4kzpd7MUxY4r/jLWGlquq"]

kind

Optional, Default=""

The kind option can be given to explicitly declare how the secret should be given. Its values can be cookie, queryparam or header. If no value is specified for kind, the API key middleware looks for a secret in all 3 possible places, and if more than one is found, it considers the request to be bad.

Docker

labels:
  - "traefik.http.middlewares.test-apikey.plugin.apiKey.kind=queryparam"

Kubernetes

apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-apikey
spec:
  plugin:
    apiKey:
      kind: queryparam

Consul Catalog

- "traefik.http.middlewares.test-apikey.plugin.apiKey.kind=queryparam"

Marathon

"labels": {
    "traefik.http.middlewares.test-apikey.plugin.apiKey.kind": "queryparam"
}

Rancher

labels:
  - "traefik.http.middlewares.test-apikey.plugin.apiKey.kind=queryparam"

File (YAML)

http:
  middlewares:
    test-apikey:
      plugin:
        apiKey:
          kind: queryparam

File (TOML)

[http.middlewares]
  [http.middlewares.test-apikey.plugin.apiKey]
    kind = "queryparam"

secretValue (deprecaded)

Deprecated, Default=""

The secretValue option should contain a hash of the API key. Supported hashing algorithms are Bcrypt, SHA1 and MD5. The hash should be generated using htpasswd.

Deprecated

This option is deprecated, please use secretValues instead.

Generating hashes using htpasswd

htpasswd -nbB "" mypassword | cut -c 2- # hash "mypassword" using bcrypt
$2y$05$Lw8/QZ2NPfe2W/kcuI3eyOViCwwmRhIt4kzpd7MUxY4r/jLWGlquq

htpasswd -nbs "" mypassword | cut -c 2- # hash "mypassword" using sha1
{SHA}kd/Z3bQZiv/FwZTNjObTOP3kcOI=

htpasswd -nbm "" mypassword | cut -c 2- # hash "mypassword" using md5
$apr1$N9VxTJ9u$hwPGeJyzqvl1p1vwJo4HL1

Sensitive Values from Kubernetes Secrets

When configuring the secretValue, it is possible to reference Kubernetes Secrets The reference to a Kubernetes Secret takes the form of a URN:

urn:k8s:secret:[name]:[valueKey]

apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-apikey
spec:
  plugin:
    apiKey:
      secretValue: "urn:k8s:secret:secretName:secretKey"

Docker

labels:
  - "traefik.http.middlewares.test-apikey.plugin.apiKey.secretValue=$2y$05$W8revhHpKlbH1UfCzpR0He/dK9mjXZRLjfq5RkYZKU7//EUrWz3lG"

Kubernetes

apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-apikey
spec:
  plugin:
    apiKey:
      secretValue: $2y$05$W8revhHpKlbH1UfCzpR0He/dK9mjXZRLjfq5RkYZKU7//EUrWz3lG

Consul Catalog

- "traefik.http.middlewares.test-apikey.plugin.apiKey.secretValue=$2y$05$W8revhHpKlbH1UfCzpR0He/dK9mjXZRLjfq5RkYZKU7//EUrWz3lG"

Marathon

"labels": {
    "traefik.http.middlewares.test-apikey.plugin.apiKey.secretValue": "$2y$05$W8revhHpKlbH1UfCzpR0He/dK9mjXZRLjfq5RkYZKU7//EUrWz3lG"
}

Rancher

labels:
  - "traefik.http.middlewares.test-apikey.plugin.apiKey.secretValue=$2y$05$W8revhHpKlbH1UfCzpR0He/dK9mjXZRLjfq5RkYZKU7//EUrWz3lG"

File (YAML)

http:
  middlewares:
    test-apikey:
      plugin:
        apiKey:
          secretValue: $2y$05$W8revhHpKlbH1UfCzpR0He/dK9mjXZRLjfq5RkYZKU7//EUrWz3lG

File (TOML)

[http.middlewares]
  [http.middlewares.test-apikey.plugin.apiKey]
    secretValue = "$2y$05$W8revhHpKlbH1UfCzpR0He/dK9mjXZRLjfq5RkYZKU7//EUrWz3lG"

Advanced Configuration Example

Below is an advanced configuration example:

Docker

labels:
  - "traefik.http.middlewares.test-apikey.plugin.apiKey.secretParam=mysecretheader"
  - "traefik.http.middlewares.test-apikey.plugin.apiKey.secretValue=$2y$05$W8revhHpKlbH1UfCzpR0He/dK9mjXZRLjfq5RkYZKU7//EUrWz3lG"
  - "traefik.http.middlewares.test-apikey.plugin.apiKey.kind=header"

Kubernetes

apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-apikey
spec:
  plugin:
    apiKey:
      secretParam: mysecretheader
      secretValue: $2y$05$W8revhHpKlbH1UfCzpR0He/dK9mjXZRLjfq5RkYZKU7//EUrWz3lG
      kind: header

Consul Catalog

- "traefik.http.middlewares.test-apikey.plugin.apiKey.secretParam=mysecretheader"
- "traefik.http.middlewares.test-apikey.plugin.apiKey.secretValue=$2y$05$W8revhHpKlbH1UfCzpR0He/dK9mjXZRLjfq5RkYZKU7//EUrWz3lG"
- "traefik.http.middlewares.test-apikey.plugin.apiKey.kind=header"

Marathon

"labels": {
    "traefik.http.middlewares.test-apikey.plugin.apiKey.secretParam": "mysecretheader",
    "traefik.http.middlewares.test-apikey.plugin.apiKey.secretValue": "$2y$05$W8revhHpKlbH1UfCzpR0He/dK9mjXZRLjfq5RkYZKU7//EUrWz3lG",
    "traefik.http.middlewares.test-apikey.plugin.apiKey.kind": "header",
}

Rancher

labels:
  - "traefik.http.middlewares.test-apikey.plugin.apiKey.secretParam=mysecretheader"
  - "traefik.http.middlewares.test-apikey.plugin.apiKey.secretValue=$2y$05$W8revhHpKlbH1UfCzpR0He/dK9mjXZRLjfq5RkYZKU7//EUrWz3lG"
  - "traefik.http.middlewares.test-apikey.plugin.apiKey.kind=header"

File (YAML)

http:
  middlewares:
    test-apikey:
      plugin:
        apiKey:
          secretParam: mysecretheader
          secretValue: $2y$05$W8revhHpKlbH1UfCzpR0He/dK9mjXZRLjfq5RkYZKU7//EUrWz3lG
          kind: header

File (TOML)

[http.middlewares]
  [http.middlewares.test-apikey.plugin.apiKey]
    secretParam = "mysecretheader"
    secretValue = "$2y$05$W8revhHpKlbH1UfCzpR0He/dK9mjXZRLjfq5RkYZKU7//EUrWz3lG"
    kind = "header"