node-jwks-rsa

The integration between koa-jwt and jwks-rsa follows this lifecycle during a request:

1. Token Decoding: koa-jwt decodes the incoming JWT and passes the request and the decoded token to jwksRsa.koaJwtSecret.
2. Key Retrieval: jwks-rsa downloads the signing keys from the configured jwksUri and searches for a key where the kid matches the kid in the JWT header.
   • If no match is found: An error is thrown.
   • If a match is found: The specific signing key is passed back to koa-jwt.
3. Validation: koa-jwt uses the provided key to validate the token's signature, expiration (exp), audience (aud), and issuer (iss).

Key Features:

• Caching: When cache: true is set, subsequent requests will use the cached keys instead of hitting the JWKS endpoint again.
• Rate Limiting: When rateLimit: true is set, the library limits the frequency of requests to the JWKS endpoint to protect your authorization server.

The integration follows this lifecycle:

1. Token Decoding: passport-jwt decodes the incoming JWT and passes the request, header, and payload to the secretOrKeyProvider (the function returned by jwksRsa.passportJwtSecret).
2. Key Retrieval: jwks-rsa fetches the signing keys from the configured jwksUri. It searches the key set for a key where the kid matches the kid in the JWT header.
   • If a match is found, the signing key is passed back to passport-jwt.
   • If no match is found, an error is thrown (which can be handled via handleSigningKeyError).
3. Validation: passport-jwt uses the provided key to validate the token's signature, expiration (exp), audience (aud), and issuer (iss).

Key Features:

• Caching: When cache: true is set, subsequent requests with the same keys do not trigger new calls to the JWKS endpoint.
• Rate Limiting: When rateLimit: true is set, the library limits the number of requests made to the JWKS endpoint (controlled by jwksRequestsPerMinute) to prevent abuse from invalid kid values.

To prevent service failure when the JWKS endpoint is unreachable after cacheMaxAge has expired, use cacheMaxAgeFallback. This setting allows the library to continue serving the last known good signing key for an additional duration.

Note: This is an availability vs. security tradeoff. If keys are rotated during a compromise while the endpoint is down, stale keys will still be trusted until the fallback window expires.

Use the onStaleCacheFallback callback to monitor when stale keys are being served (e.g., for alerting).

const jwksClient = require('jwks-rsa');

const client = jwksClient({
  cache: true,
  cacheMaxAge: 600000,          // 10 minutes — normal freshness TTL
  cacheMaxAgeFallback: 3600000, // 1 hour — serve stale key if JWKS endpoint is unreachable
  jwksUri: 'https://sandrino.auth0.com/.well-known/jwks.json',
  onStaleCacheFallback: (err, kid, staleKey) => {
    console.warn(`JWKS endpoint unavailable, serving stale key for kid '${kid}': ${err.message}`);
  }
});

const kid = 'RkI5MjI5OUY5ODc1N0Q4QzM0OUYzNkVGMTJDOUEzQkFCOTU3NjE2Rg';
const key = await client.getSigningKey(kid);
const signingKey = key.getPublicKey();

You can use jwksRsa.expressJwtSecret to create a secret provider for express-jwt. This provider dynamically retrieves the correct signing key from a JWKS endpoint based on the kid (Key ID) found in the JWT header. This is specifically useful when using the RS256 algorithm.

Common configuration options for expressJwtSecret include:

• cache: Set to true to enable caching of signing keys to avoid repeated JWKS endpoint requests.
• rateLimit: Set to true to enable rate limiting on JWKS requests.
• jwksRequestsPerMinute: Defines the rate limit threshold.
• jwksUri: The URL of your JWKS endpoint (e.g., https://my-authz-server/.well-known/jwks.json).

const Express = require('express');
const { expressjwt: jwt } = require('express-jwt');
const jwksRsa = require('jwks-rsa');

const app = new Express();
app.use(jwt({
  secret: jwksRsa.expressJwtSecret({
    cache: true,
    rateLimit: true,
    jwksRequestsPerMinute: 5,
    jwksUri: `https://my-authz-server/.well-known/jwks.json`
  }),
  audience: 'urn:my-resource-server',
  issuer: 'https://my-authz-server/',
  algorithms: [ 'RS256' ]
}));

The jwks-rsa library provides passportJwtSecret, a helper function that generates a secretOrKeyProvider for passport-jwt. This provider dynamically retrieves the correct signing key from a JWKS endpoint based on the kid (Key ID) found in the JWT header.

To use it, pass the result of jwksRsa.passportJwtSecret() to the secretOrKeyProvider option in your JwtStrategy configuration. You should also specify the jwksUri and typically enable cache and rateLimit for production use.

const JwtStrategy = require('passport-jwt').Strategy;
const jwksRsa = require('jwks-rsa');

passport.use(
  new JwtStrategy({
    // Dynamically provide a signing key based on the kid in the header
    secretOrKeyProvider: jwksRsa.passportJwtSecret({
      cache: true,
      rateLimit: true,
      jwksRequestsPerMinute: 5,
      jwksUri: `https://my-authz-server/.well-known/jwks.json`
    }),
    jwtFromRequest: ExtractJwt.fromAuthHeaderAsBearerToken(),

    // Validate the audience and the issuer.
    audience: 'urn:my-resource-server',
    issuer: 'https://my-authz-server/',
    algorithms: ['RS256']
  },
  verify)
);