Koa-JWT: Authentication Middleware for Koa

Koa-jwt is an essential middleware for the Koa framework that allows you to handle JSON Web Tokens (JWT) for authentication and authorization. It’s built on top of the popular jsonwebtoken library and provides seamless integration with Koa.

Getting Started with Koa-JWT

To start using koa-jwt, you need to install it along with Koa and the jsonwebtoken package:

  
    npm install koa koa-router koa-jwt jsonwebtoken
  

Basic Setup

Create a simple Koa app and use the koa-jwt middleware to protect a route:

  
    const Koa = require('koa');
    const Router = require('koa-router');
    const jwt = require('koa-jwt');
    const app = new Koa();
    const router = new Router();
    
    const secret = 'your_secret_key';
    
    // Public route
    router.get('/public', (ctx) => {
      ctx.body = 'This is a public route';
    });
    
    // Protected route
    router.get('/protected', jwt({ secret }), (ctx) => {
      ctx.body = 'This is a protected route';
    });
    
    app.use(router.routes());
    app.use(router.allowedMethods());
    
    app.listen(3000, () => {
      console.log('Server is running on port 3000');
    });
  

Generating JWT Tokens

You can generate JWT tokens using the jsonwebtoken library:

  
    const jwt = require('jsonwebtoken');
    const secret = 'your_secret_key';
    
    const token = jwt.sign({ user: 'john_doe' }, secret, { expiresIn: '1h' });
    console.log(token);
  

Error Handling

Koa-jwt emits errors that can be handled using Koa’s error-handling middleware:

  
    app.use(async (ctx, next) => {
      try {
        await next();
      } catch (err) {
        if (401 == err.status) {
          ctx.status = 401;
          ctx.body = 'Unauthorized: Access is denied due to invalid credentials';
        } else {
          throw err;
        }
      }
    });
  

Customizing Token Retrieval

You can customize how Koa-jwt retrieves JWT tokens by defining a `getToken` function:

  
    app.use(jwt({
      secret,
      getToken: (ctx) => {
        if (ctx.cookies.get('authToken')) {
          return ctx.cookies.get('authToken');
        } else if (ctx.header.authorization && ctx.header.authorization.split(' ')[0] === 'Bearer') {
          return ctx.header.authorization.split(' ')[1];
        }
        return null;
      }
    }));
  

Example App

Here’s a complete example of a Koa app using koa-jwt with public and protected routes, token generation, and custom token retrieval:

  
    const Koa = require('koa');
    const Router = require('koa-router');
    const jwt = require('koa-jwt');
    const jsonwebtoken = require('jsonwebtoken');
    const bodyParser = require('koa-bodyparser');
    const app = new Koa();
    const router = new Router();
    
    const secret = 'your_secret_key';
    
    // Middleware to generate tokens
    app.use(bodyParser());
    router.post('/login', (ctx) => {
      const user = ctx.request.body.user;
      const token = jsonwebtoken.sign({ user }, secret, { expiresIn: '1h' });
      ctx.body = { token };
    });
    
    // Public route
    router.get('/public', (ctx) => {
      ctx.body = 'This is a public route';
    });
    
    // Protected route
    router.get('/protected', jwt({ secret }), (ctx) => {
      ctx.body = 'This is a protected route';
    });
    
    // Custom token retrieval
    app.use(jwt({
      secret,
      getToken: (ctx) => {
        if (ctx.cookies.get('authToken')) {
          return ctx.cookies.get('authToken');
        } else if (ctx.header.authorization && ctx.header.authorization.split(' ')[0] === 'Bearer') {
          return ctx.header.authorization.split(' ')[1];
        }
        return null;
      }
    }).unless({ path: [/^\/public/] }));
    
    app.use(router.routes());
    app.use(router.allowedMethods());
    
    app.listen(3000, () => {
      console.log('Server is running on port 3000');
    });
  

With this guide, you should be able to implement JWT authentication in your Koa applications using koa-jwt. It’s a powerful tool that simplifies the process of securing your routes and managing user sessions.

Hash: 77a64ab2dea833701190f94ae75e32ced316521b17c48e127b03ecdff16a3b98