Skip to content

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.

labels:
  - "traefik.http.middlewares.test-apikey.plugin.apiKey.secretParam=mysecret"
apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-apikey
spec:
  plugin:
    apiKey:
      secretParam: mysecret
- "traefik.http.middlewares.test-apikey.plugin.apiKey.secretParam=mysecret"
"labels": {
    "traefik.http.middlewares.test-apikey.plugin.apiKey.secretParam": "mysecret"
}
labels:
  - "traefik.http.middlewares.test-apikey.plugin.apiKey.secretParam=mysecret"
http:
  middlewares:
    test-apikey:
      plugin:
        apiKey:
          secretParam: mysecret
[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.

labels:
  - "traefik.http.middlewares.test-apikey.plugin.apiKey.secretNonBase64Encoded=true"
apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-apikey
spec:
  plugin:
    apiKey:
      secretNonBase64Encoded: true
- "traefik.http.middlewares.test-apikey.plugin.apiKey.secretNonBase64Encoded=true"
"labels": {
    "traefik.http.middlewares.test-apikey.plugin.apiKey.secretNonBase64Encoded": "true"
}
labels:
  - "traefik.http.middlewares.test-apikey.plugin.apiKey.secretNonBase64Encoded=true"
http:
  middlewares:
    test-apikey:
      plugin:
        apiKey:
          secretNonBase64Encoded: true
[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
labels:
  - "traefik.http.middlewares.test-apikey.plugin.apiKey.secretValues=$2y$05$W8revhHpKlbH1UfCzpR0He/dK9mjXZRLjfq5RkYZKU7//EUrWz3lG,$2y$05$Lw8/QZ2NPfe2W/kcuI3eyOViCwwmRhIt4kzpd7MUxY4r/jLWGlquq"
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
- "traefik.http.middlewares.test-apikey.plugin.apiKey.secretValues=$2y$05$W8revhHpKlbH1UfCzpR0He/dK9mjXZRLjfq5RkYZKU7//EUrWz3lG,$2y$05$Lw8/QZ2NPfe2W/kcuI3eyOViCwwmRhIt4kzpd7MUxY4r/jLWGlquq"
"labels": {
    "traefik.http.middlewares.test-apikey.plugin.apiKey.secretValues": "$2y$05$W8revhHpKlbH1UfCzpR0He/dK9mjXZRLjfq5RkYZKU7//EUrWz3lG,$2y$05$Lw8/QZ2NPfe2W/kcuI3eyOViCwwmRhIt4kzpd7MUxY4r/jLWGlquq"
}
labels:
  - "traefik.http.middlewares.test-apikey.plugin.apiKey.secretValues=$2y$05$W8revhHpKlbH1UfCzpR0He/dK9mjXZRLjfq5RkYZKU7//EUrWz3lG,$2y$05$Lw8/QZ2NPfe2W/kcuI3eyOViCwwmRhIt4kzpd7MUxY4r/jLWGlquq"
http:
  middlewares:
    test-apikey:
      plugin:
        apiKey:
          secretValues: 
            - $2y$05$W8revhHpKlbH1UfCzpR0He/dK9mjXZRLjfq5RkYZKU7//EUrWz3lG
            - $2y$05$Lw8/QZ2NPfe2W/kcuI3eyOViCwwmRhIt4kzpd7MUxY4r/jLWGlquq
[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.

labels:
  - "traefik.http.middlewares.test-apikey.plugin.apiKey.kind=queryparam"
apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-apikey
spec:
  plugin:
    apiKey:
      kind: queryparam
- "traefik.http.middlewares.test-apikey.plugin.apiKey.kind=queryparam"
"labels": {
    "traefik.http.middlewares.test-apikey.plugin.apiKey.kind": "queryparam"
}
labels:
  - "traefik.http.middlewares.test-apikey.plugin.apiKey.kind=queryparam"
http:
  middlewares:
    test-apikey:
      plugin:
        apiKey:
          kind: queryparam
[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"
labels:
  - "traefik.http.middlewares.test-apikey.plugin.apiKey.secretValue=$2y$05$W8revhHpKlbH1UfCzpR0He/dK9mjXZRLjfq5RkYZKU7//EUrWz3lG"
apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-apikey
spec:
  plugin:
    apiKey:
      secretValue: $2y$05$W8revhHpKlbH1UfCzpR0He/dK9mjXZRLjfq5RkYZKU7//EUrWz3lG
- "traefik.http.middlewares.test-apikey.plugin.apiKey.secretValue=$2y$05$W8revhHpKlbH1UfCzpR0He/dK9mjXZRLjfq5RkYZKU7//EUrWz3lG"
"labels": {
    "traefik.http.middlewares.test-apikey.plugin.apiKey.secretValue": "$2y$05$W8revhHpKlbH1UfCzpR0He/dK9mjXZRLjfq5RkYZKU7//EUrWz3lG"
}
labels:
  - "traefik.http.middlewares.test-apikey.plugin.apiKey.secretValue=$2y$05$W8revhHpKlbH1UfCzpR0He/dK9mjXZRLjfq5RkYZKU7//EUrWz3lG"
http:
  middlewares:
    test-apikey:
      plugin:
        apiKey:
          secretValue: $2y$05$W8revhHpKlbH1UfCzpR0He/dK9mjXZRLjfq5RkYZKU7//EUrWz3lG
[http.middlewares]
  [http.middlewares.test-apikey.plugin.apiKey]
    secretValue = "$2y$05$W8revhHpKlbH1UfCzpR0He/dK9mjXZRLjfq5RkYZKU7//EUrWz3lG"

Advanced Configuration Example

Below is an advanced configuration example:

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"
apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-apikey
spec:
  plugin:
    apiKey:
      secretParam: mysecretheader
      secretValue: $2y$05$W8revhHpKlbH1UfCzpR0He/dK9mjXZRLjfq5RkYZKU7//EUrWz3lG
      kind: header
- "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"
"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",
}
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"
http:
  middlewares:
    test-apikey:
      plugin:
        apiKey:
          secretParam: mysecretheader
          secretValue: $2y$05$W8revhHpKlbH1UfCzpR0He/dK9mjXZRLjfq5RkYZKU7//EUrWz3lG
          kind: header
[http.middlewares]
  [http.middlewares.test-apikey.plugin.apiKey]
    secretParam = "mysecretheader"
    secretValue = "$2y$05$W8revhHpKlbH1UfCzpR0He/dK9mjXZRLjfq5RkYZKU7//EUrWz3lG"
    kind = "header"