Package detail

jwks-rsa

auth010.6mMIT3.1.0

Library to retrieve RSA public keys from a JWKS endpoint

jwks, rsa, jwt

readme

Release Downloads CircleCI

📚 Documentation - 🚀 Getting Started - 💬 Feedback

Documentation

Examples - documentation of the options and code samples for common scenarios.
Docs Site - explore our Docs site and learn more about Auth0.

Getting Started

Installation

Using npm in your project directory run the following command:

npm install --save jwks-rsa

Supports all currently registered JWK types and JWS Algorithms, see panva/jose#262 for more information.

Configure the client

Provide a JWKS endpoint which exposes your signing keys.

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

const client = jwksClient({
  jwksUri: 'https://sandrino.auth0.com/.well-known/jwks.json',
  requestHeaders: {}, // Optional
  timeout: 30000 // Defaults to 30s
});

Retrieve a key

Then use getSigningKey to retrieve a signing key that matches a specific kid.

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

Feedback

Contributing

We appreciate feedback and contribution to this repo! Before you get started, please see the following:

Raise an issue

To provide feedback or report a bug, please raise an issue on our issue tracker.

Vulnerability Reporting

Please do not report security vulnerabilities on the public GitHub issue tracker. The Responsible Disclosure Program details the procedure for disclosing security issues.

What is Auth0?

Auth0 is an easy to implement, adaptable authentication and authorization platform. To learn more checkout Why Auth0?

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

changelog

Change Log

v3.1.0 (2023-10-05)

Full Changelog

Added

feat: resolve bun/deno compat issues #374 (panva)

v3.0.1 (2023-01-12)

Full Changelog

Fixed

update types/jsonwebtoken update v9.0.0 #349 (ToshihitoKon)
Bump jsonwebtoken from 8.5.1 to 9.0.0 #344 (dependabot[bot])

v3.0.0 (2022-11-01)

Full Changelog

⚠️ BREAKING CHANGES

This release drops support for Node 10 and 12

[major] bump jose #333 (panva)

v2.1.5 (2022-10-10)

Full Changelog

Fixed

Fix GetVerificationKey typing to include undefined #329 (AaronMoat)

v2.1.4 (2022-06-07)

Full Changelog

Fixed

Type definitions depend on jsonwebtoken #314 (adamjmcgrath)

v2.1.3 (2022-05-20)

Full Changelog

Fixed

Fix issue with ES Express import #310 (adamjmcgrath)

v2.1.2 (2022-05-12)

Full Changelog

Fixed

fix: express build error #304 (blindperson)

v2.1.1 (2022-05-06)

Full Changelog

Fixed

fix: types-compabitility for express-jwt @ 7 #301 (carboneater)

v2.1.0 (2022-04-26)

Full Changelog

Added

add support for express-jwt@7 #297 (jfromaniello)

Fixed

fix(type): correct the wrong type of the getSigningKey function arg… #289 (stegano)

v2.0.5 (2021-10-15)

Full Changelog

Fixed

