Skip to content

In nimbus-jose-jwt, what is difference between lifespan and refreshTime?

The class DefaultJWKSetCache of nimbus-jose-jwt has two fields, lifespan and refreshTime.
From Java docs –

lifespan – The lifespan of the cached JWK set before it expires, negative means no expiration.
refreshTime – The time after which the cached JWK set is marked for refresh, negative if not specified. Should be shorter or equal to the lifespan.

What is the difference between these two. Does it mean that,
after the lifespan expiry the cached JWK set will be evicted and loaded again from jwks remote url (saying remote url as i am using RemoteJWKSet).
and after the refresh expiry the existing JWK set will be updated with the keys retrieved from remote url.

But i don’t understand the practical difference between the two. Both seem to be doing same. Can some one explain the details with more granularity and any example.

Edit – if i give no expiry for lifespan, and 1 hour expiry for refreshTime, am i guaranteed that my keys will be updated every one hour.


The lifespan is the time after which the DefaultJWKSetCache will evict cached JWKSet. I.e., after lifespan time units passed since the cache was populated the calls to JWKSetCache.get() will always return null until new JWKSet is stored to the cache.

The refreshTime is the time that impacts value returned by JWKSetCache.requiresRefresh() method. After refreshTime time units passed since the cache was populated this method will return true, otherwise, it will return false. This setting does not impact cache behavior in any way.

The RemoteJWKSet uses the value returned by JWKSetCache.requiresRefresh() to re-download JWKSet from remote URL before the cache is actually expired. This is why documentation recommends to set refreshTime to a lesser value than lifespan.

Currently, RemoteJWKSet triggers download of remote JWKSet when either lifespan or refreshTime has passed (see this line.) Hence, there is not much difference in setting either one of these as of today. I guess some more complex logic can be potentially implemented having these two values separate.