Skip to main content

JWT Authentication

The JWT middleware verifies that a valid JWT token is provided in the Authorization header (Authorization: Bearer <JWT>). If the token can't be passed as an Authorization header, it can be given as form data or as a query parameter. See the tokenKey option for more information.

With no specific configuration, a JWT middleware only validates the signature of a JWT and checks the nbf, exp and iat standard claims (if they are present).
Custom claim validation can be configured with Custom Claims Validation.

Configuration Options​

warning

At least one of signingSecret, publicKey, jwksFile or jwksUrl options must be set.

signingSecret​

FieldDescriptionDefaultRequired
signingSecretDefines the secret used for signing the JWT certificates.
It is then used by the middleware to verify incoming requests.

At least one of signingSecret, publicKey, jwksFile or jwksUrl options must be set.		""No
Storing secret values in Kubernetes secrets

When configuring the signingSecret, it is possible to reference a Kubernetes secret defined in the same namespace as the Middleware. The reference to a Kubernetes secret takes the form of a URN:

urn:k8s:secret:[name]:[valueKey]
Referencing the Kubernetes secret
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-jwt
spec:
  plugin:
    jwt:
      signingSecret: urn:k8s:secret:my-secret:signingSecret

signingSecretBase64Encoded​

FieldDescriptionDefaultRequired
signingSecretBase64EncodedDefines whether the signingSecret is base64-encoded.
If set to true, the signingSecret is base64-decoded before being used.		falseNo
Defining that the signing secret is base64 encoded
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
    name: test-jwt
spec:
  plugin:
    jwt:
      signingSecret: c3VwZXItc2VjcmV0Cg==
      signingSecretBase64Encoded: true

publicKey​

FieldDescriptionDefaultRequired
publicKeyDefines the public key used to verify secret signature in incoming requests.
In that case, users should sign their token using a private key corresponding to the configured public key.

At least one of signingSecret, publicKey, jwksFile or jwksUrl options must be set.		""No
Defining the public key used to verify the signature
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
    name: test-jwt
spec:
  plugin:
    jwt:
      publicKey: |-
        -----BEGIN PUBLIC KEY-----
        MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAnzyis1ZjfNB0bBgKFMSv
        vkTtwlvBsaJq7S5wA+kzeVOVpVWwkWdVha4s38XM/pa/yr47av7+z3VTmvDRyAHc
        aT92whREFpLv9cj5lTeJSibyr/Mrm/YtjCZVWgaOYIhwrXwKLqPr/11inWsAkfIy
        tvHWTxZYEcXLgAXFuUuaS3uF9gEiNQwzGTU1v0FqkqTBr4B8nW3HCN47XUu0t8Y0
        e+lf4s4OxQawWD79J9/5d3Ry0vbV3Am1FtGJiJvOwRsIfVChDpYStTcHTCMqtvWb
        V6L11BWkpzGXSW4Hv43qa+GSYOD2QU68Mb59oSk2OB+BtOLpJofmbGEGgvmwyCI9
        MwIDAQAB
        -----END PUBLIC KEY-----

jwksFile​

FieldDescriptionDefaultRequired
jwksFileDefines a set of JWK to be used to verify the signature of JWTs.
More information on JWK can be found in the reference documentation.
The option can either be a path to a file mounted on the API Gateway or directly the content of a JWK set file.

At least one of signingSecret, publicKey, jwksFile or jwksUrl options must be set.		""No
JWT Header Key ID

If the JWT header contains a kid header, the middleware expects to find a JWK. If a JWK cannot be found, it returns a 401 Unauthorized error.

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
    name: test-jwt
spec:
  plugin:
    jwt:
      jwksFile: |-
        {
          "keys": [
            {
              "use": "sig",
              "kty": "EC",
              "kid": "key-id",
              "crv": "P-256",
              "alg": "ES256",
              "x": "EVs_o5-uQbTjL3chynL4wXgUg2R9q9UU8I5mEovUf84",
              "y": "kGe5DgSIycKp8w9aJmoHhB1sB3QTugfnRWm5nU_TzsY"
            }
          ]
        }

jwksUrl​

FieldDescriptionDefaultRequired
jwksUrlDefines the URL of the host serving a JWK set. More information on JWK can be found in the reference.

At least one of signingSecret, publicKey, jwksFile or jwksUrl options must be set.		""No

The keys are cached if the HTTP Cache Control allows for caching.