Destroy the request when reaches the timeout (#270) #271 (amrsalama)
[SDK-2833] Fix issue where errors were being cached #268 (adamjmcgrath)

[2.0.4] - (2021-07-16)

Fixed

[SDK-2626] getKeysInterceptor types #251 (davidpatrick)

[2.0.3] - (2021-04-20)

Fixed

Fix retrieveSigningKeys error #242 (davidpatrick)

Security

Bump jose from 2.0.3 to 2.0.5 #244 (dependabot)

[2.0.2] - (2021-03-24)

Fixed

Interceptor bind client #237 (erikfried)
Update type def for getSigningKey #236 (davidpatrick)
Use hostname instead of host when creating request #233 (cjlpowers)

[2.0.1] - (2021-03-12)

Added

Callback backwards compatbility for getSigningKey #227 (davidpatrick)

Fixed

Fix typescript declarations for v2 #229 (davidpatrick)
Fix typescript types for fetcher #231 (itajaja)

[2.0.0] - (2021-03-01)

With version 2 we have added full JWK/JWS support. With this we have bumped the node version to minimum 10. We have also removed Axios and exposed a fetcher option to allow user's to completely override how the request to the jwksUri endpoint is made.

Breaking Changes

Drops support for Node < 10
No more callbacks, using async/await(promises)
Removed Axios and changed the API to JwksClient

Changes

Added

Full JWK/JWS Support #205 (panva)

Changed

Simplify request wrapper #218 (davidpatrick)
Pins to Node Version 10,12,14 #212 (davidpatrick)
Migrate from callbacks to async/await #222 (davidpatrick)

Migration Guide from v1 to v2

Proxies

The proxy option has been removed from the JwksClient. Support for it was a little spotty through Axios, and we wanted to allow users to have more control over the flow. Now you can specify your proxy by overriding the requestAgent used with an agent with built-in proxy support, or by completely overriding the request library with the fetcher option.

// OLD
const oldClient = jwksClient({
  jwksUri: 'https://sandrino.auth0.com/.well-known/jwks.json',
  proxy: 'https://username:pass@address:port'
});

// NEW
const HttpsProxyAgent = require('https-proxy-agent');
const newClient = jwksClient({
  jwksUri: 'https://sandrino.auth0.com/.well-known/jwks.json',
  requestAgent: new HttpsProxyAgent('https://username:pass@address:port')
});

Request Agent Options

The library no longer gates what http(s) Agent is used, so we have removed requestAgentOptions and now expose the requestAgent option when creating a jwksClient.

// OLD
const oldClient = jwksClient({
  jwksUri: 'https://sandrino.auth0.com/.well-known/jwks.json',
  requestAgentOptions: {
    ca: fs.readFileSync(caFile)
  }
});

// NEW
const newClient = jwksClient({
  jwksUri: 'https://sandrino.auth0.com/.well-known/jwks.json',
  requestAgent: new https.Agent({
    ca: fs.readFileSync(caFile)
  })
});

Migrated Callbacks to Async/Await

The library no longer supports callbacks. We have migrated to async/await(promises).

// OLD
client.getSigningKey(kid, (err, key) => {
  const signingKey = key.getPublicKey();
});

// NEW
const key = await client.getSigningKey(kid);
const signingKey = key.getPublicKey();

[1.12.3] - (2021-02-25)

Added

Add alg to SigningKey types #220 (okko)

Fixed

Fix npmjs resolves #221 (adamjmcgrath)
Fix Import default Axios instance #216 (dsebastien)

[1.12.2] - (2021-01-07)

Fixed

Added coverage folders to .npmignore

[1.12.1] - (2020-12-29)

Security

Bump Axios to ^0.21.1 #208 (72636c)

[1.12.0] - (2020-12-08)

Added

Provide an alternative source for supplying keysets #202 (davidpatrick)

Deprecation We are deprecating passing in a jwksObject to the client for reasons laid out in #202. In order to load keys from anything other than the jwksUri, please use the getKeysInterceptor.

  const client = new JwksClient({ 
    jwksUri: 'https://my-enterprise-id-provider/.well-known/jwks.json',
    getKeysInterceptor: (cb) => {
      const file = fs.readFileSync(jwksFile);
      return cb(null, file.keys);
    }
  });

[1.11.0] - (2020-10-23)

Added

Add ability to configure proxy with env vars #188 (lubomir-haralampiev)

[1.10.1] - (2020-09-24)

Fixed

fix proxy agent for http #182 (NShahri)
fix dependencies for --production flag with npm #180 (alexrqs)

[1.10.0] - (2020-09-23)

Added

getSigningKeys return algorithm #168 (moander)

Fixed

Add missing async methods to Typescript type definitions #163 (mwgamble)
Fixing proxy on Axios #176 (davidpatrick)
Fix caching and rateLimiting on getSigningKeyAsync #177 (davidpatrick)

[1.9.0] - (2020-08-18)

Added

Add promisified methods to JwksClient #161 (jimmyjames)
Update express-jwt ^6.0.0 #157 (davidpatrick)

Fixed

Update Buffer initialization to non-deprecated method #154 (cwardcode)
Use axios url parameter instead of baseURL #153 (novascreen)

Security

Bump lodash from 4.17.15 to 4.17.19 [#152](https://github.com/auth0/node-jwks

[1.8.1] - (2020-06-18)

Fixed

Fix #139 strictSsl: false option being ignored #146 (kopancek)

Security

Update dependencies to latest #147 (lbalmaceda)

[1.8.0] - (2020-04-12)

Added

Added timeout with default value of 30s #132 (Cooke)

Changed

Migrate from Deprecated Request Lib #135 (davidpatrick)

Fixed

Allow JWT to not contain a "kid" value#55 (dejan9393)

[1.7.0] - (2020-02-18)

This release includes a change to the default caching mechanism. Caching is on now by default, with the decrease of the default time of 10hours to 10minutes. This change introduces better support for signing key rotation.

Added

Add proxy option to jwksClient #125 (Ogdentrod)

Changed

[SDK-1221] Modify Cache Defaults #123 (davidpatrick)

Fixed

Add Linter step to CI #129 (davidpatrick)
Send the explicit commit SHA to Codecov #128 (lbalmaceda)

[1.6.2] - (2020-01-21)

This patch release includes an alias for accessing the public key of a given JSON Web Key (JWK). This is in response to an unintended breaking change that was introduced as part of the last Typescript definitions change, included in the release with version 1.6.0.

Now, no matter what the public key algorithm is, you can obtain it like this:

client.getSigningKey(kid, (err, jwk) => {
  const publicKey = jwk.getPublicKey();
});

Fixed

Add alias for obtaining the public key #119 (lbalmaceda)
Handling case when Jwk doesn't have 'use' parameter #116 (manpreet-compro)

[1.6.1] - (2020-01-13)

Changed

NPM dependencies update #112 (ecasilla)
Update lru-memoizer to 2.0.1 #106 (sobil)

[1.6.0] - (2019-07-09)

Added

Add agentOptions to customize request TLS/SSL options. https://github.com/auth0/node-jwks-rsa/pull/84

[1.5.1] - (2019-05-21)

Changed

Now includes the jsonwebtoken as a runtime dependency not dev to avoid breaks with 1.5.0 installs
Various dependencies in both the library and samples updated

[1.5.0] - (2019-05-09)

Added

Integrate with passport-jwt #77 (gconnolly)

[1.4.0] - (2019-02-07)

Added

Allow custom headers in request #77 (Mutmatt)

[1.3.0] - (2018-06-20)

Added

Adding support for hapi 17.x.x #38 (degrammer)

Fixed

Fixing wrong error message #41 (adematte)

[1.2.1] - 2017-10-19

Changed

Fixed TypeScript definition

[1.2.0] - 2017-06-27

Added

Koa integration

Changed

ms updated to v2.0.0