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 of whitelisted issuers.
• Flexible claim checks, including optional wildcards and Go template interpolation.
• Configurable HTTP redirects for unauthorized and forbidden calls for interactive requests.

Configuration

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

experimental:
  plugins:
    jwt:
      moduleName: github.com/Brainnwave/jwt-middleware
      version: v1.1.11

1b. or with command-line options:

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

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

1. use the middleware in services via docker-compose labels

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

Options

The plugin supports the following configuration options.

Template Interpolation

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

These variables are useful with dynamic requirements, particularly in multitenancy scenarios. However, if using Host, care must be taken to ensure that the traefik router can only be reached through that hostname, i.e. through some well-controlled route, such as behind an API gateway, proxy or other ingress. If the traefik router is reachable directly by some public IP, it would be easy to spoof a different Host by manipulating DNS for the IP externally; a static requirement should be used instead in such an architecture.

Addiionally, 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 enviorment 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

Will suceed when called on https://customer.example.com/example

require:
  aud: "customer.example.com"

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

Note that the wildcard is granted to the user in their claim, not asked for in the requirements. 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"]
  }
}

Examples

Interactive webserver with redirection to login and error pages

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

Specifying a fixed ECDSA public key

http:
  middlewares:
    secure-interactive:
      plugin:
        jwt:
          secret: |
            -----BEGIN PUBLIC KEY-----
            MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEmHp6e95bmF2NqgziUMZP/+x8r2dH
            m/UisMRtEhOY6vE92LCdFpyqtwYwPVryYexT0ITtQldD5O091QcuIOm6KQ==
            -----END PUBLIC KEY-----
          require:
            aud: test.example.com

Don't verify TLS for auth.example.com

http:
  middlewares:
    secure-interactive:
      plugin:
        jwt:
          issuers:
            - https://auth.example.com
          insecureSkipVerify:
            - auth.example.com
          require:
            aud: test.example.com
          redirectUnauthorized: "https://example.com/login?return_to={{`{{.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 forking and modifying, 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