Class RemoteJwksSource

java.lang.Object
com.revetsec.jose.RemoteJwksSource
All Implemented Interfaces:
JwksSource

@ThreadSafe public final class RemoteJwksSource extends Object implements JwksSource
A JSON Web Key Set fetched from a URI and cached, such as an OpenID provider's 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
  • Method Details

    • withUri

      Starts building a source for the key set at uri.
      Parameters:
      uri - the key set's URI: absolute, https (or http to 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 - if uri is null
      Since:
      1.0.0
    • warmUp

      public void 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

      public @NonNull URI getUri()
      Returns the key set's URI.
      Returns:
      the URI, as configured
      Since:
      1.0.0
    • toString

      Describes the source by its URI, cut to its scheme, host, port and path, and its settings.
      Overrides:
      toString in class Object
      Returns:
      the description
      Since:
      1.0.0