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.

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

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​

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