README

jwks-client

A library to retrieve signing keys from a JWKS (JSON Web Key Set) endpoint. This is a fork of the jwks-rsa-package to support ECDSA-keys as well. Functionally it is almost the same, except for the generalised response, which always uses publicKey regardless of the key used.

npm install --save jwks-client

Usage

You'll provide the client with the JWKS endpoint which exposes your signing keys. Using the getSigningKey you can then get the signing key that matches a specific kid.

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

const client = jwksClient({
  strictSsl: true, // Default value
  jwksUri: 'https://jacokoster.nl/.well-known/jwks.json'
});

const kid = 'RkI5MjI5OUY5ODc1N0Q4QzM0OUYzNkVGMTJDOUEzQkFCOTU3NjE2Rg';
client.getSigningKey(kid, (err, key) => {
  const signingKey = key.publicKey;
});

Caching

In order to prevent a call to be made each time a signing key needs to be retrieved you can also configure a cache as follows. If a signing key matching the kid is found, this will be cached and the next time this kid is requested the signing key will be served from the cache instead of calling back to the JWKS endpoint.

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

const client = jwksClient({
  cache: true,
  cacheMaxEntries: 5, // Default value
  cacheMaxAge: ms('10h'), // Default value
  jwksUri: 'https://jacokoster.nl/.well-known/jwks.json'
});

const kid = 'RkI5MjI5OUY5ODc1N0Q4QzM0OUYzNkVGMTJDOUEzQkFCOTU3NjE2Rg';
client.getSigningKey(kid, (err, key) => {
  const signingKey = key.publicKey;
});

Rate Limiting

Even if caching is enabled the library will call the JWKS endpoint if the kid is not available in the cache, because a key rotation could have taken place. To prevent attackers to send many random kids you can also configure rate limiting. This will allow you to limit the number of calls that are made to the JWKS endpoint per minute (because it would be highly unlikely that signing keys are rotated multiple times per minute).

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

const client = jwksClient({
  cache: true,
  rateLimit: true,
  jwksRequestsPerMinute: 10, // Default value
  jwksUri: 'https://jacokoster.nl/.well-known/jwks.json'
});

const kid = 'RkI5MjI5OUY5ODc1N0Q4QzM0OUYzNkVGMTJDOUEzQkFCOTU3NjE2Rg';
client.getSigningKey(kid, (err, key) => {
  const signingKey = key.publicKey;
});

Custom headers

It's possible to include custom headers to the request done to the key-server.

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

const client = jwksClient({
  jwksUri: 'https://jacokoster.nl/.well-known/jwks.json',
  headers: {
    'User-Agent': 'custom-request'
  }
});

const kid = 'RkI5MjI5OUY5ODc1N0Q4QzM0OUYzNkVGMTJDOUEzQkFCOTU3NjE2Rg';
client.getSigningKey(kid, (err, key) => {
  const signingKey = key.publicKey;
});

Running Tests

npm run test

Showing Trace Logs

To show trace logs you can set the following environment variable:

DEBUG=jwks

Output:

jwks Retrieving keys from http://my-authz-server/.well-known/jwks.json +5ms
jwks Keys: +8ms [ { alg: 'RS256',
  kty: 'RSA',
  use: 'sig',
  x5c: [ 'pk1' ],
  kid: 'ABC' },
{ alg: 'RS256', kty: 'RSA', use: 'sig', x5c: [], kid: '123' } ]

Usage no npm install needed!