Package org.jose4j.jwk

Class HttpsJwks

java.lang.Object
org.jose4j.jwk.HttpsJwks
public class HttpsJwks extends Object
Represents a set of JSON Web Keys (typically public keys) published at an HTTPS URI. Keys will be retrieved from the given location and cached based on the cache directive headers and/or the setDefaultCacheDuration(long). The keys are cached per HttpsJwks instance so your application will need to keep using the same instance, however is appropriate for that application, to get the benefit of the caching. This class, when used with HttpsJwksVerificationKeyResolver, can help facilitate the consuming side of a key publication and rotation model like that which is described in OpenID Connect, section 10.
See Also:

  • Field Details

    • log

      private static final org.slf4j.Logger log

    • location

      private final String location

    • defaultCacheDuration

      private volatile long defaultCacheDuration

    • simpleHttpGet

      private volatile SimpleGet simpleHttpGet

    • retainCacheOnErrorDurationMills

      private volatile long retainCacheOnErrorDurationMills

    • cache

      private volatile HttpsJwks.Cache cache

    • refreshLock

      private final ReentrantLock refreshLock

    • refreshReprieveThreshold

      private long refreshReprieveThreshold

  • Constructor Details

    • HttpsJwks

      public HttpsJwks(String location)
      Create a new HttpsJwks that cab be used to retrieve JWKs from the given location.
      Parameters:
      location - the HTTPS URI of the JSON Web Key Set

  • Method Details

    • setDefaultCacheDuration

      public void setDefaultCacheDuration(long defaultCacheDuration)
      The time period to cache the JWKs from the endpoint, if the cache directive headers of the response are not present or indicate that the content should not be cached. This is useful because the content of a JWKS endpoint should be cached in the vast majority of situations and cache directive headers that indicate otherwise are likely a mistake or misconfiguration. The default value, used when this method is not called, of the default cache duration is 3600 seconds (1 hour).
      Parameters:
      defaultCacheDuration - the length in seconds of the default cache duration

    • setRetainCacheOnErrorDuration

      public void setRetainCacheOnErrorDuration(long retainCacheOnErrorDuration)
      Sets the length of time, before trying again, to keep using the cache when an error occurs making the request to the JWKS URI or parsing the response. When equal or less than zero, an exception will be thrown from getJsonWebKeys() when an error occurs. When larger than zero, the previously established cached list of keys (if it exists) will be used/returned and another attempt to fetch the keys from the JWKS URI will not be made for the given duration. The default value is 0.
      Parameters:
      retainCacheOnErrorDuration - the length in seconds to keep using the cache when an error occurs before trying again

    • setSimpleHttpGet

      public void setSimpleHttpGet(SimpleGet simpleHttpGet)
      Sets the SimpleGet instance to use when making the HTTP GET request to the JWKS location. By default a new instance of Get is used. This method should be used right after construction, if a different implementation of SimpleGet or non-default configured instance of Get is needed.
      Parameters:
      simpleHttpGet - the instance of the implementation of SimpleGet to use

    • getLocation

      public String getLocation()
      Gets the location of the JWKS endpoint/URL.
      Returns:
      the location

    • setRefreshReprieveThreshold

      public void setRefreshReprieveThreshold(long refreshReprieveThreshold)
      Sets the period of time as a threshold for which a subsequent refresh() calls will use the cache and not actually refresh from the JWKS endpoint/URL.
      Parameters:
      refreshReprieveThreshold - the threshold time in milliseconds (probably should be a relatevily small value). The default value, if unset is 300.

    • getJsonWebKeys

      public List<JsonWebKey> getJsonWebKeys() throws JoseException, IOException
      Gets the JSON Web Keys from the JWKS endpoint location or from local cache, if appropriate.
      Returns:
      a list of JsonWebKeys
      Throws:
      JoseException - if a problem is encountered parsing the JSON content into JSON Web Keys.
      IOException - if a problem is encountered making the HTTP request.

    • refresh

      public void refresh() throws JoseException, IOException
      Forces a refresh of the cached JWKs from the JWKS endpoint. With slight caveat/optimization that if the cache age is less than refreshReprieveThreshold it will not actually force a refresh but use the cache instead.
      Throws:
      JoseException - if an problem is encountered parsing the JSON content into JSON Web Keys.
      IOException - if a problem is encountered making the HTTP request.

    • getDateHeaderValue

      static long getDateHeaderValue(SimpleResponse response, String headerName, long defaultValue)

    • getHeaderValues

      private static List<String> getHeaderValues(SimpleResponse response, String headerName)

    • getExpires

      static long getExpires(SimpleResponse response)

    • getCacheLife

      static long getCacheLife(SimpleResponse response)

    • getCacheLife

      static long getCacheLife(SimpleResponse response, long currentTime)