jwt_middleware

Dynamic JWT Validation Middleware

This is a middleware plugin for Traefik with the following features:

• Validation of JSON Web Tokens in cookies, headers, and/or query string parameters for access control.
• Dynamic lookup of public keys from the well-known OpenID configuration/jwks of whitelisted issuers.
• Flexible claim checks, including optional wildcards and Go template interpolation.
• Configurable HTTP redirects for unauthorized and forbidden calls for interactive requests.
• gRPC compatibility.

Configuration

Add

1a. Add the plugin to traefik, either in your static traefik config file:

experimental:
  plugins:
    jwt:
      moduleName: github.com/agilezebra/jwt-middleware
      version: v1.4.3

1b. or with command-line options:

command:
  ...
  - "--experimental.plugins.jwt.modulename=github.com/agilezebra/jwt-middleware"
  - "--experimental.plugins.jwt.version=v1.4.3"

Configure

2a. Configure and activate the plugin as a middleware, either in your dynamic traefik config:

http:
  middlewares:
    secure-api:
      plugin:
        jwt:
          issuers:
            - https://auth.example.com
          require:
            aud: test.example.com

2b. or via Traefik's Kubernetes Middleware CRD:

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: secure-api
spec:
  plugin:
    jwt:
      issuers:
        - https://auth.example.com
      require:
        aud: test.example.com

Notes:

• If you use the Kubernetes Middleware CRD, you should not use the @file suffix in the middleware references below.
• A drawback of using the Kubernetes Middleware CRD is that you cannot use YAML aliases and anchors to keep shared config DRY across middleware definitions, as shown in the example below.

Use

3a. Use the middleware in services via docker compose labels

  labels:
    - "traefik.http.routers.my-service.middlewares=secure-api@file"

3b. or via Kubernetes Ingress annotations

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: my-service
  annotations:
    traefik.ingress.kubernetes.io/router.middlewares: secure-api@file
...

3c. or via Traefik's Kubernetes IngressRoute CRD

apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
  name: my-service
spec:
  routes:
  - middlewares:
    - name: secure-api@file
    ...

Options

The plugin supports the following configuration options.

Template Interpolation

The following per-request variables and functions are available for Go template interpolation:

These variables are useful with dynamic claim requirements, particularly in multitenancy scenarios. However, if interpolating Host as a requirement, care must be taken to ensure that the service can only be reached through that hostname and not directly by some public IP. I.e. routing should be well-controlled, such as behind an API gateway, proxy or other ingress selecting on Host, or where all traefik rules are guaranteed to match using Host. Otherwise, it would be easy to spoof a different Host by fabricating a DNS record for that IP externally; a static requirement should be used instead in such an architecture.

Additionally, all environment variables are accessible with template interpolation, which makes programmatically setting a static value in the traefik dynamic config file easier. Note that the per-request variables will overwrite traefik's view of an environment variable with the same name, so any shadowed environment variables need to be renamed appropriately.

Claim Matching

The following config snippet / JWT example pairs illustrate requirements and claims that satisfy them:

Simple

require:
  aud: "customer.example.com"

{
  "iss": "auth.example.com",
  "aud": "customer.example.com"
}

Dynamic Requirement

E.g. for requiring that a token's audience matches the domain being accessed (see notes in Template Interpolation above for caution on how and when this is safe to use dynamically like this)

Will succeed when called on https://customer.example.com/example but fail on https://other.example.com/example Note that it is necessary to escape the Go template to prevent traefik from attempting to interpret it.

require:
  aud: "{{`{{.Host}}`}}"

{
  "iss": "auth.example.com",
  "aud": "customer.example.com"
}

Wildcard Claim

require:
  aud: "customer.example.com"

{
  "iss": "auth.example.com",
  "aud": "*.example.com"
}

Note that the wildcard claim is granted to the user in their JWT, not asked for in the requirements. I.e. you are granting a key that can open multiple locks rather than creating a lock that accepts multiple keys. If you don't want to support these optional wildcards, simply do not issue such JWTs.

