Skip to content

Cache JWKS results

Problem to solve

The 10Duke Scale API exposes the public key(s) necessary to verify the authenticity and integrity of license JSON Web Tokens (JWTs) via a JSON Web Key Set (JWKS).

The SDK automates retrieval of the JWKS such that the client application does not directly interact with the JWKS endpoint. Currently, the JWKS endpoint is accessed each time a checkout / start, heartbeat, release / end call is made.

The 10Duke Scale API is metered and billed per API request (via a monthly quota that can be topped up with additional purchases). Calls to the JWKS endpoint are counted against that monthly quota.

As the application developer does not direclty make the API calls to the JWKS endpoint it can be surprising when there are many calls to the JWKS endpoint.

10Duke Scale treats license verification keys as immutable. A new key can be generated, but an existing key cannot be modified.

The content of the JWKS is slow moving and the public keys within it can be considered immutable. This makes it suitable for caching on the client or device.

Proposal

Cache JWKS results as a map/dictionary keyed on the key id (kid ).

The cache must be able to be configured to persist the public keys between application sessions.

Enabled by default with a file system cache (using configuration item public_key_path as the location). Consider providing a persistence interface (store) that can configured via DI and Client Builder to set alternative persistence mechanism.

Any call to JWKS should immediately persist discovered keys to the cache (adding new keys that were not in the cache - not updating existing keys). Cache should be loaded at intialization of the licence checkout client.

When verifying license token JWT, the code should check the cache for the kid (from the JWT header) and only call the JWKS endpoint if the public key for the kid is not already present in the cache (cache-miss).

As the public keys for license verification are immutable, there is no cache invalidation mechanism for the keys. Keys in the cache effectively never expire.

Intended users

Should be automatically enabled for all SDK users.

Acceptance criteria (done when...)

  • A cache is provided for public keys loaded from the licensing API JWKS endpoint
  • JWKS Cache is configured / enabled by default
  • Licensing client initialization (via DI or client builder) loads the cache from persistent storage
  • Keys loaded via JWKS are persisted to configured persistence mechanism
  • Verifying JWTs first checks for the public key in the cache and only calls the JWKS endpoint if the key is not found in the cache
  • A default implementation of persistent store for public keys is provided - stores the keys on the file system in the location specified by configuration item public_key_path