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

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

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

Endpoints

Traffic Policy

Domains & TLS

Identity & Access

Observability

ngrok Agent

Kubernetes Operator

API Gateway

Device Gateway

Site-to-Site Connectivity

Webhooks to On-Prem

Security Best Practices

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

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