Custom Nested Claims

require:
  authority:
    app1.example.com: ["admin", "superuser"]

{
  "iss": "auth.example.com",
  "authority": {
    "app1.example.com": ["user", "admin"],
    "app2.example.com": ["user"]
  }
}

And logic

require:
  role:
    $and: ["hr", "power"] # both are required

Note that, similar to MongoDB, the $and and $or operators are a single-value object with operator as the key and the choices as an array value.

{
  "role": ["hr", "power"],
}

Complex nested logic

require:
  role:
    $or:
      - $and: ["hr", "power"] # both are required
      - "admin" # this alone will pass

Note that mixing yaml array styles here is arbitrary and both are used to enhance clarity of the structure.

{
  "role": ["hr", "power"],
}

{
  "role": ["admin"],
}

Algorithm Confusion Protection

The plugin is protected against JWT Algorithm Confusion attacks, where an attacker attempts to use an asymmetric public key (RSA/EC) as a symmetric HMAC secret. The protection is inherent in how the plugin stores and uses keys:

1. Strongly Typed Keys: When a public key is configured (via secrets or fetched from an issuer's JWKS), it is parsed into its appropriate Go type (*rsa.PublicKey or *ecdsa.PublicKey), not stored as raw bytes.

2. Type-Safe Verification: When the JWT library verifies a token signature, it receives the key in its typed form. If a token specifies alg: HS256 (HMAC) but the key retrieved is an RSA public key, the JWT library will reject it with key is of invalid type: HMAC verify expects []byte because it cannot use an RSA key structure as an HMAC secret.

Using validMethods for Additional Protection

While the plugin is inherently protected against algorithm confusion due to strong typing, you can use the validMethods configuration option to explicitly limit which algorithms are acceptable. This is a defense-in-depth measure that is particularly useful when:

• You only use RSA or EC signatures from trusted issuers and want to reject all HMAC tokens
• You want to ensure only specific algorithms (e.g., only ES384) are used

Examples

Only accept RSA signatures from issuers (rejecting all HMAC tokens etc):

http:
  middlewares:
    secure-api:
      plugin:
        jwt:
          issuers:
            - https://auth.example.com
          validMethods:
            - RS256
            - RS384
            - RS512
          require:
            aud: test.example.com

Interactive webserver with redirection to login and error pages

http:
  middlewares:
    secure-web:
      plugin:
        jwt:
          issuers:
            - https://auth.example.com
          require:
            aud: test.example.com
          redirectUnauthorized: "https://example.com/login?return_to={{`{{URLQueryEscape .URL}}`}}"
          redirectForbidden: "https://example.com/unauthorized"

Configuring API and interactive endpoints together effectively

http:
  middlewares:
    secure-api:
      plugin:
        jwt:
          &secure-api
          issuers:
            - https://auth.example.com
          require:
            aud: test.example.com

    secure-web:
      plugin:
        jwt:
          <<: *secure-api
          redirectUnauthorized: "https://example.com/login?return_to={{`{{URLQueryEscape .URL}}`}}"
          redirectForbidden: "https://example.com/unauthorized"

Specifying a fixed ECDSA public key

http:
  middlewares:
    secure-web:
      plugin:
        jwt:
          secret: |
            -----BEGIN EC PUBLIC KEY-----
            MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEE7gFCo/g2PQmC3i5kIqVgCCzr2D1
            nbCeipqfvK1rkqmKfhb7rlVehfC7ITUAy8NIvQ/AsXClvgHDv55BfOoL6w==
            -----END EC PUBLIC KEY-----
          require:
            aud: test.example.com

Specifying some known public keys upfront without prefetching them

http:
  middlewares:
    secure-web:
      plugin:
        jwt:
          issuers:
            - https://auth.example.com
          skipPrefetch: true
          secrets:
            b5c252d9c851331f41ae99d90e0847f7da9b6568: |
              -----BEGIN EC PUBLIC KEY-----
              MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEE7gFCo/g2PQmC3i5kIqVgCCzr2D1
              nbCeipqfvK1rkqmKfhb7rlVehfC7ITUAy8NIvQ/AsXClvgHDv55BfOoL6w==
              -----END EC PUBLIC KEY-----
            b6a5717df9dc13c9b15aab32dc811fd38144d43c: |
              -----BEGIN RSA PUBLIC KEY-----
              MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAzAOwEhcoj+yqyJK0Czvu
              COVoUdpaCYGeoeMB2gpclh5bHTqdfjrbko/tLpvkLKXliuWGwMMT5YC/WbhsWeAS
              ak3FMXUNGhuMoM3SebygwFNpF/kBQLayPcrlP0JtwIDEEkpWpE8b0D1GwzwbU73T
              Zedw0xrHMtH0YDbY5Q/G5/FW6wnZYOzLZdogOX0eSTlRy5T+DlYL6oDpdvqKKHGe
              gdP4r2ZVZ3CjWBcx4mERJTriGwlDkoHs/Zpvv2T+uBRSWmRnxaI62r2Nr9DJIh47
              DG7dq6bMdUOWOBRc9yBmgTF+K8/3JwDJo5JjCP9WfqAV8qtxA9g99mpbvAAqMGqa
              0QIDAQAB
              -----END RSA PUBLIC KEY-----
          require:
            aud: test.example.com

Don't verify TLS for auth.example.com

http:
  middlewares:
    secure-web:
      plugin:
        jwt:
          issuers:
            - https://auth.example.com
          insecureSkipVerify:
            - auth.example.com
          require:
            aud: test.example.com
          redirectUnauthorized: "https://example.com/login?return_to={{`{{URLQueryEscape .URL}}`}}"
          redirectForbidden: "https://example.com/unauthorized"

Non-standard JWKS endpoint

Firebase App Check is an example of a provider that does not provide an OpenID configuration document or a JWKS endpoint at the issuer base URL. Instead, it has a fixed JWKS endpoint. Use the alternate issuer/jwks map notation to specify the JWKS endpoint directly:

http:
  middlewares:
    secure-app:
      plugin:
        jwt:
          issuers:
            - issuer: https://firebaseappcheck.googleapis.com/123456789
              jwks: https://firebaseappcheck.googleapis.com/v1/jwks
          require:
            aud: projects/123456789

Philosophy

This plugin is designed to be simple and focused on a single responsibility: validating JWT tokens.

It upholds the original philosophy of JWTs: that a user's privileges can be encoded directly in the token and cryptographically signed by the issuer, allowing for stateless validation. There is therefore a deliberate design decision not to support the lookup of permissions from external databases or policy engines. The advantages of this approach are that it adds no latency to the critical path of every request and requires no external dependency at runtime. The trade-off is that if a user's privileges change, a new token must be issued to reflect this (i.e. the user must log in again).

Nothing prevents downstream backends from performing more dynamic or granular access control lookups (e.g. against an ACL database) once a request has been authenticated by this middleware. However, that is intentionally out of scope here. If you require a JWT middleware with integration to a policy engine (such as Open Policy Agent), alternatives exist: for example traefik-jwt-plugin.

Enhancements and Contributing

If you require some different behaviour, please do raise an issue in the first instance and we'll try to accommodate it promptly.

If contributing:

• Please ensure tests are added/updated and coverage remains at 100%.
• Please respect the existing code style, especially that all identifiers are descriptive and unabbreviated (sorry Rob P).

If you find this plugin useful, please consider giving it a star on GitHub.

Acknowledgements

Inspired by code from https://github.com/legege/jwt-validation-middleware, https://github.com/23deg/jwt-middleware and https://github.com/team-carepay/traefik-jwt-plugin