Common JWKS fetch (proto)

Configuration for fetching a JSON Web Key Set (JWKS) from a remote HTTP server and caching it, shared by extensions that need remote JWKS.

extensions.filters.common.jwks.v3.RemoteJwks

[extensions.filters.common.jwks.v3.RemoteJwks proto]

This message specifies how to fetch JWKS from remote and how to cache it.

{
  "http_uri": {...},
  "cache_duration": {...},
  "async_fetch": {...},
  "retry_policy": {...}
}

http_uri

(config.core.v3.HttpUri, REQUIRED) The HTTP URI to fetch the JWKS. For example:

http_uri:
  uri: https://www.googleapis.com/oauth2/v1/certs
  cluster: jwt.www.googleapis.com|443
  timeout: 1s

cache_duration: (Duration) Duration after which the cached JWKS should be expired. If not specified, default cache duration is 10 minutes.

async_fetch

(extensions.filters.common.jwks.v3.JwksAsyncFetch) Fetch Jwks asynchronously in the main thread before the listener is activated. Fetched Jwks can be used by all worker threads.

If this feature is not enabled:

The Jwks is fetched on-demand when the requests come. During the fetching, first few requests are paused until the Jwks is fetched.
Each worker thread fetches its own Jwks since Jwks cache is per worker thread.

If this feature is enabled:

Fetched Jwks is done in the main thread before the listener is activated. Its fetched Jwks can be used by all worker threads. Each worker thread doesn’t need to fetch its own.
Jwks is ready when the requests come, not need to wait for the Jwks fetching.

retry_policy

(config.core.v3.RetryPolicy) Retry policy for fetching Jwks. optional. turned off by default.

For example:

retry_policy:
  retry_back_off:
    base_interval: 0.01s
    max_interval: 20s
  num_retries: 10

will yield a randomized truncated exponential backoff policy with an initial delay of 10ms 10 maximum attempts spaced at most 20s seconds.

retry_policy:
  num_retries:1

uses the default retry backoff strategy. with the default base interval is 1000 milliseconds. and the default maximum interval of 10 times the base interval.

if num_retries is omitted, the default is to allow only one retry.

If enabled, the retry policy will apply to all Jwks fetching approaches, e.g. on demand or asynchronously in background.

extensions.filters.common.jwks.v3.JwksAsyncFetch

[extensions.filters.common.jwks.v3.JwksAsyncFetch proto]

Fetch Jwks asynchronously in the main thread when the filter config is parsed. The listener is activated only after the Jwks is fetched. When the Jwks is expired in the cache, it is fetched again in the main thread. The fetched Jwks from the main thread can be used by all worker threads.

{
  "fast_listener": ...,
  "failed_refetch_duration": {...}
}

fast_listener: (bool) If false, the listener is activated after the initial fetch is completed. The initial fetch result can be either successful or failed. If true, it is activated without waiting for the initial fetch to complete. Default is false.

failed_refetch_duration: (Duration) The duration to refetch after a failed fetch. If not specified, default is 1 second.