Class RemoteJwksSource
- All Implemented Interfaces:
JwksSource
jwks_uri.
Lazy, on the caller's thread. RemoteJwksSource.Builder.build() does no I/O, creates no HTTP client and starts
no thread. The first call that needs a key, or warmUp(), fetches the key set on the calling thread, and
concurrent callers wait for that one fetch, each within its own deadline: a validation's is this source's request
timeout. Revetsec starts no thread of its own; the JDK's HTTP client runs its own, as it always does.
Caching. A fetched key set stays fresh for a time to live taken from the response's
Cache-Control (max-age; no-store and no-cache mean the minimum) or Expires,
clamped to the minimum and maximum time to live, or for the default time to live when the response has neither.
There are no conditional requests. After it expires, the next call that needs a key fetches it again. A key set in
which every key was skipped is still a key set, so an identity provider can withdraw all its keys; each skipped key
is reported to JoseObserver.didSkipJwk(URI, Integer, JwkSkipReason) on every fetch.
Unknown keys. A token whose key is not in a fresh key set (an unknown kid, or no key that
fits a token without one) refreshes the key set early, at most once per unknown-key refresh cooldown. The cooldown
holds back only these refreshes: the first fetch, warmUp() and refreshes after expiry neither wait for it
nor start it, so a key an identity provider starts using just after a scheduled fetch is fetched at once. A request
sent for an unknown key keeps its cooldown whatever its outcome. A key named by the token's kid that does not
fit the token's algorithm, or two keys that fit, never cause a refresh.
Failures. A failed fetch, a timeout included, starts a backoff that every fetch respects,
warmUp() included: the unknown-key cooldown, doubled after each further failure up to ten cooldowns (at
most 10 minutes), which is 30, 60, 120, 240 and then 300 seconds at the default cooldown. A Retry-After on a
429 or 503 may lengthen a step, up to that cap. A successful fetch does not reset the backoff: the failure count
falls by one for each full cap interval without a failure. During a backoff no request is sent, and each call that
would have fetched is reported to JoseObserver.didSuppressJwksFetch(URI, Duration). At the
defaults, one endpoint that keeps failing gets at most 15 requests in its first hour, and 12 an hour after that.
Request limit. No more than two requests of any kind start within one cooldown.
RemoteJwksSource.Builder.build() refuses a cooldown longer than the minimum time to live, so each successful fetch leaves a
key set fresh for at least one cooldown, and each failed one starts a backoff of at least one cooldown. The
unknown-key cooldown, the backoff and the time to live therefore keep requests within this limit on their own, and
it holds back no call, a refresh after expiry included, unless fetches were cut short: by an interrupt, by an
Error, or by a leader held past the longest a fetch may take, as a slow observer can hold it. A call the
limit holds back sends nothing and is reported to
JoseObserver.didSuppressJwksFetch(URI, Duration): an expired key set answers it for the keys it
holds, a call for an unknown key gets no key, and any other call throws a transient
JwksUnavailableException of category ErrorCategory.TRANSPORT with no cause.
Stale keys. While refreshes fail or are held back, an expired key set still answers, for the keys
it holds, until the maximum staleness after its expiry, provided the cached snapshot remains retained.
An observed clock rollback discards the snapshot entirely, including otherwise eligible stale keys. A failed
refresh after rollback has no stale fallback; only a later successful fetch establishes another snapshot.
Catching up the wall clock does not revive the discarded material. Other calls throw JwksUnavailableException.
Time. The time to live, cooldown, backoff and staleness follow the configured Clock. An
instant recorded in the future of the clock's current time counts as passed. Any observed backward step
discards the cached key set, even inside its original fresh/stale window, and never extends that old window. Deadlines and elapsed times use System.nanoTime().
Bound to one URI, not to an issuer. Share an instance only among validators that expect the same
issuer, because every key in it is trusted for any token they check. Sources compare by reference.
toString() shows the URI cut to its scheme, host, port and path, and the settings.
- Since:
- 1.0.0
- Author:
- Mark Allen
-
Nested Class Summary
Nested Classes -
Method Summary
Modifier and TypeMethodDescriptiongetUri()Returns the key set's URI.toString()Describes the source by its URI, cut to its scheme, host, port and path, and its settings.voidwarmUp()Fetches the key set now, unless a fresh one is cached (even one with no usable key), so the first validation does not wait for it.static @NonNull RemoteJwksSource.BuilderStarts building a source for the key set aturi.
-
Method Details
-
withUri
Starts building a source for the key set aturi.- Parameters:
uri- the key set's URI: absolute,https(orhttpto a loopback host where allowed), with no user information and no fragment, and permitted by the outbound URI policy; a query is allowed.RemoteJwksSource.Builder.build()checks it- Returns:
- a new builder
- Throws:
NullPointerException- ifuriisnull- Since:
- 1.0.0
-
warmUp
Fetches the key set now, unless a fresh one is cached (even one with no usable key), so the first validation does not wait for it. It waits for a fetch another caller already started instead of starting its own. It follows the backoff after a failure, throwing that failure without sending a request, and the limit of two requests per cooldown, but not the unknown-key cooldown, which it neither waits for nor starts. It waits at most the request timeout.- Throws:
JwksUnavailableException- if the fetch failed, a recent failure or the request limit held it back, or the wait ended, even when an expired key set is still cached- Since:
- 1.0.0
-
getUri
-
toString
-