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:

HttpsJwksVerificationKeyResolver

Constructor Summary

Constructors

Constructor and 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 and 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 Detail

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 Detail

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.