JWT Validation Action

The JWT Validation Traffic Policy action enables you to validate JSON Web Tokens (JWT) on your endpoints before routing traffic to your upstream service. Guides for configuring this action with the following providers are available:

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

issuer

object

Required

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

Show child attributes

allow_list

array of objects

Required

List of allowed issuers. Minimum 1.

Show child attributes

allow_list[*].value

string

Required

Supports CEL

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.

audience

object

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

Show child attributes

allow_list

array of objects

List of allowed audiences. Minimum 1.

Show child attributes

allow_list[*].value

string

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.

http

object

Required

Configuration object for the HTTP requests containing JWTs.

Show child attributes

tokens

array of objects

Required

List of tokens to validate. Minimum 1.

Show child attributes

tokens[*].type

enum

Required

Type of the JWT, which acts as a hint about how ngrok should parse the token.

tokens[*].method

enum

Required

Location in the request to expect the JWT.When choosing header, the content-type header must be set to either application/json or application/x-www-form-urlencoded.When choosing body, the method must be POST, PUT, or PATCHIncluding a token as a URL query parameter is not supported.

tokens[*].name

string

Required

Supports CEL

Name of the header or body field where the JWT is expected (Example: “Authorization”). This is not case sensitive.

tokens[*].prefix

string

Supports CEL

Any prefix to strip from the header or body field before parsing the JWT (Example: “Bearer ”).

jws

object

Required

Configuration object for signed JWTs (JWS).

Show child attributes

allowed_algorithms

array of strings

Required

List of allowed signing algorithms. The value none is not supported here because it is insecure. Minimum 1.

keys

array of objects

Required

Configuration for the JWT signing keys.

Show child attributes

keys[*].identification

array of objects

JWT metadata.

Show child attributes

keys[*].identification[*].token_claims

array of strings

List of claims present in this token. Supported values: [‘kid’]

keys[*].sources

array of objects

Required

Configuration for the key material used to verify the signed JWTs.

Show child attributes

keys[*].sources[*].additional_jkus

array of strings

Required

Supports CEL

List of URLs which serve the possible signing keys in JWKS format. These URLs are cached and refreshed roughly every 15 minutes.

Behavior

Request validation

The request is allowed only if it has been correctly signed by the issuer and the defined claims match. For efficient validation of tokens, it is recommended to include the optional kid claim in your JWTs and JWK payload. Custom validation can be implemented in Traffic Policies via the actions.ngrok.jwt_validation.tokens Action Result Variable and its corresponding properties.

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 optionally specify one or more audience (aud) claims for JWT validation. If present, the aud claim 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.

Non-terminating action

This is a Non-terminating action. It does not return a response, and will allow Traffic Policy processing to continue to the next Action in the chain. All Cloud Endpoint Traffic Policies must end with a terminating action. This requirement does not apply to Agent Endpoints.

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 the 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, a request is sent to the 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.tokens

array of objects

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

Show child attributes

tokens[i].header

object

The header portion of the JWT, parsed into a key-value map containing metadata about the token.

tokens[i].location

string

The part of the HTTP request where the JWT was located (for example, header, body).

tokens[i].location_property

string

The specific header or body field that contained the JWT (for example, “Authorization”).

tokens[i].payload

object

The payload portion of the JWT, parsed into a key-value map representing the claims.

tokens[i].signature

string

The signature portion of the JWT, encoded in base64, used for verifying token integrity.

tokens[i].verified

boolean

Indicates whether the token passed verification. Returns true if verified successfully.

actions.ngrok.jwt_validation.error.code

string

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

actions.ngrok.jwt_validation.error.message

string

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

Getting Started

Concepts

Actions

Macros

Variables

Resources

Examples

Configuration reference

Supported phases

Type

Configuration fields

Behavior

Request validation

Multiple issuers

Multiple audience claims

Multiple signing keys

Multiple tokens

Non-terminating action

Examples

Basic example

Example Traffic Policy document

Example request

Action result variables

Getting Started

Concepts

Actions

Macros

Variables

Resources

Examples

​Configuration reference

​Supported phases

​Type

​Configuration fields

​Behavior

​Request validation

​Multiple issuers

​Multiple audience claims

​Multiple signing keys

​Multiple tokens

​Non-terminating action

​Examples

​Basic example

​Example Traffic Policy document

​Example request

​Action result variables

Configuration reference

Supported phases

Type

Configuration fields

Behavior

Request validation

Multiple issuers

Multiple audience claims

Multiple signing keys

Multiple tokens

Non-terminating action

Examples

Basic example

Example Traffic Policy document

Example request

Action result variables