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. Use this page to manage trusted issuers centrally, so that key rotations and policy changes apply at every surface that references the strategy without requiring surface-level edits.

Overview

Strategies are managed under Credentials → JWT Verification in the dashboard. 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 Source—YesRemote URLHow the gateway obtains public signing keys. Select Remote URL to fetch keys from a JWKS endpoint, or Static Keys to provide the keys inline.
JWKS URIURLWhen Remote URL—The JWKS endpoint the gateway fetches keys from. Keys are cached per the server’s Cache-Control header (default 24 h). The dashboard validates the URI as you type (800 ms pause). Saving is blocked until the check passes. Select Check URI to trigger validation manually. A green JWKS URI is reachable and valid message confirms success.
JWK ArrayJSONWhen Static Keys—One or more public keys as a JSON array of JWK objects, 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:

Read the token

The gateway reads the token from the Authorization: Bearer header.

Load the strategy

The strategy referenced by the surface’s Caller Context element is loaded.

Obtain signing keys

Keys are fetched from the remote JWKS URI and cached, or read from the static JWK array.

Verify the signature

The token signature is verified against the matching key.

Validate claims

The token’s iss must equal the strategy’s Expected Issuer. The token must not be expired.

Check audience

If the Caller Context element specifies accepted audiences, the token’s aud claim must contain at least one of them.

Pass claims to policy

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