Skip to main content

JWT Validation

Overview

The JWT Validation Traffic Policy action enables you to validate JSON Web Tokens (JWT) on your endpoints before routing traffic to your upstream service.

A useful tool for working with JWTs is provided at jwt.io.

Guides

We have created guides for configuring this action with the following providers:

Configuration Reference

This is the Traffic Policy configuration reference for this action.

Action Type

jwt-validation

Configuration Fields

ParameterTypeDescription
issuerJWTIssuerConfigRequired. Configuration object for the Issuer(s) of the JWTs.
audienceJWTAudienceConfigRequired. Configuration object for the Audience(s) of the JWTs.
httpJWTHTTPConfigRequired. Configuration object for the HTTP requests containing JWTs.
jwsJWTSigningConfigRequired. Configuration object for signed JWTs (JWS).

JWTIssuerConfig Parameters

ParameterTypeDescription
allow_list[]JWTIssuerRequired. List of allowed issuers. Minimum 1.
JWTIssuer Parameters
ParameterTypeDescription
valuestringRequired. Issuer URL. This can be found in the iss claim after decoding the JWT or from the /.well-known/openid-configuration endpoint in your Identity Provider.

JWTAudienceConfig Parameters

ParameterTypeDescription
allow_list[]JWTAudienceRequired. List of allowed audiences. Minimum 1.
JWTAudience Parameters
ParameterTypeDescription
valuestringRequired. Audience claim value. This can be found in the aud claim after decoding the JWT or from the request used to create the token in the first place.

JWTHTTPConfig Parameters

ParameterTypeDescription
tokens[]JWTHTTPTokenRequired. List of tokens to validate. Minimum 1.
JWTHTTPToken Parameters
ParameterTypeDescription
typestringRequired. Type of the JWT, which acts as a hint about how ngrok should parse the token. Must be one of "access_token", "at+jwt", "id_token", "it+jwt", "plain", or "jwt".
methodstringRequired. Location in the request to expect the JWT. Must be one of "header" or "body". We do not support including a token as a URL query parameter. When choosing body, the method must be POST, PUT, or PATCH and the content-type header must be set to either application/json or application/x-www-form-urlencoded.
namestringRequired. Name of the header or body field where the JWT is expected (Example: "Authorization"). This is not case sensitive.
prefixstringAny prefix to strip from the header or body field before parsing the JWT (Example: "Bearer ").

JWTSigningConfig Parameters

ParameterTypeDescription
allowed_algorithms[]stringRequired. List of allowed signing algorithms. We do not support none as a value here because it is insecure. Minimum 1.
keys[]JWTSigningKeysRequired. Configuration for the JWT signing keys.
JWTSigningKeys Parameters
ParameterTypeDescription
sources[]JWTSigningKeySourcesRequired. Configuration for the key material used to verify the signed JWTs.
JWTSigningKeySources Parameters
ParameterTypeDescription
additional_jkus[]stringRequired. List of URLs which serve the possible signing keys in JWKS format. These urls are cached and refreshed roughly every 15 minutes.

Supported Phases

  • on_http_request

Supported Schemes

  • https
  • http

Behavior

Request Validation

The request is allowed only if it has been correctly signed by the issuer and the defined claims match.

Multiple Issuers

You can specify multiple issuers for JWT validation. A request is considered validated if it presents a JWT signed by any of the specified issuers.

The issuer must exactly match the one provided in the JWT, including any trailing slashes (/) present in the iss claim.

Multiple Audience Claims

You can specify multiple audience claims for JWT validation.

The JWT must contain at least one of the specified audience claims and exactly match for validation to succeed.

Multiple Signing Keys

You can provide multiple JSON Web Key Set (JWKS) URLs and signing algorithms.

During JWT validation the list of JWKS and algorithms provided will be used in an attempt to validate the JWT. The list will be tried in order and is cached for performance. The cache is refreshed roughly every 15 minutes.

Multiple Tokens

If multiple tokens are defined within the HTTP configuration parameter, all tokens must be present in the request. If all tokens are not present, a 401 Unauthorized status code will be returned.

Examples

Basic Example

The following Traffic Policy configuration is an example configuration of the jwt-validation action for a more real world example check out our Auth0 guide.

Example Traffic Policy Document

---
on_http_request:
- actions:
- type: "jwt-validation"
config:
issuer:
allow_list:
- value: "https://example.com/issuer"
audience:
allow_list:
- value: "urn:example:api"
http:
tokens:
- type: "access_token"
method: "header"
name: "Authorization"
prefix: "Bearer "
- type: "it+jwt"
method: "body"
name: "_id_token"
jws:
allowed_algorithms:
- "RS256"
- "ES256"
keys:
sources:
additional_jkus:
- "https://example.com/issuer/jku"

Example Request

$ curl --request GET \
--url http://example-api.ngrok.app/ \
--header 'authorization: Bearer <VALID-JWT>'
HTTP/2 200 OK
content-type: text/html

...

In this example, we are sending a request to our API with a valid JWT token in the Authorization header with the Bearer prefix and getting back a 200 OK response.

Action Result Variables

The following variables are made available for use in subsequent expressions and CEL interpolations after the action has run. Variable values will only apply to the last action execution, results are not concatenated.

NameTypeDescription
actions.ngrok.jwt_validation.tokens[]JWTThe JWTs processed by the action.
actions.ngrok.jwt_validation.tokens[i].headermap[string]stringThe header portion of the JWT, parsed into a key value map.
actions.ngrok.jwt_validation.tokens[i].locationstringThe location in the request where the JWT was included.
actions.ngrok.jwt_validation.tokens[i].location_propertystringThe name of the header or body field where the JWT was included.
actions.ngrok.jwt_validation.tokens[i].payloadmap[string]stringThe payload portion of the JWT, parsed into a key value map.
actions.ngrok.jwt_validation.tokens[i].signaturestringThe signature portion of the JWT, in base64 encoded format.
actions.ngrok.jwt_validation.tokens[i].verifiedbooleanSet to true if token was verified.
actions.ngrok.jwt_validation.error.codestringCode for an error that occurred during the invocation of an action.
actions.ngrok.jwt_validation.error.messagestringMessage for an error that occurred during the invocation of an action.