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
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.
local
A local file on the file-system. This file will be read once on startup and cached.
source
local
To use this variation, please specify the type: local
in your configuration.
path
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
remote
To use this variation, please specify the type: remote
in your configuration.
url
The URL to fetch the JWKS key set from, via HTTP/HTTPS.
cache_duration
"10m"
Duration after which the cached JWKS should be expired. If not specified, the default value will be used.
prefetch
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
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
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
[
{
"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.
header
source
header
To use this variation, please specify the type: header
in your configuration.
name
prefix
query_param
source
query_param
To use this variation, please specify the type: query_param
in your configuration.
name
cookies
source
cookies
To use this variation, please specify the type: cookies
in your configuration.
name
reject_unauthenticated_requests
If set to true
, the entire request will be rejected if the JWT token is not present in the request.
allowed_algorithms
[
"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
Forward the JWT token to the upstream service in the specified header.
forward_claims_to_upstream_header
Forward the JWT claims to the upstream service in the specified header.