koa-jwt

Koa JWT authentication middleware.

koa-jwt

Koa middleware that validates JSON Web Tokens and sets ctx.user (by default) if a valid token is provided.

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

See this article for a good introduction.

$ npm install koa-jwt

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

var koa = require('koa');
var jwt = require('koa-jwt');
 
var app = koa();
 
// Custom 401 handling if you don't want to expose koa-jwt errors to users 
app.use(function *(next){
  try {
    yield next;
  } catch (err) {
    if (401 == err.status) {
      this.status = 401;
      this.body = 'Protected resource, use Authorization header to get access\n';
    } else {
      throw err;
    }
  }
});
 
// Unprotected middleware 
app.use(function *(next){
  if (this.url.match(/^\/public/)) {
    this.body = 'unprotected\n';
  } else {
    yield next;
  }
});
 
// Middleware below this line is only reached if JWT token is valid 
app.use(jwt({ secret: 'shared-secret' }));
 
// Protected middleware 
app.use(function *(){
  if (this.url.match(/^\/api/)) {
    this.body = 'protected\n';
  }
});
 
app.listen(3000);

Alternatively, you can 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.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.jwtdata.

You can specify audience and/or issuer as well:

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

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

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 }));

Note that koa-jwt exports the sign, verify and decode functions from the above module as a convenience.

Also note that verify is thunkified to play nice with co/koa.

$ npm install
$ npm test

Stian Grytøyr

This code is largely based on express-jwt.

  • [soygul] (https://github.com/soygul)
  • [tunnckoCore] (https://github.com/tunnckoCore)
  • [getuliojr] (https://github.com/getuliojr)
  • [cesarandreu] (https://github.com/cesarandreu)

The MIT License