JWKS caching

Efficiently handling JSON Web Key Sets (JWKS) is crucial for the performance and security of any authentication system. nevisAuth provides straightforward mechanisms to manage JWKS, whether they are fetched from a remote endpoint or loaded from a local file.

JWKS Loading and Caching

nevisAuth can acquire JSON Web Key Sets from two primary sources:

1. A remote jwks_uri endpoint.
2. A local file system path.

(either configured directly or via nevisMeta)

To ensure high performance and resilience, especially when fetching keys over a network, nevisAuth implements a caching layer. Caching is applied to both sources and maintained globally. Cache contains entries per HttpClient + URI, so even though the cache is global, the different AuthStates / Services maintain their cache separately to provide more flexibility.

JWKS usage

nevisAuth uses the JWKS cache in the following places:

• RelyingPartyState
• AuthorizationServer
• OAuth2ClientState
• PARService

Configuration Options

The behavior of the JWKS caching is controlled by two system properties. You can set these properties in the JAVA_OPTS in env.conf.

• -Dch.nevis.auth.jwk.cache.enabled (Boolean, optional, true)

  Enables or disables the in-memory caching of a JWK set fetched from a jwks_uri. When enabled, nevisAuth stores the key set for a defined period, avoiding repeated network requests for the same set of keys. Caching is highly recommended for production environments to reduce latency and network traffic to the identity provider.

• -Dch.nevis.auth.jwk.cache.timeToLive (Long, optional, 1800000 - 30 minutes)

  Specifies the duration, in milliseconds, that a cached JWK set is considered valid. After this time-to-live (TTL) expires, nevisAuth will refresh this entry in the cache. This setting allows you to balance performance with how quickly your system will pick up on key rotations at the provider.