npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@ohanapediatrics/koa-jwt

v3.6.1

Published

Koa JWT authentication middleware.

Downloads

2

Readme

koa-jwt

node version npm download npm stats test status coverage license

Table of Contents

Introduction

This module lets you authenticate HTTP requests using JSON Web Tokens in your Koa (node.js) applications.

See this article for a good introduction.

  • If you are using koa version 2+, and you have a version of node < 7.6, install koa-jwt@2.
  • koa-jwt version 3+ on the master branch uses async / await and hence requires node >= 7.6.
  • If you are using koa version 1, you need to install koa-jwt@1 from npm. This is the code on the koa-v1 branch.

Install

npm install koa-jwt

Usage

The JWT authentication middleware authenticates callers using a JWT token. If the token is valid, ctx.state.user (by default) will be set with the JSON object decoded to be used by later middleware for authorization and access control.

Retrieving the token

The token is normally provided in a HTTP header (Authorization), but it can also be provided in a cookie by setting the opts.cookie option to the name of the cookie that contains the token. Custom token retrieval can also be done through the opts.getToken option. The provided function should match the following interface:

/**
 * Your custom token resolver
 * @this The ctx object passed to the middleware
 *
 * @param  {object}      opts The middleware's options
 * @return {String|null}      The resolved token or null if not found
 */

The resolution order for the token is the following. The first non-empty token resolved will be the one that is verified.

  • opts.getToken function
  • check the cookies (if opts.cookie is set)
  • check the Authorization header for a bearer token

Passing the secret

One can provide a single secret, or array of secrets in opts.secret. An alternative is to have an earlier middleware set ctx.state.secret, typically per request. If this property exists, it will be used instead of opts.secret.

Checking if the token is revoked

You can provide a async function to jwt for it check the token is revoked. Only you set the function in opts.isRevoked. The provided function should match the following interface:

/**
 * Your custom isRevoked resolver
 *
 * @param  {object}      ctx The ctx object passed to the middleware
 * @param  {object}      decodedToken Content of the token
 * @param  {object}      token token The token
 * @return {Promise}     If the token is not revoked, the promise must resolve with false, otherwise (the promise resolve with true or error) the token is revoked
 */

Example

var Koa = require('koa');
var jwt = require('koa-jwt');

var app = new Koa();

// Custom 401 handling if you don't want to expose koa-jwt errors to users
app.use(function(ctx, next){
  return next().catch((err) => {
    if (401 == err.status) {
      ctx.status = 401;
      ctx.body = 'Protected resource, use Authorization header to get access\n';
    } else {
      throw err;
    }
  });
});

// Unprotected middleware
app.use(function(ctx, next){
  if (ctx.url.match(/^\/public/)) {
    ctx.body = 'unprotected\n';
  } else {
    return next();
  }
});

// Middleware below this line is only reached if JWT token is valid
app.use(jwt({ secret: 'shared-secret' }));

// Protected middleware
app.use(function(ctx){
  if (ctx.url.match(/^\/api/)) {
    ctx.body = 'protected\n';
  }
});

app.listen(3000);

Alternatively you can conditionally run the jwt middleware under certain conditions:

var koa = require('koa');
var jwt = require('koa-jwt');

var app = new Koa();

// Middleware below this line is only reached if JWT token is valid
// unless the URL starts with '/public'
app.use(jwt({ secret: 'shared-secret' }).unless({ path: [/^\/public/] }));

// Unprotected middleware
app.use(function(ctx, next){
  if (ctx.url.match(/^\/public/)) {
    ctx.body = 'unprotected\n';
  } else {
    return next();
  }
});

// Protected middleware
app.use(function(ctx){
  if (ctx.url.match(/^\/api/)) {
    ctx.body = 'protected\n';
  }
});

app.listen(3000);

For more information on unless exceptions, check koa-unless.

If you want to do something with authentication errors within this piece of middleware, you can add the onError option. This should be a function that accepts and Error object and the Koa context.

app.use(jwt({
    secret: 'shared-secret',
    onError: (error, ctx) => {
        ctx.state.authError = error.message;
    }
}));

You can also add the passthrough option to always yield next, even if no valid Authorization header was found:

app.use(jwt({ secret: 'shared-secret', passthrough: true }));

This lets downstream middleware make decisions based on whether ctx.state.user is set.

If you prefer to use another ctx key for the decoded data, just pass in key, like so:

app.use(jwt({ secret: 'shared-secret', key: 'jwtdata' }));

This makes the decoded data available as ctx.state.jwtdata.

You can specify audience and/or issuer as well:

app.use(jwt({ secret:   'shared-secret',
              audience: 'http://myapi/protected',
              issuer:   'http://issuer' }));

You can specify an array of secrets.

The token will be considered valid if it validates successfully against any of the supplied secrets. This allows for rolling shared secrets, for example:

app.use(jwt({ secret: ['old-shared-secret', 'new-shared-secret'] }));

Token Verification Exceptions

If the JWT has an expiration (exp), it will be checked.

All error codes for token verification can be found at: https://github.com/auth0/node-jsonwebtoken#errors--codes.

Notifying a client of error codes (e.g token expiration) can be achieved by sending the err.originalError.message error code to the client.

// Custom 401 handling (first middleware)
app.use(function (ctx, next) {
  return next().catch((err) => {
    if (err.status === 401) {
      ctx.status = 401;
      ctx.body = {
        error: err.originalError ? err.originalError.message : err.message
      };
    } else {
      throw err;
    }
  });
});

If the tokenKey option is present, and a valid token is found, the original raw token is made available to subsequent middleware as ctx.state[opts.tokenKey].

This module also support tokens signed with public/private key pairs. Instead of a secret, you can specify a Buffer with the public key:

var publicKey = fs.readFileSync('/path/to/public.pub');
app.use(jwt({ secret: publicKey }));

If the secret option is a function, this function is called for each JWT received in order to determine which secret is used to verify the JWT.

The signature of this function should be (header, payload) => [Promise(secret)], where header is the token header and payload is the token payload. For instance to support JWKS token header should contain alg and kid: algorithm and key id fields respectively.

This option can be used to support JWKS (JSON Web Key Set) providers by using node-jwks-rsa. For example:

const { koaJwtSecret } = require('jwks-rsa');

app.use(jwt({
  secret: koaJwtSecret({
    jwksUri: 'https://sandrino.auth0.com/.well-known/jwks.json',
    cache: true,
    cacheMaxEntries: 5,
    cacheMaxAge: ms('10h')
  }),
  audience: 'http://myapi/protected',
  issuer: 'http://issuer'
}));

Related Modules

Note that koa-jwt no longer exports the sign, verify and decode functions from jsonwebtoken in the koa-v2 branch.

Tests

npm install
npm test

Authors/Maintainers

Credits

The initial code was largely based on express-jwt.

Contributors

License

The MIT License