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.

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

• Auth0

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

Configuration Reference

The Traffic Policy configuration reference for this action.

Supported Phases

on_http_request

Type

jwt-validation

Configuration Fields

• issuerobjectRequired

  Configuration object for the Issuer(s) of the JWTs.

• audienceobjectRequired

  Configuration object for the Audience(s) of the JWTs.

• httpobjectRequired

  Configuration object for the HTTP requests containing JWTs.

• jwsobjectRequired

  Configuration object for signed JWTs (JWS).

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

YAML

---
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"

JSON

{
  "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.

• actions.ngrok.jwt_validation.tokensarray of objects

  The list of JSON Web Tokens (JWTs) processed by the action.

• actions.ngrok.jwt_validation.error.codestring

  A machine-readable code describing an error that occurred during the action's execution.

• actions.ngrok.jwt_validation.error.messagestring

  A human-readable message providing details about an error that occurred during the action's execution.