Rate limit descriptor from JWT claim (proto)

This extension has the qualified name envoy.rate_limit_descriptors.jwt_claim

Note

This extension is functional but has not had substantial production burn time, use only with this caveat.

This extension is not hardened and should only be used in deployments where both the downstream and upstream are trusted.

Tip

This extension extends and can be used with the following extension category:

envoy.rate_limit_descriptors

This extension must be configured with one of the following type URLs:

type.googleapis.com/envoy.extensions.rate_limit_descriptors.jwt_claim.v3.Descriptor

extensions.rate_limit_descriptors.jwt_claim.v3.Descriptor

[extensions.rate_limit_descriptors.jwt_claim.v3.Descriptor proto]

The following descriptor entry is appended with a value extracted from a named claim in a JWT found in an HTTP request header.

("<descriptor_key>", "<claim_value>")

Warning

SECURITY WARNING: This extension does NOT verify JWT signatures. Any party can present a forged or expired JWT with arbitrary claims, and those claims will be used as rate limit descriptor values. This means an attacker can trivially evade or manipulate per-claim rate limits (e.g. impersonate another subject, or rotate a fake claim value on every request to bypass limiting entirely) unless the JWT signature is verified elsewhere in the request path — for example, by an upstream mTLS-authenticated service, or by an envoy.filters.http.jwt_authn filter earlier in the same filter chain that rejects invalid tokens before this descriptor action runs.

DO NOT use this extension to gate access, apply differentiated rate limits by trust level, or make any authorization-adjacent decision based on the extracted claim, unless signature verification is PROVABLY performed elsewhere in the request path.

If you need Envoy itself to verify the JWT before rate limiting, use the envoy.filters.http.jwt_authn filter (placed before the rate limit filter) together with a request_headers or metadata descriptor action instead of this extension.

{
  "descriptor_key": ...,
  "header_name": ...,
  "value_prefix": ...,
  "claim_name": ...,
  "default_value": ...,
  "skip_if_absent": ...
}

descriptor_key: (string, REQUIRED) The key to use in the descriptor entry.

header_name: (string, REQUIRED) The name of the HTTP header containing the JWT, e.g. “authorization”.

value_prefix: (string) The value prefix to strip before parsing the remainder as a JWT, e.g. “Bearer “ (with a trailing space) for an “authorization” header formatted as “Authorization: Bearer <token>”. If the header value does not start with this prefix, the descriptor is not populated (falls through to default_value/skip_if_absent below).

claim_name: (string, REQUIRED) The name of the JWT claim to extract. Can be a nested claim, dot- separated, e.g. “claim.nested.key”. Matches the same convention as JwtClaimToHeader.claim_name. Only string-valued claims are supported; non-string claims (numbers, booleans, arrays, objects) are treated as absent. An empty string-valued claim populates the descriptor with an empty value.

default_value: (string) The default value to use if the header is absent, is not a structurally valid JWT, or the named claim is absent/non-string.

skip_if_absent: (bool) If true, Envoy skips this descriptor entry (rather than aborting the whole descriptor for this action list) when the header is absent, the JWT cannot be parsed, or the named claim is absent/non-string, and default_value is not specified. An empty string-valued claim is present and produces an entry with an empty value regardless of this setting.