Documentation
Plugins
JWT Authentication

JWT Authentication

The jwt_auth plugin implements the JSON Web Tokens specification.

It can be used to verify the JWT signature, and optionally validate the token issuer and audience. It can also forward the token and its claims to the upstream service.

The JWKS configuration can be either a local file on the file-system, or a remote JWKS provider.

By default, the plugin will look for the JWT token in the Authorization header, with the Bearer prefix.

You can also configure the plugin to reject requests that don’t have a valid JWT token.

Configuration

Examples

This example is loading a JWKS file from the local file-system. The token is looked up in the Authorization header.

YAML

config:
  jwks_providers:
    - path: "jwks.json"
      source: "local"
  lookup_locations:
    - name: "Authorization"
      prefix: "Bearer"
      source: "header"
enabled: true
type: "jwt_auth"

JSON

{
  "config": {
    "jwks_providers": [
      {
        "path": "jwks.json",
        "source": "local"
      }
    ],
    "lookup_locations": [
      {
        "name": "Authorization",
        "prefix": "Bearer",
        "source": "header"
      }
    ]
  },
  "enabled": true,
  "type": "jwt_auth"
}

Reference

jwks_providers
array
required

A list of JWKS providers to use for verifying the JWT signature. Can be either a path to a local JSON of the file-system, or a URL to a remote JWKS provider.

The following options are valid for this field:
local

A local file on the file-system. This file will be read once on startup and cached.

source
literal: local
required

To use this variation, please specify the type: local in your configuration.

path
string
required

A path to a local file on the file-system. Relative to the location of the root configuration file.

remote

A remote JWKS provider. The JWKS will be fetched via HTTP/HTTPS and cached.

source
literal: remote
required

To use this variation, please specify the type: remote in your configuration.

url
string
required

The URL to fetch the JWKS key set from, via HTTP/HTTPS.

cache_duration
string
default: "10m"

Duration after which the cached JWKS should be expired. If not specified, the default value will be used.

prefetch
boolean
optional

If set to true, the JWKS will be fetched on startup and cached. In case of invalid JWKS, the error will be ignored and the plugin will try to fetch again when server receives the first request. If set to false, the JWKS will be fetched on-demand, when the first request comes in.

issuers
array
optional

Specify the principal that issued the JWT, usually a URL or an email address. If specified, it has to match the iss field in JWT, otherwise the token’s iss field is not checked.

audiences
array
optional

The list of JWT audiences are allowed to access. If this field is set, the token’s aud field must be one of the values in this list, otherwise the token’s aud field is not checked.

lookup_locations
array
default: [ { "name": "Authorization", "prefix": "Bearer", "source": "header" } ]

A list of locations to look up for the JWT token in the incoming HTTP request. The first one that is found will be used.

The following options are valid for this field:
header
source
literal: header
required

To use this variation, please specify the type: header in your configuration.

name
string
required
prefix
string
optional
query_param
source
literal: query_param
required

To use this variation, please specify the type: query_param in your configuration.

name
string
required
cookies
source
literal: cookies
required

To use this variation, please specify the type: cookies in your configuration.

name
string
required
reject_unauthenticated_requests
boolean
optional

If set to true, the entire request will be rejected if the JWT token is not present in the request.

allowed_algorithms
array
optional
default: [ "HS256", "HS384", "HS512", "RS256", "RS384", "RS512", "ES256", "ES384", "PS256", "PS384", "PS512", "EdDSA" ]

List of allowed algorithms for verifying the JWT signature. If not specified, the default list of all supported algorithms in jsonwebtoken crate are used.

forward_token_to_upstream_header
string
optional

Forward the JWT token to the upstream service in the specified header.

forward_claims_to_upstream_header
string
optional

Forward the JWT claims to the upstream service in the specified header.

CORSDisable Introspection