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:

  • Constructor Summary

    Constructors
    Constructor
    Description
    HttpsJwks(String location)
    Create a new HttpsJwks that cab be used to retrieve JWKs from the given location.

  • Method Summary

    Modifier and Type
    Method
    Description
    List<JsonWebKey>
    getJsonWebKeys()
    Gets the JSON Web Keys from the JWKS endpoint location or from local cache, if appropriate.
    String
    getLocation()
    Gets the location of the JWKS endpoint/URL.
    void
    refresh()
    Forces a refresh of the cached JWKs from the JWKS endpoint.
    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.
    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.
    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.
    void
    setSimpleHttpGet(SimpleGet simpleHttpGet)
    Sets the SimpleGet instance to use when making the HTTP GET request to the JWKS location.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • 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.