This option can either be set to a full URL (e.g.: https://www.googleapis.com/oauth2/v3/certs) or to a path (e.g.: /oauth2/v3/certs). In the first case, the middleware fetches the keys located at the URL to verify the token.
In the second case, the middleware builds the full URL using the iss property found in the JWT claims. It does so by concatenating the host defined by iss and the path set by jwksURL.

JWT Header Key ID

If the JWT header contains a kid header, the middleware expects to find a JWK. If a JWK cannot be found, it returns a 401 Unauthorized error.

JWT Issuer Claim

If jwksUrl is set to a path and the iss property is missing in the JWT it's trying to verify, the middleware returns a 401 Unauthorized error.

Defining the JWKS URL
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
    name: test-jwt
spec:
  plugin:
    jwt:
      jwksUrl: https://www.googleapis.com/oauth2/v3/certs

forwardAuthorization​

FieldDescriptionDefaultRequired
forwardAuthorizationDefines whether the authorization header will be forwarded or stripped from a request after it has been approved by the middleware.falseNo
Forwarding the authorization header
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-jwt
spec:
  plugin:
    jwt:
      forwardAuthorization: true

forwardHeaders​

FieldDescriptionDefaultRequired
forwardHeadersDefines the HTTP headers to add to requests and populates them with values extracted from the access token claims returned by the authorization server.[]No
note

Claims to be forwarded that are not found in the JWT result in empty headers.

note

The forwardHeaders option can only be used with JWT-formatted token.

Forwarding the grp and exp claims as HTTP headers
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-jwt
spec:
  plugin:
    jwt:
      forwardHeaders:
        Group: grp
        Expires-At: exp

tokenKey​

FieldDescriptionDefaultRequired
tokenKeyDefines the name of the query and form data parameter used for passing the JWT, for applications that can't pass it in the Authorization header.
The middleware always looks in the Authorization header first, even with this option enabled.		""No
RFC Recommendations

This option should only be enabled if the JWT cannot be passed as an Authorization header, as it is not recommended by the RFC.

Defining the name of the query or form data parameter
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-jwt
spec:
  plugin:
    jwt:
      tokenKey: access_token

claims​

FieldDescriptionDefaultRequired
claimsDefines the claims to validate in order to authorize the request.""No
note

The claims option can only be used with JWT-formatted token.

Validating that clients are in the admin group
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-jwt
spec:
  plugin:
    jwt:
      claims: Equals(`grp`, `admin`)

Syntax​

The following functions are supported in claims:

FunctionDescriptionExample
EqualsValidates the equality of the value in key with value.Equals(`grp`, `admin`)
PrefixValidates the value in key has the prefix of value.Prefix(`referrer`, `http://example.com\`)
Contains (string)Validates the value in key contains value.Contains(`referrer`, `/foo/`)
Contains (array)Validates the key array contains the value.Contains(`areas`, `home`)
SplitContainsValidates the value in key contains the value once split by the separator.SplitContains(`scope`, ` `, `writer`)
OneOfValidates the key array contains one of the values.OneOf(`areas`, `office`, `lab`)

All functions can be joined by boolean operands. The supported operands are:

OperandDescriptionExample
&&Compares two functions and returns true only if both evaluate to true.Equals(`grp`, `admin`) && Equals(`active`, `true`)
||Compares two functions and returns true if either evaluate to true.Equals(`grp`, `admin`) || Equals(`active`, `true`)
!Returns false if the function is true, otherwise returns true.!Equals(`grp`, `testers`)

All examples will return true for the following data structure:

JSON
{
  "active": true,
  "grp": "admin",
  "scope": "reader writer deploy",
  "referrer": "http://example.com/foo/bar",
  "areas": [
    "office",
    "home"
  ]
}

Nested Claims​

Nested claims are supported by using a . between keys. For example:

Key
user.name
Claims
{
  "active": true,
  "grp": "admin",
  "scope": "reader writer deploy",
  "referrer": "http://example.com/foo/bar",
  "areas": [
    "office",
    "home"
  ],
  "user" {
    "name": "John Snow",
    "status": "undead"
  }
}
Result
John Snow
Handling keys that contain a '.'

If the key contains a dot, the dot can be escaped using \.

Handling a key that contains a ''

If the key contains a \, it needs to be doubled \\.

usernameClaim​

FieldDescriptionDefaultRequired
usernameClaimDefines the claim that will be evaluated to populate the clientusername in the access logs.""No
note

The usernameClaim option can only be used with JWT-formatted token.

Defining the claim used to log the clientusername
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-jwt
spec:
  plugin:
    jwt:
      usernameClaim: userId

clientConfig​

Defines the configuration used to connect the API Gateway to a Third Party Software such as an Identity Provider.

clientConfig.tls​

The table below lists the configuration options in Traefik Hub to define a TLS connection.

ValueDescriptionRequired
clientConfig.tls.caPEM-encoded certificate bundle or a URN referencing a secret containing the certificate bundle used to establish a TLS connection with the authorization serverNo
clientConfig.tls.certPEM-encoded certificate or a URN referencing a secret containing the certificate used to establish a TLS connection with the Vault serverNo
clientConfig.tls.keyPEM-encoded key or a URN referencing a secret containing the key used to establish a TLS connection with the Vault server.No
clientConfig.tls.insecureSkipVerifyDisables TLS certificate verification when communicating with the authorization server.
Useful for testing purposes but strongly discouraged for production.		No
Storing secret values in Kubernetes secrets

When configuring the tls.ca, tls.cert, tls.key, it is possible to reference Kubernetes secrets defined in the same namespace as the Middleware.
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-jwt
spec:
  plugin:
    jwt:
      clientConfig:
        tls:
          ca: "urn:k8s:secret:tls:ca"
          cert: "urn:k8s:secret:tls:cert"
          key: "urn:k8s:secret:tls:key"
          insecureSkipVerify: true

clientConfig.timeoutSeconds​

FieldDescriptionDefaultRequired
clientConfig.timeoutSecondsDefines the time before giving up requests to the authorization server.5No
Increasing the timeout
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-jwt
spec:
  plugin:
    jwt:
      clientConfig:
        timeoutSeconds: 15

clientConfig.maxRetries​

FieldDescriptionDefaultRequired
clientConfig.maxRetriesDefines the number of retries for requests to authorization server that fail.3No
Increasing the maximum number of retries
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-jwt
spec:
  plugin:
    jwt:
      clientConfig:
        maxRetries: 5

Advanced Configuration Example​

Below is an advanced configuration example using custom claims validation and forward headers:

Validating claims and forwarding headers
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-jwt
spec:
  plugin:
    jwt:
      signingSecret: my-secret
      forwardHeaders:
        Group: grp
        Expires-At: exp
      claims: Equals(`grp`, `admin`)