JWKSCache#

class gafaelfawr.cache.JWKSCache(lifetime, min_refresh)#

Bases: BaseCache

A cache of the signing keys of a single JWT issuer.

This holds the parsed keys from an issuer’s JSON Web Key Set (JWKS), indexed by key ID, along with the JWKS URI discovered from the issuer’s OpenID Connect metadata, for a fixed lifetime so that each token verification does not require retrieving and parsing the keys again. All of the retrieval logic is handled by the verifier that uses it, currently GitHubActionsTokenVerifier.

The caller should first call get without a lock and use the result if it contains the needed key. Otherwise, the caller should take the lock, call get again, and only if the key is still missing retrieve a fresh set and store it, so that concurrent requests do not all fetch the keys at once. Since anyone can present a token naming an unknown key ID, the caller should also check recently_refreshed before retrieving the keys again, so that a stream of such tokens cannot force a request to the issuer for each one.

Parameters:
  • lifetime (timedelta) – How long to cache the keys.

  • min_refresh (timedelta) – Minimum interval between refreshes prompted by an unknown key ID.

Methods Summary

clear()

Invalidate the cache.

get()

Retrieve the cached keys, if available and not expired.

get_jwks_uri()

Retrieve the cached JWKS URI, if available and not expired.

lock()

Return the cache lock for use in a context manager.

recently_refreshed()

Whether the keys were stored within the minimum refresh interval.

store(jwks_uri, keys)

Store a freshly retrieved key set in the cache.

Methods Documentation

async clear()#

Invalidate the cache.

Used primarily for testing.

Return type:

None

Overrides:

BaseCache.clear

get()#

Retrieve the cached keys, if available and not expired.

Returns:

The cached keys indexed by key ID, or None if there is no cached key set or it has expired.

Return type:

dict[str, PyJWK] | None

get_jwks_uri()#

Retrieve the cached JWKS URI, if available and not expired.

The URI is cached for the same lifetime as the keys, so that a refresh prompted by an unknown key ID does not have to retrieve the issuer’s OpenID Connect metadata again, but a change to that metadata is picked up once the cache expires.

Returns:

The JWKS URI from which the cached keys were retrieved, or None if there is no cached key set or it has expired.

Return type:

str | None

lock()#

Return the cache lock for use in a context manager.

Returns:

The lock for the cache.

Return type:

Lock

recently_refreshed()#

Whether the keys were stored within the minimum refresh interval.

Returns:

True if a key set was stored less than the minimum refresh interval ago, in which case the caller should not retrieve the keys again in response to an unknown key ID.

Return type:

bool

store(jwks_uri, keys)#

Store a freshly retrieved key set in the cache.

Parameters:
  • jwks_uri (str) – The JWKS URI from which the keys were retrieved.

  • keys (dict[str, PyJWK]) – The parsed keys, indexed by key ID.

Return type:

None