JWT Validation
Overview
The JWT Validation action allows you to configure ngrok to validate JSON Web Tokens (JWT) at our cloud edge before routing the traffic to your origin service. You will need to tell ngrok where to find the token, as well as the claims and algorithms used to verify it's authenticity. When configuring this action in a locally running agent, it is pushed to our global network which secures traffic before it hits your network.
The request is allowed only if it has been correctly signed by the issuer and the defined claims match.
We have created guides for configuring this action with the following providers:
A useful tool for working with JWTs is provided at jwt.io.
Example
Use this action config in your Traffic Policy
- YAML
- JSON
# snippet
---
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"
// snippet
{
"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"
]
}
}
}
}
}
]
}
Behavior
Multiple Issuers
You may specify multiple issuers to be used for JWT validation. A request is considered
validated if it presents a JWT signed by any of the specified issuers. The issuer must match the one
provided in the JWT exactly, including the trailing slash (/
) if present in the token's iss
claim.
Multiple Audience Claims
You may specify multiple audience claims to be used for JWT validation. JWT validation will require at least one of the audience claims to be present within the JWT. This is also an exact match.
Multiple Signing Keys
You have the ability to 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. This 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
status code will be returned.
Reference
Supported Directions
- Inbound
Configuration
Type |
---|
jwt-validation |
Parameter | Type | Description |
---|---|---|
issuer | JWTIssuerConfig | configuration about the Issuer(s) of the JWTs. |
audience | JWTAudienceConfig | configuration about the Audience(s) of the JWTs. |
http | JWTHTTPConfig | configuration about the HTTP requests containing JWTs. |
jws | JWTSigningConfig | configuration about signed JWTs (JWS). |
JWTIssuerConfig Parameters
Parameter | Type | Description |
---|---|---|
allow_list | JWTIssuer | the list of allowed issuers. |
JWTIssuer Parameters
Parameter | Type | Description |
---|---|---|
value | string | the URL of the issuer. This can be found in the iss claim after decoding the JWT or from the /.well-known/openid-configuration endpoint in your Identity Provider. |
JWTAudienceConfig Parameters
Parameter | Type | Description |
---|---|---|
allow_list | JWTAudience | the list of allowed audiences. |
JWTAudience Parameters
Parameter | Type | Description |
---|---|---|
value | string | the value of the audience claim. 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. |
JWTHTTPConfig Parameters
Parameter | Type | Description |
---|---|---|
tokens | JWTHTTPToken | the list of tokens to validate. |
JWTHTTPToken Parameters
Parameter | Type | Description |
---|---|---|
type | string | the type of the JWT, which acts as a hint to ngrok about how ngrok should parse the token. Must be one of "access_token", "at+jwt", "id_token", "it+jwt", "plain", or "jwt". |
method | string | the location in the request to expect the JWT. Must be one of "header" or "body". We do not support including a token as a URL query parameter. When choosing body , the method must be POST , PUT , or PATCH and the content type header must be set to either application/json or application/x-www-form-urlencoded . |
name | string | the name of the header or body field where the JWT is expected (Example: "Authorization" ). This is not case sensitive. |
prefix | string | Any prefix to strip from the header or body field before parsing the JWT (Example: "Bearer " ). |
JWTSigningConfig Parameters
Parameter | Type | Description |
---|---|---|
allowed_algorithms | List<string> | the list of allowed signing algorithms. We do not support none as a value here because it is insecure. |
keys | JWTSigningKeys | the configuration for the JWT signing keys. |
JWTSigningKeys Parameters
Parameter | Type | Description |
---|---|---|
sources | JWTSigningKeySources | the configuration for the key material used to verify the signed JWTs. |
JWTSigningKeySources Parameters
Parameter | Type | Description |
---|---|---|
additional_jkus | List<string> | a list of URLs which serve the possible signing keys in JWKS format. These urls are cached and refreshed roughly every 15 minutes. |
Action Result Variables
The following variables are available following the invocation of this action.
Name | Type | Description |
---|---|---|
actions.ngrok.jwt_validation.tokens | []JWT | The JWTs processed by the action. |
actions.ngrok.jwt_validation.tokens[i].header | map[string]string | The header portion of the JWT, parsed into a key value map. |
actions.ngrok.jwt_validation.tokens[i].location | string | The location in the request where the JWT was included. |
actions.ngrok.jwt_validation.tokens[i].location_property | string | The name of the header or body field where the JWT was included. |
actions.ngrok.jwt_validation.tokens[i].payload | map[string]string | The payload portion of the JWT, parsed into a key value map. |
actions.ngrok.jwt_validation.tokens[i].signature | string | The signature portion of the JWT, in base64 encoded format. |
actions.ngrok.jwt_validation.tokens[i].verified | boolean | True if this token was verified. |
actions.ngrok.jwt_validation.error.code | string | Code for an error that occurred during the invocation of an action. |
actions.ngrok.jwt_validation.error.message | string | Message for an error that occurred during the invocation of an action. |