API Key Authentication

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

---

Configuration Options

keySource

This option defines how the client secret should be given.

note

At least one of the following options have to be defined.

Field	Description	Default	Required
keySource.header	Defines the header name containing the secret sent by the client.	""	No
keySource.headerAuthScheme	Defines the scheme when using Authorization as header name. Check out the Authorization header documentation.	""	No
keySource.query	Defines the query parameter name containing the secret sent by the client.	""	No
keySource.cookie	Defines the cookie name containing the secret sent by the client.	""	No

Requiring the secret to be passed as a Bearer token

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-apikey
spec:
  plugin:
    apiKey:
      keySource:
        header: Authorization
        headerAuthScheme: Bearer

secretNonBase64Encoded

Field	Description	Default	Required
secretNonBase64Encoded	Defines whether the secret sent by the client is base64 encoded.	false	No

Disabling base64 encoding of secret

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

secretValues

Field	Description	Default	Required
secretValues	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.	[]	Yes

Storing secret values in 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.io/v1alpha1
kind: Middleware
metadata:
  name: test-apikey
spec:
  plugin:
    apiKey:
      secretValues:
        - urn:k8s:secret:secretName:secretKey
        - urn:k8s:secret:secretName:secretKey

Generating hashes using htpasswd.

bcrypt

Using bcrypt

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

sha1

Using sha1

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

md5

Using md5

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

Defining the hash values

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