Cache JSON Web Key Sets (JWKSs) downloaded from an identity provider (such as Keycloak).
JWKSs allow services to validate JSON Web Tokens (JWTs) without making requests to the issuer of the token. Only the JWKS must be available. However, if the service restarts, or a key is rotated, the service must contact the issuer again to retrieve the JWKS. If the issuer is unavailable, the service cannot validate tokens.
The problem is made worse by naive implementations of the JWKS retrieval mechanism present in many frameworks.
jwks-cache attempts to mitigate common pitfalls by using the excellent Nimbus JOSE + JWT library for features like:
- Rate limiting
- Caching with refresh-ahead
- Retrial
- Outage tolerance
Additional to these features, we offer persistence of cached JWKSs to ensure a service can safely restart, even if the issuer is unavailable.
jwks-cache is a Spring Boot project, so all regular Spring Boot configuration can be applied. Additionally, we provide these settings:
| Parameter | Default | Description | Example |
|---|---|---|---|
jaconi.jwks.urls |
[] |
The JWKS URLs to download and expose | ["https://example.com/.well-known/jwks.json"] |
jaconi.jwks.persistence.file.enabled |
false |
Cache a JWKS as file | true |
jaconi.jwks.persistence.file.path |
/var/cache/jwks-cache |
The storage location for a cached JWKS | /mnt/volume/cache |
When configuring consuming services, simply move the existing JWKS URL to jaconi.jwks.urls and configure the
jwks-cache instead: :8080/.well-known/jwks.json.
A liveness endpoint is available at :8080/livez. A readiness endpoint is available at :8080/readyz.
JSON logging can be enabled by using the Spring profile json-logging. See Adding Active Profiles for details.
Prometheus metrics are exposed at :8081/actuator/prometheus by default.
A custom metric is available to monitor the JWKS endpoints: jwks_cache_endpoints. The value is 0 for unhealthy, and
1 for healthy endpoints. The endpoints URL is in the url tag.