Interface JoseObserver
- All Known Subinterfaces:
AccessTokenObserver, OAuthObserver, OidcObserver
JwtValidator and RemoteJwksSource, for metrics, logs and alerts.
Every hook is a default method that does nothing, so an implementation overrides only the hooks it needs.
Hooks run synchronously on the calling thread, never while Revetsec holds a lock. Anything a hook throws is
contained and does not affect the operation, except a VirtualMachineError. Keep hooks fast: a slow hook
slows the call that fired it.
Hooks never receive a string taken from a token or a key set: no key ID, claim or header value. A key is named by
its position in the set's keys array. URIs are cut to their scheme, host, port and path. Elapsed durations
are measured with System.nanoTime(); untilNextAttempt follows the key source's
Clock, and timeToLive comes from the response's cache headers within the source's limits.
A failure hook receives the same exception instance the caller gets.
An observer may be called from many threads at once, so implementations must be thread-safe.
- Since:
- 1.0.0
- Author:
- Mark Allen
-
Method Summary
Modifier and TypeMethodDescriptiondefault voiddidAcceptAnyAudience(@NonNull String issuer) Called when a validator configured to accept any audience is built, and on each of its validations, because accepting any audience lets a token issued for another application through.default voiddidFailToFetchJwks(@NonNull URI jwksUri, @NonNull JwksUnavailableException exception, @NonNull Boolean servingStaleKeys, @NonNull Duration elapsed) Called when a key set fetch failed, by the one caller that fetched it.default voiddidFailToValidateJwt(@NonNull RevetsecException exception, @NonNull Duration elapsed) Called whenJwtValidator.validateResult(String)rejects a token or cannot get its keys, before returning the rejection or propagating the key-source failure.default voiddidFetchJwks(@NonNull URI jwksUri, @NonNull Integer usableKeyCount, @NonNull Integer skippedKeyCount, @NonNull Duration timeToLive, @NonNull Duration elapsed) Called when a key set fetch succeeded, by the one caller that fetched it.default voiddidSkipJwk(@NonNull URI jwksUri, @NonNull Integer keyIndex, @NonNull JwkSkipReason reason) Called for each key a fetched key set holds but Revetsec does not use, on every fetch.default voiddidSuppressJwksFetch(@NonNull URI jwksUri, @NonNull Duration untilNextAttempt) Called on every call that needed a key set fetch but sent no request, because a recent failure, the unknown-key cooldown or the limit on attempts per cooldown held it back.default voiddidUseUnpatchedRuntime(@NonNull String runtimeVersion) Called when a component that acknowledged running below Revetsec's minimum Java runtime version is built, and on each of its fetches.default voiddidValidateJwt(@NonNull JwsAlgorithm algorithm, @NonNull Duration elapsed) Called whenJwtValidator.validateResult(String)accepted a token.static @NonNull JoseObserverReturns an observer whose hooks do nothing: the default for every component that takes an observer.default voidwillFetchJwks(@NonNull URI jwksUri) Called just before aRemoteJwksSourcesends a request for its key set, by the one caller that fetches it.
-
Method Details
-
disabledInstance
Returns an observer whose hooks do nothing: the default for every component that takes an observer.- Returns:
- the shared observer that does nothing
- Since:
- 1.0.0
-
willFetchJwks
Called just before aRemoteJwksSourcesends a request for its key set, by the one caller that fetches it.- Parameters:
jwksUri- the key set's URI, cut to its scheme, host, port and path- Since:
- 1.0.0
-
didFetchJwks
default void didFetchJwks(@NonNull URI jwksUri, @NonNull Integer usableKeyCount, @NonNull Integer skippedKeyCount, @NonNull Duration timeToLive, @NonNull Duration elapsed) Called when a key set fetch succeeded, by the one caller that fetched it. A key set in which every key was skipped still succeeds.- Parameters:
jwksUri- the key set's URI, cut to its scheme, host, port and pathusableKeyCount- how many keys are usableskippedKeyCount- how many keys were skipped (each also reported todidSkipJwk(URI, Integer, JwkSkipReason))timeToLive- how long the key set stays fresh, from the response's cache headers within the source's limitselapsed- how long the fetch took- Since:
- 1.0.0
-
didSuppressJwksFetch
Called on every call that needed a key set fetch but sent no request, because a recent failure, the unknown-key cooldown or the limit on attempts per cooldown held it back. Many of these in a short time can mean that someone is sending tokens with made-up key IDs.- Parameters:
jwksUri- the key set's URI, cut to its scheme, host, port and pathuntilNextAttempt- how long until a fetch may be sent again, on the source's clock- Since:
- 1.0.0
-
didSkipJwk
default void didSkipJwk(@NonNull URI jwksUri, @NonNull Integer keyIndex, @NonNull JwkSkipReason reason) Called for each key a fetched key set holds but Revetsec does not use, on every fetch. Some identity providers publish an encryption key beside their signing keys, so this hook can fire on every fetch in normal operation.- Parameters:
jwksUri- the key set's URI, cut to its scheme, host, port and pathkeyIndex- the key's zero-based position in the set'skeysarrayreason- why the key is not used- Since:
- 1.0.0
-
didValidateJwt
Called whenJwtValidator.validateResult(String)accepted a token.- Parameters:
algorithm- the token's algorithmelapsed- how long validation took, any key set fetch included- Since:
- 1.0.0
-
didFailToValidateJwt
Called whenJwtValidator.validateResult(String)rejects a token or cannot get its keys, before returning the rejection or propagating the key-source failure.- Parameters:
exception- the fixed rejection diagnostic as aJoseException, or theJwksUnavailableExceptionabout to be thrownelapsed- how long validation took, any key set fetch included- Since:
- 1.0.0
-
didAcceptAnyAudience
Called when a validator configured to accept any audience is built, and on each of its validations, because accepting any audience lets a token issued for another application through.- Parameters:
issuer- the validator's expected issuer- Since:
- 1.0.0
-
didUseUnpatchedRuntime
Called when a component that acknowledged running below Revetsec's minimum Java runtime version is built, and on each of its fetches.- Parameters:
runtimeVersion- the running Java version, such as17.0.2- Since:
- 1.0.0
-