Skip to content
A library to retrieve RSA public keys from a JWKS (JSON Web Key Set) endpoint.
JavaScript TypeScript
Branch: master
Clone or download
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github Setup the .github/stale.yml for Probot:Stale Oct 26, 2019
examples
src Merge branch 'master' into support-private-cert-tls Jul 8, 2019
tests
.babelrc
.editorconfig Adding missing types definition dependency, .editorconfig, and fixing… Apr 17, 2017
.eslintrc Initial commit Jul 18, 2016
.gitignore fixed typescript definitions and added tests Jun 4, 2019
.npmignore
CHANGELOG.md Release 1.6.0 Jul 9, 2019
LICENSE Initial commit Jul 18, 2016
README.md Merge branch 'master' into support-private-cert-tls Jul 8, 2019
index.d.ts
package-lock.json Update lru-memoizer to 2.0.1 Aug 26, 2019
package.json
tsconfig.json fixed typescript definitions and added tests Jun 4, 2019

README.md

jwks-rsa

NPM version License Downloads

A library to retrieve RSA signing keys from a JWKS (JSON Web Key Set) endpoint.

npm install --save jwks-rsa

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-rsa');

const client = jwksClient({
  strictSsl: true, // Default value
  jwksUri: 'https://sandrino.auth0.com/.well-known/jwks.json',
  requestHeaders: {}, // Optional
  requestAgentOptions: {} // Optional
});

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

  // Now I can use this to configure my Express or Hapi middleware
});

Integrations are also provided with:

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-rsa');

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

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

  // Now I can use this to configure my Express or Hapi middleware
});

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-rsa');

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

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

  // Now I can use this to configure my Express or Hapi middleware
});

Using AgentOptions for TLS/SSL Configuration

The requestAgentOptions property can be used to configure SSL/TLS options. An example use case is providing a trusted private (i.e. enterprise/corporate) root certificate authority to establish TLS communication with the jwks_uri.

const jwksClient = require("jwks-rsa");
const client = jwksClient({
  strictSsl: true, // Default value
  jwksUri: 'https://my-enterprise-id-provider/.well-known/jwks.json',
  requestHeaders: {}, // Optional
  requestAgentOptions: {
    ca: fs.readFileSync(caFile)
  }
});

For more information, see the NodeJS request library agentOptions documentation.

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' } ]

License

This project is licensed under the MIT license. See the LICENSE file for more info.

You can’t perform that action at this time.