> ## Documentation Index
> Fetch the complete documentation index at: https://ngrok.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# JWT Validation Action
> Validate JSON Web Tokens (JWT) on your endpoints before routing traffic to your upstream service.
export const ConfigChildren = ({children}) => {
return
{children}
;
};
export const ConfigField = ({title, type, cel = false, defaultValue = false, required = false, children}) => {
const id = `config-${title.replace(/\.|\s|\*/g, "_")}`;
return
{title}
{type &&
{type}
}
{defaultValue &&
default:
{defaultValue}
}
{required &&
Required
}
{cel &&
Supports CEL
}
{children}
;
};
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](/integrations/jwt-validation/auth0/)
A useful tool for working with JWTs is provided at [jwt.io](https://jwt.io).
## Configuration reference
The [Traffic Policy](/traffic-policy/) configuration
reference for this action.
### Supported phases
`on_http_request`
### Type
`jwt-validation`
### Configuration fields
Configuration object for the Issuer(s) of the JWTs.
List of allowed issuers. Minimum `1`.
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.
Configuration object for the Audience(s) of the JWTs.
List of allowed audiences. Minimum `1`.
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.
Configuration object for the HTTP requests containing JWTs.
List of tokens to validate. Minimum `1`.
Type of the JWT, which acts as a hint about how ngrok should parse the token.
`id_token`
`access_token`
`at+jwt`
`it+jwt`
`plain`
`jwt`
Location in the request to expect the JWT.
`header`
`body`
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 PATCH
Including a token as a URL query parameter is not supported.
Name of the header or body field where the JWT is expected (Example: "Authorization"). This is not case sensitive.
Any prefix to strip from the header or body field before parsing the JWT (Example: "Bearer ").
Configuration object for signed JWTs (JWS).
List of allowed signing algorithms. The value none is not supported here because it is insecure. Minimum `1`.
Configuration for the JWT signing keys.
JWT metadata.
List of claims present in this token. Supported values: \['kid']
Configuration for the key material used to verify the signed JWTs.
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-variables) 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](/traffic-policy/)
configuration is an example configuration of the `jwt-validation` action. For a
more real-world example, check out the [Auth0 guide](/integrations/jwt-validation/auth0/).
#### Example Traffic Policy document
```yaml policy.yml theme={null}
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 policy.json theme={null}
{
"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
```bash theme={null}
$ curl --request GET \
--url http://example-api.ngrok.app/ \
--header 'authorization: Bearer '
```
```http theme={null}
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.
The list of JSON Web Tokens (JWTs) processed by the action.
The header portion of the JWT, parsed into a key-value map containing metadata about the token.
The part of the HTTP request where the JWT was located (for example,{" "}
header, body).
The specific header or body field that contained the JWT (for example,{" "}
"Authorization").
The payload portion of the JWT, parsed into a key-value map
representing the claims.
The signature portion of the JWT, encoded in base64, used for
verifying token integrity.
Indicates whether the token passed verification. Returns{" "}
true if verified successfully.
A machine-readable code describing an error that occurred during the
action's execution.
A human-readable message providing details about an error that occurred
during the action's execution.