Interface JoseObserver

All Known Subinterfaces:
AccessTokenObserver, OAuthObserver, OidcObserver

@ThreadSafe public interface JoseObserver
Receives events from 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 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

      default void willFetchJwks(@NonNull URI jwksUri)
      Called just before a RemoteJwksSource sends 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 path
      usableKeyCount - how many keys are usable
      skippedKeyCount - how many keys were skipped (each also reported to didSkipJwk(URI, Integer, JwkSkipReason))
      timeToLive - how long the key set stays fresh, from the response's cache headers within the source's limits
      elapsed - how long the fetch took
      Since:
      1.0.0
    • didFailToFetchJwks

      default void didFailToFetchJwks(@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.
      Parameters:
      jwksUri - the key set's URI, cut to its scheme, host, port and path
      exception - the failure, the same instance that caller receives unless it is served stale keys
      servingStaleKeys - whether the caller is served keys from the expired key set instead
      elapsed - how long the fetch took
      Since:
      1.0.0
    • didSuppressJwksFetch

      default void didSuppressJwksFetch(@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. 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 path
      untilNextAttempt - 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 path
      keyIndex - the key's zero-based position in the set's keys array
      reason - why the key is not used
      Since:
      1.0.0
    • didValidateJwt

      default void didValidateJwt(@NonNull JwsAlgorithm algorithm, @NonNull Duration elapsed)
      Called when JwtValidator.validateResult(String) accepted a token.
      Parameters:
      algorithm - the token's algorithm
      elapsed - how long validation took, any key set fetch included
      Since:
      1.0.0
    • didFailToValidateJwt

      default void didFailToValidateJwt(@NonNull RevetsecException exception, @NonNull Duration elapsed)
      Called when JwtValidator.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 a JoseException, or the JwksUnavailableException about to be thrown
      elapsed - how long validation took, any key set fetch included
      Since:
      1.0.0
    • didAcceptAnyAudience

      default void didAcceptAnyAudience(@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.
      Parameters:
      issuer - the validator's expected issuer
      Since:
      1.0.0
    • didUseUnpatchedRuntime

      default void didUseUnpatchedRuntime(@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.
      Parameters:
      runtimeVersion - the running Java version, such as 17.0.2
      Since:
      1.0.0