jwks-rsa

What is jwks-rsa?

The jwks-rsa npm package is a library that helps to retrieve RSA signing keys from a JWKS (JSON Web Key Set) endpoint. It is primarily used in scenarios where you need to verify the signature of JSON Web Tokens (JWTs) against public keys published in a JWKS. This is common in modern authentication flows, especially those implementing OpenID Connect.

What are jwks-rsa's main functionalities?

Retrieving RSA signing keys

This feature allows you to retrieve RSA signing keys from a JWKS endpoint. The `getSigningKey` method is used to fetch the key using the `kid` (key ID) from the JWT header. This is useful for verifying JWT signatures.

const jwksClient = require('jwks-rsa');
const client = jwksClient({
  jwksUri: 'https://your-domain.com/.well-known/jwks.json'
});

function getKey(header, callback){
  client.getSigningKey(header.kid, function(err, key) {
    var signingKey = key.publicKey || key.rsaPublicKey;
    callback(null, signingKey);
  });
}

Integrating with Express.js for JWT authentication

This code snippet demonstrates how to use jwks-rsa with express-jwt middleware for securing Express.js applications. The `expressJwtSecret` method is used to dynamically provide a signing key based on the incoming JWT's `kid`.

const jwt = require('express-jwt');
const jwksRsa = require('jwks-rsa');

const checkJwt = jwt({
  secret: jwksRsa.expressJwtSecret({
    cache: true,
    rateLimit: true,
    jwksRequestsPerMinute: 5,
    jwksUri: 'https://your-domain.com/.well-known/jwks.json'
  }),
  audience: 'your-audience',
  issuer: 'https://your-domain.com/',
  algorithms: ['RS256']
});

Other packages similar to jwks-rsa

node-jose

A package for JavaScript Object Signing and Encryption (JOSE) and JSON Web Token (JWT) implementation. It offers similar functionalities for handling JWKS but is more comprehensive in terms of JOSE standards support, including encryption and decryption capabilities, which jwks-rsa does not directly offer.

jsonwebtoken

This package is primarily focused on creating and verifying JSON Web Tokens (JWTs). While it doesn't directly handle JWKS, it is often used in conjunction with libraries like jwks-rsa for verifying JWT signatures against public keys obtained from a JWKS endpoint.

README

📚 Documentation - 🚀 Getting Started - 💬 Feedback

Documentation

• Examples - 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:

• Auth0's general contribution guidelines
• Auth0's code of conduct guidelines

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

v3.0.0 (2022-11-01)

Full Changelog

⚠️ BREAKING CHANGES

This release drops support for Node 10 and 12

• [major] bump jose #333 (panva)