Class RemoteJwksSource.Builder
java.lang.Object
com.revetsec.jose.RemoteJwksSource.Builder
- Enclosing class:
RemoteJwksSource
Builds a
RemoteJwksSource.
Each setter stores its value, and build() checks them all, in this order: each setting against its
range, then the time-to-live order, then the unknown-key refresh cooldown against the minimum time to live; the
minimum Java runtime; an injected client's redirect policy; then the URI.
null restores a setting's default. Nothing here does I/O.
- Since:
- 1.0.0
- Author:
- Mark Allen
-
Method Summary
Modifier and TypeMethodDescriptionacknowledgeUnpatchedRuntime(@Nullable Boolean acknowledgeUnpatchedRuntime) Sets whether to allow a Java runtime below Revetsec's minimum for network I/O (17.0.3, or 18.0.1 on Java 18), whose TLS and certificate checks are exposed to CVE-2022-21449.allowInsecureLoopback(@Nullable Boolean allowInsecureLoopback) Sets whether plainhttpis allowed to a loopback address or to exactlylocalhost, for tests.build()Builds the source, with no I/O.Sets the clock for the time to live, cooldown, backoff and staleness.defaultTimeToLive(@Nullable Duration defaultTimeToLive) Sets the time a fetched key set is cached when its response has neithermax-agenorExpires.httpClient(@Nullable HttpClient httpClient) Sets the HTTP client to fetch with.maximumKeys(@Nullable Integer maximumKeys) Sets the most keys a key set may hold, counting every element of itskeysarray, usable or not.maximumResponseBytes(@Nullable Integer maximumResponseBytes) Sets the largest key set response body accepted, in bytes.maximumStaleness(@Nullable Duration maximumStaleness) Sets how long after it expires a key set may still answer for the keys it holds, while refreshes fail or are held back.maximumTimeToLive(@Nullable Duration maximumTimeToLive) Sets the longest time a fetched key set is cached, whatever its cache headers say.minimumTimeToLive(@Nullable Duration minimumTimeToLive) Sets the shortest time a fetched key set is cached, whatever its cache headers say.observer(@Nullable JoseObserver observer) Sets the observer that receives this source's events.outboundUriPolicy(@Nullable OutboundUriPolicy outboundUriPolicy) Sets the policy the URI must pass.requestTimeout(@Nullable Duration requestTimeout) Sets how long one fetch may take, which is also the deadline of a standalone call.unknownKeyRefreshCooldown(@Nullable Duration unknownKeyRefreshCooldown) Sets the shortest time between two refreshes that tokens with unknown key IDs trigger.
-
Method Details
-
httpClient
Sets the HTTP client to fetch with. Build rejects redirect following, an Authenticator or a CookieHandler without sending a request. The application owns injected TLS/proxy configuration and egress beyond URI checks.- Parameters:
httpClient- a client using Redirect.NEVER, with no Authenticator or CookieHandler;nullrestores the default, a process-wide client Revetsec creates on the first fetch- Returns:
- this builder
- Since:
- 1.0.0
-
outboundUriPolicy
public @NonNull RemoteJwksSource.Builder outboundUriPolicy(@Nullable OutboundUriPolicy outboundUriPolicy) Sets the policy the URI must pass.- Parameters:
outboundUriPolicy- the policy;nullrestores the default,OutboundUriPolicy.defaultInstance()- Returns:
- this builder
- Since:
- 1.0.0
-
allowInsecureLoopback
public @NonNull RemoteJwksSource.Builder allowInsecureLoopback(@Nullable Boolean allowInsecureLoopback) Sets whether plainhttpis allowed to a loopback address or to exactlylocalhost, for tests. A request tolocalhostreaches loopback only as the host's name resolution decides, which usually means its hosts file.- Parameters:
allowInsecureLoopback- whether to allow it;nullrestores the default,false- Returns:
- this builder
- Since:
- 1.0.0
-
clock
Sets the clock for the time to live, cooldown, backoff and staleness. Outside tests, keep the default: a clock that stands still never lets the key set expire.- Parameters:
clock- the clock;nullrestores the default,Clock.systemUTC()- Returns:
- this builder
- Since:
- 1.0.0
-
requestTimeout
Sets how long one fetch may take, which is also the deadline of a standalone call.- Parameters:
requestTimeout- from 1 to 60 seconds;nullrestores the default, 10 seconds- Returns:
- this builder
- Since:
- 1.0.0
-
minimumTimeToLive
Sets the shortest time a fetched key set is cached, whatever its cache headers say. It must be at least the unknown-key refresh cooldown, so that the limit of two requests per cooldown holds back no refresh after expiry unless fetches were cut short;build()checks that.- Parameters:
minimumTimeToLive- from 30 seconds to 1 hour, and no shorter than the unknown-key refresh cooldown;nullrestores the default, 1 minute- Returns:
- this builder
- Since:
- 1.0.0
-
defaultTimeToLive
Sets the time a fetched key set is cached when its response has neithermax-agenorExpires.- Parameters:
defaultTimeToLive- from 30 seconds to 24 hours;nullrestores the default, 10 minutes- Returns:
- this builder
- Since:
- 1.0.0
-
maximumTimeToLive
Sets the longest time a fetched key set is cached, whatever its cache headers say.- Parameters:
maximumTimeToLive- from 1 minute to 24 hours;nullrestores the default, 6 hours- Returns:
- this builder
- Since:
- 1.0.0
-
unknownKeyRefreshCooldown
public @NonNull RemoteJwksSource.Builder unknownKeyRefreshCooldown(@Nullable Duration unknownKeyRefreshCooldown) Sets the shortest time between two refreshes that tokens with unknown key IDs trigger. It is also the first step of the backoff after a failed fetch, and the window of the limit of two requests of any kind. It must be no longer than the minimum time to live, so that this limit holds back no refresh after expiry unless fetches were cut short;build()checks that.- Parameters:
unknownKeyRefreshCooldown- from 1 second to 10 minutes, and no longer than the minimum time to live;nullrestores the default, 30 seconds- Returns:
- this builder
- Since:
- 1.0.0
-
maximumStaleness
Sets how long after it expires a key set may still answer for the keys it holds, while refreshes fail or are held back.- Parameters:
maximumStaleness- from zero, which never serves an expired key set, to 24 hours;nullrestores the default, 12 hours- Returns:
- this builder
- Since:
- 1.0.0
-
maximumResponseBytes
public @NonNull RemoteJwksSource.Builder maximumResponseBytes(@Nullable Integer maximumResponseBytes) Sets the largest key set response body accepted, in bytes.- Parameters:
maximumResponseBytes- from 16 KiB to 4 MiB;nullrestores the default, 256 KiB- Returns:
- this builder
- Since:
- 1.0.0
-
maximumKeys
Sets the most keys a key set may hold, counting every element of itskeysarray, usable or not.- Parameters:
maximumKeys- from 1 to 1,000;nullrestores the default, 100- Returns:
- this builder
- Since:
- 1.0.0
-
observer
Sets the observer that receives this source's events.- Parameters:
observer- the observer;nullrestores the default,JoseObserver.disabledInstance()- Returns:
- this builder
- Since:
- 1.0.0
-
acknowledgeUnpatchedRuntime
public @NonNull RemoteJwksSource.Builder acknowledgeUnpatchedRuntime(@Nullable Boolean acknowledgeUnpatchedRuntime) Sets whether to allow a Java runtime below Revetsec's minimum for network I/O (17.0.3, or 18.0.1 on Java 18), whose TLS and certificate checks are exposed to CVE-2022-21449. The choice is reported toJoseObserver.didUseUnpatchedRuntime(String)when the source is built and on every fetch.- Parameters:
acknowledgeUnpatchedRuntime- whether to accept the risk;nullrestores the default,false- Returns:
- this builder
- Since:
- 1.0.0
-
build
Builds the source, with no I/O.- Returns:
- a new source
- Throws:
IllegalArgumentException- if a setting is out of range, the time-to-live settings are not ordered minimum, default, maximum, the unknown-key refresh cooldown is longer than the minimum time to live, the injected client follows redirects, or the URI is not permittedIllegalStateException- if the Java runtime is below Revetsec's minimum for network I/O and that was not acknowledged- Since:
- 1.0.0
-