Catch the highlights of GraphQLConf 2023! Click for recordings. Or check out our recap blog post.
Docs
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

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

JSON

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

Reference

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.

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.

forward_claims_to_upstream_header
string
optional

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

forward_token_to_upstream_header
string
optional

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

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.

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.

path
string
required

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

source
literal: local
required
remote

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

cache_duration
optional
default: "10m"

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

nanos
integer
required
secs
integer
required
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.

source
literal: remote
required
url
string
required

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

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

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
name
string
required
prefix
string
optional
source
literal: header
required
query_param
name
string
required
source
literal: query_param
required
cookies
name
string
required
source
literal: cookies
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.

CORSDisable Introspection