JWT Verification Strategies

Field reference for JWT Verification Strategy configuration, which defines reusable bearer-token validation rules that surfaces reference to authenticate callers.

A JWT Verification Strategy is a named, reusable configuration that tells the gateway which issuer to trust and where to find the public signing keys for bearer token validation.

Overview

Strategies are managed under Management > Credentials > JWT Verification. A strategy stores the trusted issuer URL and the public signing keys: either fetched from a remote JWKS endpoint or stored statically. Surfaces reference a strategy via the Caller Context element’s JWT Bearer configuration rather than holding issuer details directly.

This separation means that multiple surfaces can share the same issuer configuration and be updated centrally when keys rotate. Changing a strategy’s JWKS URI or static keys takes effect on the next inbound request at every surface that references it.

Fields

FieldTypeRequiredDefaultDescription
NamestringYes—Human-readable label. Shown in the JWT Verification Strategy dropdown on the Caller Context configuration panel.
Expected issuerstringYes—The exact value the token’s iss claim must match. Trailing slash differences cause rejection.
JWKS sourceremote | staticYes—How the gateway obtains public signing keys.
JWKS URIURLWhen remote—The JWKS endpoint the gateway fetches keys from. Keys are cached according to the server’s Cache-Control headers. The gateway validates the URI is reachable when the strategy is saved. A green indicator on the form confirms the URI resolved successfully.
Static JWKSJSONWhen static—One or more public keys in JWKS JSON format, stored directly in the strategy. Rotating keys requires updating this field manually.

Token validation sequence

For each request at a surface that references a strategy:

  1. The gateway reads the token from the Authorization: Bearer header.
  2. The referenced strategy is loaded.
  3. Signing keys are obtained: fetched from the remote JWKS URI and cached, or read from the static JWKS JSON.
  4. The token signature is verified against the matching key.
  5. The token’s iss must equal the strategy’s expected issuer. The token must not be expired.
  6. If the Caller Context element specifies accepted audiences, the token’s aud claim must contain at least one of them.
  7. On success, the validated token claims are available to OPA policy evaluation as input.caller.jwt_bearer.

The gateway never defaults to allowing unverified traffic when source authentication is configured. If the remote JWKS endpoint is unreachable at request time, the request fails rather than being accepted.

Accepted audiences

The Accepted Audiences list is configured on the Caller Context element attached to a surface, not on the strategy itself. A strategy can therefore be shared by surfaces with different audience requirements. Leave the Accepted Audiences list empty on the Caller Context element to accept tokens with any audience.

Deleting a strategy