node-jwks-rsa

jwks-rsa is a small, focused Node.js library maintained by Auth0 for resolving JSON Web Key Set (JWKS) signing keys used to verify JWTs. Rather than hand-rolling a fetch-and-cache loop against a /.well-known/jwks.json endpoint, consumers configure a client with a jwksUri and call getSigningKey(kid) to get back a usable public key, with the library handling key-type resolution (RSA, EC, OKP), in-memory caching, rate limiting, and graceful degradation during endpoint outages.

It ships first-class integrations for express-jwt (both v6 and v7), koa-jwt, passport-jwt, and hapi-auth-jwt2, so most Node.js JWT-verification setups can plug it in as a secretProvider/secret callback without writing key-resolution logic themselves. Because JWKS is the standard mechanism OAuth2/OIDC providers (Auth0, Okta, Azure AD, Google, and self-hosted identity providers) use to publish rotating signing keys, jwks-rsa functions as a general building block for any Node.js service verifying externally-issued JWTs, not just Auth0-issued ones.

What You Get

• A JwksClient that fetches keys from any standards-compliant JWKS endpoint and resolves RSA, EC (P-256/P-384/P-521), and OKP (Ed25519/Ed448) key types to a usable public key via the jose library
• Built-in LRU caching of resolved signing keys (cache, cacheMaxEntries, cacheMaxAge) so repeated verifications don’t hit the JWKS endpoint on every request
• A cacheMaxAgeFallback / onStaleCacheFallback mechanism that keeps serving the last known-good key for a configurable grace window if the JWKS endpoint becomes unreachable, instead of failing every verification immediately
• Per-minute rate limiting (rateLimit, jwksRequestsPerMinute) to blunt attempts to force excessive JWKS lookups via crafted kid values
• Ready-made adapters for express-jwt (v6 and v7), koa-jwt, passport-jwt, and hapi-auth-jwt2, plus a getKeysInterceptor hook for loading keys from a local file, environment variable, or external cache before falling back to the network

Common Use Cases

• Verifying JWTs issued by an OAuth2/OIDC provider (Auth0, Okta, Azure AD, or a self-hosted IdP) in an Express, Koa, or Hapi API without writing custom key-fetch logic
• Adding JWT authentication middleware to a Node.js API gateway or microservice that needs to validate tokens signed by a rotating key set
• Tolerating brief JWKS endpoint outages in production without rejecting all incoming requests, via the stale-key fallback window
• Loading signing keys from a local file or secrets manager in air-gapped or offline environments via getKeysInterceptor, while still falling back to the live endpoint when needed

Under The Hood

Architecture

The library centers on a single JwksClient (src/JwksClient.js) exposing getKeys() and getSigningKey(kid). Additional behavior is layered on via a decorator/wrapper pattern applied conditionally in the constructor: getKeysInterceptor, rateLimitSigningKey, and cacheSigningKey (src/wrappers/) each wrap and reassign this.getSigningKey in sequence when their corresponding option is set, and callbackSupport is always applied last so the public method transparently accepts both promise and legacy Node-style callback usage (via util.promisify/callbackify). Per-framework adapters (src/integrations/express.js, koa.js, hapi.js, passport.js) each wrap a JwksClient instance behind that framework’s expected secret-resolution signature — express.js notably branches on arguments.length to serve both the express-jwt v6 (4-arg callback) and v7 (2-arg promise) contracts from one function.

Tech Stack

Plain CommonJS JavaScript (Node 20/22/23+ per engines) with hand-maintained TypeScript declarations (index.d.ts) rather than a compiled TS build. Core runtime dependencies are narrow and purpose-built: jose for JWK import and SPKI export, lru-cache + lru-memoizer for the caching layer, limiter for token-bucket rate limiting, and debug for opt-in trace logging (DEBUG=jwks). JWKS retrieval uses Node’s native http/https modules directly (src/wrappers/request.js) rather than a bundled HTTP client, while still accepting a custom fetcher or requestAgent for proxy/TLS configuration. CI runs across CircleCI and GitHub Actions (codeql.yml, snyk.yml, test.yml, npm-release.yml), with Snyk and CodeQL scanning wired in alongside the standard test matrix.

Code Quality

The tests/ directory holds 14 Mocha + Chai (with chai-as-promised) spec files covering the core client, each wrapper (cache, rate limit, interceptor), the raw request layer, and every framework integration, using nock to mock JWKS HTTP responses rather than hitting real endpoints. A dedicated tests/ts-definitions.tests.ts compiles against index.d.ts to catch type-declaration drift. Error handling favors explicit typed error classes (ArgumentError, JwksError, JwksRateLimitError, SigningKeyNotFoundError) over generic thrown Errors, and failure paths (500 responses, missing keys, rate-limit exhaustion) are directly asserted in tests. nyc generates coverage reports uploaded to Codecov, and ESLint runs against both src and tests.

API Design The public surface is intentionally small: a single factory call (jwksClient({ jwksUri })) and one primary method (getSigningKey(kid)), configured entirely through a flat options object. Ergonomics are aimed at real production failure modes rather than surface API sugar — cacheMaxAgeFallback/onStaleCacheFallback for endpoint-outage tolerance, jwksRequestsPerMinute for abuse resistance, and getKeysInterceptor for offline key sourcing are all opt-in without changing the core call shape. Dual callback/promise support and the express-jwt v6/v7 arity detection mean existing integrations don’t need to change when consumers upgrade adjacent middleware versions.