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

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

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

1b. or with command-line options:

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

1. Configure and activate the plugin as a middleware in your dynamic traefik config:

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

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 traefiks 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"],
}

Examples

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"

Forking

If you require some different behaviour, please do raise an issue or pull request in GitHub in the first instance rather than simply just forking, and we'll try to accommodate it promptly (so as to reduce fragmentation of functionality).

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