Class JwksPublisher

java.lang.Object
com.revetsec.jose.JwksPublisher

@Immutable public final class JwksPublisher extends Object
Publishes an immutable snapshot of public verification keys without an OAuth authorization server, signing, storage, network access or background threads. Applications register the endpoint and supply its key snapshot. Replace the publisher to rotate keys, retaining old verification keys until outstanding signatures and cached key sets have expired. Publication does not advertise the endpoint through discovery automatically.

A set has at most 100 keys and 256 KiB of UTF-8 JSON. Nonempty key IDs must be unique; keys without IDs are allowed. GET and HEAD support entity tags and bounded If-None-Match input. Outgoing HTTP Cache-Control max-age defaults to 60 seconds and can be configured from zero through 24 hours, in whole seconds. This policy controls downstream response caching; it does not expire or reload the key snapshot and is independent of OAuth issuer policy.

Since:
1.0.0
  • Method Details

    • withKeys

      @CheckReturnValue public static @NonNull JwksPublisher.Builder withKeys(@NonNull List<@NonNull PublishedJwk> keys)
      Starts a publisher builder with a snapshot of the complete ordered key list. An empty list publishes an empty set.
      Parameters:
      keys - at most 100 public keys, in publication order
      Returns:
      the builder
      Throws:
      NullPointerException - if the list or an element is null
      IllegalArgumentException - if there are too many keys
      Since:
      1.0.0
    • fromKeys

      @CheckReturnValue public static @NonNull JwksPublisher fromKeys(@NonNull List<@NonNull PublishedJwk> keys)
      Returns a publisher with the default HTTP cache max-age. Equivalent to withKeys(keys).build().
      Parameters:
      keys - at most 100 public keys, in publication order
      Returns:
      the immutable publisher
      Throws:
      NullPointerException - if the list or an element is null
      IllegalArgumentException - if the key count, identifiers or document size is invalid
      Since:
      1.0.0
    • getKeys

      Returns the immutable ordered public key snapshot.
      Returns:
      the published keys
      Since:
      1.0.0
    • getHttpCacheMaxAge

      Returns the max-age advertised in outgoing HTTP Cache-Control headers. It does not control key loading.
      Returns:
      the HTTP cache max-age in whole seconds
      Since:
      1.0.0
    • toJson

      Serializes the public JWKS document to JSON text, in the supplied key order. The HTTP cache max-age does not affect the document.
      Returns:
      the JSON text, matching the UTF-8 document served by GET
      Since:
      1.0.0
    • toJsonObject

      Returns the immutable public JWKS document, in the supplied key order.
      Returns:
      the JSON document
      Since:
      1.0.0
    • responseFor

      @CheckReturnValue public @NonNull JwksResponse responseFor(@NonNull String httpMethod)
      Prepares a GET or HEAD response without a conditional header. Other methods receive 405.
      Parameters:
      httpMethod - the exact, case-sensitive HTTP method
      Returns:
      the prepared response
      Throws:
      NullPointerException - if the method is null
      Since:
      1.0.0
    • responseFor

      @CheckReturnValue public @NonNull JwksResponse responseFor(@NonNull String httpMethod, @Nullable String ifNoneMatch)
      Prepares a public response. GET/HEAD use weak If-None-Match comparison, including lists and the wildcard, to return 304 when appropriate. Malformed conditional syntax is ignored; input longer than 8192 characters receives a bodyless, non-cacheable 400. Combine repeated header occurrences with commas before calling this method.
      Parameters:
      httpMethod - the exact, case-sensitive HTTP method
      ifNoneMatch - the complete If-None-Match field value, or null if absent
      Returns:
      the prepared response, including method or header rejection
      Throws:
      NullPointerException - if the method is null
      Since:
      1.0.0
    • toString

      Returns a diagnostic without keys, key identifiers or certificate contents.
      Overrides:
      toString in class Object
      Returns:
      the diagnostic description
      Since:
      1.0.0